chore(python): Add minimal type stubs for .pyx files (#468)

These are generic stubs that are not particularly good; however, they
are low-maintenance and do the trick of listing methods and Enum values
for the limited set of user-facing functions that return a `CBuffer` or
`CArrayView`. They are also nice for local development since the
user-facing interface wraps the Cython code.

<img width="401" alt="Screenshot 2024-05-14 at 12 36 18 PM"
src="https://github.com/apache/arrow-nanoarrow/assets/10995762/b855fe9f-aa3b-4ad2-9b91-a5dfca07fa90">

Author: paleolimbot

.gitattributes

@@ -17,3 +17,4 @@
 
 dist/* linguist-generated
 extensions/nanoarrow_ipc/thirdparty/* linguist-vendored
+python/src/nanoarrow/*.pxi linguist-generated

.github/workflows/python.yaml

@@ -58,6 +58,19 @@ jobs:
         run: |
           pytest python/tests -v -s
 
+      - name: Check type stubs
+        if: success() && matrix.python-version == '3.12'
+        run: |
+          pip install mypy "black==22.3.0"
+          python/generate_type_stubs.sh
+
+          if git diff --name-only | grep -e "\\.pxi$"; then
+            echo "Type stubs were changed. Update them with python/generate_type_stubs.sh."
+          fi
+
+          stubtest nanoarrow._lib
+          stubtest nanoarrow._ipc_lib
+
       - name: Run doctests
         if: success() && matrix.python-version == '3.12'
         run: |

python/generate_type_stubs.sh

@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+SOURCE_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+# Generates src/nanoarrow/*.pxi given the currently installed copy of
+# nanoarrow. Requires mypy and black (where black is pinned to the
+# same version as in pre-commit)
+
+pushd "${SOURCE_DIR}"
+
+# Generate stubs using mypy
+stubgen --module nanoarrow._lib --include-docstrings -o src
+stubgen --module nanoarrow._ipc_lib --include-docstrings -o src
+
+# Reformat stubs
+black src/nanoarrow/*.pyi
+
+popd

python/src/nanoarrow/_ipc_lib.pyi

@@ -0,0 +1,28 @@
+import _cython_3_0_10
+from _typeshed import Incomplete
+
+__reduce_cython__: _cython_3_0_10.cython_function_or_method
+__setstate_cython__: _cython_3_0_10.cython_function_or_method
+__test__: dict
+init_array_stream: _cython_3_0_10.cython_function_or_method
+
+class CIpcInputStream:
+    @classmethod
+    def __init__(cls, *args, **kwargs) -> None:
+        """Create and return a new object.  See help(type) for accurate signature."""
+    @staticmethod
+    def from_readable(*args, **kwargs): ...
+    def is_valid(self, *args, **kwargs): ...
+    def release(self, *args, **kwargs): ...
+    def __reduce__(self): ...
+
+class PyInputStreamPrivate:
+    close_obj: Incomplete
+    obj: Incomplete
+    @classmethod
+    def __init__(cls, *args, **kwargs) -> None:
+        """Create and return a new object.  See help(type) for accurate signature."""
+    def set_buffer(self, *args, **kwargs): ...
+    def __len__(self) -> int:
+        """Return len(self)."""
+    def __reduce__(self): ...