This is an automated email from the ASF dual-hosted git repository.
alenka pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new 8a8e574b35 GH-49503: [Docs][Python] Documenting .pxi doctests are
tested via lib.pyx (#49515)
8a8e574b35 is described below
commit 8a8e574b350498e547ad7eaef2ef8fd7049d7ac0
Author: Bhavana Sundar <[email protected]>
AuthorDate: Fri Mar 20 08:38:40 2026 -0700
GH-49503: [Docs][Python] Documenting .pxi doctests are tested via lib.pyx
(#49515)
### Rationale for this change
Running `python -m pytest --doctest-cython` directly on `.pxi` files
doesn't work because Cython `.pxi` files are included in `.pyx` files at
compile time. This isn't documented, which could _potentially_ confuse
contributors.
Please see discussion in #49279 (comment) by @ AlenkaF for additional
context.
### What changes are included in this PR?
Added a `note` to the Doctest section of the Developing PyArrow
documentation explaining that:
- `.pxi` files cannot be tested directly with `--doctest-cython`
- Doctests should be run on the `.pyx` file they are included in (e.g.,
`lib.pyx`)
- Errors will appear under the `.pyx` file, not the original `.pxi` filename
### Are these changes tested?
Documentation-only change. No code changes.
### Are there any user-facing changes?
No.
* GitHub Issue: #49503
Lead-authored-by: Bhavana Sundar <[email protected]>
Co-authored-by: Alenka Frim <[email protected]>
Signed-off-by: AlenkaF <[email protected]>
---
docs/source/developers/python/development.rst | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/docs/source/developers/python/development.rst
b/docs/source/developers/python/development.rst
index 5757b76187..e70fb44307 100644
--- a/docs/source/developers/python/development.rst
+++ b/docs/source/developers/python/development.rst
@@ -195,6 +195,17 @@ for ``.py`` files or
for ``.pyx`` and ``.pxi`` files. In this case you will also need to
install the `pytest-cython <https://github.com/lgpage/pytest-cython>`_ plugin.
+.. note::
+ Cython ``.pxi`` files are included in ``.pyx`` files at compile time,
+ so ``--doctest-cython`` cannot be run directly on ``.pxi`` files.
+ In PyArrow, all ``.pxi`` files are included into ``lib.pyx``, so run
+ doctests on that file::
+
+ $ python -m pytest --doctest-cython path/to/lib.pyx
+
+ Any doctest errors originating from ``.pxi`` files will appear under
+ ``lib.pyx``, not the original ``.pxi`` filename.
+
Testing Documentation Examples
-------------------------------
