Clarify Pheon installation and first-use examples

This commit is contained in:
Jan Petykiewicz 2026-11-17 15:07:40 -08:00
commit 4ea14085f7

View file

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