diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/utilities.rst | 45 | ||||
| -rw-r--r-- | Doc/library/functions.rst | 19 | ||||
| -rw-r--r-- | Doc/library/math.rst | 35 | ||||
| -rw-r--r-- | Doc/library/numbers.rst | 99 | ||||
| -rw-r--r-- | Doc/library/numeric.rst | 10 | ||||
| -rw-r--r-- | Doc/reference/datamodel.rst | 8 | ||||
| -rw-r--r-- | Doc/reference/expressions.rst | 3 |
7 files changed, 201 insertions, 18 deletions
diff --git a/Doc/c-api/utilities.rst b/Doc/c-api/utilities.rst index 18e2733..b9eb390 100644 --- a/Doc/c-api/utilities.rst +++ b/Doc/c-api/utilities.rst @@ -184,7 +184,8 @@ Importing Modules single: modules (in module sys) This is a simplified interface to :cfunc:`PyImport_ImportModuleEx` below, - leaving the *globals* and *locals* arguments set to *NULL*. When the *name* + leaving the *globals* and *locals* arguments set to *NULL* and *level* set + to 0. When the *name* argument contains a dot (when it specifies a submodule of a package), the *fromlist* argument is set to the list ``['*']`` so that the return value is the named module rather than the top-level package containing it as would otherwise @@ -196,6 +197,27 @@ Importing Modules to find out. Starting with Python 2.4, a failing import of a module no longer leaves the module in ``sys.modules``. + .. versionchanged:: 2.6 + always use absolute imports + + .. index:: single: modules (in module sys) + + +.. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name) + + .. index:: + single: `cfunc:PyImport_ImportModule` + + This version of `cfunc:PyImport_ImportModule` does not block. It's intended + to be used in C function which import other modules to execute a function. + The import may block if another thread holds the import lock. The function + `cfunc:PyImport_ImportModuleNoBlock` doesn't block. It first tries to fetch + the module from sys.modules and falls back to `cfunc:PyImport_ImportModule` + unless the the lock is hold. In the latter case the function raises an + ImportError. + + .. versionadded:: 2.6 + .. cfunction:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist) @@ -214,6 +236,24 @@ Importing Modules Failing imports remove incomplete module objects, like with :cfunc:`PyImport_ImportModule`. + .. versionchanged:: 2.6 + The function is an alias for `cfunc:PyImport_ImportModuleLevel` with + -1 as level, meaning relative import. + + +.. cfunction:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level) + + Import a module. This is best described by referring to the built-in Python + function :func:`__import__`, as the standard :func:`__import__` function calls + this function directly. + + The return value is a new reference to the imported module or top-level package, + or *NULL* with an exception set on failure. Like for :func:`__import__`, + the return value when a submodule of a package was requested is normally the + top-level package, unless a non-empty *fromlist* was given. + + ..versionadded:: 2.5 + .. cfunction:: PyObject* PyImport_Import(PyObject *name) @@ -222,6 +262,9 @@ Importing Modules current globals. This means that the import is done using whatever import hooks are installed in the current environment. + .. versionchanged:: 2.6 + always use absolute imports + .. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 49fd77d..48efff5 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -915,10 +915,13 @@ available. They are listed here in alphabetical order. .. function:: round(x[, n]) Return the floating point value *x* rounded to *n* digits after the decimal - point. If *n* is omitted, it defaults to zero. The result is a floating point - number. Values are rounded to the closest multiple of 10 to the power minus - *n*; if two multiples are equally close, rounding is done away from 0 (so. for - example, ``round(0.5)`` is ``1.0`` and ``round(-0.5)`` is ``-1.0``). + point. If *n* is omitted, it defaults to zero. Values are rounded to the + closest multiple of 10 to the power minus *n*; if two multiples are equally + close, rounding is done toward the even choice (so, for example, both + ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is + ``2``). Delegates to ``x.__round__(n)``. + + .. versionchanged:: 2.6 .. function:: set([iterable]) @@ -1064,6 +1067,14 @@ available. They are listed here in alphabetical order. operators such as ``super(C, self)[name]``. +.. function:: trunc(x) + + Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually + a long integer). Delegates to ``x.__trunc__()``. + + .. versionadded:: 2.6 + + .. function:: tuple([iterable]) Return a tuple whose items are the same and in the same order as *iterable*'s diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 7ea4aac..dc8c74a 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -26,8 +26,17 @@ Number-theoretic and representation functions: .. function:: ceil(x) - Return the ceiling of *x* as a float, the smallest integer value greater than or - equal to *x*. + Return the ceiling of *x* as a float, the smallest integer value greater than + or equal to *x*. If *x* is not a float, delegates to ``x.__ceil__()``, which + should return an :class:`Integral` value. + + +.. function:: copysign(x, y) + + Return *x* with the sign of *y*. ``copysign`` copies the sign bit of an IEEE + 754 float, ``copysign(1, -0.0)`` returns *-1.0*. + + ..versionadded:: 2.6 .. function:: fabs(x) @@ -37,8 +46,9 @@ Number-theoretic and representation functions: .. function:: floor(x) - Return the floor of *x* as a float, the largest integer value less than or equal - to *x*. + Return the floor of *x* as a float, the largest integer value less than or + equal to *x*. If *x* is not a float, delegates to ``x.__floor__()``, which + should return an :class:`Integral` value. .. function:: fmod(x, y) @@ -64,6 +74,23 @@ Number-theoretic and representation functions: apart" the internal representation of a float in a portable way. +.. function:: isinf(x) + + Checks if the float *x* is positive or negative infinite. + + ..versionadded:: 2.6 + + +.. function:: isnan(x) + + Checks if the float *x* is a NaN (not a number). NaNs are part of the + IEEE 754 standards. Operation like but not limited to ``inf * 0``, + ``inf / inf`` or any operation involving a NaN, e.g. ``nan * 1``, return + a NaN. + + ..versionadded:: 2.6 + + .. function:: ldexp(x, i) Return ``x * (2**i)``. This is essentially the inverse of function diff --git a/Doc/library/numbers.rst b/Doc/library/numbers.rst new file mode 100644 index 0000000..d0f9c3b --- /dev/null +++ b/Doc/library/numbers.rst @@ -0,0 +1,99 @@ + +:mod:`numbers` --- Numeric abstract base classes +================================================ + +.. module:: numbers + :synopsis: Numeric abstract base classes (Complex, Real, Integral, etc.). + +The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric abstract +base classes which progressively define more operations. These concepts also +provide a way to distinguish exact from inexact types. None of the types defined +in this module can be instantiated. + + +.. class:: Number + + The root of the numeric hierarchy. If you just want to check if an argument + *x* is a number, without caring what kind, use ``isinstance(x, Number)``. + + +Exact and inexact operations +---------------------------- + +.. class:: Exact + + Subclasses of this type have exact operations. + + As long as the result of a homogenous operation is of the same type, you can + assume that it was computed exactly, and there are no round-off errors. Laws + like commutativity and associativity hold. + + +.. class:: Inexact + + Subclasses of this type have inexact operations. + + Given X, an instance of :class:`Inexact`, it is possible that ``(X + -X) + 3 + == 3``, but ``X + (-X + 3) == 0``. The exact form this error takes will vary + by type, but it's generally unsafe to compare this type for equality. + + +The numeric tower +----------------- + +.. class:: Complex + + Subclasses of this type describe complex numbers and include the operations + that work on the builtin :class:`complex` type. These are: conversions to + :class:`complex` and :class:`bool`, :attr:`.real`, :attr:`.imag`, ``+``, + ``-``, ``*``, ``/``, :func:`abs`, :meth:`conjugate`, ``==``, and ``!=``. All + except ``-`` and ``!=`` are abstract. + +.. attribute:: Complex.real + + Abstract. Retrieves the :class:`Real` component of this number. + +.. attribute:: Complex.imag + + Abstract. Retrieves the :class:`Real` component of this number. + +.. method:: Complex.conjugate() + + Abstract. Returns the complex conjugate. For example, ``(1+3j).conjugate() == + (1-3j)``. + +.. class:: Real + + To :class:`Complex`, :class:`Real` adds the operations that work on real + numbers. + + In short, those are: a conversion to :class:`float`, :func:`trunc`, + :func:`round`, :func:`math.floor`, :func:`math.ceil`, :func:`divmod`, ``//``, + ``%``, ``<``, ``<=``, ``>``, and ``>=``. + + Real also provides defaults for :func:`complex`, :attr:`Complex.real`, + :attr:`Complex.imag`, and :meth:`Complex.conjugate`. + + +.. class:: Rational + + Subtypes both :class:`Real` and :class:`Exact`, and adds + :attr:`Rational.numerator` and :attr:`Rational.denominator` properties, which + should be in lowest terms. With these, it provides a default for + :func:`float`. + +.. attribute:: Rational.numerator + + Abstract. + +.. attribute:: Rational.denominator + + Abstract. + + +.. class:: Integral + + Subtypes :class:`Rational` and adds a conversion to :class:`long`, the + 3-argument form of :func:`pow`, and the bit-string operations: ``<<``, + ``>>``, ``&``, ``^``, ``|``, ``~``. Provides defaults for :func:`float`, + :attr:`Rational.numerator`, and :attr:`Rational.denominator`. diff --git a/Doc/library/numeric.rst b/Doc/library/numeric.rst index 0d9d59f..d2b4d8b 100644 --- a/Doc/library/numeric.rst +++ b/Doc/library/numeric.rst @@ -6,16 +6,18 @@ Numeric and Mathematical Modules ******************************** The modules described in this chapter provide numeric and math-related functions -and data types. The :mod:`math` and :mod:`cmath` contain various mathematical -functions for floating-point and complex numbers. For users more interested in -decimal accuracy than in speed, the :mod:`decimal` module supports exact -representations of decimal numbers. +and data types. The :mod:`numbers` module defines an abstract hierarchy of +numeric types. The :mod:`math` and :mod:`cmath` modules contain various +mathematical functions for floating-point and complex numbers. For users more +interested in decimal accuracy than in speed, the :mod:`decimal` module supports +exact representations of decimal numbers. The following modules are documented in this chapter: .. toctree:: + numbers.rst math.rst cmath.rst decimal.rst diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 0ec255f..3c7f8e6 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -152,7 +152,7 @@ Ellipsis object is accessed through the literal ``...`` or the built-in name ``Ellipsis``. Its truth value is true. -Numbers +:class:`numbers.Number` .. index:: object: numeric These are created by numeric literals and returned as results by arithmetic @@ -164,7 +164,7 @@ Numbers Python distinguishes between integers, floating point numbers, and complex numbers: - Integers + :class:`numbers.Integral` .. index:: object: integer These represent elements from the mathematical set of integers (positive and @@ -202,7 +202,7 @@ Numbers operation except left shift, if it yields a result in the plain integer domain without causing overflow, will yield the same result when using mixed operands. - Floating point numbers + :class:`numbers.Real` (:class:`float`) .. index:: object: floating point pair: floating point; number @@ -217,7 +217,7 @@ Numbers overhead of using objects in Python, so there is no reason to complicate the language with two kinds of floating point numbers. - Complex numbers + :class:`numbers.Complex` .. index:: object: complex pair: complex; number diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 6e160ee..cf95636 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -768,7 +768,8 @@ float result is delivered. For example, ``10**2`` returns ``100``, but ``10**-2`` returns ``0.01``. Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`. -Raising a negative number to a fractional power results in a :exc:`ValueError`. +Raising a negative number to a fractional power results in a :class:`complex` +number. (Since Python 2.6. In earlier versions it raised a :exc:`ValueError`.) .. _unary: |