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: Selected types and methods include concise computational geometry notes on parameters, units, topology, approximation, and common pitfalls. There are 182 authored learning entries and 16 Rhino examples in the companion reference. Remaining members use API-derived summaries.
• API-derived baseline: Generated signatures are derived from RhinoCommon; Python interop details and overloads still need validation in Rhino.

Installation

VS Code extension (no terminal required)

The companion NexoRhino extension bundles these stubs for Pylance. Install its VSIX from Extensions > ... > Install from VSIX..., then open a project folder. Version 1.1.0 (stable) configures Pylance automatically; NexoRhino: Repair IntelliSense Configuration is available for manual repair. Marketplace publication is a separate step; see the extension build and publishing guide.

PyCharm plugin

For JetBrains users, the NexoRhino PyCharm plugin bundles the same stubs. Install its ZIP with Plugins > Install Plugin from Disk, then restart the IDE and open a project. Version 1.1.0 (stable) automatically attaches its stubs and restores them after project-model sync. Tools > NexoRhino > Repair Code Insight Configuration is available for manual repair. This build targets PyCharm 2026.2.x. See the Persian publishing guide.

Python package

The distribution is named NexoRhino-py-stubs, version 1.1.0. 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==1.1.0

The pinned 1.1.0 command is available after this version 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 or verify a PyPI Trusted Publisher 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 v1.1.0 targeting the commit containing these changes. Use a normal release after all release checks pass.
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.

The existing NexoNest proprietary terms are included in LICENSE; third-party attribution is in NOTICE.

This stable release has a bounded, partial scope. The Geometry baseline and selected supporting types are API-derived, but supporting namespaces remain partial. ViewportInfo belongs to Rhino.DocObjects. Static checks and packaging checks do not establish full API correctness or compatibility with every Rhino Python runtime or 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 current baseline represents the public top-level types in Rhino 8's Rhino.Geometry namespace. Every signature is generated from RhinoCommon and its matching XML documentation. Authored short and extended explanations live in the separate learning catalogue and survive regeneration.

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 regenerates every public Rhino.Geometry type and the selected supporting files (RhinoDoc, UnitSystem, RhinoViewport, ViewportInfo, DimensionStyle, and CommonObject) from RhinoCommon.dll and the matching XML documentation. Generation is deterministic and leaves identical files untouched. All Geometry types, including the seven learning foundations, are generated from the installed API. Authored education lives in the JSON catalogue; no signature file bypasses generation.

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 syntax, bound annotations, local imports, overload groups, public-type coverage, namespace exports, inheritance, Python input names and output tuple shapes for out/ref, and preserved educational notes. The suite reads the installed RhinoCommon DLL, so it detects API drift when Rhino is updated.

Portable checks do not need Rhino:

python RhinoPy/tests/test_stub_contracts.py
python RhinoPy/tests/test_learning_reference.py
python -m pip install -r RhinoPy/tests/requirements.txt
python -m pyright --project RhinoPy/tests/pyrightconfig.json

Pyright checks all stubs and consumer examples, including inherited curve members, multiple overloads, output tuples, and class/instance method binding. The portable suite skips the installed-DLL and generator integration tests; the PowerShell suite runs both, including restoration of stale foundation output, unchanged-file timestamps, regeneration stability and learning-link validation. These checks also run in the Python package build workflow.

See the authoring guidance for educational notes, published learning links, and the current interop limits.

Tests inside Rhino and PyCharm

With Rhino open and its StartScriptServer running:

powershell -NoProfile -ExecutionPolicy Bypass -File RhinoPy/tests/test_rhino_host.ps1

This checks real Python.NET calls without adding objects to the active document. The PyCharm plugin's platform tests additionally check generated member completion, returned-point completion, Python signatures, and educational quick documentation. See the host-verification section of the authoring guidance for tested versions and PyCharm educational documentation. Educational hover in Rhino is outside this package's supported scope.

Learning reference and release order

The canonical education source is RhinoPy/tools/geometry-learning-notes.json. Short notes appear in PyCharm Quick Documentation. Extended explanations, topic and class tags, 16 executable examples, and all 205 class / 2,583 member targets are rendered into the NexoNest reference. Overloads share one method anchor. Ctrl+Q shows a dedicated clickable tag such as #Curve.ClosestPoint immediately below the signature. The extended reference adds 25 concept tutorials and 14 worked numerical explanations with use cases, common mistakes and related lessons. Shared tutorials live in RhinoPy/tools/geometry-learning-topics.json.

The URL contract is https://nexonest.com/nexorhino/geometry.html#Rhino.Geometry.Class.Member. For example, Curve.ClosestPoint opens that exact lesson. Member names and fragment case remain stable across releases.

Build or check the website copies using an existing NexoNest checkout:

python RhinoPy/tools/learning_reference.py --site-root C:/path/to/NexoNest
python RhinoPy/tools/learning_reference.py --site-root C:/path/to/NexoNest --check

The builder writes nexorhino/geometry.html, css/nexorhino-learning.css, and js/nexorhino-learning.js; it requires no website framework or remote API. Update NexoNest's project guide and run its SEO/guide checks after integrating changes. Publish and verify the website before releasing packages that contain these URLs. Local builds do not prove public availability. See CHANGELOG.md and the release procedure.

Continuity and recovery

PROJECT_RECOVERY.md records recovery paths and backup gaps. Keep durable technical context in the existing guide/map and update recovery coverage when data locations change.