pytest-cython

What it is and what it does

pytest-cython is a pytest plugin that extends pytest's doctest discovery and execution to Cython `.pyx` source files. It allows you to write and run doctests directly in docstrings of Cython extension modules, treating them as executable documentation that pytest can validate. This bridges the gap between Cython's compiled C/C++ extensions and Python's standard doctest workflow, letting developers verify that code examples in their Cython module documentation actually work.

The plugin integrates seamlessly with pytest's command-line interface via the `--doctest-cython` flag. It has a single runtime dependency on pytest itself, making installation straightforward. Compatibility is versioned: the current 0.4.x release targets pytest 9 and Cython 3. The package has been maintained since 2016 and remains actively developed, with no known security vulnerabilities.

Use it for:

• Verify that code examples in Cython module docstrings execute correctly as part of your test suite.
• Document C/C++ extension behavior through executable examples without maintaining separate test files.
• Catch documentation drift in Cython projects by running doctests alongside unit tests in CI/CD.
• Test the public API of compiled Cython modules by embedding doctests in `.pyx` files.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A pytest plugin that runs doctests embedded in Cython `.pyx` extension modules, enabling documentation-driven testing of C/C++ code compiled through Cython.

Yes, if you maintain Cython extensions and want to validate embedded documentation. The plugin is low-friction (one dependency, pure Python), actively maintained, and has no security issues. The main caveat: license terms are undocumented in the package metadata—verify the actual license in the repository before use in proprietary or restricted contexts. Not applicable if you don't use Cython or don't write doctests.

Install

pytest-cython on PyPI

pip install pytest-cython

uv add pytest-cython

poetry add pytest-cython

Installing pytest-cython

Before you install

Low friction: pure Python wheel with only pytest as a runtime dependency. Active maintenance with a recent release (156 days ago) and no known vulnerabilities.

License in practice

License status is unclear—no SPDX identifier or raw license text is recorded. Verify the actual license terms in the repository before adopting in a commercial or restricted context.

Quickstart

pip install pytest-cython

# In your project, run:
pytest --doctest-cython

# Or for a specific .pyx file:
pytest --doctest-cython path/to/module.pyx

Requires Python >=3.8. The --import-mode=importlib option is not supported; --import-mode=prepend with non-editable packages requires PY_IGNORE_IMPORTMISMATCH=1 environment variable.

Verify before relying

• Whether the package is actually licensed under an open-source or proprietary license (license metadata is missing).
• Real-world compatibility with Cython 3.x versions beyond the documented 0.4.x / Cython 3 pairing.
• Whether doctests in compiled .pyx modules execute with the same semantics as Python doctests.

Package facts

Evidence: pytest_cython-0.4.0-py3-none-any.whl

Keywords: pytest, py.test, cython, doctest

Tags

More Utilities packages