Python's min() and max(): Find Smallest and Largest Values

Calling min() and max() With a Single Iterable Argument

The built-in min() and max() have two different signatures that allow you to call them either with an iterable as their first argument or with two or more regular arguments. The signature that accepts a single iterable argument looks something like this:

min(iterable, *[, default, key]) -> minimum_value

max(iterable, *[, default, key]) -> maximum_value

Both functions take a required argument called iterable and return the minimum and maximum values respectively. They also take two optional keyword-only arguments: default and key.

Here’s a summary of what the arguments to min() and max() do:

Later in this tutorial, you’ll learn more about the optional default and key arguments. For now, just focus on the iterable argument, which is a required argument that leverages the standard behavior of min() and max() in Python:

>>> min([3, 5, 9, 1, -5])
-5

>>> min([])
Traceback (most recent call last):
    ...
ValueError: min() arg is an empty sequence

>>> max([3, 5, 9, 1, -5])
9

>>> max([])
Traceback (most recent call last):
    ...
ValueError: max() arg is an empty sequence

In these examples, you call min() and max() with a list of integer numbers and then with an empty list. The first call to min() returns the smallest number in the input list, -5. In contrast, the first call to max() returns the largest number in the list, or 9. If you pass an empty iterator to min() or max(), then you get a ValueError because there’s nothing to do on an empty iterable.

An important detail to note about min() and max() is that all the values in the input iterable must be comparable. Otherwise, you get an error. For example, numeric values work okay:

>>> min([3, 5.0, 9, 1.0, -5])
-5

>>> max([3, 5.0, 9, 1.0, -5])
9

These examples combine int and float numbers in the calls to min() and max(). You get the expected result in both cases because these data types are comparable.

However, what would happen if you mixed strings and numbers? Check out the following examples:

>>> min([3, "5.0", 9, 1.0, "-5"])
Traceback (most recent call last):
    ...
TypeError: '<' not supported between instances of 'str' and 'int'

>>> max([3, "5.0", 9, 1.0, "-5"])
Traceback (most recent call last):
    ...
TypeError: '>' not supported between instances of 'str' and 'int'

You can’t call min() or max() with an iterable of noncomparable types as an argument. In this example, a function tries to compare a number to a string, which is like comparing apples and oranges. The end result it that you get a TypeError.

Calling min() and max() With Multiple Arguments

The second signature of min() and max() allows you to call them with any number of arguments, provided that you use at least two arguments. This signature has the following form:

min(arg_1, arg_2[, ..., arg_n], *[, key]) -> minimum_value

max(arg_1, arg_2[, ..., arg_n], *[, key]) -> maximum_value

Again, these functions return the minimum and maximum values, respectively. Here’s the meaning of the arguments in the above signature:

This variation of min() or max() doesn’t have a default argument. You must provide at least two arguments in the call for the function to work correctly. So, a default value isn’t required, because you’ll always have at least two values to compare in order to find the minimum or maximum.

To try out this alternative signature, run the following examples:

>>> min(3, 5, 9, 1, -5)
-5

>>> max(3, 5, 9, 1, -5)
9

You can call min() or max() with two or more regular arguments. Again, you’ll get the minimum or maximum value in the input data, respectively. The only condition is that the arguments must be comparable.

Removing the Smallest and Largest Numbers in a List

To kick things off, you’ll start with a short example of how to remove the minimum and maximum values from a list of numbers. To do that, you can call .remove() on your input list. Depending on your needs, you’ll use min() or max() to select the value that you’ll remove from the underlying list:

>>> sample = [4, 5, 7, 6, -12, 4, 42]

>>> sample.remove(min(sample))
>>> sample
[4, 5, 7, 6, 4, 42]

>>> sample.remove(max(sample))
>>> sample
[4, 5, 7, 6, 4]

In these examples, the minimum and maximum values in sample could be outlier data points that you want to remove so that they don’t affect your further analysis. Here, min() and max() provide the arguments to .remove().

Building Lists of Minimum and Maximum Values

