From af0a46760fbfbcac8dc356c90e68cca3465f80f9 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 14 Jun 2022 17:53:31 +0100 Subject: [PATCH 1/3] [Docs] Move Cython remarks to the new ext_modules page This helps to consolidate all the information about extensions in a single place and make it easier for users to find the correct guidance. --- docs/userguide/dependency_management.rst | 4 +- docs/userguide/distribution.rst | 38 ------------- docs/userguide/ext_modules.rst | 68 ++++++++++++++++++------ 3 files changed, 55 insertions(+), 55 deletions(-) diff --git a/docs/userguide/dependency_management.rst b/docs/userguide/dependency_management.rst index c7f1e05921..a35d7bfc53 100644 --- a/docs/userguide/dependency_management.rst +++ b/docs/userguide/dependency_management.rst @@ -15,6 +15,8 @@ dependency. :pep:`direct URLs <440#direct-references>`. +.. _build-requires: + Build system requirement ======================== @@ -24,7 +26,7 @@ do the packaging (in our case, ``setuptools`` of course). This needs to be specified in your ``pyproject.toml`` file (if you have forgot what this is, go to :doc:`/userguide/quickstart` or :doc:`/build_meta`): -.. code-block:: ini +.. code-block:: toml [build-system] requires = ["setuptools"] diff --git a/docs/userguide/distribution.rst b/docs/userguide/distribution.rst index db0f1a5f59..b4f319852e 100644 --- a/docs/userguide/distribution.rst +++ b/docs/userguide/distribution.rst @@ -117,44 +117,6 @@ Or of course you can create more elaborate aliases that do all of the above. See the sections below on the :ref:`egg_info ` and :ref:`alias ` commands for more ideas. -Distributing Extensions compiled with Cython --------------------------------------------- - -``setuptools`` will detect at build time whether Cython is installed or not. -If Cython is not found ``setuptools`` will ignore pyx files. - -To ensure Cython is available, include Cython in the build-requires section -of your pyproject.toml:: - - [build-system] - requires=[..., "cython"] - -Built with pip 10 or later, that declaration is sufficient to include Cython -in the build. For broader compatibility, declare the dependency in your -setup-requires of setup.cfg:: - - [options] - setup_requires = - ... - cython - -As long as Cython is present in the build environment, ``setuptools`` includes -transparent support for building Cython extensions, as -long as extensions are defined using ``setuptools.Extension``. - -If you follow these rules, you can safely list ``.pyx`` files as the source -of your ``Extension`` objects in the setup script. If it is, then ``setuptools`` -will use it. - -Of course, for this to work, your source distributions must include the C -code generated by Cython, as well as your original ``.pyx`` files. This means -that you will probably want to include current ``.c`` files in your revision -control system, rebuilding them whenever you check changes in for the ``.pyx`` -source files. This will ensure that people tracking your project in a revision -control system will be able to build it even if they don't have Cython -installed, and that your source releases will be similarly usable with or -without Cython. - .. _Specifying Your Project's Version: diff --git a/docs/userguide/ext_modules.rst b/docs/userguide/ext_modules.rst index 213e13c0c2..69b0a286b1 100644 --- a/docs/userguide/ext_modules.rst +++ b/docs/userguide/ext_modules.rst @@ -45,11 +45,23 @@ To instruct setuptools to compile the ``foo.c`` file into the extension module ) .. seealso:: - You can find more information on the `Python docs about C/C++ extensions`_. - Alternatively, you might also be interested in learn about `Cython`_. + You can find more information on the `Python docs about C/C++ extensions`_. + Alternatively, you might also be interested in learn about `Cython`_. - If you plan to distribute a package that uses extensions across multiple - platforms, :pypi:`cibuildwheel` can also be helpful. + If you plan to distribute a package that uses extensions across multiple + platforms, :pypi:`cibuildwheel` can also be helpful. + +.. important:: + All files used to compile your extension need to be available on the system + when building the package, so please make sure to include some documentation + on how developers interested in building your package from source + can obtain operating system level dependencies + (e.g. compilers and external binary libraries/artifacts). + + You will also need to make sure that all auxiliary files that are contained + inside your :term:`project` (e.g. C headers authored by you or your team) + are configured to be included in your :term:`sdist `. + Please have a look on our section on :ref:`Controlling files in the distribution`. Compiler and linker options @@ -89,23 +101,47 @@ The linker searches for libraries in the following order: * first, in directories given by ``-L`` options (in left-to-right order), * then, in directories given by the environment variable ``LIBRARY_PATH`` (in left-to-right order). -.. important:: - All files used to compile your extension need to be available on the system - when building the package, so please make sure to include some documentation - on how developers interested in building your package from source - can obtain operating system level dependencies - (e.g. compilers and external binary libraries/artifacts). - You will also need to make sure that all auxiliary files that are contained - inside your :term:`project` (e.g. C headers authored by you or your team) - are configured to be included in your :term:`sdist `. - Please have a look on our section on :ref:`Controlling files in the distribution`. +Distributing Extensions compiled with Cython +============================================ + +``setuptools`` will detect at build time whether :pypi:`Cython` is installed or not. +If Cython is not found ``setuptools`` will ignore ``.pyx`` files. + +To ensure Cython is available, include Cython in the :ref:`build-requires` section +of your ``pyproject.toml``: + +.. code-block:: toml + + [build-system] + requires = [..., "cython"] + +For :pypi:`pip` 10 or later, that declaration is sufficient to include Cython +in the build. + +As long as Cython is present in the build environment **and** extensions +are defined using ``setuptools.Extension``, ``setuptools`` includes +transparent support for building Cython extensions. + +If you follow these rules, you can safely list ``.pyx`` files as the source +of your ``Extension`` objects in the setup script. If it is, then ``setuptools`` +will use it. +Of course, for this to work, your source distributions must include the C +code generated by Cython, as well as your original ``.pyx`` files. This means +that you will probably want to include current ``.c`` files in your :wiki:`revision +control system`, rebuilding them whenever you check changes in for the ``.pyx`` +source files. This will ensure that people tracking your project in a revision +control system will be able to build it even if they don't have Cython +installed, and that your source releases will be similarly usable with or +without Cython. +Please checkout our docs on :ref:`controlling files in the distribution` for +more information. ---- -API Reference -------------- +Extension API Reference +======================= .. autoclass:: setuptools.Extension From 89d9f0afcb838b4dc236461acf5eb1f558036141 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 14 Jun 2022 17:57:29 +0100 Subject: [PATCH 2/3] Add news fragment --- changelog.d/3373.doc.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 changelog.d/3373.doc.rst diff --git a/changelog.d/3373.doc.rst b/changelog.d/3373.doc.rst new file mode 100644 index 0000000000..c9cf808289 --- /dev/null +++ b/changelog.d/3373.doc.rst @@ -0,0 +1,2 @@ +Moved remarks about using :pypi:`Cython` to the newly created page for +extension modules. From a4117e13b4ae096ca7e5d150974f49a7ce5328ca Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 14 Jun 2022 19:29:12 +0100 Subject: [PATCH 3/3] Simplify text about Cython --- docs/userguide/ext_modules.rst | 44 ++++++++++++++++------------------ 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/docs/userguide/ext_modules.rst b/docs/userguide/ext_modules.rst index 69b0a286b1..0467f4ec15 100644 --- a/docs/userguide/ext_modules.rst +++ b/docs/userguide/ext_modules.rst @@ -105,36 +105,33 @@ The linker searches for libraries in the following order: Distributing Extensions compiled with Cython ============================================ -``setuptools`` will detect at build time whether :pypi:`Cython` is installed or not. -If Cython is not found ``setuptools`` will ignore ``.pyx`` files. +When your :pypi:`Cython` extension modules *are declared using the* +:class:`setuptools.Extension` *class*, ``setuptools`` will detect at build time +whether Cython is installed or not. -To ensure Cython is available, include Cython in the :ref:`build-requires` section -of your ``pyproject.toml``: +If Cython is present, then ``setuptools`` will use it to build the ``.pyx`` files. +Otherwise, ``setuptools`` will try to find and compile the equivalent ``.c`` files +(instead of ``.pyx``). These files can be generated using the +`cython command line tool`_. + +You can ensure that Cython is always automatically installed into the build +environment by including it as a :ref:`build dependency ` in +your ``pyproject.toml``: .. code-block:: toml [build-system] requires = [..., "cython"] -For :pypi:`pip` 10 or later, that declaration is sufficient to include Cython -in the build. - -As long as Cython is present in the build environment **and** extensions -are defined using ``setuptools.Extension``, ``setuptools`` includes -transparent support for building Cython extensions. - -If you follow these rules, you can safely list ``.pyx`` files as the source -of your ``Extension`` objects in the setup script. If it is, then ``setuptools`` -will use it. - -Of course, for this to work, your source distributions must include the C -code generated by Cython, as well as your original ``.pyx`` files. This means -that you will probably want to include current ``.c`` files in your :wiki:`revision -control system`, rebuilding them whenever you check changes in for the ``.pyx`` -source files. This will ensure that people tracking your project in a revision -control system will be able to build it even if they don't have Cython -installed, and that your source releases will be similarly usable with or -without Cython. +Alternatively, you can include the ``.c`` code that is pre-compiled by Cython +into your source distribution, alongside the original ``.pyx`` files (this +might save a few seconds when building from an ``sdist``). +To improve version compatibility, you probably also want to include current +``.c`` files in your :wiki:`revision control system`, and rebuild them whenever +you check changes in for the ``.pyx`` source files. +This will ensure that people tracking your project will be able to build it +without installing Cython, and that there will be no variation due to small +differences in the generate C files. Please checkout our docs on :ref:`controlling files in the distribution` for more information. @@ -150,3 +147,4 @@ Extension API Reference .. _Cython: https://cython.readthedocs.io/en/stable/index.html .. _directory options: https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html .. _environment variables: https://gcc.gnu.org/onlinedocs/gcc/Environment-Variables.html> +.. _cython command line tool: https://cython.readthedocs.io/en/stable/src/userguide/source_files_and_compilation.html