Commit 81212165 authored by Stefan Behnel's avatar Stefan Behnel

Minor doc cleanups.

parent b859cf2b
...@@ -12,8 +12,8 @@ Python classes exactly as in Python: ...@@ -12,8 +12,8 @@ Python classes exactly as in Python:
Based on what Python calls a "built-in type", however, Cython supports Based on what Python calls a "built-in type", however, Cython supports
a second kind of class: *extension types*, sometimes referred to as a second kind of class: *extension types*, sometimes referred to as
"cdef classes" due to the keywords used for their declaration. They "cdef classes" due to the Cython language keywords used for their declaration.
are somewhat restricted compared to Python classes, but are generally They are somewhat restricted compared to Python classes, but are generally
more memory efficient and faster than generic Python classes. The more memory efficient and faster than generic Python classes. The
main difference is that they use a C struct to store their fields and methods main difference is that they use a C struct to store their fields and methods
instead of a Python dict. This allows them to store arbitrary C types instead of a Python dict. This allows them to store arbitrary C types
...@@ -42,8 +42,9 @@ integrates a single hard-coded function. In order to remedy this, ...@@ -42,8 +42,9 @@ integrates a single hard-coded function. In order to remedy this,
with hardly sacrificing speed, we will use a cdef class to represent a with hardly sacrificing speed, we will use a cdef class to represent a
function on floating point numbers: function on floating point numbers:
The directive cpdef makes two versions of the method available; one The ``cpdef`` command (or ``@cython.ccall`` in Python syntax) makes two versions
fast for use from Cython and one slower for use from Python. Then: of the method available; one fast for use from Cython and one slower for use
from Python. Then:
.. tabs:: .. tabs::
.. group-tab:: Pure Python .. group-tab:: Pure Python
...@@ -58,7 +59,7 @@ fast for use from Cython and one slower for use from Python. Then: ...@@ -58,7 +59,7 @@ fast for use from Cython and one slower for use from Python. Then:
This does slightly more than providing a python wrapper for a cdef This does slightly more than providing a python wrapper for a cdef
method: unlike a cdef method, a cpdef method is fully overridable by method: unlike a cdef method, a cpdef method is fully overridable by
methods and instance attributes in Python subclasses. It adds a methods and instance attributes in Python subclasses. This adds a
little calling overhead compared to a cdef method. little calling overhead compared to a cdef method.
To make the class definitions visible to other modules, and thus allow for To make the class definitions visible to other modules, and thus allow for
......
...@@ -14,6 +14,7 @@ Language Basics ...@@ -14,6 +14,7 @@ Language Basics
.. include:: .. include::
../two-syntax-variants-used ../two-syntax-variants-used
.. _declaring_data_types: .. _declaring_data_types:
Declaring Data Types Declaring Data Types
...@@ -237,6 +238,7 @@ Here is a simple example: ...@@ -237,6 +238,7 @@ Here is a simple example:
You can read more about them in :ref:`extension-types`. You can read more about them in :ref:`extension-types`.
.. _typing_types: .. _typing_types:
.. _types: .. _types:
...@@ -362,7 +364,8 @@ Within a Cython module, Python functions and C functions can call each other ...@@ -362,7 +364,8 @@ Within a Cython module, Python functions and C functions can call each other
freely, but only Python functions can be called from outside the module by freely, but only Python functions can be called from outside the module by
interpreted Python code. So, any functions that you want to "export" from your interpreted Python code. So, any functions that you want to "export" from your
Cython module must be declared as Python functions using ``def``. Cython module must be declared as Python functions using ``def``.
There is also a hybrid function, declared with :keyword:`cpdef` in ``.pyx`` files or with the ``@ccall`` decorator. These functions There is also a hybrid function, declared with :keyword:`cpdef` in ``.pyx``
files or with the ``@ccall`` decorator. These functions
can be called from anywhere, but use the faster C calling convention can be called from anywhere, but use the faster C calling convention
when being called from other Cython code. They can also be overridden when being called from other Cython code. They can also be overridden
by a Python method on a subclass or an instance attribute, even when called from Cython. by a Python method on a subclass or an instance attribute, even when called from Cython.
...@@ -396,6 +399,7 @@ using normal C declaration syntax. For example, ...@@ -396,6 +399,7 @@ using normal C declaration syntax. For example,
cdef int eggs(unsigned long l, float f): cdef int eggs(unsigned long l, float f):
... ...
``ctuples`` may also be used ``ctuples`` may also be used
.. tabs:: .. tabs::
...@@ -461,12 +465,13 @@ In the case of non-Python object return types, the equivalent of zero is returne ...@@ -461,12 +465,13 @@ In the case of non-Python object return types, the equivalent of zero is returne
A more complete comparison of the pros and cons of these different method A more complete comparison of the pros and cons of these different method
types can be found at :ref:`early-binding-for-speed`. types can be found at :ref:`early-binding-for-speed`.
Python objects as parameters and return values Python objects as parameters and return values
---------------------------------------------- ----------------------------------------------
If no type is specified for a parameter or return value, it is assumed to be a If no type is specified for a parameter or return value, it is assumed to be a
Python object. (Note that this is different from the C convention, where it Python object. (Note that this is different from the C convention, where it
would default to int.) For example, the following defines a C function that would default to ``int``.) For example, the following defines a C function that
takes two Python objects as parameters and returns a Python object takes two Python objects as parameters and returns a Python object
.. tabs:: .. tabs::
...@@ -495,8 +500,7 @@ parameters and a new reference is returned). ...@@ -495,8 +500,7 @@ parameters and a new reference is returned).
This only applies to Cython code. Other Python packages which This only applies to Cython code. Other Python packages which
are implemented in C like NumPy may not follow these conventions. are implemented in C like NumPy may not follow these conventions.
The type name ``object`` can also be used to explicitly declare something as a Python
The name object can also be used to explicitly declare something as a Python
object. This can be useful if the name being declared would otherwise be taken object. This can be useful if the name being declared would otherwise be taken
as the name of a type, for example, as the name of a type, for example,
...@@ -517,8 +521,8 @@ as the name of a type, for example, ...@@ -517,8 +521,8 @@ as the name of a type, for example,
cdef ftang(object int): cdef ftang(object int):
... ...
declares a parameter called ``int`` which is a Python object. You can also use declares a parameter called ``int`` which is a Python object. You can also use
object as the explicit return type of a function, e.g. ``object`` as the explicit return type of a function, e.g.
.. tabs:: .. tabs::
...@@ -560,6 +564,7 @@ will display:: ...@@ -560,6 +564,7 @@ will display::
Inside owned_reference: 3 Inside owned_reference: 3
Inside borrowed_reference: 2 Inside borrowed_reference: 2
.. _optional_arguments: .. _optional_arguments:
Optional Arguments Optional Arguments
...@@ -625,6 +630,7 @@ terminate the list of positional arguments: ...@@ -625,6 +630,7 @@ terminate the list of positional arguments:
Shown above, the signature takes exactly two positional Shown above, the signature takes exactly two positional
parameters and has two required keyword parameters. parameters and has two required keyword parameters.
Function Pointers Function Pointers
----------------- -----------------
...@@ -633,6 +639,7 @@ Functions declared in a ``struct`` are automatically converted to function point ...@@ -633,6 +639,7 @@ Functions declared in a ``struct`` are automatically converted to function point
For using error return values with function pointers, see the note at the bottom For using error return values with function pointers, see the note at the bottom
of :ref:`error_return_values`. of :ref:`error_return_values`.
.. _error_return_values: .. _error_return_values:
Error return values Error return values
...@@ -803,6 +810,7 @@ return value and raise it yourself, for example: ...@@ -803,6 +810,7 @@ return value and raise it yourself, for example:
.. literalinclude:: ../../examples/userguide/language_basics/open_file.pyx .. literalinclude:: ../../examples/userguide/language_basics/open_file.pyx
.. _overriding_in_extension_types: .. _overriding_in_extension_types:
Overriding in extension types Overriding in extension types
...@@ -951,6 +959,7 @@ Sometimes Cython will complain unnecessarily, and sometimes it will fail to ...@@ -951,6 +959,7 @@ Sometimes Cython will complain unnecessarily, and sometimes it will fail to
detect a problem that exists. Ultimately, you need to understand the issue and detect a problem that exists. Ultimately, you need to understand the issue and
be careful what you do. be careful what you do.
.. _type_casting: .. _type_casting:
Type Casting Type Casting
...@@ -1033,6 +1042,7 @@ Cython uses ``"<"`` and ``">"``. In pure python mode, the ``cython.cast()`` fun ...@@ -1033,6 +1042,7 @@ Cython uses ``"<"`` and ``">"``. In pure python mode, the ``cython.cast()`` fun
perform a ``Py_INCREF`` and ``Py_DECREF`` operation. Casting to perform a ``Py_INCREF`` and ``Py_DECREF`` operation. Casting to
``<PyObject *>`` creates a borrowed reference, leaving the refcount unchanged. ``<PyObject *>`` creates a borrowed reference, leaving the refcount unchanged.
.. _checked_type_casts: .. _checked_type_casts:
Checked Type Casts Checked Type Casts
...@@ -1048,6 +1058,7 @@ if ``x`` is not an instance of ``MyExtensionType``. ...@@ -1048,6 +1058,7 @@ if ``x`` is not an instance of ``MyExtensionType``.
This tests for the exact class for builtin types, This tests for the exact class for builtin types,
but allows subclasses for :ref:`extension-types`. but allows subclasses for :ref:`extension-types`.
.. _statements_and_expressions: .. _statements_and_expressions:
Statements and expressions Statements and expressions
...@@ -1065,6 +1076,7 @@ Reference counts are maintained automatically for all Python objects, and all ...@@ -1065,6 +1076,7 @@ Reference counts are maintained automatically for all Python objects, and all
Python operations are automatically checked for errors, with appropriate Python operations are automatically checked for errors, with appropriate
action taken. action taken.
Differences between C and Cython expressions Differences between C and Cython expressions
-------------------------------------------- --------------------------------------------
...@@ -1106,6 +1118,7 @@ direct equivalent in Python. ...@@ -1106,6 +1118,7 @@ direct equivalent in Python.
p = <char*>q p = <char*>q
Scope rules Scope rules
----------- -----------
...@@ -1116,6 +1129,7 @@ variable residing in the scope where it is assigned. The type of the variable ...@@ -1116,6 +1129,7 @@ variable residing in the scope where it is assigned. The type of the variable
depends on type inference, except for the global module scope, where it is depends on type inference, except for the global module scope, where it is
always a Python object. always a Python object.
.. _built_in_functions: .. _built_in_functions:
Built-in Functions Built-in Functions
...@@ -1183,6 +1197,7 @@ Operator Precedence ...@@ -1183,6 +1197,7 @@ Operator Precedence
Keep in mind that there are some differences in operator precedence between Keep in mind that there are some differences in operator precedence between
Python and C, and that Cython uses the Python precedences, not the C ones. Python and C, and that Cython uses the Python precedences, not the C ones.
Integer for-loops Integer for-loops
------------------ ------------------
...@@ -1229,6 +1244,7 @@ Some things to note about the for-from loop: ...@@ -1229,6 +1244,7 @@ Some things to note about the for-from loop:
Like other Python looping statements, break and continue may be used in the Like other Python looping statements, break and continue may be used in the
body, and the loop may have an else clause. body, and the loop may have an else clause.
.. _cython_file_types: .. _cython_file_types:
Cython file types Cython file types
...@@ -1240,6 +1256,7 @@ There are three file types in Cython: ...@@ -1240,6 +1256,7 @@ There are three file types in Cython:
* The definition files, carrying a ``.pxd`` suffix. * The definition files, carrying a ``.pxd`` suffix.
* The include files, carrying a ``.pxi`` suffix. * The include files, carrying a ``.pxi`` suffix.
The implementation file The implementation file
----------------------- -----------------------
...@@ -1328,6 +1345,7 @@ of functions or class bodies. ...@@ -1328,6 +1345,7 @@ of functions or class bodies.
separate parts that may be more appropriate in many cases. See separate parts that may be more appropriate in many cases. See
:ref:`sharing-declarations`. :ref:`sharing-declarations`.
.. _conditional_compilation: .. _conditional_compilation:
Conditional Compilation Conditional Compilation
...@@ -1348,6 +1366,7 @@ constants within a Cython source file. ...@@ -1348,6 +1366,7 @@ constants within a Cython source file.
Cython currently does not support conditional compilation and compile-time Cython currently does not support conditional compilation and compile-time
definitions in Pure Python mode. As it stands, this is unlikely to change. definitions in Pure Python mode. As it stands, this is unlikely to change.
Compile-Time Definitions Compile-Time Definitions
------------------------ ------------------------
...@@ -1386,6 +1405,7 @@ expression must evaluate to a Python value of type ``int``, ``long``, ...@@ -1386,6 +1405,7 @@ expression must evaluate to a Python value of type ``int``, ``long``,
.. literalinclude:: ../../examples/userguide/language_basics/compile_time.pyx .. literalinclude:: ../../examples/userguide/language_basics/compile_time.pyx
Conditional Statements Conditional Statements
---------------------- ----------------------
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment