add stubs

Author: cvanelteren

.gitattributes

@@ -0,0 +1,2 @@
+ultraplot/*.pyi linguist-generated=true
+ultraplot/**/*.pyi linguist-generated=true

.github/workflows/main.yml

@@ -22,6 +22,7 @@ jobs:
               - 'environment.yml'
               - '.github/workflows/**'
               - 'tools/ci/**'
+              - 'tools/generate_stubs.py'
 
   select-tests:
     runs-on: ubuntu-latest
@@ -99,6 +100,7 @@ jobs:
             --always-full 'pyproject.toml' \
             --always-full 'environment.yml' \
             --always-full 'ultraplot/__init__.py' \
+            --always-full 'tools/generate_stubs.py' \
             --ignore 'docs/**' \
             --ignore 'README.rst'
           echo "Selection output:"
@@ -138,6 +140,42 @@ jobs:
           echo "Detected test matrix: $(echo "$OUTPUT" | jq -c '.test_matrix')"
           python tools/ci/version_support.py --format github-output >> $GITHUB_OUTPUT
 
+  stubs:
+    name: Static API stubs
+    runs-on: ubuntu-latest
+    needs:
+      - run-if-changes
+    if: always() && needs.run-if-changes.outputs.run == 'true'
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Install UltraPlot and typing tools
+        run: pip install -e ".[typing]"
+
+      - name: Verify generated stubs
+        run: python tools/generate_stubs.py --check
+
+      - name: Check Pylance-compatible consumption
+        run: basedpyright tools/ci/stub_consumer.py --level error
+
+      - name: Check Pyrefly consumption and generated syntax
+        run: |
+          pyrefly check tools/ci/stub_consumer.py \
+            --search-path . \
+            --python-interpreter-path "$(command -v python)" \
+            --progress-bar no
+          pyrefly check 'ultraplot/**/*.pyi' \
+            --search-path . \
+            --python-interpreter-path "$(command -v python)" \
+            --ignore-missing-imports icecream \
+            --ignore-missing-imports matplotlib.fontconfig_pattern \
+            --progress-bar no
+
   coverage:
     name: Coverage
     runs-on: ubuntu-latest
@@ -213,14 +251,15 @@ jobs:
     needs:
       - build
       - run-if-changes
+      - stubs
     if: always()
     runs-on: ubuntu-latest
     steps:
       - run: |
           if [[ '${{ needs.run-if-changes.outputs.run }}' == 'false' ]]; then
             echo "No changes detected, tests skipped."
           else
-            if [[ '${{ needs.build.result }}' == 'success' ]]; then
+            if [[ '${{ needs.build.result }}' == 'success' && '${{ needs.stubs.result }}' == 'success' ]]; then
               echo "All tests passed successfully!"
             else
               echo "Tests failed!"

docs/contributing.rst

@@ -130,6 +130,37 @@ When adding a new submodule, make sure it is compatible with the lazy loader:
 By following these steps, your module will integrate cleanly with the lazy loading
 system without requiring manual registry updates.
 
+Editor type information and docstrings
+--------------------------------------
+
+UltraPlot ships generated ``.pyi`` files so static analysis tools such as Pylance
+and Pyrefly can see the public API and fully expanded docstrings without importing
+the package. The runtime modules remain the source of truth and continue to use the
+lazy loader.
+
+After changing a Python signature, annotation, public import, or docstring snippet,
+install the pinned typing tools, regenerate the stubs from the repository root, and
+commit the updated ``.pyi`` files:
+
+.. code-block:: bash
+
+   pip install -e ".[typing]"
+   python tools/generate_stubs.py
+
+Installation does not generate or modify these files. Release artifacts include the
+stubs that were generated and checked into the repository. The generator runs
+Pyrefly against an isolated source-only package, merges its inferred annotations
+into a complete syntax-derived representation of the package, and statically
+expands registered docstring snippets. This preserves declarations that Pyrefly
+cannot discover through decorators or lazy loading.
+
+To rerun inference and verify that every committed stub is up to date without
+changing files, run:
+
+.. code-block:: bash
+
+   python tools/generate_stubs.py --check
+
 
 .. _contrib_pr:
 

pyproject.toml

@@ -50,7 +50,7 @@ packages = {find = {exclude=["docs*", "baseline*", "logo*"]}}
 include-package-data = true
 
 [tool.setuptools.package-data]
-ultraplot = ["py.typed"]
+ultraplot = ["py.typed", "*.pyi", "**/*.pyi"]
 
 [tool.setuptools_scm]
 write_to = "ultraplot/_version.py"
@@ -74,6 +74,10 @@ filterwarnings = [
 ]
 mpl-default-style = { axes.prop_cycle = "cycler('color', ['#4c72b0ff', '#55a868ff', '#c44e52ff', '#8172b2ff', '#ccb974ff', '#64b5cdff'])" }
 [project.optional-dependencies]
+typing = [
+    "basedpyright==1.31.4",
+    "pyrefly==1.2.0",
+]
 docs = [
     "jupyter",
     "jupytext",

tools/ci/stub_consumer.py

@@ -0,0 +1,6 @@
+"""Representative lazy public imports consumed by static type checkers."""
+
+import ultraplot as uplt
+
+reveal_type(uplt.subplots)
+reveal_type(uplt.Axes.format)