Metadata-Version: 2.4
Name: NexoRhino-py-stubs
Version: 0.1.0a1
Summary: Educational Python type stubs for Rhino 8 RhinoCommon, focused on Rhino.Geometry
Project-URL: Repository, https://github.com/Hossein-Nazari-Dev/NexoDesignSuite
Project-URL: Issues, https://github.com/Hossein-Nazari-Dev/NexoDesignSuite/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Stubs Only
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown

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

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

```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 a pending publisher on PyPI 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 `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
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
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.
