From 2e83f128d457556349fde44318663346a8316843 Mon Sep 17 00:00:00 2001 From: "ggellner@encolpuis" Date: Sat, 27 Sep 2008 19:28:49 -0400 Subject: [PATCH] Fixed heading levels. Added some Cython branding! --- _static/cythonlogo.png | Bin 0 -> 4625 bytes conf.py | 8 ++++- docs/early_binding_for_speed.rst | 7 ++-- docs/extension_types.rst | 27 +++++++++------- docs/external_C_code.rst | 35 +++++++++++--------- docs/language_basics.rst | 13 ++++---- docs/limitations.rst | 2 +- docs/numpy_tutorial.rst | 4 ++- docs/overview.rst | 6 ++-- docs/pyrex_differences.rst | 41 +++++++++++------------ docs/sharing_declarations.rst | 13 ++++---- docs/source_files_and_compilation.rst | 31 +++++++++++++++--- docs/tutorial.rst | 13 ++++---- docs/wrapping_CPlusPlus.rst | 45 +++++++++++++------------- index.rst | 7 ++-- 15 files changed, 145 insertions(+), 107 deletions(-) create mode 100644 _static/cythonlogo.png diff --git a/_static/cythonlogo.png b/_static/cythonlogo.png new file mode 100644 index 0000000000000000000000000000000000000000..2b4ee54ce55100ca8e20c7b02e3cd32c88dfe4f5 GIT binary patch literal 4625 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 Hu0mjfdEMKv literal 0 HcmV?d00001 diff --git a/conf.py b/conf.py index 77e05fa3..1a0ea082 100644 --- a/conf.py +++ b/conf.py @@ -87,12 +87,18 @@ html_style = 'default.css' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['.static'] +html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. html_last_updated_fmt = '%b %d, %Y' +# Include the Cython logo in the sidebar +html_logo = '_static/cythonlogo.png' + +# used a favicon! +html_favicon = '_static/favicon.ico' + # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True diff --git a/docs/early_binding_for_speed.rst b/docs/early_binding_for_speed.rst index 53a00a07..07e0047a 100644 --- a/docs/early_binding_for_speed.rst +++ b/docs/early_binding_for_speed.rst @@ -1,9 +1,10 @@ .. highlight:: cython -.. _early-binding-speed-label: +.. _early-binding-for-speed: +************************** Early Binding for Speed -======================= +************************** As a dynamic language, Python encourages a programming style of considering classes and objects in terms of their methods and attributes, more than where @@ -98,7 +99,7 @@ overheads. Consider this code: rect = Rectangle(x0, y0, x1, y1) return rect.area() -.. Note:: +.. note:: in earlier versions of Cython, the :keyword:`cpdef` keyword is :keyword:`rdef` - but has the same effect). diff --git a/docs/extension_types.rst b/docs/extension_types.rst index 75ee4427..5ac7f75c 100644 --- a/docs/extension_types.rst +++ b/docs/extension_types.rst @@ -1,10 +1,13 @@ .. highlight:: cython +.. _extension-types: + +****************** Extension Types -=============== +****************** Introduction -------------- +============== As well as creating normal user-defined classes with the Python class statement, Cython also lets you create new built-in Python types, known as @@ -35,7 +38,7 @@ extension types to wrap arbitrary C data structures and provide a Python-like interface to them. Attributes ------------ +============ Attributes of an extension type are stored directly in the object's C struct. The set of attributes is fixed at compile time; you can't add attributes to an @@ -75,7 +78,7 @@ and the depth attribute readable but not writable. are always readable and writable by direct access. Type declarations ------------------ +=================== Before you can directly access the attributes of an extension type, the Cython compiler must know that you have an instance of that type, and not just a @@ -112,7 +115,7 @@ The same consideration applies to local variables, for example,:: return sh2 Extension types and None ------------------------- +========================= When you declare a parameter or C variable as being of an extension type, Cython will allow it to take on the value ``None`` as well as values of its @@ -171,7 +174,7 @@ with checking that it has the right type. will invoke Python operations and therefore be much slower. Special methods ---------------- +================ Although the principles are similar, there are substantial differences between many of the :meth:`__xxx__` special methods of extension types and their Python @@ -180,7 +183,7 @@ read it carefully before attempting to use any special methods in your extension types. Properties ----------- +============ There is a special syntax for defining properties in an extension class:: @@ -251,7 +254,7 @@ when it is deleted.:: We don't have: [] Subclassing ------------ +============= An extension type may inherit from a built-in type or another extension type:: @@ -316,7 +319,7 @@ method using the usual Python technique, i.e.:: Parrot.describe(self) Forward-declaring extension types ---------------------------------- +=================================== Extension types can be forward-declared, like :keyword:`struct` and :keyword:`union` types. This will be necessary if you have two extension types @@ -342,7 +345,7 @@ definition, for example,:: # attributes and methods Making extension types weak-referenceable ------------------------------------------ +========================================== By default, extension types do not support having weak references made to them. You can enable weak referencing by declaring a C attribute of type @@ -355,7 +358,7 @@ object called :attr:`__weakref__`. For example,:: cdef object __weakref__ Public and external extension types ------------------------------------ +==================================== Extension types can be declared extern or public. An extern extension type declaration makes an extension type defined in external C code available to a @@ -373,7 +376,7 @@ objects defined in the Python core or in a non-Cython extension module. In Pyrex versions before 0.8, extern extension types were also used to reference extension types defined in another Pyrex module. While you can still do that, Cython provides a better mechanism for this. See - :ref:`sharing-declarations-label`. + :ref:`sharing-declarations`. Here is an example which will let you get at the C-level members of the built-in complex object.:: diff --git a/docs/external_C_code.rst b/docs/external_C_code.rst index fdfdaeef..9e0ac729 100644 --- a/docs/external_C_code.rst +++ b/docs/external_C_code.rst @@ -1,7 +1,10 @@ .. highlight:: cython +.. external-C-code: + +********************************** Interfacing with External C Code -================================ +********************************** One of the main uses of Cython is wrapping existing libraries of C code. This is achieved by using external declarations to declare the C functions and @@ -15,7 +18,7 @@ Cython module can be used as a bridge to allow Python code to call C code, it can also be used to allow C code to call Python code. External declarations ---------------------- +======================= By default, C functions and variables declared at the module level are local to the module (i.e. they have the C static storage class). They can also be @@ -26,7 +29,7 @@ declared extern to specify that they are defined elsewhere, for example:: cdef extern void order_spam(int tons) Referencing C header files -^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------- When you use an extern definition on its own as in the examples above, Cython includes a declaration for it in the generated C file. This can cause problems @@ -143,7 +146,7 @@ A few more tricks and tips: ... Styles of struct, union and enum declaration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------------------------- There are two main ways that structs, unions and enums can be declared in C header files: using a tag name, or using a typedef. There are also some @@ -198,7 +201,7 @@ Note that in all the cases below, you refer to the type in Cython code simply as :ctype:`Foo`, not ``struct Foo``. Accessing Python/C API routines -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------------- One particular use of the ``cdef extern from`` statement is for gaining access to routines in the Python/C API. For example,:: @@ -210,14 +213,14 @@ routines in the Python/C API. For example,:: will allow you to create Python strings containing null bytes. Special Types -^^^^^^^^^^^^^ +-------------- Cython predefines the name ``Py_ssize_t`` for use with Python/C API routines. To make your extensions compatible with 64-bit systems, you should always use this type where it is specified in the documentation of Python/C API routines. Windows Calling Conventions -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------- The ``__stdcall`` and ``__cdecl`` calling convention specifiers can be used in Cython, with the same syntax as used by C compilers on Windows, for example,:: @@ -230,7 +233,7 @@ If ``__stdcall`` is used, the function is only considered compatible with other ``__stdcall`` functions of the same signature. Resolving naming conflicts - C name specifications -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------------------------------- Each Cython module has a single module-level namespace for both Python and C names. This can be inconvenient if you want to wrap some external C functions @@ -274,7 +277,7 @@ enums, struct and union members, and enum values. For example,:: second "beta" = 3 Using Cython Declarations from C --------------------------------- +================================== Cython provides two methods for making C declarations from a Cython module available for use by external C code – public declarations and C API @@ -287,7 +290,7 @@ declarations. :keyword:`cimport` statement for that. Sharing Declarations Between Cython Modules. Public Declarations -^^^^^^^^^^^^^^^^^^^ +--------------------- You can make C types, variables and functions defined in a Cython module accessible to C code that is linked with the module, by declaring them with @@ -313,7 +316,7 @@ file consists of the full dotted name of the module, e.g. a module called :mod:`foo.spam` would have a header file called :file:`foo.spam.h`. C API Declarations -^^^^^^^^^^^^^^^^^^ +------------------- The other way of making declarations available to C code is to declare them with the :keyword:`api` keyword. You can use this keyword with C functions and @@ -381,8 +384,8 @@ E.g. a module called :mod:`foo.spam` would have an API header file called :file:`foo.spam_api.h` and an importing function called :func:`import_foo__spam`. -Multiple public and api declarations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Multiple public and API declarations +-------------------------------------- You can declare a whole group of items as :keyword:`public` and/or :keyword:`api` all at once by enclosing them in a :keyword:`cdef` block, for @@ -393,11 +396,11 @@ example,:: char *get_lunch(float tomato_size) This can be a useful thing to do in a ``.pxd`` file (see -:ref:`sharing-declarations-label`) to make the module's public interface +:ref:`sharing-declarations`) to make the module's public interface available by all three methods. Acquiring and Releasing the GIL -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------------- Cython provides facilities for releasing the Global Interpreter Lock (GIL) before calling C code, and for acquiring the GIL in functions that are to be @@ -428,7 +431,7 @@ header:: ... Declaring a function as callable without the GIL -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------------------------- You can specify :keyword:`nogil` in a C function header or function type to declare that it is safe to call without the GIL.:: diff --git a/docs/language_basics.rst b/docs/language_basics.rst index 85ee148b..12348fdc 100644 --- a/docs/language_basics.rst +++ b/docs/language_basics.rst @@ -1,12 +1,13 @@ .. highlight:: cython -.. _language-basics-label: +.. _language-basics: +***************** Language Basics -=============== +***************** Python functions vs. C functions --------------------------------- +================================== There are two kinds of function definition in Cython: @@ -123,7 +124,7 @@ an anonymous :keyword:`enum` declaration for this purpose, for example,:: ctypedef int *IntPtr Grouping multiple C declarations -================================ +================================== If you have a series of declarations that all begin with :keyword:`cdef`, you can group them into a :keyword:`cdef` block like this:: @@ -422,7 +423,7 @@ The include statement ---------------------- .. warning:: - This feature is deprecated. Use :ref:`sharing-declarations-label` instead. + This feature is deprecated. Use :ref:`sharing-declarations` instead. A Cython source file can include material from other files using the include statement, for example:: @@ -440,7 +441,7 @@ the level of the include statement that is including the file. There are other mechanisms available for splitting Cython code into separate parts that may be more appropriate in many cases. See - :ref:`sharing-declarations-label`. + :ref:`sharing-declarations`. Keyword-only arguments ---------------------- diff --git a/docs/limitations.rst b/docs/limitations.rst index a4f82eea..bd537f19 100644 --- a/docs/limitations.rst +++ b/docs/limitations.rst @@ -1,6 +1,6 @@ .. highlight:: cython -.. _cython-limitations-label: +.. _cython-limitations: ************* Limitations diff --git a/docs/numpy_tutorial.rst b/docs/numpy_tutorial.rst index 02e26d62..1721b896 100644 --- a/docs/numpy_tutorial.rst +++ b/docs/numpy_tutorial.rst @@ -1,6 +1,6 @@ .. highlight:: cython -.. _numpy_tute-label: +.. _numpy_tutorial: ************************** Cython for NumPy users @@ -34,6 +34,7 @@ The style of this tutorial will not fit everybody, so you can also consider: Cython at a glance ==================== + Cython is a compiler which compiles Python-like code files to C code. Still, ''Cython is not a Python to C translator''. That is, it doesn't take your full program and "turns it into C" -- rather, the result makes full use of the @@ -56,6 +57,7 @@ functions and generator functions). Your Cython environment ======================== + Using Cython consists of these steps: 1. Write a :file:`.pyx` source file diff --git a/docs/overview.rst b/docs/overview.rst index 0dc43801..6e2a6dbf 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -1,6 +1,6 @@ .. highlight:: cython -.. _overview-label: +.. _overview: ******** Overview @@ -24,9 +24,9 @@ and for fast C modules that speed up the execution of Python code. Future Plans ============ Cython is not finished. Substantial tasks remaining. See -:ref:`cython-limitations-label` for a current list. +:ref:`cython-limitations` for a current list. .. rubric:: Footnotes -.. [#] For differences with Pyrex see :ref:`pyrex-differences-label`. +.. [#] For differences with Pyrex see :ref:`pyrex-differences`. diff --git a/docs/pyrex_differences.rst b/docs/pyrex_differences.rst index 2478b5ff..e07052a3 100644 --- a/docs/pyrex_differences.rst +++ b/docs/pyrex_differences.rst @@ -1,17 +1,18 @@ .. highlight:: cython -.. _pyrex-differences-label: +.. _pyrex-differences: +************************************** Differences between Cython and Pyrex -==================================== +************************************** Package names and cross-directory imports ------------------------------------------ +========================================== Just like in python. List Comprehensions -------------------- +==================== `[expr(x) for x in A]` is now available, implementing the full specification at http://www.python.org/dev/peps/pep-0202/ . Looping is optimized if ``A`` is @@ -20,7 +21,7 @@ a list. Also, use the :keyword:`for` ... :keyword:`from` syntax too, e.g.:: [i*i for i from 0 <= i < 10] Conditional expressions "x if b else y" (python 2.5) ----------------------------------------------------- +===================================================== Conditional expressions as described in http://www.python.org/dev/peps/pep-0308/:: @@ -30,7 +31,7 @@ http://www.python.org/dev/peps/pep-0308/:: Only one of ``X`` and ``Y`` is evaluated, (depending on the value of C). cdef inline ------------ +============= Module level functions can now be declared inline, with the :keyword:`inline` keyword passed on to the C compiler. These can be as fast as macros.:: @@ -43,7 +44,7 @@ function table, so the compiler won't be able to inline them in almost all cases. Assignment on declaration (e.g. "cdef int spam = 5") ----------------------------------------------------- +====================================================== In Pyrex, one must write:: @@ -62,7 +63,7 @@ The expression on the right hand side can be arbitrarily complicated, e.g.:: 'by' expression in for loop (e.g. "for i from 0 <= i < 10 by 2") ----------------------------------------------------------------- +================================================================== :: @@ -82,7 +83,7 @@ yields:: Boolean int type (e.g. it acts like a c int, but coerces to/from python as a boolean) -------------------------------------------------------------------------------------- +====================================================================================== In C, ints are used for truth values. In python, any object can be used as a truth value (using the :meth:`__nonzero__` method, but the canonical choices @@ -107,7 +108,7 @@ happen via ``x.__nonzero__()``. (Actually, if ``x`` is the python object ``True`` or ``False`` then no method call is made.) Executable class bodies ------------------------ +========================= Including a working :func:`classmethod`:: @@ -119,7 +120,7 @@ Including a working :func:`classmethod`:: print "hi", a cpdef functions ---------------- +================= Cython adds a third function type on top of the usual :keyword:`def` and :keyword:`cdef`. If a function is declared :keyword:`cpdef` it can be called @@ -154,12 +155,12 @@ method on the class directly, e.g.:: x.foo() # will check to see if overridden A.foo(x) # will call A's implementation whether overridden or not -See :ref:`early-binding-speed-label` for explanation and usage tips. +See :ref:`early-binding-for-speed` for explanation and usage tips. .. _automatic-range-conversion: Automatic range conversion -------------------------------------- +============================ This will convert statements of the form ``for i in range(...)`` to ``for i from ...`` when ``i`` is any cdef'd integer type, and the direction (i.e. sign @@ -175,7 +176,7 @@ of step) can be determined. way to set this). More friendly type casting --------------------------- +=========================== In Pyrex, if one types ``x`` where ``x`` is a Python object, one will get the memory address of ``x``. Likewise, if one types ``i`` where ``i`` @@ -193,7 +194,7 @@ with type checking (i.e. it will throw an error if ``x`` is not a (subclass of) :ctype:`MyExtensionType`. Optional arguments in cdef/cpdef functions ------------------------------------------- +============================================ Cython now supports optional arguments for :keyword:`cdef` and :keyword:`cpdef` functions. @@ -232,13 +233,13 @@ with corresponding ``.pyx`` file:: :keyword:`cdef` functions. Function pointers in structs ----------------------------- +============================= Functions declared in :keyword:`structs` are automatically converted to function pointers for convenience. C++ Exception handling ----------------------- +========================= :keyword:`cdef` functions can now be declared as:: @@ -247,15 +248,15 @@ C++ Exception handling cdef int foo(...) except +python_error_raising_function in which case a Python exception will be raised when a C++ error is caught. -See :ref:`wrapping-cplusplus-label` for more details. +See :ref:`wrapping-cplusplus` for more details. Synonyms --------- +========= ``cdef import from`` means the same thing as ``cdef extern from`` Source code encoding --------------------- +====================== .. TODO: add the links to the relevent PEPs diff --git a/docs/sharing_declarations.rst b/docs/sharing_declarations.rst index 807fcfae..518579ad 100644 --- a/docs/sharing_declarations.rst +++ b/docs/sharing_declarations.rst @@ -1,9 +1,10 @@ .. highlight:: cython -.. _sharing-declarations-label: +.. _sharing-declarations: +******************************************** Sharing Declarations Between Cython Modules -=========================================== +******************************************** This section describes a new set of facilities for making C declarations, functions and extension types in one Cython module available for use in @@ -11,7 +12,7 @@ another Cython module. These facilities are closely modelled on the Python import mechanism, and can be thought of as a compile-time version of it. Definition and Implementation files ------------------------------------ +==================================== A Cython module can be split into two parts: a definition file with a ``.pxd`` suffix, containing C declarations that are to be available to other Cython @@ -21,7 +22,7 @@ module's definition file, it imports it using the :keyword:`cimport` statement. What a Definition File contains -------------------------------- +================================ A definition file can contain: @@ -43,14 +44,14 @@ Python class definitions, or any executable statements. declaration if you want to make something available to external C code. What an Implementation File contains ------------------------------------- +====================================== An implementation file can contain any kind of Cython statement, although there are some restrictions on the implementation part of an extension type if the corresponding definition file also defines that type (see below). The cimport statement ---------------------- +======================= The :keyword:`cimport` statement is used in a definition or implementation file to gain access to names declared in another definition diff --git a/docs/source_files_and_compilation.rst b/docs/source_files_and_compilation.rst index b8c7a5ad..c5535613 100644 --- a/docs/source_files_and_compilation.rst +++ b/docs/source_files_and_compilation.rst @@ -1,6 +1,6 @@ .. highlight:: cython -.. _compilation_label: +.. _compilation: **************************** Source Files and Compilation @@ -44,7 +44,7 @@ would be:: ) To understand the :file:`setup.py` more fully look at the official -``distutils`` documentation. To compile the extension for use in the +:mod:`distutils` documentation. To compile the extension for use in the current directory use:: $ python setup.py build_ext --inplace @@ -52,15 +52,36 @@ current directory use:: Cython Files Depending on C Files =================================== -TODO +When you have come C files that have been wrapped with cython and you want to +compile them into your extension the basic :file:`setup.py` file to do this +would be:: + + from distutils.core import setup + from distutils.extension import Extension + from Cython.Distutils import build_ext + + sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c'] + + setup( + cmdclass = {'build_ext': build_ext}, + ext_modules = [Extension("example", sourcefiles)] + ) + +Notice that the files have been given a name, this is not necessary, but it +makes the file easier to format if the list gets long. + +If any of the files depend on include paths information can be passed to the +:obj:`Extension` class through the :keyword:`include_dirs` option, which is a +list of paths to the include directories. + Multiple Cython Files in a Package =================================== TODO -Distributing Pyrex modules -=========================== +Distributing Cython modules +============================ It is strongly recommended that you distribute the generated ``.c`` files as well as your Cython sources, so that users can install your module without needing to have Cython available. diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 3800a203..3ffdd5ae 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -1,6 +1,6 @@ .. highlight:: cython -.. _tutorial_label: +.. _tutorial: ********* Tutorial @@ -13,7 +13,7 @@ The fundamental nature of Cython can be summed up as follows: Cython is Python with C data types. Cython is Python: Almost any piece of Python code is also valid Cython code. -(There are a few :ref:`cython-limitations-label`, but this approximation will +(There are a few :ref:`cython-limitations`, but this approximation will serve for now.) The Cython compiler will convert it into C code which makes equivalent calls to the Python/C API. @@ -38,7 +38,8 @@ So lets start with the canonical python hello world:: print "Hello World" So the first thing to do is rename the file to :file:`helloworld.pyx`. Now we -need to make the :file:`setup.py`, which is like a python Makefile.:: +need to make the :file:`setup.py`, which is like a python Makefile (for more +information see :ref:`compilation`):: from distutils.core import setup from distutils.extension import Extension @@ -53,8 +54,8 @@ To use this to build your Cython file use the commandline options:: $ python setup.py build_ext --inplace -Which will leave a file in your local directory called `helloworld.so` in unix -or `helloworld.dll` in Windows. Now to use this file start the python +Which will leave a file in your local directory called :file:`helloworld.so` in unix +or :file:`helloworld.dll` in Windows. Now to use this file: start the python interpreter and simply import it as if it was a regular python module:: >>> import helloworld @@ -138,5 +139,5 @@ take a look at the C code generated for this module. Language Details ================ -For more about the Cython language, see :ref:`language-basics-label`. +For more about the Cython language, see :ref:`language-basics`. diff --git a/docs/wrapping_CPlusPlus.rst b/docs/wrapping_CPlusPlus.rst index 111a31a4..24360529 100644 --- a/docs/wrapping_CPlusPlus.rst +++ b/docs/wrapping_CPlusPlus.rst @@ -1,12 +1,13 @@ .. highlight:: cython -.. _wrapping-cplusplus-label: +.. _wrapping-cplusplus: +******************************** Wrapping C++ Classes in Cython -==================================== +******************************** Overview --------- +========= This page aims to get you quickly up to speed so you can wrap C++ interfaces with a minimum of pain and 'surprises'. @@ -24,7 +25,7 @@ you wrap a lot of C++ code with only moderate effort. There are some limitations, which we will discuss at the end of the document. Procedure Overview ------------------- +==================== * Specify C++ language in :file:`setup.py` script * Create ``cdef extern from`` blocks and declare classes as @@ -34,7 +35,7 @@ Procedure Overview * Create Cython wrapper class An example C++ API ------------------- +=================== Here is a tiny C++ API which we will use as an example throughout this document. Let's assume it will be in a header file called @@ -54,7 +55,7 @@ document. Let's assume it will be in a header file called This is pretty dumb, but should suffice to demonstrate the steps involved. Specify C++ language in setup.py --------------------------------- +================================= In Cython :file:`setup.py` scripts, one normally instantiates an Extension object. To make Cython generate and compile a C++ source, you just need @@ -73,7 +74,7 @@ to add a keyword to your Extension construction statement, as in:: With the language="c++" keyword, Cython distutils will generate a C++ file. Create cdef extern from block ------------------------------ +============================== The procedure for wrapping a C++ class is quite similar to that for wrapping normal C structs, with a couple of additions. Let's start here by creating the @@ -84,7 +85,7 @@ basic ``cdef extern from`` block:: This will make the C++ class def for Rectangle available. Declare class as a ctypedef struct -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------------- Now, let's add the Rectangle class to this extern from block -- just copy the class def from :file:`Rectangle.h` and adjust for Cython syntax, so now it @@ -99,7 +100,7 @@ We don't have any way of accessing the constructor/destructor or methods, but we'll cover this now. Add constructors and destructors -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------------- We now need to expose a constructor and destructor into the Cython namespace. Again, we'll be using C name specifications:: @@ -111,7 +112,7 @@ namespace. Again, we'll be using C name specifications:: void del_Rectangle "delete" (c_Rectangle *rect) Add class methods -^^^^^^^^^^^^^^^^^ +------------------- Now, let's add the class methods. You can circumvent Cython syntax limitations by declaring these as function pointers. Recall that in the C++ @@ -142,7 +143,7 @@ In Pyrex you must explicitly declare these as function pointers, i.e. ``(int *getArea)()``. Create Cython wrapper class ---------------------------- +============================= At this point, we have exposed into our pyx file's namespace a struct which gives us access to the interface of a C++ Rectangle type. Now, we need to make @@ -177,7 +178,7 @@ attribute access, you could just implement some properties:: ... Caveats and Limitations ------------------------ +======================== In this document, we have discussed a relatively straightforward way of wrapping C++ classes with Cython. However, there are some limitations in @@ -189,13 +190,13 @@ The major limitations I'm most immediately aware of (and there will be many more) include: Overloading -^^^^^^^^^^^ +------------ Presently, it's not easy to overload methods or constructors, but there may be a workaround if you try some creative C name specifications Access to C-only functions -^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------- Whenever generating C++ code, Cython generates declarations of and calls to functions assuming these functions are C++ (ie, not declared as extern "C" @@ -209,7 +210,7 @@ module which: respective pure-C function Inherited C++ methods -^^^^^^^^^^^^^^^^^^^^^ +---------------------- If you have a class ``Foo`` with a child class ``Bar``, and ``Foo`` has a method :meth:`fred`, then you'll have to cast to access this method from @@ -228,10 +229,10 @@ It might take some experimenting by others (you?) to find the most elegant ways of handling this issue. Advanced C++ features -^^^^^^^^^^^^^^^^^^^^^ +---------------------- Exceptions -"""""""""" +^^^^^^^^^^^ Cython cannot throw C++ exceptions, or catch them with a try-except statement, but it is possible to declare a function as potentially raising an C++ @@ -258,7 +259,7 @@ raise_py_error does not actually raise an exception a RuntimeError will be raised. Templates -""""""""" +^^^^^^^^^^ Cython does not natively understand C++ templates but we can put them to use in some way. As an example consider an STL vector of C ints:: @@ -274,7 +275,7 @@ now we can use the vector like this:: v.push_back(2) Overloading -""""""""""" +^^^^^^^^^^^^ To support function overloading simply add a different alias to each signature, so if you have e.g. :: @@ -288,7 +289,7 @@ in your C++ header then interface it like this in your :: int fooii "foo"(int, int) Operators -""""""""" +^^^^^^^^^^ Some operators (e.g. +,-,...) can be accessed from Cython like this:: @@ -296,12 +297,12 @@ Some operators (e.g. +,-,...) can be accessed from Cython like this:: c_Rectangle add "operator+"(c_Rectangle right) Declaring/Using References -"""""""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Question: How do you declare and call a function that takes a reference as an argument? Conclusion ----------- +============ A great many existing C++ classes can be wrapped using these techniques, in a way much easier than writing a large messy C shim module. There's a bit of diff --git a/index.rst b/index.rst index b7eb9cf9..4c14c1cd 100644 --- a/index.rst +++ b/index.rst @@ -1,9 +1,6 @@ -.. Cython documentation master file, created by sphinx-quickstart on Fri Apr 25 12:49:32 2008. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. -Welcome to Cython's documentation! -================================================ +Welcome to Cython's Users Guide +================================= Contents: -- 2.26.2