docs(python): README + examples + type stub for the ifclite-geom wheel

[louistrue]

Why

The ifclite-geom PyO3 wheel (added in #1316, published as ifclite-geom-v4.1.0) shipped with no usage docs: a pip install user has nothing to point at to learn which functions exist or how to call them. This came up directly from someone testing the wheel.

What

• rust/python/README.md — quickstart, full output schema for both functions, notes, examples index. Wired as the PyPI project page via project.readme so it renders on https://pypi.org/project/ifclite-geom.
• pyproject.toml — readme, project.urls Homepage + Documentation.
• examples/ — runnable scripts: quickstart_numpy.py, dump_json.py, export_obj.py (numpy-only).
• ifclite_geom.pyi — type stub (TypedDict-shaped) so editors / type checkers get signatures + docstrings off the compiled module; bundled via [tool.maturin] include.
• src/lib.rs — fold global_id / name into the geometry_data_buffers dict so the fast path matches geometry_data_json (lets a consumer map triangles back to IFC entities); add #[pyo3(signature = (ifc_bytes))] so help() shows the arg.
• Version 4.1.0 → 4.2.0 (Cargo.toml + Cargo.lock). Additive API; the README and the new fields only reach PyPI on the next ifclite-geom-v* tag.

Verification

• cargo check on rust/python passes (run standalone; the crate is workspace-excluded). No new warnings from these edits.
• All example scripts + the stub pass python -m py_compile.
• The python-wheels CI builds wheels for this PR (paths trigger on rust/python/**).

One thing to confirm at review

The type stub ships via [tool.maturin] include = [{ path = "ifclite_geom.pyi", format = "wheel" }]. Please eyeball a CI wheel artifact to confirm ifclite_geom.pyi lands at the wheel root, adjacent to ifclite_geom.<abi>.so (where type checkers look). If maturin places it elsewhere, we switch to a python-source layout. The README, examples, and the global_id/name change are independent of this.

Release note

To publish: tag ifclite-geom-v4.2.0 after merge (existing trusted-publishing workflow).

Summary by CodeRabbit

• New Features

  • Added per-element identity fields (global ID and name) to geometry data exports.
  • Added example scripts demonstrating JSON export, OBJ file generation, and NumPy integration.

• Documentation

  • Added comprehensive module documentation with API reference and usage examples.
  • Added type stubs for improved IDE support and code completion.

• Chores

  • Version bumped to 4.2.0 with updated package metadata.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ifc-lite	Ready	Preview, Comment	Jun 23, 2026 10:39am

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
ifc-lite-dev	Ignored	Preview	Jun 23, 2026 10:39am
ifc-lite-viewer-embed	Ignored		Jun 23, 2026 10:39am

[coderabbitai]

Warning

Review limit reached

@louistrue, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 3 minutes and 22 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses rolling per-developer review limits. Reviews become available again as older review attempts age out of the rolling limit window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 63deed4c-3c5c-4275-b59b-bfdb2e6d6d90

📥 Commits

Reviewing files that changed from the base of the PR and between c24c532 and da88ae0.

📒 Files selected for processing (4)

• rust/python/examples/dump_json.py
• rust/python/examples/export_obj.py
• rust/python/examples/quickstart_numpy.py
• rust/python/ifclite_geom.pyi

📝 Walkthrough

Walkthrough

The ifc-lite-python crate is bumped to 4.2.0. The Rust geometry_data_buffers function now sets global_id and name on each per-element dictionary. A new Python type stub (ifclite_geom.pyi) defines ElementBuffers and GeometryBuffers TypedDicts and is shipped in the wheel via a maturin include directive. A new README.md and three example scripts (NumPy quickstart, JSON dump, OBJ export) are added.

Changes

ifclite-geom v4.2.0: per-element identity, type stubs, packaging, and examples

Layer / File(s)	Summary
Per-element identity fields in Rust bindings and type stubs rust/python/src/lib.rs, rust/python/ifclite_geom.pyi	geometry_data_buffers now sets global_id and name on each element dict from the Rust export struct; docstrings for both functions document the new fields. The type stub introduces ElementBuffers and GeometryBuffers TypedDicts and declares both public entry points with updated signatures.
Wheel packaging and project metadata rust/python/Cargo.toml, rust/python/pyproject.toml	Crate version bumped to 4.2.0; pyproject.toml adds readme, Homepage/Documentation URLs, and a maturin include directive that ships ifclite_geom.pyi in the built wheel.
Public API documentation rust/python/README.md	New README covers installation, quick-start, both API entry points with buffer formats and return shapes, output semantics (welded meshes, RTC offset, occurrences-only scope), error types, example inventory, and license.
Example scripts rust/python/examples/quickstart_numpy.py, rust/python/examples/dump_json.py, rust/python/examples/export_obj.py	Three new scripts: quickstart_numpy.py inspects geometry buffers with NumPy; dump_json.py writes geometry JSON to disk; export_obj.py emits a Wavefront OBJ with global 1-based vertex indexing per element. Each includes a CLI entry point.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• LTplus-AG/ifc-lite#1316: Introduced the original PyO3 geometry-data binding and GeometryDataExport/buffer export pipeline that this PR extends with global_id and name fields.
• LTplus-AG/ifc-lite#1324: Modified the same geometry_data_buffers/geometry_data_json functions in rust/python/src/lib.rs for PyO3 0.29 compatibility, touching the same dict construction code this PR also changes.

Poem

🐇 A rabbit hops through IFC land,
Now every shape has a name in hand!
global_id stamped, name tucked in tight,
Stubs shipped in the wheel, the types look right.
Three example scripts to light the way—
OBJ, JSON, NumPy hooray! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: adding documentation (README), type stub, and examples for the ifclite-geom Python wheel.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/python-wheel-readme

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c24c5327b7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Add the required MPL header to new source files

The repo's AGENTS.md says every new source file must start with the MPL-2.0 header, but the new Python examples and ifclite_geom.pyi begin directly with docstrings/type-stub comments. This leaves the newly added source files outside the repository's required licensing convention; please add the standard header to each new source file.

Useful? React with 👍 / 👎.

[louistrue]

Addressed the Codex review: added the MPL-2.0 header (Python # style, per LICENSE_HEADER.md) to the three new examples/*.py files and ifclite_geom.pyi in da88ae0. Markdown docs follow the existing convention of no header.