Now say that you have a list of lists representing a matrix of numeric values, and you need to build lists containing the smallest and largest values from every row in the input matrix. To do this, you can use min() and max() along with a list comprehension:

>>> matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]

>>> [min(x) for x in matrix]
[1, 4, 7]

>>> [max(x) for x in matrix]
[3, 6, 9]

The first comprehension iterates over the sublists in matrix and uses min() to build a list containing the smallest value from each sublist. The second comprehension does a similar task but uses max() to create a list containing the largest values from the sublists in matrix.

Even though min() and max() provide a quick way to deal with the examples in this section, the NumPy library is highly recommended when it comes to processing matrixes in Python because NumPy has specific and optimized tools for the job.

Clipping Values to the Edges of an Interval

Sometimes you have a list of numeric values and want to clip them to the edges or limits of a given interval. For example, if a given value is greater than the interval’s upper limit, then you need to convert it down to that limit. To do this operation, you can use min().

Wait! Why min()? You’re dealing with the large values, aren’t you? The point is that you need to compare each large value to the interval’s upper limit and then choose the smaller of the two. You’ll essentially set all large values to a prescribed upper limit:

>>> # Clip values to the largest interval's edge

>>> upper = 100
>>> numbers = [42, 78, 200, -230, 25, 142]

>>> [min(number, upper) for number in numbers]
[42, 78, 100, -230, 25, 100]

The call to min() compares every number to the interval’s upper limit. If the target number is greater than the limit, then min() returns the limit. The net effect is that all the values that are greater than the limit are now clipped to it. In this example, the numbers 200 and 142 are clipped to 100, which is the interval’s upper limit.

In contrast, if you want to clip small values to the interval’s lower limit, then you can use max(), like in the following example:

>>> # Clip values to the smallest interval's edge

>>> lower = 10
>>> numbers = [42, 78, 200, -230, 25, 142]

>>> [max(number, lower) for number in numbers]
[42, 78, 200, 10, 25, 142]

This call to max() clips the small values to the interval’s lower limit. To do this clipping, max() compares the current number and the interval’s limit to find the maximum value. In the example, -230 is the only number that gets clipped.

Finally, you can run both operations in one go by combining min() and max(). Here’s how to do it:

>>> # Clipping values to 10 - 100

>>> lower, upper = 10, 100
>>> numbers = [42, 78, 100, -230, 25, 142]

>>> [max(min(number, upper), lower) for number in numbers]
[42, 78, 100, 10, 25, 100]

To clip all the values that fall outside the interval’s limits, this comprehension combines min() and max(). The call to min() compares the current value to the interval’s upper limit, while the call to max() compares the result to the lower limit. The final result is that values lower than or greater than the corresponding limit are clipped to the limit itself.

This comprehension works similarly to the clip() function from NumPy, which takes an array and the limits of the target interval, then it clips all values outside the interval to the interval’s edges.

Finding the Closest Points

Now say that you have a list of tuples containing pairs of values that represent Cartesian points. You want to process all these pairs of points and find out which pair has the smallest distance between points. In this situation, you can do something like the following:

>>> import math

>>> point_pairs = [
...     ((12, 5), (9, 4)),
...     ((2, 5), (3, 7)),
...     ((4, 11), (15, 2))
... ]

>>> min(point_pairs, key=lambda points: math.dist(*points))
((2, 5), (3, 7))

In this example, you first import math to get access to dist(). This function returns the Euclidean distance between two points, p and q, each given as a sequence of coordinates. The two points must have the same number of dimensions.

The min() function works its magic through its key argument. In this example, key takes a lambda function that computes the distance between two points. This function becomes the comparison criteria for min() to find the pair of points with the minimal distance between points.

In this example, you need a lambda function because key expects a single-argument function, while math.dist() requires two arguments. So, the lambda function takes a single argument, points, and then unpacks it into two arguments to feed into math.dist().

Identifying Cheap and Expensive Products

Now say you have a dictionary with the names and prices of several products, and you want to identify the cheapest and most expensive products. In this situation, you can use .items() and an appropriate lambda function as the key argument:

