Installed-wheel public surface¶
The root rfgen package deliberately exposes only __version__ and
open_store. Importing it does not eagerly import numerical backends, cloud
SDKs, or a storage implementation. rfgen.public contains the corresponding
installed-wheel diagnostic API used by rfgen doctor.
Module summary¶
import rfgen
with rfgen.open_store("./out/dataset", mode="r") as store:
for metadata in store:
print(metadata.record_id)
assert isinstance(rfgen.__version__, str)
open_store delegates to rfgen.public.open_store and returns the standard
StoreHandle lifecycle described in
Storage. The root module is the supported user import path.
Root exports¶
rfgen.__version__¶
__version__: str
The installed rfgen version. It is the same value reported in
DoctorReportV1 and by rfgen version.
rfgen.open_store(uri, *, mode="r", storage_options=None)¶
def open_store(
uri: str,
*,
mode: Literal["r", "a"] = "r",
storage_options: Mapping[str, object] | None = None,
) -> StoreHandle
Opens one built-in store and returns its StoreHandle. mode="r" maps to the
store’s read lifecycle and mode="a" to append. The URI is required to be a
non-empty string. storage_options may contain only schema_version,
compression, chunk_samples, record_axis, and assets_path; individual
backends validate the values they consume.
URI form |
Selected backend |
|---|---|
|
Zarr |
|
HDF5 |
|
WebDataset |
|
SigMF |
It raises ConfigError for an unknown URI scheme, empty URI, unsupported
mode, or unknown option. It preserves BackendUnavailableError when the
chosen optional backend is absent and StorageError for a backend failure.
Unexpected implementation exceptions become StorageError with only backend
and exception-type context, so credentials and URI secrets are not exposed.
rfgen.public capability diagnostics¶
rfgen.public depends on standard-library package metadata, Pydantic, and
the built-in storage classes. It does not import a requested extra until its
probe checks import availability. Its public API is also the source for the
doctor CLI recipe.
A capability probe is a bounded diagnostic check of one named runtime feature, not a generation job. Doctor leaves unrequested optional features unprobed so the base installation remains quick to inspect and does not import extras the user did not ask it to test.
Class index¶
Class |
Role |
|---|---|
Closed doctor outcome enum. |
|
Immutable runtime identity projections. |
|
One probe’s requested state, outcome, timing, and redacted detail. |
|
Immutable report shared by text and JSON doctor output. |
ProbeStatus¶
ProbeStatus is a string enum with PASS, FAIL, UNAVAILABLE, and
SKIPPED. PASS means a requested check completed successfully.
UNAVAILABLE means a requested feature could not be checked because its
optional dependency is missing or its name is unknown. FAIL means the
requested check ran but failed or exceeded its timing budget.
SKIPPED means a built-in row was not requested, so it is neither evidence
that the feature works nor a failure. Only requested rows influence a report’s
overall status.
PythonIdentity and PlatformIdentity¶
Both are frozen, extra-forbidden Pydantic models. PythonIdentity has
implementation, version, and executable. PlatformIdentity has
system, release, and machine. They are report metadata, not capability
probes.
CapabilityProbeV1¶
class CapabilityProbeV1(BaseModel):
name: str
requested: bool
status: ProbeStatus
latency_ms: int # >= 0
diagnostic_code: str
redacted_detail: str | None = None
One immutable probe row. redacted_detail is only an exception type for a
failed probe, never exception text. Diagnostic codes are NOT_REQUESTED,
OK, UNKNOWN_CAPABILITY, MISSING_EXTRA, TIMEOUT, or PROBE_FAILED.
DoctorReportV1¶
class DoctorReportV1(BaseModel):
schema_version: Literal[1] = 1
started_at: datetime
finished_at: datetime
rfgen_version: str
python: PythonIdentity
platform: PlatformIdentity
requested: tuple[str, ...]
probes: tuple[CapabilityProbeV1, ...]
diagnostic_codes: tuple[str, ...]
overall: ProbeStatus
The report is frozen and rejects unknown fields. requested, probes, and
diagnostic_codes are deterministically sorted. Text and JSON CLI output are
different renderings of this same report.
doctor_report(*, required=(), probes=(), timeout_s=10.0)¶
def doctor_report(
*,
required: Sequence[str] = (),
probes: Sequence[str] = (),
timeout_s: float = 10.0,
) -> DoctorReportV1
Builds one report. timeout_s must be in [0.1, 300] or the function raises
ValueError. Names from required and probes are deduplicated and sorted.
The built-in names version, entry-points, and presets always appear but
are SKIPPED unless requested. Optional supported names are adsb, aws,
azure, gcp, hdf5, sigmf, sionna, spark, torch, torchsig, and
webdataset; a missing extra is UNAVAILABLE with MISSING_EXTRA. Any other
requested name is UNAVAILABLE with UNKNOWN_CAPABILITY.
If a requested probe fails or exceeds the timing budget, its row is FAIL.
The overall result is FAIL if any requested row fails, otherwise
UNAVAILABLE if any requested row is unavailable, otherwise PASS. Runtime
metadata lookup failures are represented as a redacted PROBE_FAILED row.
doctor_exit_code(report)¶
def doctor_exit_code(report: DoctorReportV1) -> int
Maps a validated report to the doctor command’s public exit status: PASS or
SKIPPED maps to 0, UNAVAILABLE to 3, and FAIL to 4. The CLI itself
uses exit 5 only if building the report raises an unexpected internal error.