rok commented on code in PR #55264:
URL: https://github.com/apache/arrow/pull/55264#discussion_r4590004546


##########
docs/source/developers/python/development.rst:
##########
@@ -105,69 +105,178 @@ Type Checking
 =============
 
 PyArrow provides type stubs (``*.pyi`` files) for static type checking. These
-stubs are located in the ``pyarrow-stubs/`` directory and are automatically
-included in the distributed wheel packages.
+stubs are located in the ``pyarrow-stubs/`` directory, which is laid out as a
+:pep:`561` stub-only package for ``pyarrow``, so type checkers and IDEs pick
+it up from the ``arrow/python`` directory.
+
+.. note::
+   The stubs aren't included in the distributed wheel packages until they are
+   complete (see `GH-49831 <https://github.com/apache/arrow/issues/49831>`_).
+
+Run all the commands in this section from the ``arrow/python`` directory,
+which holds the type checker configurations in ``pyproject.toml``:
+
+.. code-block::
+
+   $ cd arrow/python
+
+Maintaining Type Stubs
+-----------------------
+
+Type stubs for PyArrow are maintained in the ``pyarrow-stubs/``
+directory. These stubs mirror the structure of the main ``pyarrow/`` package.
+
+When adding or modifying public APIs:
+
+1. **Update the corresponding .pyi stub file** in ``pyarrow-stubs/``
+   to reflect the new or changed function/class signatures.
+
+2. **Run type checkers** to ensure the stubs are correct and complete.
+
+The stub files are automatically copied into the built wheel during the build
+process and will be included when users install PyArrow, enabling type checking
+in downstream projects and for users' IDEs.

Review Comment:
   ```suggestion
   The stub files will be automatically copied into the built wheel during the 
build
   process and will be included when users install PyArrow, enabling type 
checking
   in downstream projects and for users' IDEs (once `issue 32609 
<https://github.com/apache/arrow/issues/32609>` is sufficiently resolved).
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to