Python API

The pystards package provides a Pythonic, NumPy-friendly interface to StarDS. This page is generated from the package docstrings.

Note

The API reference below is rendered by mkdocstrings. Because pystards loads a compiled SWIG extension at import time, the built _pystards module must be importable when the docs are built (see Building the docs).

Quick reference

Class / function	Purpose
StarDataset	Create, open, read, and write .stards files
NDArray	NumPy-compatible array wrapper
MetadataValue	Type-erased metadata container
zeros, ones, arange, full	Array creation helpers
DataType, CompressionAlgorithm, FileMode	Enumerations
set_log_level, get_log_level, LogLevel	Runtime logging control

StarDataset

pystards.dataset.StarDataset

Persistent storage for N-dimensional arrays.

Supports local files, HTTP, and S3. Remote paths may be given either as a plain URL/URI or with the GDAL virtual-filesystem prefix — both are accepted:

• S3: s3://bucket/key or /vsis3/bucket/key
• HTTP: https://host/path or /vsicurl/https://host/path

Examples:

>>> with StarDataset.create("data.stards") as store:
...     store["matrix"] = np.random.rand(100, 100)
...     store.meta["units"] = "meters"
>>> store = StarDataset.open("s3://bucket/data.stards", mode="r")
>>> keys = store.keys()

filename property

Path this dataset was opened from.

create(filename, config=None) classmethod

Create a new STAR dataset file.

open(filename, mode='rw', options=None) classmethod

Open an existing STAR dataset file.

Parameters:

Name	Type	Description	Default
filename	str	Path to the .stards file.	required
mode	str	Open mode ("r", "rw", "w").	'rw'
options		Optional pystards.OpenOptions controlling read-time behavior such as layer_inheritance (off by default).	None

open_bytes(data, options=None) classmethod

Open a dataset from an in-memory byte buffer.

The byte counterpart of :meth:open: data is a bytes-like object (bytes, bytearray, memoryview, or a uint8 NumPy array) holding a complete .stards image — e.g. bytes received over a socket or read from a database — rather than a file path.

The dataset is read-only (there is no backing file to flush to); use :meth:write_bytes to serialize modifications back out to bytes.

Parameters:

Name	Type	Description	Default
data		A complete .stards image as a bytes-like object.	required
options		Optional pystards.OpenOptions (e.g. layer_inheritance).	None

write_bytes()

Serialize this dataset to a bytes object (a complete .stards image).

The byte counterpart of :meth:save_to: returns the exact bytes that would be written to a file, without touching the filesystem. Works on any dataset, including read-only ones and datasets from :meth:open_bytes. Round-trips with :meth:open_bytes.

put(key, value)

Store an array (stored separately, supports slicing).

get(key)

Retrieve an array as a NumPy array.

get_slice(key, slices)

Get a slice of a large array.

Parameters:

Name	Type	Description	Default
key	str	Array key	required
slices	List[tuple]	List of (start, stop[, step]) tuples, one per dimension.	required

put_metadata(key, value)

Store a value in the metadata block (equivalent to ds.meta[key] = value).

keys()

All array keys (excludes internal layer-prefixed keys).

flush()

Write pending changes to disk.

close()

Flush pending writes to disk (dataset remains usable).

is_sliceable(key)

Return True if the array can be read in slices (see :meth:get_slice).

is_metadata_loaded()

Return True if the metadata block has been read into memory.

is_read_only()

Return True if the dataset was opened read-only.

save_to(target_path)

Save the dataset to a different file (e.g. read-only -> writable, or local <-> S3).

get_all_metadata()

All metadata entries as a dict of {key: np.ndarray}.

get_layer(layer_name)

Get an existing layer view (raises RuntimeError if it doesn't exist).

create_layer(layer_name)

Create a new layer and return its view.

set_layer_inheritance(on)

Enable or disable base-layer inheritance for layer lookups.

Inheritance is off by default: a key absent from a layer is reported as missing rather than falling back to the base layer. This is a read-time setting (it changes in-memory behavior only, never the file) and can be toggled at any time after opening.

layer_inheritance()

Return whether base-layer inheritance is currently enabled.

NDArray

pystards.ndarray.NDArray

Unified wrapper for C++ NDArray template instantiations.

from_numpy(arr) staticmethod

Create an NDArray from a NumPy array, Python list, scalar, or string.

to_numpy()

Convert to a NumPy array (single memcpy for numeric; element copy for strings).

Array creation helpers

pystards.ndarray.zeros(shape, dtype=np.float64)

Create an array of zeros.

pystards.ndarray.ones(shape, dtype=np.float64)

Create an array of ones.

pystards.ndarray.arange(start, stop=None, step=1, dtype=None)

Create an array with evenly spaced values.

pystards.ndarray.full(shape, fill_value, dtype=None)

Create an array filled with a constant value.

MetadataValue

pystards.metadata.MetadataValue

Wrapper for a C++ MetadataValue with NumPy conversion.

dtype property

Get the STAR DataType.

shape property

Get shape as a tuple.

ndim property

Number of dimensions.

size property

Total number of elements.

to_numpy()

Convert to a NumPy array.

The element-type switch happens in C++ (star_meta_to_numpy): numeric types round-trip via the zero-copy buffer protocol, strings via an object array.

Logging

pystards.logger

Logger configuration for STARDS

LogLevel

Log level constants

set_log_level(level)

Set the STARDS logging level at runtime.

Parameters:

Name	Type	Description	Default
level		Log level (use LogLevel.TRACE, .DEBUG, .INFO, .WARN, or .ERROR) or integer 0-4	required

Examples:

>>> import pystards
>>> pystards.set_log_level(pystards.LogLevel.DEBUG)
>>> # Now debug messages will be printed

>>> # Or use integer directly
>>> pystards.set_log_level(1)  # DEBUG

get_log_level()

Get the current STARDS logging level.

Returns:

Name	Type	Description
int		Current log level (0=TRACE, 1=DEBUG, 2=INFO, 3=WARN, 4=ERROR)

Examples:

>>> import pystards
>>> level = pystards.get_log_level()
>>> print(f"Current log level: {level}")

Building this page

pystards imports the compiled SWIG extension (_pystards) at import time, so the extension must be built and importable before the documentation is built:

# Build the Python bindings first (see the Installation guide), then serve the
# docs (config lives under docs-site/):
export PYTHONPATH="$PWD/build/bindings/python"
mkdocs serve -f docs-site/mkdocs.yml

If the extension is not importable, mkdocstrings cannot introspect the package and this page will fail to render.