From 4104a516f38c0e936641e373503ffb239650bc3c Mon Sep 17 00:00:00 2001 From: Stefan Behnel Date: Wed, 13 Feb 2013 09:43:35 +0100 Subject: [PATCH] add tutorial section on naming C function parameters --- docs/src/tutorial/clibraries.rst | 6 ++++++ docs/src/tutorial/external.rst | 46 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 49 insertions(+), 3 deletions(-) diff --git a/docs/src/tutorial/clibraries.rst b/docs/src/tutorial/clibraries.rst index c3409bc..72d8c0d 100644 --- a/docs/src/tutorial/clibraries.rst +++ b/docs/src/tutorial/clibraries.rst @@ -77,6 +77,12 @@ use in your code or in other declarations, so that Cython gets to see a sufficient and consistent subset of them. Then, consider adapting them somewhat to make them more comfortable to work with in Cython. +Specifically, you should take care of choosing good argument names +for the C functions, as Cython allows you to pass them as keyword +arguments. Changing them later on is a backwards incompatible API +modification. Choosing good names right away will make these +functions more pleasant to work with from Cython code. + One noteworthy difference to the header file that we use above is the declaration of the ``Queue`` struct in the first line. ``Queue`` is in this case used as an *opaque handle*; only the library that is diff --git a/docs/src/tutorial/external.rst b/docs/src/tutorial/external.rst index 35df8f4..ec021dc 100644 --- a/docs/src/tutorial/external.rst +++ b/docs/src/tutorial/external.rst @@ -38,8 +38,12 @@ Cython also provides declarations for the C math library:: cdef double f(double x): return sin(x*x) -However, this is a library that is not linked by default on some Unix-like -systems, such as Linux. In addition to cimporting the + +Dynamic linking +--------------- + +The libc math library is special in that it is not linked by default +on some Unix-like systems, such as Linux. In addition to cimporting the declarations, you must configure your build system to link against the shared library ``m``. For distutils, it is enough to add it to the ``libraries`` parameter of the ``Extension()`` setup:: @@ -60,12 +64,16 @@ shared library ``m``. For distutils, it is enough to add it to the ext_modules = ext_modules ) + +External declarations +--------------------- + If you want to access C code for which Cython does not provide a ready to use declaration, you must declare them yourself. For example, the above ``sin()`` function is defined as follows:: cdef extern from "math.h": - double sin(double) + double sin(double x) This declares the ``sin()`` function in a way that makes it available to Cython code and instructs Cython to generate C code that includes @@ -77,3 +85,35 @@ Just like the ``sin()`` function from the math library, it is possible to declare and call into any C library as long as the module that Cython generates is properly linked against the shared or static library. + + +Naming parameters +----------------- + +Both C and Cython support signature declarations without parameter +names like this:: + + cdef extern from "string.h": + char* strstr(const char*, const char*) + +However, this prevents Cython code from calling it with keyword +arguments (supported since Cython 0.19). It is therefore preferable +to write the declaration like this instead:: + + cdef extern from "string.h": + char* strstr(const char *haystack, const char *needle) + +You can now make it clear which of the two arguments does what in +your call, thus avoiding any ambiguities and often making your code +more readable:: + + cdef char* data = "hfvcakdfagbcffvschvxcdfgccbcfhvgcsnfxjh" + + pos = strstr(needle='akd', haystack=data) + print pos != NULL + +Note that changing existing parameter names later is a backwards +incompatible API modification, just as for Python code. Thus, if +you provide your own declarations for external C or C++ functions, +it is usually worth the additional bit of effort to choose the +names of their arguments well. -- 2.7.4