源文件和编译 ¶

Cython 源文件名由模块名称组成，之后紧跟 .pyx 扩展名，例如，称为 primes 的模块拥有的源文件名为 primes.pyx .

Cython 代码，不像 Python，必须被编译。这分 2 阶段发生：

.pyx 文件通过 Cython 编译成 .c 文件。
.c 文件由 C 编译器编译成 .so 文件 (或 .pyd 文件在 Windows)

一旦有编写 .pyx 文件，有 2 种方式将其转换成扩展模块。

以下小节描述构建扩展模块的几种方式，及如何将指令传递给 Cython 编译器。

从命令行编译 ¶

有 2 种命令行编译方式。

cython 命令接受 .py or .pyx 文件并将其编译成 C/C++ 文件。
cythonize 命令接受 .py or .pyx 文件并将其编译成 C/C++ 文件。然后将 C/C++ 文件编译成可直接从 Python 导入的扩展模块。

编译采用 `cython` 命令 ¶

One way is to compile it manually with the Cython compiler, e.g.:

$ cython primes.pyx

This will produce a file called primes.c , which then needs to be compiled with the C compiler using whatever options are appropriate on your platform for generating an extension module. For these options look at the official Python documentation.

The other, and probably better, way is to use the distutils extension provided with Cython. The benefit of this method is that it will give the platform specific compilation options, acting like a stripped down autotools.

编译采用 `cythonize` 命令 ¶

运行 cythonize compiler command with your options and list of .pyx files to generate an extension module. For example:

$ cythonize -a -i yourmod.pyx

This creates a yourmod.c 文件 (或 yourmod.cpp in C++ mode), compiles it, and puts the resulting extension module ( .so or .pyd , depending on your platform) next to the source file for direct import ( -i builds “in place”). The -a switch additionally produces an annotated html file of the source code.