>>> prices = {
...    "banana": 1.20,
...    "pineapple": 0.89,
...    "apple": 1.57,
...    "grape": 2.45,
... }

>>> min(prices.items(), key=lambda item: item[1])
('pineapple', 0.89)

>>> max(prices.items(), key=lambda item: item[1])
('grape', 2.45)

In this example, the lambda function takes a key-value pair as an argument and returns the corresponding value so that min() and max() have proper comparison criteria. As a result, you get a tuple with the cheapest and most expensive products in the input data.

Finding Coprime Integer Numbers

Another interesting example of using min() to solve a real-world problem is when you need to figure out if two numbers are coprime. In other words, you need to know if your numbers’ only common divisor is 1.

In that situation, you can code a Boolean-valued or predicate function like the following:

>>> def are_coprime(a, b):
...     for i in range(2, min(a, b) + 1):
...         if a % i == 0 and b % i == 0:
...             return False
...     return True
...

>>> are_coprime(2, 3)
True
>>> are_coprime(2, 4)
False

In this code snippet, you define are_coprime() as a predicate function that returns True if the input numbers are coprime. If the numbers aren’t coprime, then the function returns False.

The function’s main component is a for loop that iterates over a range of values. To set the upper limit for this range object, you use min() with the input numbers as arguments. Again, you’re using min() to set the upper limit of some interval.

Timing Different Implementations of Your Code

You can also use min() to compare several of your algorithms, evaluate their execution times, and determine which algorithm is the most efficient. The example below uses timeit.repeat() to measure the execution times for two different ways of building a list containing the square values of the numbers from 0 to 99:

>>> import timeit

>>> min(
...     timeit.repeat(
...         stmt="[i ** 2 for i in range(100)]",
...         number=1000,
...         repeat=3
...     )
... )
0.022141209003166296

>>> min(
...     timeit.repeat(
...         stmt="list(map(lambda i: i ** 2, range(100)))",
...         number=1000,
...         repeat=3
...     )
... )
0.023857666994445026

The call to timeit.repeat() runs a string-based statement a given number of times. In these examples, the statement is repeated three times. The call to min() returns the smallest execution time from the three repetitions.

By combining min(), repeat(), and other Python timer functions, you can get an idea of which of your algorithms is most efficient in terms of execution time. The example above shows that list comprehensions can be a little bit faster than the built-in map() function when it comes to building new lists.

Understanding the Code Behind min() and max()

To find the minimum value in a small list of numbers as a human, you’d normally check the numbers and implicitly compare all of them in your mind. Yes, your brain is amazing! However, computers aren’t that smart. They need detailed instructions to accomplish any task.

You’ll have to tell your computer to iterate over all the values while comparing them in pairs. In the process, the computer has to take note of the current minimum value in each pair until the list of values is processed entirely.

This explanation may be hard to visualize, so here’s a Python function that does the work:

>>> def find_min(iterable):
...     minimum = iterable[0]
...     for value in iterable[1:]:
...         if value < minimum:
...             minimum = value
...     return minimum
...

>>> find_min([2, 5, 3, 1, 9, 7])
1

In this code snippet, you define find_min(). This function assumes that iterable isn’t empty and that its values are in an arbitrary order.

The function treats the first value as a tentative minimum. Then the for loop iterates over the rest of the elements in the input data.

The conditional statement compares the current value to the tentative minimum in the first iteration. If the current value is smaller than minimum, then the conditional updates minimum accordingly.

Each new iteration compares the current value to the updated minimum. When the function reaches the end of iterable, minimum will hold the smallest value in the input data.

Cool! You’ve coded a function that finds the smallest value in an iterable of numbers. Now revisit find_min() and think of how you’d code a function to find the largest value. Yes, that’s it! You just have to change the comparison operator from less than (<) to greater than (>), and probably rename the function and some local variables to prevent confusion.

Your new function can look something like this:

>>> def find_max(iterable):
...     maximum = iterable[0]
...     for value in iterable[1:]:
...         if value > maximum:
...             maximum = value
...     return maximum
...

>>> find_max([2, 5, 3, 1, 9, 7])
9

Note that find_max() shares most of its code with find_min(). The most important difference, apart from naming, is that find_max() uses the greater than operator (>) instead of the less than operator (<).

As an exercise, you can think of how to avoid repetitive code in find_min() and find_max() following the DRY (don’t repeat yourself) principle. This way, you’ll be ready to emulate the complete behavior of min() and max() using your Python skills, which you’ll tackle in just a moment.

Before diving in, you need to be aware of the knowledge requirements. You’ll be combining topics like conditional statements, exception handling, list comprehensions, definite iteration with for loops, and *args and optional arguments in functions.

If you feel that you don’t know everything about these topics, then don’t worry. You’ll learn by doing. If you get stuck, then you can go back and review the linked resources.

Planning Your Custom min() and max() Versions

To write your custom implementations of min() and max(), you’ll start by coding a helper function that’s able to find the smallest or largest value in the input data, depending on the arguments you use in the call. Of course, the helper function will especially depend on the operator used for comparing the input values.

Your helper function will have the following signature:

min_max(*args, operator, key=None, default=None) -> extreme_value

Here’s what each argument does:

The body of min_max() will start by processing *args to build a list of values. Having a standardized list of values will allow you to write the required algorithm to find the minimum and maximum values in the input data.

Then the function needs to deal with the key and default arguments before computing the minimum and maximum, which is the final step inside min_max().

With min_max() in place, the final step is to define two independent functions on top of it. These functions will use appropriate comparison operator functions to find the minimum and maximum values, respectively. You’ll learn more about operator functions in a moment.

Standardizing the Input Data From *args

To standardize the input data, you need to check if the user is providing a single iterable or any number of regular arguments. Fire up your favorite code editor or IDE and create a new Python file called min_max.py. Then add the following piece of code to it:

# min_max.py

def min_max(*args, operator, key=None, default=None):
    if len(args) == 1:
        try:
            values = list(args[0])  # Also check if the object is iterable
        except TypeError:
            raise TypeError(
                f"{type(args[0]).__name__} object is not iterable"
            ) from None
    else:
        values = args

Here, you define min_max(). The function’s first portion standardizes the input data for further processing. Because the user will be able to call min_max() with either a single iterable or with several regular arguments, you need to check the length of args. To do this check, you use the built-in len() function.

If args holds only one value, then you need to check if that argument is an iterable object. You use list(), which implicitly does the check and also turns the input iterable into a list.

If list() raises a TypeError, then you catch it and raise your own TypeError to inform the user that the provided object isn’t iterable, just like min() and max() do in their standard form. Note that you use the from None syntax to hide away the traceback of the original TypeError.

The else branch runs when args holds more than one value, which handles the cases where the user calls the function with several regular arguments instead of with a single iterable of values.

If this conditional doesn’t ultimately raise a TypeError, then values will hold a list of values that may be empty. Even if the resulting list is empty, it’s now clean and ready for continuing the process of finding its minimum or maximum value.

Processing the default Argument

To continue writing min_max(), you can now process the default argument. Go ahead and add the following code to the end of the function:

# min_max.py
# ...

def min_max(*args, operator, key=None, default=None):
    # ...

    if not values:
        if default is None:
            raise ValueError("args is an empty sequence")
        return default

In this code snippet, you define a conditional to check if values holds an empty list. If that’s the case, then you check the default argument to see if the user provided a value for it. If default is still None, then a ValueError is raised. Otherwise, default gets returned. This behavior emulates the standard behavior of min() and max() when you call them with empty iterables.

Handling the Optional key Function

Now you need to process the key argument and prepare the data for finding the smallest and largest values according to the provided key. Go ahead and update min_max() with the following code:

# min_max.py
# ...

def min_max(*args, operator, key=None, default=None):
    # ...

    if key is None:
        keys = values
    else:
        if callable(key):
            keys = [key(value) for value in values]
        else:
            raise TypeError(f"{type(key).__name__} object is not a callable")

You start this code fragment with a conditional that checks if the user hasn’t provided a key function. If they haven’t, then you create a list of keys directly from your original values. You’ll use these keys as comparison keys in computing the minimum and maximum.

