Handles (reportnet_api.handles)
Generated by
scripts/generate_docs.py(scripts/regen_docs.sh). Do not edit by hand.
Handles are frozen dataclasses from reportnet_api.handles that delegate to the easy functions and add no endpoint, so the ReportNet rights needed are those of those calls. Get one with easy.find_dataflow(client, id_or_name) (flow), then flow.dataset(id, country code or name) (ds). A handle is a snapshot: flow.refresh() returns a new one.Properties are written without brackets.
Members
- Dataflow.dataset
- Dataflow.datasets
- Dataflow.refresh
- Dataset.export
- Dataset.export_validations
- Dataset.read
- Dataset.read_all
- Dataset.tables
- Dataset.upload
- Dataset.validate
- Dataset.validation_errors
- Dataset.validation_summary
Dataflow.dataset
One dataset by id, country code or name; exactly one match or LookupError.
Call: flow.dataset(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
key |
int \| str |
yes | ||
kind |
str \| None |
no | None |
Returns: Dataset
A string is tried as a provider code (case-insensitive), then as a name:
exact first, then substring. kind ("design", "reporting", "test", ...)
narrows the candidates first.
Dataflow.datasets
The dataflow's datasets as a DataFrame (easy.list_datasets).
Call: flow.datasets
No arguments.
Returns: pd.DataFrame
Dataflow.refresh
A new handle read afresh from the server; this one is left unchanged.
Call: flow.refresh(...)
No arguments.
Returns: Dataflow
Dataset.export
Export the dataset as a ZIP of CSV or Parquet files at dest (easy.export_to_file).
Call: ds.export(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
dest |
str \| os.PathLike[str] |
yes | ||
**kwargs |
Any |
no |
Returns: Path
Starts an export job and leaves a job record behind. Keyword arguments
(file_format, table_schema_id, timeout, progress) go to export_to_file.
Dataset.export_validations
Save the validation failures as a CSV at dest (easy.export_validations).
Call: ds.export_validations(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
dest |
str \| os.PathLike[str] |
yes | ||
**kwargs |
Any |
no |
Returns: Path
Close any open Reportnet page for this dataset first: the backend deletes the file once the web app downloads it.
Dataset.read
One table as a DataFrame (easy.read_table).
Call: ds.read(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
table |
str \| None |
no | None |
|
allow_data_lake |
bool |
no | False |
|
**kwargs |
Any |
no |
Returns: pd.DataFrame
Without table the dataset must hold exactly one table with data. Raises
DataLakeError on a data-lake dataflow, as read_all does.
Dataset.read_all
All tables as {table_name: DataFrame} (easy.read_tables).
Call: ds.read_all(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
allow_data_lake |
bool |
no | False |
|
**kwargs |
Any |
no |
Returns: dict[str, pd.DataFrame]
The handle's provider_id is passed unless you give one. Other keyword
arguments (page_size, progress, table_schema_id) go to read_tables;
see it for the ETL credential caveats. Raises DataLakeError on a data-lake
dataflow (big_data), where this route returns no rows: use export(), or
allow_data_lake=True to try anyway.
Dataset.tables
The dataset's tables as a DataFrame (easy.list_tables).
Call: ds.tables
No arguments.
Returns: pd.DataFrame
Dataset.upload
Import a file into the dataset and wait for it (easy.import_file). WRITES.
Call: ds.upload(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
path |
str \| os.PathLike[str] |
yes | ||
**kwargs |
Any |
no |
Returns: dict[str, Any]
The file name must match a table name and the header must name every field
(checked first). replace=True deletes the existing data first and needs
confirm=True. The handle's provider_id is passed unless you give one.
Dataset.validate
Start a validation, wait for it, return the failures (easy.validate_and_wait). WRITES.
Call: ds.validate(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
**kwargs |
Any |
no |
Returns: pd.DataFrame
Replaces the dataset's validation results and locks the dataset while it runs.
Dataset.validation_errors
Failed validations, one row per failing rule (easy.validation_errors).
Call: ds.validation_errors(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
**kwargs |
Any |
no |
Returns: pd.DataFrame
Dataset.validation_summary
Failures counted per table and level (easy.validation_summary).
Call: ds.validation_summary(...)
No arguments.
Returns: pd.DataFrame