Metadata-Version: 2.4
Name: NexoRhino-py-stubs
Version: 1.1.0
Summary: Educational Python type stubs for Rhino 8 RhinoCommon, focused on Rhino.Geometry
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/Hossein-Nazari-Dev/NexoDesignSuite
Project-URL: Issues, https://github.com/Hossein-Nazari-Dev/NexoDesignSuite/issues
Project-URL: Documentation, https://nexonest.com/nexorhino/geometry.html
Project-URL: Homepage, https://nexonest.com/projects-pages/nexoRhino.html
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Stubs Only
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# 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](vscode-extension/README.md) 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](vscode-extension/PUBLISHING.md).

### PyCharm plugin

For JetBrains users, the [NexoRhino PyCharm plugin](pycharm-plugin/README.md)
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](pycharm-plugin/PUBLISHING.fa.md).

### 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.

```powershell
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

```powershell
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:

| Field | Value |
| --- | --- |
| PyPI Project Name | `NexoRhino-py-stubs` |
| Owner | `Hossein-Nazari-Dev` |
| Repository name | `NexoDesignSuite` |
| Workflow name | `publish.yml` |
| Environment name | `pypi` |

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
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
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:

```powershell
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](RhinoPy/rhino-stubs/Guidance.md) for educational notes,
published learning links, and the current interop limits.


### Tests inside Rhino and PyCharm

With Rhino open and its `StartScriptServer` running:

```powershell
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](https://nexonest.com/nexorhino/geometry.html#Rhino.Geometry.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:

```powershell
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](CHANGELOG.md)
and [the release procedure](RELEASING.md).

## Continuity and recovery

[PROJECT_RECOVERY.md](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.
