Clarify Pheon installation and first-use examples
This commit is contained in:
parent
31afef0529
commit
4ea14085f7
1 changed files with 31 additions and 28 deletions
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue