Text of peps.python.org › pep-0485 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 485 – A Function for testing approximate equality | peps.python.org

PEP 485 – A Function for testing approximate equality PEP 485 – A Function for testing approximate equality Author : Christopher Barker <PythonCHB at gmail.com> Status : Final Type : Standards Track Created : 20-Jan-2015 Python-Version : 3.5 Post-History : Resolution : Python-Dev message Table of Contents Abstract Rationale Existing Implementations Proposed Implementation Handling of non-finite numbers Non-float types Behavior near zero Implementation Relative Difference How much difference does it make?

Symmetry Which symmetric test? Large Tolerances Defaults Relative Tolerance Default Absolute tolerance default Expected Uses Inappropriate uses Other Approaches unittest.TestCase.assertAlmostEqual numpy isclose() Boost floating-point comparison Alternate Proposals A Recipe zero_tol No absolute tolerance Other tests References Copyright Abstract This PEP proposes the addition of an isclose() function to the standard library math module that determines whether one value is approximately equal or “close” to another value.

Rationale Floating point values contain limited precision, which results in their being unable to exactly represent some values, and for errors to accumulate with repeated computation. As a result, it is common advice to only use an equality comparison in very specific situations. Often an inequality comparison fits the bill, but there are times (often in testing) where the programmer wants to determine whether a computed value is “close” to an expected value, without requiring them to be exactly equal.

This is common enough, particularly in testing, and not always obvious how to do it, that it would be useful addition to the standard library. Existing Implementations The standard library includes the unittest.TestCase.assertAlmostEqual method, but it: Is buried in the unittest.TestCase class Is an assertion, so you can’t use it as a general test at the command line, etc. (easily) Is an absolute difference test. Often the measure of difference requires, particularly for floating point numbers, a relative error, i.e.

“Are these two values within x% of each-other?”, rather than an absolute error. Particularly when the magnitude of the values is unknown a priori. The numpy package has the allclose() and isclose() functions, but they are only available with numpy. The statistics package tests include an implementation, used for its unit tests. One can also find discussion and sample implementations on Stack Overflow and other help sites.

Many other non-python systems provide such a test, including the Boost C++ library and the APL language [4] . These existing implementations indicate that this is a common need and not trivial to write oneself, making it a candidate for the standard library. Proposed Implementation NOTE: this PEP is the result of extended discussions on the python-ideas list [1] . The new function will go into the math module, and have the following signature: isclose ( a , b , rel_tol = 1e-9 , abs_tol = 0.0 ) a and b : are the two values to be tested to relative closeness rel_tol : is the relative tolerance – it is the amount of error allowed, relative to the larger absolute value of a or b.

For example, to set a tolerance of 5%, pass tol=0.05. The default tolerance is 1e-9, which assures that the two values are the same within about 9 decimal digits. rel_tol must be greater than 0.0 abs_tol : is a minimum absolute tolerance level – useful for comparisons near zero. Modulo error checking, etc, the function will return the result of: abs ( a - b ) <= max ( rel_tol * max ( abs ( a ), abs ( b )), abs_tol ) The name, isclose , is selected for consistency with the existing isnan and isinf .

Handling of non-finite numbers The IEEE 754 special values of NaN, inf, and -inf will be handled according to IEEE rules. Specifically, NaN is not considered close to any other value, including NaN. inf and -inf are only considered close to themselves. Non-float types The primary use-case is expected to be floating point numbers. However, users may want to compare other numeric types similarly. In theory, it should work for any type that supports abs() , multiplication, comparisons, and subtraction.

However, the implementation in the math module is written in C, and thus can not (easily) use python’s duck typing. Rather, the values passed into the function will be converted to the float type before the calculation is performed. Passing in types (or values) that cannot be converted to floats will raise an appropriate Exception (TypeError, ValueError, or OverflowError). The code will be tested to accommodate at least some values of these types: Decimal int Fraction complex : For complex, a companion function will be added to the cmath module.

In cmath.isclose() , the tolerances are specified as floats, and the absolute value of the complex values will be used for scaling and comparison. If a complex tolerance is passed in, the absolute value will be used as the tolerance. NOTE: it may make sense to add a Decimal.isclose() that works properly and completely with the decimal type, but that is not included as part of this PEP. Behavior near zero Relative comparison is problematic if either value is zero.

By definition, no value is small relative to zero. And computationally, if either value is zero, the difference is the absolute value of the other value, and the computed absolute tolerance will be rel_tol times that value. When rel_tol is less than one, the difference will never be less than the tolerance. However, while mathematically correct, there are many use cases where a user will need to know if a computed value is “close” to zero.

This calls for an absolute tolerance test. If the user needs to call this function inside a loop or comprehension, where some, but not all, of the expected values may be zero, it is important that both a relative tolerance and absolute tolerance can be tested for with a single function with a single set of parameters. There is a similar issue if the two values to be compared straddle zero: if a is approximately equal to -b, then a and b will never be computed as “close”.

To handle this case, an optional parameter, abs_tol can be used to set a minimum tolerance used in the case of very small or zero computed relative tolerance. That is, the values will be always be considered close if the difference between them is less than abs_tol The default absolute tolerance value is set to zero because there is no value that is appropriate for the general case. It is impossible to know an appropriate value without knowing the likely values expected for a given use case.

If all the values tested are on order of one, then a value of about 1e-9 might be appropriate, but that would be far too large if expected values are on order of 1e-9 or smaller. Any non-zero default might result in user’s tests passing totally inappropriately. If, on the other hand, a test against zero fails the first time with defaults, a user will be prompted to select an appropriate value for the problem at hand in order to get the test to pass.

NOTE: that the author of this PEP has resolved to go back over many of his tests that use the numpy allclose() function, which provides a default absolute tolerance, and make sure that the default value is appropriate. If the user sets the rel_tol parameter to 0.0, then only the absolute tolerance will effect the result. While not the goal of the function, it does allow it to be used as a purely absolute tolerance check as well.

Implementation A sample implementation in python is available (as of Jan 22, 2015) on gitHub: https://github.com/PythonCHB/close_pep/blob/master/is_close.py This implementation has a flag that lets the user select which relative tolerance test to apply – this PEP does not suggest that that be retained, but rather that the weak test be selected. There are also drafts of this PEP and test code, etc. there: https://github.com/PythonCHB/close_pep Relati

The rest of this page is on the live site.