NexoRhino-py-stubs: Educational Stubs for RhinoCommon in Python

Welcome to NexoRhino-py-stubs, a growing set of Python stub files (.pyi) for the RhinoCommon API.

This project is a dedicated resource designed to make Python scripting for Rhino and Grasshopper more intuitive and educational. My primary goal is to provide rich docstrings, computational geometry notes, and clear code examples directly within your IDE's autocompletion, turning the stubs into a powerful learning tool.

Features

• Geometry Type Hinting: Provides a Rhino.Geometry baseline plus selected supporting namespaces for completion and static analysis. Coverage of RhinoCommon as a whole is incomplete.
• Educational Docstrings: Each class, method, and property is documented with detailed explanations, mathematical concepts, and practical usage examples. The goal is to explain not just what the code does, but also why and how it works.
• API-derived baseline: Generated signatures are derived from RhinoCommon; Python interop details and overloads still need validation in Rhino.

Installation

The distribution is named NexoRhino-py-stubs, version 0.1.0a1. It installs a partial PEP 561 Rhino-stubs package. It contains no runtime implementation and does not install Rhino. Execute scripts inside a compatible Rhino environment; installing stubs alone does not make import Rhino runnable.

python -m pip install NexoRhino-py-stubs==0.1.0a1

The PyPI command is available after the first release is published. To install directly from a checkout before publication, run python -m pip install ..

Install into the interpreter used by your editor. In VS Code use Python: Select Interpreter to select that interpreter. The committed settings also enable source-stub lookup when opening either the repository root or RhinoPy directly. Python/Pylance must be enabled.

In PyCharm, open Settings > Project > Python Interpreter, add an existing local interpreter, and select the interpreter where you installed the package.

Build and publish

python -m pip install build twine
python -m build
python -m twine check --strict dist/*

Publishing uses GitHub Actions and PyPI Trusted Publishing (no API token). Configure a pending publisher on PyPI with these exact values:

1. In the GitHub repository, create the pypi environment under Settings > Environments. Its deployment rules must allow the release tag.
2. Commit and push the package files and .github/workflows/publish.yml.
3. Check that the Build and publish to PyPI workflow succeeds.
4. Create and publish a GitHub Release with tag v0.1.0a1 targeting the commit containing these changes. Mark this alpha release as a pre-release.
5. The workflow builds and checks both distributions, then publishes to PyPI.

Pushes, pull requests, and manual workflow runs only build and validate. Publication happens when a GitHub Release is published. For future releases, update project.version in pyproject.toml and use the matching v<version> tag. PyPI does not allow replacing files for an already published version.

No license has been assigned to this repository yet.

This is an alpha: RhinoDoc.pyi, UnitSystem.pyi, Display/ViewportInfo.pyi, and DocObjects/__init__.pyi are currently empty. Syntax and packaging checks do not establish full API correctness or compatibility with every editor.

Scope and quality standard

This repository is a Python-first, English-language learning companion for Rhino.Geometry. Every completed stub follows the same standard:

1. An API signature is checked against the official RhinoCommon documentation.
2. Overloads are represented when they materially improve editor completion.
3. Public classes and commonly used members explain the geometric concept in plain English, including units, mutation, and common pitfalls where useful.
4. Examples are short RhinoPython snippets that can be copied into Rhino.

The namespace is delivered in coherent groups. The current baseline covers the public types exposed by Rhino 8's Rhino.Geometry namespace. The frequently used numeric and spatial value types are hand-curated with additional learning notes; the remaining baseline API is generated from the installed RhinoCommon assembly and its official XML documentation.

Regenerating the baseline

On a computer with Rhino 8 installed, run the following from the repository root in PowerShell:

powershell -ExecutionPolicy Bypass -File .\RhinoPy\tools\generate_geometry_stubs.ps1

The generator preserves the hand-curated foundation files and regenerates the remaining public Rhino.Geometry types from RhinoCommon.dll.

Verifying the stubs

Run the verification suite after regenerating or editing a stub:

powershell -ExecutionPolicy Bypass -File .\RhinoPy\tests\test_geometry_stubs.ps1

It validates Python syntax, complete public-type coverage, namespace exports, public method-name coverage in generated baseline files, and the learning contract/docstrings in the hand-curated foundation. The suite reads the installed RhinoCommon DLL, so it detects API drift when Rhino is updated.