On the other hand, if the user has provided a key argument, then you need to make sure that the argument is actually a function or callable object. To do this, you use the built-in callable() function, which returns True if its argument is a callable and False otherwise.

Once you’re sure that key is a callable object, then you build the list of comparison keys by applying key to each value in the input data.

Finally, if key isn’t a callable object, then the else clause runs, raising a TypeError, just like min() and max() do in a similar situation.

Finding Minimum and Maximum Values

The last step to finish your min_max() function is to find the minimum and maximum values in the input data, just like min() and max() do. Go ahead and wrap up min_max() with the following code:

# min_max.py
# ...

def min_max(*args, operator, key=None, default=None):
    # ...

    extreme_key, extreme_value = keys[0], values[0]
    for key, value in zip(keys[1:], values[1:]):
        if operator(key, extreme_key):
            extreme_key = key
            extreme_value = value
    return extreme_value

You set the extreme_key and extreme_value variables to the first value in keys and in values, respectively. These variables will provide the initial key and value for computing the minimum and maximum.

Then you loop over the remaining keys and values in one go using the built-in zip() function. This function will yield key-value tuples by combining the values in your keys and values lists.

The conditional inside the loop calls operator to compare the current key to the tentative minimum or maximum key stored in extreme_key. At this point, the operator argument will hold either lt() or gt() from the operator module, depending on if you want to find the minimum or maximum value, respectively.

For example, when you want to find the smallest value in the input data, operator will hold the lt() function. When you want to find the largest value, operator will hold gt().

Every loop iteration compares the current key to the tentative minimum or maximum key and updates the values of extreme_key and extreme_value accordingly. At the end of the loop, these variables will hold the minimum or maximum key and its corresponding value. Finally, you just need to return the value in extreme_value.

Coding Your Custom min() and max() Functions

With the min_max() helper function in place, you can define your custom versions of min() and max(). Go ahead and add the following functions to the end of your min_max.py file:

# min_max.py

from operator import gt, lt

# ...

def custom_min(*args, key=None, default=None):
    return min_max(*args, operator=lt, key=key, default=default)

def custom_max(*args, key=None, default=None):
    return min_max(*args, operator=gt, key=key, default=default)

In this code snippet, you first import gt() and lt() from the operator module. These functions are the functional equivalent of the greater than (>) and less than (<) operators, respectively. For example, the Boolean expression x < y is equivalent to the function call lt(x, y). You’ll use these functions to provide the operator argument to your min_max().

Just like min() and max(), custom_min() and custom_max() take *args, key, and default as arguments and return the minimum and maximum values, respectively. To perform the computation, these functions call min_max() with the required arguments and with the appropriate comparison operator function.

In custom_min(), you use lt() to find the smallest value in the input data. In custom_max(), you use gt() to get the largest value.

Click the collapsible section below if you want to get the entire content of your min_max.py file:

# min_max.py

from operator import gt, lt

def min_max(*args, operator, key=None, default=None):
    if len(args) == 1:
        try:
            values = list(args[0])  # Also check if the object is iterable
        except TypeError:
            raise TypeError(
                f"{type(args[0]).__name__} object is not iterable"
            ) from None
    else:
        values = args

    if not values:
        if default is None:
            raise ValueError("args is an empty sequence")
        return default

    if key is None:
        keys = values
    else:
        if callable(key):
            keys = [key(value) for value in values]
        else:
            raise TypeError(f"{type(key).__name__} object is not a callable")

    extreme_key, extreme_value = keys[0], values[0]
    for key, value in zip(keys[1:], values[1:]):
        if operator(key, extreme_key):
            extreme_key = key
            extreme_value = value
    return extreme_value

def custom_min(*args, key=None, default=None):
    return min_max(*args, operator=lt, key=key, default=default)

def custom_max(*args, key=None, default=None):
    return min_max(*args, operator=gt, key=key, default=default)

Cool! You’ve finished coding your own versions of min() and max() in Python. Now go ahead and give them a try!