# Python Use `pheon.arrow` to load GDSII geometry into PyArrow, scan a hierarchy, or read only selected cells. The base `pheon` package also provides integer packing. Python 3.11 or newer is required. ## Install To install a PyPI release: ```sh python -m pip install pheon ``` The package installs PyArrow for layout reads. Existing `pheon[arrow]` requirements still work. Prebuilt wheels bundle the native library. From a source checkout, use `python -m pip install .` with Rust 1.88 or newer. Run Python outside the source checkout to use the installed package. ## Read a layout ```python from pheon import arrow layout = arrow.read_path("chip.gds") 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`. 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 ```python from pathlib import Path from pheon import arrow content = Path("chip.gds").read_bytes() # Uncompressed GDSII bytes. scan = arrow.scan_bytes(content) cells = scan.field("cells")[0].values ranges = list(zip( cells.field("struct_start_offset").to_pylist(), cells.field("struct_end_offset").to_pylist(), )) selected = arrow.read_cells_bytes(content, ranges[:2]) ``` Scanning returns library metadata, cell names, references, and complete cell byte ranges without decoding geometry or text. Selected reads return the full layout schema for the requested cells, in the requested order. Use the selected result's own name and layer tables: IDs may differ between reads. Ranges must have shape `(N, 2)` with nonnegative integer offsets. Each half-open range must span exactly one complete cell, from BGNSTR through ENDSTR. An empty list returns metadata without cells. For compressed files, decompress the bytes before scanning or selecting ranges. ## Pack integers ```python import pheon int2_bytes = pheon.pack_int2([1, 2, 3]) int4_bytes = pheon.pack_int4([100, 200]) ``` These helpers return big-endian GDSII integer bytes. They accept NumPy arrays, 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. ## 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. ## Use from Klamath or Masque Klamath's `native` extra installs Pheon's packing helpers. Masque's `arrow` extra installs Pheon for layout reads. 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.