cythonize command accepts multiple source files and glob patterns like **/*.pyx as argument and also understands the common -j option for running multiple parallel build jobs. When called without further options, it will only translate the source files to .c or .cpp files. Pass the -h flag for a complete list of supported options.

There simpler command line tool cython only invokes the source code translator.

In the case of manual compilation, how to compile your .c files will vary depending on your operating system and compiler. The Python documentation for writing extension modules should have some details for your system. On a Linux system, for example, it might look similar to this:

$ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing \
      -I/usr/include/python3.5 -o yourmod.so yourmod.c

( gcc will need to have paths to your included header files and paths to libraries you want to link with.)

After compilation, a yourmod.so ( yourmod.pyd for Windows) file is written into the target directory and your module, yourmod , is available for you to import as with any other Python module. Note that if you are not relying on cythonize or distutils, you will not automatically benefit from the platform specific file extension that CPython generates for disambiguation, such as yourmod.cpython-35m-x86_64-linux-gnu.so on a regular 64bit Linux installation of CPython 3.5.

基本 setup.py ¶

由 Cython 提供的 distutils 扩展允许传递 .pyx 文件直接到 Extension 构造函数在 setup 文件中。

If you have a single Cython file that you want to turn into a compiled extension, say with filename example.pyx the associated setup.py would be:

from distutils.core import setup
from Cython.Build import cythonize
setup(
    ext_modules = cythonize("example.pyx")
)

To understand the setup.py more fully look at the official distutils documentation. To compile the extension for use in the current directory use:

$ python setup.py build_ext --inplace

配置 C 构建 ¶

If you have include files in non-standard places you can pass an include_path 参数用于 cythonize :

from distutils.core import setup
from Cython.Build import cythonize
setup(
    name="My hello app",
    ext_modules=cythonize("src/*.pyx", include_path=[...]),
)

Often, Python packages that offer a C-level API provide a way to find the necessary include files, e.g. for NumPy:

include_path = [numpy.get_include()]

注意

Using memoryviews or importing NumPy with import numpy does not mean that you have to add the path to NumPy include files. You need to add this path only if you use cimport numpy .

Despite this, you will still get warnings like the following from the compiler, because Cython is using a deprecated Numpy API:

.../include/numpy/npy_1_7_deprecated_api.h:15:2: warning: #warning "Using deprecated NumPy API, disable it by " "#defining NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION" [-Wcpp]

For the time being, it is just a warning that you can ignore.

If you need to specify compiler options, libraries to link with or other linker options you will need to create Extension instances manually (note that glob syntax can still be used to specify multiple extensions in one line):

from distutils.core import setup
from distutils.extension import Extension
from Cython.Build import cythonize
extensions = [
    Extension("primes", ["primes.pyx"],
        include_dirs=[...],
        libraries=[...],
        library_dirs=[...]),
    # Everything but primes.pyx is included here.
    Extension("*", ["*.pyx"],
        include_dirs=[...],
        libraries=[...],
        library_dirs=[...]),
]
setup(
    name="My hello app",
    ext_modules=cythonize(extensions),
)

Note that when using setuptools, you should import it before Cython as setuptools may replace the Extension class in distutils. Otherwise, both might disagree about the class to use here.

Note also that if you use setuptools instead of distutils, the default action when running python setup.py 安装 是创建压缩 egg 文件不会工作采用 cimport for pxd 文件当试着从依赖包使用它们时。为阻止这种情况，包括 zip_safe=False 在自变量到 setup() .

If your options are static (for example you do not need to call a tool like pkg-config to determine them) you can also provide them directly in your .pyx or .pxd source file using a special comment block at the start of the file:

# distutils: libraries = spam eggs
# distutils: include_dirs = /opt/food/include

If you cimport multiple .pxd files defining libraries, then Cython merges the list of libraries, so this works as expected (similarly with other options, like include_dirs above).

If you have some C files that have been wrapped with Cython and you want to compile them into your extension, you can define the distutils sources parameter:

# distutils: sources = helper.c, another_helper.c

Note that these sources are added to the list of sources of the current extension module. Spelling this out in the setup.py file looks as follows:

from distutils.core import setup
from Cython.Build import cythonize
from distutils.extension import Extension
sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c']
extensions = [Extension("example", sourcefiles)]
setup(
    ext_modules=cythonize(extensions)
)

Extension class takes many options, and a fuller explanation can be found in the distutils documentation . Some useful options to know about are include_dirs , libraries ，和 library_dirs which specify where to find the .h and library files when linking to external libraries.

Sometimes this is not enough and you need finer customization of the distutils Extension . To do this, you can provide a custom function create_extension to create the final Extension object after Cython has processed the sources, dependencies and # distutils directives but before the file is actually Cythonized. This function takes 2 arguments template and kwds ，其中 template 是 Extension object given as input to Cython and kwds 是 dict with all keywords which should be used to create the Extension . The function create_extension must return a 2-tuple (extension, metadata) ，其中 extension is the created Extension and metadata is metadata which will be written as JSON at the top of the generated C files. This metadata is only used for debugging purposes, so you can put whatever you want in there (as long as it can be converted to JSON). The default function (defined in Cython.Build.Dependencies ) is:

def default_create_extension(template, kwds):
    if 'depends' in kwds:
        include_dirs = kwds.get('include_dirs', []) + ["."]
        depends = resolve_depends(kwds['depends'], include_dirs)
        kwds['depends'] = sorted(set(depends + template.depends))
    t = template.__class__
    ext = t(**kwds)
    metadata = dict(distutils=kwds, module_name=kwds['name'])
    return ext, metadata

In case that you pass a string instead of an Extension to cythonize() ， template will be an Extension without sources. For example, if you do cythonize("*.pyx") ， template 将是 Extension(name="*.pyx", sources=[]) .

Just as an example, this adds mylib as library to every extension:

from Cython.Build.Dependencies import default_create_extension
def my_create_extension(template, kwds):
    libs = kwds.get('libraries', []) + ["mylib"]
    kwds['libraries'] = libs
    return default_create_extension(template, kwds)
ext_modules = cythonize(..., create_extension=my_create_extension)

注意

If you Cythonize in parallel (using the nthreads argument), then the argument to create_extension must be pickleable. In particular, it cannot be a lambda function.

Cythonize 自变量 ¶

函数 cythonize() can take extra arguments which will allow you to customize your build.

Cython.Build. cythonize ( module_list , exclude=None , nthreads=0 , aliases=None , quiet=False , force=False , language=None , exclude_failures=False , **options ) ¶

参数：	module_list – As module list, pass either a glob pattern, a list of glob patterns or a list of Extension objects. The latter allows you to configure the extensions separately through the normal distutils options. You can also pass Extension objects that have glob patterns as their sources. Then, cythonize will resolve the pattern and create a copy of the Extension for every matching file. exclude – When passing glob patterns as `module_list` , you can exclude certain module names explicitly by passing them into the `exclude` 选项。 nthreads – The number of concurrent builds for parallel compilation (requires the `multiprocessing` 模块)。 aliases – If you want to use compiler directives like `# distutils: ...` but can only know at compile time (when running the `setup.py` ) which values to use, you can use aliases and pass a dictionary mapping those aliases to Python strings when calling `cythonize()` . As an example, say you want to use the compiler directive `# distutils: include_dirs = ../static_libs/include/` but this path isn’t always fixed and you want to find it when running the `setup.py` . You can then do `# distutils: include_dirs = MY_HEADERS` , find the value of `MY_HEADERS` 在 `setup.py` , put it in a python variable called `foo` as a string, and then call `cythonize(..., aliases={'MY_HEADERS': foo})` . quiet – If True, Cython won’t print error and warning messages during the compilation. force – Forces the recompilation of the Cython modules, even if the timestamps don’t indicate that a recompilation is necessary. 语言 – To globally enable C++ mode, you can pass `language='c++'` . Otherwise, this will be determined at a per-file level based on compiler directives. This affects only modules found based on file names. Extension instances passed into `cythonize()` will not be changed. It is recommended to rather use the compiler directive `# distutils: language = c++` than this option. exclude_failures – For a broad ‘try to compile’ mode that ignores compilation failures and simply excludes the failed extensions, pass `exclude_failures=True` . Note that this only really makes sense for compiling `.py` files which can also be used without compilation. annotate – If `True` , will produce a HTML file for each of the `.pyx` or `.py` files compiled. The HTML file gives an indication of how much Python interaction there is in each of the source code lines, compared to plain C code. It also allows you to see the C/C++ code generated for each line of Cython code. This report is invaluable when optimizing a function for speed, and for determining when to 释放 GIL ：一般而言， `nogil` block may contain only “white” code. See examples in 确定在哪里添加类型 or Primes . compiler_directives – Allow to set compiler directives in the `setup.py` 像这样： `compiler_directives={'embedsignature': True}` 。见编译器指令 .

一个包中多个 Cython 文件 ¶

To automatically compile multiple Cython files without listing all of them explicitly, you can use glob patterns:

setup(
    ext_modules = cythonize("package/*.pyx")
)

You can also use glob patterns in Extension objects if you pass them through cythonize() :

extensions = [Extension("*", ["*.pyx"])]
setup(
    ext_modules = cythonize(extensions)
)

分发 Cython 模块 ¶

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.

It is also recommended that Cython compilation not be enabled by default in the version you distribute. Even if the user has Cython installed, he/she probably doesn’t want to use it just to install your module. Also, the installed version may not be the same one you used, and may not compile your sources correctly.

This simply means that the setup.py file that you ship with will just be a normal distutils file on the generated .c files, for the basic example we would have instead:

from distutils.core import setup
from distutils.extension import Extension
setup(
    ext_modules = [Extension("example", ["example.c"])]
)

This is easy to combine with cythonize() by changing the file extension of the extension module sources:

from distutils.core import setup
from distutils.extension import Extension
USE_CYTHON = ...   # command line option, try-import, ...
ext = '.pyx' if USE_CYTHON else '.c'
extensions = [Extension("example", ["example"+ext])]
if USE_CYTHON:
    from Cython.Build import cythonize
    extensions = cythonize(extensions)
setup(
    ext_modules = extensions
)

If you have many extensions and want to avoid the additional complexity in the declarations, you can declare them with their normal Cython sources and then call the following function instead of cythonize() to adapt the sources list in the Extensions when not using Cython:

import os.path
def no_cythonize(extensions, **_ignore):
    for extension in extensions:
        sources = []
        for sfile in extension.sources:
            path, ext = os.path.splitext(sfile)
            if ext in ('.pyx', '.py'):
                if extension.language == 'c++':
                    ext = '.cpp'
                else:
                    ext = '.c'
                sfile = path + ext
            sources.append(sfile)
        extension.sources[:] = sources
    return extensions

Another option is to make Cython a setup dependency of your system and use Cython’s build_ext module which runs cythonize as part of the build process:

setup(
    setup_requires=[
        'cython>=0.x',
    ],
    extensions = [Extension("*", ["*.pyx"])],
    cmdclass={'build_ext': Cython.Build.build_ext},
    ...
)

If you want to expose the C-level interface of your library for other libraries to cimport from, use package_data to install the .pxd files, e.g.:

setup(
    package_data = {
        'my_package': ['*.pxd'],
        'my_package/sub_package': ['*.pxd'],
    },
    ...
)

这些 .pxd files need not have corresponding .pyx modules if they contain purely declarations of external libraries.

Remember that if you use setuptools instead of distutils, the default action when running python setup.py 安装 是创建压缩 egg 文件不会工作采用 cimport for pxd 文件当试着从依赖包使用它们时。为阻止这种情况，包括 zip_safe=False 在自变量到 setup() .

集成多个模块 ¶

In some scenarios, it can be useful to link multiple Cython modules (or other extension modules) into a single binary, e.g. when embedding Python in another application. This can be done through the inittab import mechanism of CPython.

Create a new C file to integrate the extension modules and add this macro to it:

#if PY_MAJOR_VERSION < 3
# define MODINIT(name)  init ## name
#else
# define MODINIT(name)  PyInit_ ## name
#endif

If you are only targeting Python 3.x, just use PyInit_ as prefix.

Then, for each of the modules, declare its module init function as follows, replacing some_module_name with the name of the module:

PyMODINIT_FUNC  MODINIT(some_module_name) (void);

In C++, declare them as extern C .

If you are not sure of the name of the module init function, refer to your generated module source file and look for a function name starting with PyInit_ .

Next, before you start the Python runtime from your application code with Py_Initialize() , you need to initialise the modules at runtime using the PyImport_AppendInittab() C-API function, again inserting the name of each of the modules:

PyImport_AppendInittab("some_module_name", MODINIT(some_module_name));

This enables normal imports for the embedded extension modules.

In order to prevent the joined binary from exporting all of the module init functions as public symbols, Cython 0.28 and later can hide these symbols if the macro CYTHON_NO_PYINIT_EXPORT is defined while C-compiling the module C files.

Also take a look at the cython_freeze tool. It can generate the necessary boilerplate code for linking one or more modules into a single Python executable.

编译采用 `pyximport` ¶

For building Cython modules during development without explicitly running setup.py after each change, you can use pyximport :

>>> import pyximport; pyximport.install()
>>> import helloworld
Hello World

This allows you to automatically run Cython on every .pyx that Python is trying to import. You should use this for simple Cython builds only where no extra C libraries and no special building setup is needed.

It is also possible to compile new .py modules that are being imported (including the standard library and installed packages). For using this feature, just tell that to pyximport :

>>> pyximport.install(pyimport=True)

In the case that Cython fails to compile a Python module, pyximport will fall back to loading the source modules instead.

注意：不推荐让 pyximport 在最终用户侧构建代码，因为它会挂钩到他们的导入系统。迎合最终用户的最佳方式是提供预构建的二进制包以 wheel 打包格式。

自变量 ¶

函数 pyximport.install() can take several arguments to influence the compilation of Cython or Python files.

pyximport. 安装 ( pyximport=True , pyimport=False , build_dir=None , build_in_temp=True , setup_args=None , reload_support=False , load_py_module_on_import_failure=False , inplace=False , language_level=None ) ¶

参数：	pyximport – If set to False, does not try to import `.pyx` 文件。 pyimport – You can pass `pyimport=True` to also install the `.py` import hook in your meta-path. Note, however, that it is rather experimental, will not work at all for some `.py` files and packages, and will heavily slow down your imports due to search and compilation. Use at your own risk. build_dir – By default, compiled modules will end up in a `.pyxbld` directory in the user’s home directory. Passing a different path as `build_dir` will override this. build_in_temp – If `False` , will produce the C files locally. Working with complex dependencies and debugging becomes more easy. This can principally interfere with existing files of the same name. setup_args – Dict of arguments for Distribution. See `distutils.core.setup()` . reload_support – Enables support for dynamic `reload(my_module)` , e.g. after a change in the Cython code. Additional files `<so_path>.reloadNN` may arise on that account, when the previously loaded module file cannot be overwritten. load_py_module_on_import_failure – If the compilation of a `.py` file succeeds, but the subsequent import fails for some reason, retry the import with the normal `.py` module instead of the compiled module. Note that this may lead to unpredictable results for modules that change the system state during their import, as the second import will rerun these modifications in whatever state the system was left after the import of the compiled module failed. inplace – Install the compiled module ( `.so` for Linux and Mac / `.pyd` for Windows) next to the source file. language_level – The source language level to use: 2 or 3. The default is to use the language level of the current Python runtime for .py files and Py2 for `.pyx` 文件。

依赖处理 ¶

由于 pyximport does not use cythonize() internally, it currently requires a different setup for dependencies. It is possible to declare that your module depends on multiple files, (likely .h and .pxd files). If your Cython module is named foo and thus has the filename foo.pyx then you should create another file in the same directory called foo.pyxdep 。 modname.pyxdep file can be a list of filenames or “globs” (like *.pxd or include/*.h ). Each filename or glob must be on a separate line. Pyximport will check the file date for each of those files before deciding whether to rebuild the module. In order to keep track of the fact that the dependency has been handled, Pyximport updates the modification time of your “.pyx” source file. Future versions may do something more sophisticated like informing distutils of the dependencies directly.

局限性 ¶

pyximport does not use cythonize() . Thus it is not possible to do things like using compiler directives at the top of Cython files or compiling Cython code to C++.

Pyximport does not give you any control over how your Cython file is compiled. Usually the defaults are fine. You might run into problems if you wanted to write your program in half-C, half-Cython and build them into a single library.

Pyximport does not hide the Distutils/GCC warnings and errors generated by the import process. Arguably this will give you better feedback if something went wrong and why. And if nothing went wrong it will give you the warm fuzzy feeling that pyximport really did rebuild your module as it was supposed to.

Basic module reloading support is available with the option reload_support=True . Note that this will generate a new module filename for each build and thus end up loading multiple shared libraries into memory over time. CPython has limited support for reloading shared libraries as such, see PEP 489 .

Pyximport puts both your .c file and the platform-specific binary into a separate build directory, usually $HOME/.pyxblx/ . To copy it back into the package hierarchy (usually next to the source file) for manual reuse, you can pass the option inplace=True .

编译采用 `cython.inline` ¶

One can also compile Cython in a fashion similar to SciPy’s weave.inline 。例如：

>>> import cython
>>> def f(a):
...     ret = cython.inline("return a+b", b=3)
...

Unbound variables are automatically pulled from the surrounding local and global scopes, and the result of the compilation is cached for efficient re-use.

编译采用 Sage ¶

The Sage notebook allows transparently editing and compiling Cython code simply by typing %cython at the top of a cell and evaluate it. Variables and functions defined in a Cython cell are imported into the running session. Please check Sage documentation 了解细节。

You can tailor the behavior of the Cython compiler by specifying the directives below.

编译采用 Jupyter 笔记本 ¶

It’s possible to compile code in a notebook cell with Cython. For this you need to load the Cython magic:

%load_ext cython

Then you can define a Cython cell by writing %%cython on top of it. Like this:

%%cython
cdef int a = 0
for i in range(10):
    a += i
print(a)

Note that each cell will be compiled into a separate extension module. So if you use a package in a Cython cell, you will have to import this package in the same cell. It’s not enough to have imported the package in a previous cell. Cython will tell you that there are “undefined global names” at compilation time if you don’t comply.

The global names (top level functions, classes, variables and modules) of the cell are then loaded into the global namespace of the notebook. So in the end, it behaves as if you executed a Python cell.

Additional allowable arguments to the Cython magic are listed below. You can see them also by typing `%%cython? in IPython or a Jupyter notebook.

-a, –annotate	Produce a colorized HTML version of the source.
-+, –cplus	Output a C++ rather than C file.
-f, –force	Force the compilation of a new module, even if the source has been previously compiled.
-3	Select Python 3 syntax
-2	Select Python 2 syntax
-c=COMPILE_ARGS, –compile-args=COMPILE_ARGS	Extra flags to pass to compiler via the extra_compile_args.
–link-args LINK_ARGS	Extra flags to pass to linker via the extra_link_args.
-l LIB, –lib LIB	Add a library to link the extension against (can be specified multiple times).
-L dir	Add a path to the list of library directories (can be specified multiple times).
-I INCLUDE, –include INCLUDE	Add a path to the list of include directories (can be specified multiple times).
-S, –src	Add a path to the list of src files (can be specified multiple times).
-n NAME, –name NAME	Specify a name for the Cython module.
–pgo	Enable profile guided optimisation in the C compiler. Compiles the cell twice and executes it in between to generate a runtime profile.
–verbose	Print debug information like generated .c/.cpp file location and exact gcc/g++ command invoked.

编译器选项 ¶

Compiler options can be set in the setup.py , before calling cythonize() ，像这样：

from distutils.core import setup
from Cython.Build import cythonize
from Cython.Compiler import Options
Options.docstrings = False
setup(
    name = "hello",
    ext_modules = cythonize("lib.pyx"),
)

Here are the options that are available:

Cython.Compiler.Options. docstrings = True ¶

Cython.Compiler.Options. embed_pos_in_docstring = False ¶

Cython.Compiler.Options. emit_code_comments = True ¶

Cython.Compiler.Options. generate_cleanup_code = False ¶

Cython.Compiler.Options. clear_to_none = True ¶

Cython.Compiler.Options. annotate = False ¶

Cython.Compiler.Options. fast_fail = False ¶

Cython.Compiler.Options. warning_errors = False ¶

Cython.Compiler.Options. error_on_unknown_names = True ¶

Cython.Compiler.Options. error_on_uninitialized = True ¶

Cython.Compiler.Options. convert_range = True ¶

Cython.Compiler.Options. cache_builtins = True ¶

Cython.Compiler.Options. gcc_branch_hints = True ¶

Cython.Compiler.Options. lookup_module_cpdef = False ¶

Cython.Compiler.Options. embed = None ¶

Cython.Compiler.Options. cimport_from_pyx = False ¶

Cython.Compiler.Options. buffer_max_dims = 8 ¶

Cython.Compiler.Options. closure_freelist_size = 8 ¶

编译器指令 ¶

Compiler directives are instructions which affect the behavior of Cython code. Here is the list of currently supported directives:

binding (True / False): Controls whether free functions behave more like Python’s CFunctions (如 len() ) or, when set to True, more like Python’s functions. When enabled, functions will bind to an instance when looked up as a class attribute (hence the name) and will emulate the attributes of Python functions, including introspections like argument names and annotations. Default is False.
boundscheck (True / False): If set to False, Cython is free to assume that indexing operations ([]-operator) in the code will not cause any IndexErrors to be raised. Lists, tuples, and strings are affected only if the index can be determined to be non-negative (or if wraparound is False). Conditions which would normally trigger an IndexError may instead cause segfaults or data corruption if this is set to False. Default is True.
wraparound (True / False): In Python, arrays and sequences can be indexed relative to the end. For example, A[-1] indexes the last value of a list. In C, negative indexing is not supported. If set to False, Cython is allowed to neither check for nor correctly handle negative indices, possibly causing segfaults or data corruption. If bounds checks are enabled (the default, see boundschecks above), negative indexing will usually raise an IndexError for indices that Cython evaluates itself. However, these cases can be difficult to recognise in user code to distinguish them from indexing or slicing that is evaluated by the underlying Python array or sequence object and thus continues to support wrap-around indices. It is therefore safest to apply this option only to code that does not process negative indices at all. Default is True.
initializedcheck (True / False): If set to True, Cython checks that a memoryview is initialized whenever its elements are accessed or assigned to. Setting this to False disables these checks. Default is True.
nonecheck (True / False): If set to False, Cython is free to assume that native field accesses on variables typed as an extension type, or buffer accesses on a buffer variable, never occurs when the variable is 设为 None . Otherwise a check is inserted and the appropriate exception is raised. This is off by default for performance reasons. Default is False.
overflowcheck (True / False): If set to True, raise errors on overflowing C integer arithmetic operations. Incurs a modest runtime penalty, but is much faster than using Python ints. Default is False.
overflowcheck.fold (True / False): If set to True, and overflowcheck is True, check the overflow bit for nested, side-effect-free arithmetic expressions once rather than at every step. Depending on the compiler, architecture, and optimization settings, this may help or hurt performance. A simple suite of benchmarks can be found in Demos/overflow_perf.pyx . Default is True.
embedsignature (True / False): If set to True, Cython will embed a textual copy of the call signature in the docstring of all Python visible functions and classes. Tools like IPython and epydoc can thus display the signature, which cannot otherwise be retrieved after compilation. Default is False.
cdivision (True / False): If set to False, Cython will adjust the remainder and quotient operators C types to match those of Python ints (which differ when the operands have opposite signs) and raise a ZeroDivisionError when the right operand is 0. This has up to a 35% speed penalty. If set to True, no checks are performed. See CEP 516 . Default 为 False。
cdivision_warnings (True / False): If set to True, Cython will emit a runtime warning whenever division is performed with negative operands. See CEP 516 . Default is False.
always_allow_keywords (True / False): Avoid the METH_NOARGS and METH_O when constructing functions/methods which take zero or one arguments. Has no effect on special methods and functions with more than one argument. The METH_NOARGS and METH_O signatures provide faster calling conventions but disallow the use of keywords.
profile (True / False): Write hooks for Python profilers into the compiled C code. Default 为 False。
linetrace (True / False): Write line tracing hooks for Python profilers or coverage reporting into the compiled C code. This also enables profiling. Default is False. Note that the generated module will not actually use line tracing, unless you additionally pass the C macro definition CYTHON_TRACE=1 to the C compiler (e.g. using the distutils option define_macros ). Define CYTHON_TRACE_NOGIL=1 to also include nogil functions and sections.
infer_types (True / False): Infer types of untyped variables in function bodies. Default is None, indicating that only safe (semantically-unchanging) inferences are allowed. In particular, inferring integral types for variables used in arithmetic expressions is considered unsafe (due to possible overflow) and must be explicitly requested.
language_level (2/3/3str): Globally set the Python language level to be used for module compilation. Default is compatibility with Python 2. To enable Python 3 source code semantics, set this to 3 (or 3str) at the start of a module or pass the “-3” or “–3str” command line options to the compiler. The 3str option enables Python 3 semantics but does not change the str type and unprefixed string literals to unicode when the compiled code runs in Python 2.x. Note that cimported files inherit this setting from the module being compiled, unless they explicitly set their own language level. Included source files always inherit this setting.
c_string_type (bytes / str / unicode)
c_string_encoding (ascii, default, utf-8, etc.): Globally set the encoding to use when implicitly coercing char* or std:string to a unicode object. Coercion from a unicode object to C type is only allowed when set to ascii or default , the latter being utf-8 in Python 3 and nearly-always ascii in Python 2.
type_version_tag (True / False): Enables the attribute cache for extension types in CPython by setting the type flag Py_TPFLAGS_HAVE_VERSION_TAG . Default is True, meaning that the cache is enabled for Cython implemented types. To disable it explicitly in the rare cases where a type needs to juggle with its tp_dict internally without paying attention to cache consistency, this option can be set to False.
unraisable_tracebacks (True / False)
iterable_coroutine (True / False): PEP 492 specifies that async-def coroutines must not be iterable, in order to prevent accidental misuse in non-async contexts. However, this makes it difficult and inefficient to write backwards compatible code that uses async-def coroutines in Cython but needs to interact with async Python code that uses the older yield-from syntax, such as asyncio before Python 3.5. This directive can be applied in modules or selectively as decorator on an async-def coroutine to make the affected coroutine(s) iterable and thus directly interoperable with yield-from.

可配置的优化 ¶

optimize.use_switch (True / False): Whether to expand chained if-else statements (including statements like if x == 1 or x == 2: ) into C switch statements. This can have performance benefits if there are lots of values but cause compiler errors if there are any duplicate values (which may not be detectable at Cython compile time for all C constants). Default is True.
optimize.unpack_method_calls (True / False): Cython can generate code that optimistically checks for Python method objects at call time and unpacks the underlying function to call it directly. This can substantially speed up method calls, especially for builtins, but may also have a slight negative performance impact in some cases where the guess goes completely wrong. Disabling this option can also reduce the code size. Default is True.

警告 ¶

All warning directives take True / False as options to turn the warning on / off.

warn.undeclared (default False): Warns about any variables that are implicitly declared without a cdef 声明
warn.unreachable (default True): Warns about code paths that are statically determined to be unreachable, e.g. returning twice unconditionally.
warn.maybe_uninitialized (default False)
warn.unused (default False)
warn.unused_arg (default False)
warn.unused_result (default False): Warns about unused assignment to the same name, such as r = 2; r = 1 + 2
warn.multiple_declarators (default True): Warns about multiple variables declared on the same line with at least one pointer type. 例如 cdef double* a, b - which, as in C, declares a as a pointer, b as a value type, but could be mininterpreted as declaring two pointers.

如何设置指令 ¶

Globally ¶

One can set compiler directives through a special header comment near the top of the file, like this:

# cython: language_level=3, boundscheck=False

The comment must appear before any code (but can appear after other comments or whitespace).

One can also pass a directive on the command line by using the -X switch:

$ cython -X boundscheck=True ...

Directives passed on the command line will override directives set in header comments.

Locally ¶

For local blocks, you need to cimport the special builtin cython 模块：

#!python
cimport cython

Then you can use the directives either as decorators or in a with statement, like this:

#!python
@cython.boundscheck(False) # turn off boundscheck for this function
def f():
    ...
    # turn it temporarily on again for this block
    with cython.boundscheck(True):
        ...

警告

These two methods of setting directives are not affected by overriding the directive on the command-line using the -X option.

在 `setup.py` ¶

Compiler directives can also be set in the setup.py file by passing a keyword argument to cythonize :

from distutils.core import setup
from Cython.Build import cythonize
setup(
    name="My hello app",
    ext_modules=cythonize('hello.pyx', compiler_directives={'embedsignature': True}),
)

This will override the default directives as specified in the compiler_directives dictionary. Note that explicit per-file or local directives as explained above take precedence over the values passed to cythonize .