From 4ea14085f7a44453ed51bb754b7edc50721d6283 Mon Sep 17 00:00:00 2001 From: Jan Petykiewicz Date: Tue, 17 Nov 2026 15:07:40 -0800 Subject: [PATCH] Clarify Pheon installation and first-use examples --- README.md | 2 +- docs/arrow-schema.md | 2 +- docs/cli.md | 14 +++++++++----- docs/python.md | 41 ++++++++++++++++++++--------------------- 4 files changed, 31 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 55285ab..470c168 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Run Python outside the source checkout to use the installed package: from pheon import arrow layout = arrow.read_path("chip.gds") -print(layout.field("cell_names")[0].as_py()) +print(layout.field("lib_name")[0].as_py()) ``` Source installation needs Rust; prebuilt Python wheels bundle the native library. diff --git a/docs/arrow-schema.md b/docs/arrow-schema.md index 97ffecd..a0abd94 100644 --- a/docs/arrow-schema.md +++ b/docs/arrow-schema.md @@ -21,7 +21,7 @@ version and the separate C API version. | `lib_name` | Utf8 | Library name. | | `mod_time`, `acc_time` | FixedSizeList(Int16, 6) | Modification/access time: year, month, day, hour, minute, second. | | `cells` | List(Cell) | Cell records. | -| `cell_names` | List(Utf8) | Names indexed by cell ID. | +| `cell_names` | List(Utf8) | Names indexed by cell ID, including targets without cell definitions. | | `layers` | List(UInt32) | Packed layer/type pairs indexed by layer ID. | ### Cell diff --git a/docs/cli.md b/docs/cli.md index 843bd68..e01228d 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,11 +1,14 @@ # Command-line tools Use `pheon` to inspect a GDSII file, compare revisions, or trace cell references. -The CLI runs independently of Python. +Use uncompressed `.gds` files with the CLI. It runs independently of Python. ## Install -From a source checkout, with Rust 1.88 or newer: +If you downloaded a CLI archive, extract it and add the directory containing +`pheon` (`pheon.exe` on Windows) to your `PATH`. Run `pheon --help` to check it. + +To install from a source checkout, use Rust 1.88 or newer: ```sh cargo install --path . --locked --bin pheon @@ -37,9 +40,10 @@ pheon diff before.gds after.gds --hierarchy ascii --max-changes 20 pheon diff before.gds after.gds --format json > report.json ``` -Reports identify changed objects and their fields, plus affected ancestors in -the hierarchy. Objects that can be paired unambiguously receive a replacement -explanation; ambiguous changes remain removals and additions. +Text reports group changes by cell. A `-` line shows an object from the old file +and a `+` line shows one from the new file. A `~` line explains a likely +replacement when Pheon can pair the two uniquely. Request a hierarchy view to +see which parent cells are affected. | Exit code | Meaning | | --- | --- | diff --git a/docs/python.md b/docs/python.md index 7f123ca..fa48cf4 100644 --- a/docs/python.md +++ b/docs/python.md @@ -6,16 +6,16 @@ Python 3.11 or newer is required. ## Install -To install a published package with Arrow support: +To install a PyPI release with Arrow support: ```sh python -m pip install 'pheon[arrow]' ``` -From a source checkout, use `python -m pip install '.[arrow]'`. Source builds -require Rust 1.88 or newer. Prebuilt wheels bundle the native library and need -no Rust installation. Use `pheon` without the `arrow` extra if you only need -integer packing; importing it does not import PyArrow. +For a local wheel, pass its file path followed by `[arrow]` in the same quotes. +Prebuilt wheels bundle the native library. From a source checkout, use +`python -m pip install '.[arrow]'` with Rust 1.88 or newer. The base `pheon` +package is enough for integer packing. Run Python outside the source checkout to use the installed package. @@ -25,19 +25,20 @@ Run Python outside the source checkout to use the installed package. from pheon import arrow layout = arrow.read_path("chip.gds") -print(layout.field("lib_name")[0].as_py()) -print(layout.field("cell_names")[0].as_py()) +names = layout.field("cell_names")[0].as_py() cells = layout.field("cells")[0].values +print([names[cell_id] for cell_id in cells.field("id").to_pylist()]) ``` `read_path` accepts strings and path-like objects, expands `~`, and recognizes gzip by its magic bytes. `read_bytes` accepts an uncompressed, contiguous byte buffer, such as `bytes`, `bytearray`, or a compatible memoryview. -Every reader returns a one-row `pyarrow.StructArray`. Geometry is grouped by -cell and element kind; cell and layer IDs resolve through tables in the same -result. See the [Arrow reference](arrow-schema.md) for fields and encodings. -The returned arrays own their storage independently of the input buffer. +Every reader returns a one-row `pyarrow.StructArray`. The example uses each +cell's ID to look up its name. The name table can also contain reference targets +without cell definitions. Geometry is grouped by cell and element kind. The +returned arrays own their storage independently of the input buffer. +See the [Arrow reference](arrow-schema.md) for fields and encodings. ## Scan, then read selected cells @@ -79,19 +80,17 @@ Python sequences, or scalars and preserve the caller's data, including for noncontiguous or differently ordered arrays. Pheon currently has no high-level Python layout writer. -## Errors and native library selection +## Handle read errors Native parse failures raise `pheon.PheonError`, a subclass of `ValueError`. Invalid buffer or range arguments raise `ValueError` or `TypeError`; file access errors use Python's normal I/O exceptions. -Python loads its bundled native library. Set `PHEON_LIBRARY` to an explicit -library path before importing Pheon to override it during development. The -loader checks C API and Arrow schema compatibility. It does not discover a -Cargo-installed executable or search PATH for a library. +## Use from Klamath or Masque -Klamath's `native` extra installs Pheon's packing helpers; Masque's `arrow` extra -installs Pheon with Arrow support. Install these in the same Python environment -as the companion package. A standalone CLI installation does not supply the -Python bindings. -For direct integration without Python, see the [native API guide](native-api.md). +Klamath's `native` extra installs Pheon's packing helpers. Masque's `arrow` extra +installs Pheon with Arrow support. Use the same Python environment as the +companion package. + +See [development](development.md) to test a locally built native library from +Python, or the [native API guide](native-api.md) to call the library directly.