feat: Add project documentation, type stubs, Pyright configuration, and parsing examples.

Author: evopen

.gitignore

@@ -1,4 +1,5 @@
 *.out
 build/
+dist/
 benchmark
 *.ipc

CMakeLists.txt

@@ -23,3 +23,10 @@ target_include_directories(rapidobj PRIVATE ${CMAKE_SOURCE_DIR}/src)
 
 # Install the extension module
 install(TARGETS rapidobj LIBRARY DESTINATION .)
+
+# Install typing metadata for IDE autocomplete and static checkers.
+install(FILES
+  ${CMAKE_SOURCE_DIR}/rapidobj.pyi
+  ${CMAKE_SOURCE_DIR}/py.typed
+  DESTINATION .
+)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rapidobj contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,58 @@
+## rapidobj
+
+`rapidobj` is a fast Wavefront OBJ parser exposed as a Python extension module
+using nanobind. It returns NumPy views for mesh data so parsing and data access
+stay efficient.
+
+## Requirements
+
+- Python 3.12+
+- CMake 3.18+
+- A C++17 compiler
+
+## Install
+
+From source:
+
+```bash
+uv sync
+uv build
+python -m pip install dist/rapidobj-0.1.0-cp312-cp312-*.whl
+```
+
+## Minimal Usage
+
+```python
+from rapidobj import parse_obj
+
+result = parse_obj("mesh.obj")
+if not result.ok:
+    raise RuntimeError(result.error_message)
+
+print(result.vertices.shape)  # (V, 3)
+print(result.faces.shape)     # (F, 3)
+print(result.texcoords.shape) # (T, 2)
+```
+
+See `examples/` for runnable scripts.
+
+## API
+
+- `parse_obj(filename: str) -> ObjParseResult`
+- `ObjParseResult.ok: bool`
+- `ObjParseResult.error_message: str`
+- `ObjParseResult.vertex_count: int`
+- `ObjParseResult.normal_count: int`
+- `ObjParseResult.uv_count: int`
+- `ObjParseResult.shape_count: int`
+- `ObjParseResult.material_count: int`
+- `ObjParseResult.texture_paths: list[str]`
+- `ObjParseResult.vertices: np.ndarray`
+- `ObjParseResult.faces: np.ndarray`
+- `ObjParseResult.texcoords: np.ndarray`
+- `ObjParseResult.wedge_texcoord_indices: np.ndarray`
+- `ObjParseResult.wedge_material_ids: np.ndarray`
+
+## Release Notes
+
+Release workflow and checklist are documented in `RELEASE.md`.

RELEASE.md

@@ -0,0 +1,32 @@
+# Release Checklist
+
+## Versioning
+
+Use semantic version tags: `vX.Y.Z`.
+
+## Build and Validate
+
+1. Clean old artifacts.
+   - `rm -rf dist/`
+2. Build distributions.
+   - `uv build`
+3. Validate metadata and artifacts.
+   - `uvx --from twine twine check dist/*`
+4. Smoke test wheel in a clean environment.
+   - Install wheel from `dist/`
+   - Import `rapidobj`
+   - Parse a small `.obj` file and assert `result.ok`
+
+## GitHub Source Release
+
+1. Push commit to `main`.
+2. Create and push tag.
+   - `git tag vX.Y.Z`
+   - `git push origin vX.Y.Z`
+3. Create GitHub release from the tag and include changelog notes.
+
+## PyPI Publish
+
+1. Upload validated artifacts:
+   - `uvx --from twine twine upload dist/*`
+2. Verify package page metadata and install command.

benchmark_overhead.py

@@ -24,6 +24,7 @@
 print("-" * 50)
 
 times = []
+ret = None
 for i in range(iterations):
     start = time.perf_counter()
     ret = parse_obj(obj_path)
@@ -41,5 +42,7 @@
 print(f"Min: {min(times):.2f} ms")
 print(f"Max: {max(times):.2f} ms")
 print()
+if ret is None:
+    raise RuntimeError("No iterations were run")
 print(f"Vertices: {ret.vertices.shape}")
 print(f"Faces: {ret.faces.shape}")

examples/parse_basic.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""Minimal rapidobj parsing example."""
+
+from __future__ import annotations
+
+import sys
+
+from rapidobj import parse_obj
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print(f"Usage: {sys.argv[0]} <mesh.obj>")
+        return 1
+
+    result = parse_obj(sys.argv[1])
+    if not result.ok:
+        print(f"Parse error: {result.error_message}")
+        return 2
+
+    print(f"vertices: {result.vertices.shape}")
+    print(f"faces: {result.faces.shape}")
+    print(f"texcoords: {result.texcoords.shape}")
+    print(f"materials: {result.material_count}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

examples/parse_error.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Minimal error handling example."""
+
+from __future__ import annotations
+
+from rapidobj import parse_obj
+
+
+def main() -> int:
+    result = parse_obj("does-not-exist.obj")
+    if result.ok:
+        print("Unexpected success")
+        return 1
+
+    print("Expected parse failure")
+    print(result.error_message)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

py.typed

@@ -0,0 +1 @@
+

pyproject.toml

@@ -3,10 +3,26 @@ name = "rapidobj"
 version = "0.1.0"
 description = "Fast OBJ parser with Python bindings"
 readme = "README.md"
+license = { file = "LICENSE" }
 requires-python = ">=3.12"
 dependencies = [
     "numpy",
 ]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: C++",
+    "Topic :: Multimedia :: Graphics :: 3D Modeling",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/dhh/rapidobj-play"
+Repository = "https://github.com/dhh/rapidobj-play"
+Issues = "https://github.com/dhh/rapidobj-play/issues"
 
 [dependency-groups]
 dev = [
@@ -23,11 +39,46 @@ requires = ["scikit-build-core>=0.10", "nanobind>=2.4.0"]
 build-backend = "scikit_build_core.build"
 
 [tool.scikit-build]
-minimum-version = "build-system.requires"
+minimum-version = "0.12"
 build-dir = "build/{wheel_tag}"
+sdist.inclusion-mode = "manual"
+sdist.include = [
+    "CMakeLists.txt",
+    "LICENSE",
+    "README.md",
+    "RELEASE.md",
+    "examples/parse_basic.py",
+    "examples/parse_error.py",
+    "py.typed",
+    "pyproject.toml",
+    "rapidobj.pyi",
+    "src/rapidobj.hpp",
+    "src/rapidobj_ext.cpp",
+]
+sdist.exclude = [
+    ".git/*",
+    ".envrc",
+    ".python-version",
+    ".venv/*",
+    ".venv/**",
+    "benchmark",
+    "benchmark.cpp",
+    "benchmark.py",
+    "benchmark_overhead.py",
+    "build/*",
+    "build/**",
+    "dist",
+    "dist/*",
+    "dist/**",
+    "feature_parity.py",
+    "main.cpp",
+    "main.py",
+    "out.ipc",
+    "sampling_points.py",
+    "uv.lock",
+]
 
 [tool.uv.sources]
-pymeshlab = { path = "../building-simp-mono/scripts/wheels/pymeshlab-2025.7-cp312-cp312-manylinux_2_35_x86_64.whl" }
 torch = [{ index = "pytorch-cu129", marker = "sys_platform == 'linux'" }]
 torchvision = [{ index = "pytorch-cu129", marker = "sys_platform == 'linux'" }]