From 559449a27882a05182d0147fec4900dab4379fb9 Mon Sep 17 00:00:00 2001 From: Stefan Behnel Date: Thu, 11 Apr 2013 19:49:30 +0200 Subject: [PATCH] update docs on optimised builtins --HG-- extra : rebase_source : fb47cc7e0154abb172016f1945dad2968b3f2a3e --- docs/src/reference/language_basics.rst | 46 +++++++++++++++++++---------- docs/src/userguide/language_basics.rst | 54 +++++++++++++++++++--------------- 2 files changed, 60 insertions(+), 40 deletions(-) diff --git a/docs/src/reference/language_basics.rst b/docs/src/reference/language_basics.rst index 4ac4cda..6c6e1d1 100644 --- a/docs/src/reference/language_basics.rst +++ b/docs/src/reference/language_basics.rst @@ -572,43 +572,52 @@ Function Pointers * Functions declared in a ``struct`` are automatically converted to function pointers. * see **using exceptions with function pointers** + Python Built-ins ================ -The following are provided: +Cython compiles calls to most built-in functions into direct calls to +the corresponding Python/C API routines, making them particularly fast. -.. todo:: incomplete +Only direct function calls using these names are optimised. If you do +something else with one of these names that assumes it's a Python object, +such as assign it to a Python variable, and later call it, the call will +be made as a Python function call. +------------------------------+-------------+----------------------------+ | Function and arguments | Return type | Python/C API Equivalent | +==============================+=============+============================+ -| abs(obj) | object | PyNumber_Absolute | +| abs(obj) | object, | PyNumber_Absolute, fabs, | +| | double, ... | fabsf, ... | ++------------------------------+-------------+----------------------------+ +| callable(obj) | bint | PyObject_Callable | +------------------------------+-------------+----------------------------+ -| bool(obj) | object | Py_True, Py_False | +| delattr(obj, name) | None | PyObject_DelAttr | +------------------------------+-------------+----------------------------+ -| chr(obj) | object | char | +| exec(code, [glob, [loc]]) | object | - | +------------------------------+-------------+----------------------------+ -| delattr(obj, name) | int | PyObject_DelAttr | +| dir(obj) | list | PyObject_Dir | +------------------------------+-------------+----------------------------+ -| dir(obj) | object | PyObject_Dir | -| getattr(obj, name) (Note 1) | | | -| getattr3(obj, name, default) | | | +| divmod(a, b) | tuple | PyNumber_Divmod | +------------------------------+-------------+----------------------------+ -| hasattr(obj, name) | int | PyObject_HasAttr | +| getattr(obj, name, [default])| object | PyObject_GetAttr | +| (Note 1) | | | +------------------------------+-------------+----------------------------+ -| hash(obj) | int | PyObject_Hash | +| hasattr(obj, name) | bint | PyObject_HasAttr | +------------------------------+-------------+----------------------------+ -| intern(obj) | object | PyObject_InternFromString | +| hash(obj) | int / long | PyObject_Hash | +------------------------------+-------------+----------------------------+ -| isinstance(obj, type) | int | PyObject_IsInstance | +| intern(obj) | object | Py*_InternFromString | +------------------------------+-------------+----------------------------+ -| issubclass(obj, type) | int | PyObject_IsSubclass | +| isinstance(obj, type) | bint | PyObject_IsInstance | +------------------------------+-------------+----------------------------+ -| iter(obj) | object | PyObject_GetIter | +| issubclass(obj, type) | bint | PyObject_IsSubclass | ++------------------------------+-------------+----------------------------+ +| iter(obj, [sentinel]) | object | PyObject_GetIter | +------------------------------+-------------+----------------------------+ | len(obj) | Py_ssize_t | PyObject_Length | +------------------------------+-------------+----------------------------+ -| pow(x, y, z) (Note 2) | object | PyNumber_Power | +| pow(x, y, [z]) | object | PyNumber_Power | +------------------------------+-------------+----------------------------+ | reload(obj) | object | PyImport_ReloadModule | +------------------------------+-------------+----------------------------+ @@ -617,6 +626,11 @@ The following are provided: | setattr(obj, name) | void | PyObject_SetAttr | +------------------------------+-------------+----------------------------+ +Note 1: Pyrex originally provided a function :func:`getattr3(obj, name, default)` +corresponding to the three-argument form of the Python builtin :func:`getattr()`. +Cython still supports this function, but the usage is deprecated in favour of +the normal builtin, which Cython can optimise in both forms. + ============================ Error and Exception Handling diff --git a/docs/src/userguide/language_basics.rst b/docs/src/userguide/language_basics.rst index cc8cb91..06a324b 100644 --- a/docs/src/userguide/language_basics.rst +++ b/docs/src/userguide/language_basics.rst @@ -387,35 +387,48 @@ Python variable residing in the scope where it is assigned. Built-in Functions ------------------ -Cython compiles calls to the following built-in functions into direct calls to +Cython compiles calls to most built-in functions into direct calls to the corresponding Python/C API routines, making them particularly fast. +Only direct function calls using these names are optimised. If you do +something else with one of these names that assumes it's a Python object, +such as assign it to a Python variable, and later call it, the call will +be made as a Python function call. + +------------------------------+-------------+----------------------------+ | Function and arguments | Return type | Python/C API Equivalent | +==============================+=============+============================+ -| abs(obj) | object | PyNumber_Absolute | +| abs(obj) | object, | PyNumber_Absolute, fabs, | +| | double, ... | fabsf, ... | ++------------------------------+-------------+----------------------------+ +| callable(obj) | bint | PyObject_Callable | ++------------------------------+-------------+----------------------------+ +| delattr(obj, name) | None | PyObject_DelAttr | ++------------------------------+-------------+----------------------------+ +| exec(code, [glob, [loc]]) | object | - | +------------------------------+-------------+----------------------------+ -| delattr(obj, name) | int | PyObject_DelAttr | +| dir(obj) | list | PyObject_Dir | +------------------------------+-------------+----------------------------+ -| dir(obj) | object | PyObject_Dir | -| getattr(obj, name) (Note 1) | | | -| getattr3(obj, name, default) | | | +| divmod(a, b) | tuple | PyNumber_Divmod | +------------------------------+-------------+----------------------------+ -| hasattr(obj, name) | int | PyObject_HasAttr | +| getattr(obj, name, [default])| object | PyObject_GetAttr | +| (Note 1) | | | +------------------------------+-------------+----------------------------+ -| hash(obj) | int | PyObject_Hash | +| hasattr(obj, name) | bint | PyObject_HasAttr | +------------------------------+-------------+----------------------------+ -| intern(obj) | object | PyObject_InternFromString | +| hash(obj) | int / long | PyObject_Hash | +------------------------------+-------------+----------------------------+ -| isinstance(obj, type) | int | PyObject_IsInstance | +| intern(obj) | object | Py*_InternFromString | +------------------------------+-------------+----------------------------+ -| issubclass(obj, type) | int | PyObject_IsSubclass | +| isinstance(obj, type) | bint | PyObject_IsInstance | +------------------------------+-------------+----------------------------+ -| iter(obj) | object | PyObject_GetIter | +| issubclass(obj, type) | bint | PyObject_IsSubclass | ++------------------------------+-------------+----------------------------+ +| iter(obj, [sentinel]) | object | PyObject_GetIter | +------------------------------+-------------+----------------------------+ | len(obj) | Py_ssize_t | PyObject_Length | +------------------------------+-------------+----------------------------+ -| pow(x, y, z) (Note 2) | object | PyNumber_Power | +| pow(x, y, [z]) | object | PyNumber_Power | +------------------------------+-------------+----------------------------+ | reload(obj) | object | PyImport_ReloadModule | +------------------------------+-------------+----------------------------+ @@ -424,17 +437,10 @@ the corresponding Python/C API routines, making them particularly fast. | setattr(obj, name) | void | PyObject_SetAttr | +------------------------------+-------------+----------------------------+ -Note 1: There are two different functions corresponding to the Python -:func:`getattr` depending on whether a third argument is used. In a Python -context, they both evaluate to the Python :func:`getattr` function. - -Note 2: Only the three-argument form of :func:`pow` is supported. Use the -``**`` operator otherwise. - -Only direct function calls using these names are optimised. If you do -something else with one of these names that assumes it's a Python object, such -as assign it to a Python variable, and later call it, the call will be made as -a Python function call. +Note 1: Pyrex originally provided a function :func:`getattr3(obj, name, default)` +corresponding to the three-argument form of the Python builtin :func:`getattr()`. +Cython still supports this function, but the usage is deprecated in favour of +the normal builtin, which Cython can optimise in both forms. Operator Precedence -- 2.7.4