Commit 8fbf1e07 authored by scoder's avatar scoder Committed by GitHub

Merge pull request #2179 from gabrieldemarmiesse/pyximport

Added argument list for pyximport.
parents 59d0330d d41f336d
...@@ -43,7 +43,8 @@ extensions = [ ...@@ -43,7 +43,8 @@ extensions = [
'cython_highlighting', 'cython_highlighting',
'sphinx.ext.pngmath', 'sphinx.ext.pngmath',
'sphinx.ext.todo', 'sphinx.ext.todo',
'sphinx.ext.intersphinx' 'sphinx.ext.intersphinx',
'sphinx.ext.autodoc'
] ]
try: import rst2pdf try: import rst2pdf
......
...@@ -18,7 +18,7 @@ one may want to read more about ...@@ -18,7 +18,7 @@ one may want to read more about
There are several ways to build Cython code: There are several ways to build Cython code:
- Write a distutils/setuptools ``setup.py``. This is the normal and recommended way. - Write a distutils/setuptools ``setup.py``. This is the normal and recommended way.
- Use ``pyximport``, importing Cython ``.pyx`` files as if they - Use :ref:`Pyximport<pyximport>`, importing Cython ``.pyx`` files as if they
were ``.py`` files (using distutils to compile and build in the background). were ``.py`` files (using distutils to compile and build in the background).
This method is easier than writing a ``setup.py``, but is not very flexible. This method is easier than writing a ``setup.py``, but is not very flexible.
So you'll need to write a ``setup.py`` if, for example, you need certain compilations options. So you'll need to write a ``setup.py`` if, for example, you need certain compilations options.
......
...@@ -77,7 +77,7 @@ It is shipped and installed with Cython and can be used like this:: ...@@ -77,7 +77,7 @@ It is shipped and installed with Cython and can be used like this::
>>> import helloworld >>> import helloworld
Hello World Hello World
Since Cython 0.11, the :mod:`pyximport` module also has experimental Since Cython 0.11, the :ref:`Pyximport<pyximport>` module also has experimental
compilation support for normal Python modules. This allows you to compilation support for normal Python modules. This allows you to
automatically run Cython on every .pyx and .py module that Python automatically run Cython on every .pyx and .py module that Python
imports, including the standard library and installed packages. imports, including the standard library and installed packages.
...@@ -87,7 +87,7 @@ modules instead. The .py import mechanism is installed like this:: ...@@ -87,7 +87,7 @@ modules instead. The .py import mechanism is installed like this::
>>> pyximport.install(pyimport=True) >>> pyximport.install(pyimport=True)
Note that it is not recommended to let :mod:`pyximport` build code Note that it is not recommended to let :ref:`Pyximport<pyximport>` build code
on end user side as it hooks into their import system. The best way on end user side as it hooks into their import system. The best way
to cater for end users is to provide pre-built binary packages in the to cater for end users is to provide pre-built binary packages in the
`wheel <https://wheel.readthedocs.io/>`_ packaging format. `wheel <https://wheel.readthedocs.io/>`_ packaging format.
......
...@@ -216,7 +216,7 @@ meaningful output from the cProfile module. The rest of the code is mostly ...@@ -216,7 +216,7 @@ meaningful output from the cProfile module. The rest of the code is mostly
unchanged, I only typed some variables which will likely speed things up a bit. unchanged, I only typed some variables which will likely speed things up a bit.
We also need to modify our profiling script to import the Cython module directly. We also need to modify our profiling script to import the Cython module directly.
Here is the complete version adding the import of the pyximport module:: Here is the complete version adding the import of the :ref:`Pyximport<pyximport>` module::
#!/usr/bin/env python #!/usr/bin/env python
# encoding: utf-8 # encoding: utf-8
......
...@@ -107,6 +107,14 @@ on end user side as it hooks into their import system. The best way ...@@ -107,6 +107,14 @@ on end user side as it hooks into their import system. The best way
to cater for end users is to provide pre-built binary packages in the to cater for end users is to provide pre-built binary packages in the
`wheel <https://wheel.readthedocs.io/>`_ packaging format. `wheel <https://wheel.readthedocs.io/>`_ packaging format.
Arguments
---------
The function ``pyximport.install()`` can take several arguments to
influence the compilation of Cython or Python files.
.. autofunction:: pyximport.install
Dependency Handling Dependency Handling
-------------------- --------------------
......
...@@ -485,49 +485,53 @@ def install(pyximport=True, pyimport=False, build_dir=None, build_in_temp=True, ...@@ -485,49 +485,53 @@ def install(pyximport=True, pyimport=False, build_dir=None, build_in_temp=True,
setup_args=None, reload_support=False, setup_args=None, reload_support=False,
load_py_module_on_import_failure=False, inplace=False, load_py_module_on_import_failure=False, inplace=False,
language_level=None): language_level=None):
"""Main entry point. Call this to install the .pyx import hook in """ Main entry point for pyxinstall.
Call this to install the ``.pyx`` import hook in
your meta-path for a single Python process. If you want it to be your meta-path for a single Python process. If you want it to be
installed whenever you use Python, add it to your sitecustomize installed whenever you use Python, add it to your ``sitecustomize``
(as described above). (as described above).
You can pass ``pyimport=True`` to also install the .py import hook :param pyximport: If set to False, does not try to import ``.pyx`` files.
:param pyimport: You can pass ``pyimport=True`` to also
install the ``.py`` import hook
in your meta-path. Note, however, that it is highly experimental, in your meta-path. Note, however, that it is highly experimental,
will not work for most .py files, and will therefore only slow will not work for most ``.py`` files, and will therefore only slow
down your imports. Use at your own risk. down your imports. Use at your own risk.
By default, compiled modules will end up in a ``.pyxbld`` :param build_dir: By default, compiled modules will end up in a ``.pyxbld``
directory in the user's home directory. Passing a different path directory in the user's home directory. Passing a different path
as ``build_dir`` will override this. as ``build_dir`` will override this.
``build_in_temp=False`` will produce the C files locally. Working :param build_in_temp: If ``False``, will produce the C files locally. Working
with complex dependencies and debugging becomes more easy. This with complex dependencies and debugging becomes more easy. This
can principally interfere with existing files of the same name. can principally interfere with existing files of the same name.
build_in_temp can be overridden by <modulename>.pyxbld/make_setup_args()
by a dict item of 'build_in_temp'
``setup_args``: dict of arguments for Distribution - see :param setup_args: Dict of arguments for Distribution.
distutils.core.setup() . They are extended/overridden by those of See ``distutils.core.setup()``.
<modulename>.pyxbld/make_setup_args()
``reload_support``: Enables support for dynamic :param reload_support: Enables support for dynamic
reload(<pyxmodulename>), e.g. after a change in the Cython code. ``reload(my_module)``, e.g. after a change in the Cython code.
Additional files <so_path>.reloadNN may arise on that account, when Additional files ``<so_path>.reloadNN`` may arise on that account, when
the previously loaded module file cannot be overwritten. the previously loaded module file cannot be overwritten.
``load_py_module_on_import_failure``: If the compilation of a .py :param load_py_module_on_import_failure: If the compilation of a ``.py``
file succeeds, but the subsequent import fails for some reason, file succeeds, but the subsequent import fails for some reason,
retry the import with the normal .py module instead of the retry the import with the normal ``.py`` module instead of the
compiled module. Note that this may lead to unpredictable results compiled module. Note that this may lead to unpredictable results
for modules that change the system state during their import, as for modules that change the system state during their import, as
the second import will rerun these modifications in whatever state the second import will rerun these modifications in whatever state
the system was left after the import of the compiled module the system was left after the import of the compiled module
failed. failed.
``inplace``: Install the compiled module next to the source file. :param 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. :param language_level: The source language level to use: 2 or 3.
The default is to use the language level of the current Python The default is to use the language level of the current Python
runtime for .py files and Py2 for .pyx files. runtime for .py files and Py2 for ``.pyx`` files.
""" """
if setup_args is None: if setup_args is None:
setup_args = {} setup_args = {}
......
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