# 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 published package 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. 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") print(layout.field("lib_name")[0].as_py()) print(layout.field("cell_names")[0].as_py()) cells = layout.field("cells")[0].values ``` `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. ## 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. ## Errors and native library selection 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. 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).