Notebook helpers (reportnet_api.easy)
Generated by
scripts/generate_docs.py(scripts/regen_docs.sh). Do not edit by hand.
Hand-written helpers in reportnet_api.easy. They are plain functions, not methods of a resource, and make no endpoint of their own: the ReportNet rights needed are those of the underlying API calls (see the resource pages).
Functions
- apply_schema_dtypes
- check_access
- check_import_file
- connect
- connect_interactive
- demo_client
- export_table
- export_to_file
- export_validations
- find_dataflow
- guide
- import_dataframe
- import_file
- is_data_lake
- list_dataflows
- list_datasets
- list_providers
- list_tables
- read_all_records
- read_many
- read_records
- read_table
- read_tables
- validate_and_wait
- validation_errors
- validation_summary
apply_schema_dtypes
Convert columns to the types the dataset schema declares.
Call: easy.apply_schema_dtypes(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
tables |
dict[str, pd.DataFrame] |
yes | ||
field_types |
dict[str, dict[str, str]] |
yes |
Returns: dict[str, pd.DataFrame]
Handles NUMBER_INTEGER (Int64), NUMBER_DECIMAL (Float64), DATE, DATETIME (UTC)
and BOOLEAN (true/false, any case); every other type stays text. A column
whose values do not all fit keeps its original text and a RuntimeWarning names
it, so a wrong guess never silently changes data. Returns new frames.
check_access
Read-only self-check of a credential: which kind, alive, dataflow reachable.
Call: easy.check_access(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataflow_id |
int \| None |
no | None |
|
show |
bool |
no | True |
Returns: list[dict[str, str]]
Makes one call (list dataflows, page size 1) and, with dataflow_id, one
more (the dataflow's datasets). Nothing is written. Returns rows with
check, result and detail and prints them as a table unless
show=False. The credential itself is never printed.
The expected rows are static advice for the credential's scheme taken
from the live-testing notes; they were not probed by this call.
check_import_file
Read-only pre-check of an import file; returns the problems found (empty = ok).
Call: easy.check_import_file(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
path |
str \| os.PathLike[str] |
yes | ||
delimiter |
str \| None |
no | None |
Returns: list[str]
Only .csv files are checked (a ZIP or workbook is left to Reportnet). The name
must match a table of the dataset (ignoring case: whether the backend is
case-sensitive is unverified) and the first line must name exactly that table's
fields, split by delimiter (or by any of , | ; tab when None, since the
dataset's own delimiter cannot be read). Live: a header with only some of the
fields was cancelled (the sandbox). If the schema cannot be read, returns [].
connect
Build a client from arguments or environment variables.
Call: easy.connect(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
token |
str \| None |
no | None |
|
base_url |
str \| None |
no | None |
|
scheme |
str \| None |
no | None |
|
token_provider |
Callable[[], str] \| None |
no | None |
|
retry |
RetryPolicy \| bool \| None |
no | None |
Returns: ReportnetClient
token falls back to REPORTNET_API_KEY, base_url to REPORTNET_BASE_URL
and then production. The scheme is chosen from the value: a "Bearer "
prefix or a JWT-shaped value (three dot-separated base64url parts) is sent
as Bearer; anything else is a dataflow API key (ApiKey scheme). Live,
both an ApiKey and a Bearer token are bare UUIDs and look alike, so for a
Bearer token pass scheme="Bearer" (or the "Bearer " prefix); sent as
an ApiKey it fails with a 500 "Access is denied". Which one you have
matters: API keys carry Reporter-level access only. Set REPORTNET_TOKEN_SCHEME
(ApiKey or Bearer) to fix the scheme once, e.g. next to a Bearer token
in REPORTNET_API_KEY; precedence is scheme=, a "Bearer " prefix, that
variable, then the guess from the value. The chosen scheme shows in the
client's repr; the secret never does.
token_provider is a zero-arg callable returning the current token, called
before every request (instead of token; the scheme defaults to Bearer).
retry=True retries transient failures with a default RetryPolicy; pass
your own policy for other settings.
A Bearer token expires after a few minutes. If you have your own way to get fresh
tokens, pass it as token_provider; client.user.refresh_token() renews a login
when you hold the refresh token issued with it. This library does not log in.
Live-tested notes:
- A dead or revoked ApiKey shows up as a 500 '401 UNAUTHORIZED' on any call; check with
list_datasets. An ApiKey only works for its own dataflow (403 elsewhere).
connect_interactive
Like connect(), but asks for the credential with a hidden prompt.
Call: easy.connect_interactive(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
base_url |
str \| None |
no | None |
|
scheme |
str \| None |
no | None |
|
retry |
RetryPolicy \| bool \| None |
no | None |
|
prompt |
str |
no | 'Reportnet API key or token (input hidden): ' |
Returns: ReportnetClient
Use it in a notebook so the key is typed, not pasted into a cell that gets
saved with the notebook. Same scheme/retry options as connect().
demo_client
A client that answers from built-in fictional data: no network, no credential.
Call: easy.demo_client(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
quiet |
bool |
no | False |
Returns: ReportnetClient
For training and first tries (list_dataflows(c), list_datasets(c, 1),
read_table(c, 102, 1), find_dataflow(c, "demo")); see reportnet_api.demo.
Prints a one-line notice unless quiet=True.
export_table
Export one table (by name) to dest as csv/xlsx/..., waiting for the file.
Call: easy.export_table(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
table |
str |
yes | ||
dest |
str \| os.PathLike[str] |
yes | ||
file_format |
str |
no | 'csv' |
|
big_data |
bool |
no | True |
|
timeout |
float |
no | 300.0 |
|
progress |
Progress |
no | None |
Returns: Path
Unlike export_to_file() this is not a job: the backend generates the file
in the background and only notifies the Reportnet UI, so the helper polls the
download until the file appears. Raises reportnet_api.jobs.JobError after
timeout seconds. It leaves a notification in the user's Reportnet UI.
Needs a Bearer token (an ApiKey gets 403). big_data=True (default) uses the
routes the Reportnet UI calls; the plain ones never produced a file live.
Check dest afterwards: a leftover file with the same name on the server
could be served instead. progress=True shows a "waiting for the file" line
with the elapsed seconds; a callable gets event dicts.
Live-tested notes:
- Live-checked with a Bearer token (CSV, 0.6s); an ApiKey gets 403. Leaves a notification in the user's Reportnet UI.
export_to_file
Export a dataset as a ZIP of CSV (or Parquet) files at dest.
Call: easy.export_to_file(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
dataflow_id |
int |
yes | ||
dest |
str \| os.PathLike[str] |
yes | ||
file_format |
Literal['csv', 'parquet'] |
no | 'csv' |
|
table_schema_id |
str \| None |
no | None |
|
timeout |
float |
no | 300.0 |
|
progress |
Progress |
no | None |
Returns: Path
Starts the async export job, waits for it to finish, then downloads the
ZIP. Raises reportnet_api.jobs.JobError if the job fails or timeout
seconds pass. Same ETL-access caveat as read_tables(). progress=True shows
one updating status line; a callable gets event dicts (see wait_for_job()).
Newer Reportnet versions refuse the CSV and Parquet ZIP exports for a dataflow
that is not a data lake (live on the sandbox, 2026-11-18). For CSV this then
falls back to the older JSON export and writes the ZIP itself: one
<table>.csv per table, comma-separated UTF-8, fields in schema order (then
country_code when the records carry one), no record id column. That export is
read into memory whole. Parquet has no such
fallback; the JobError says so.
Live-tested notes:
- Live-checked with an ApiKey for CSV and Parquet; a Bearer Custodian/Steward credential got 403 on the v4 export.
export_validations
Save a dataset's validation failures as a CSV at dest and return the path.
Call: easy.export_validations(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
dest |
str \| os.PathLike[str] |
yes | ||
timeout |
float |
no | 300.0 |
|
poll_interval |
float |
no | 2.0 |
Returns: Path
Generates the export and waits for it (validation.export_validations_to_file).
Columns: Entity, Table, Field, Code, QC Name, QC Description, Severity Level,
Message, Number of records. Works on data-lake datasets (live-tested on the
sandbox). Close any open Reportnet page for the same dataset first: the backend
deletes the file when it is served, so the web app, which downloads it on the
notification, can take it before this does and the wait ends in a JobError
timeout. Leaves a notification in the user's Reportnet UI.
find_dataflow
One dataflow handle by id or name text (see handles.find_dataflow).
Call: easy.find_dataflow(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
query |
int \| str |
yes |
Returns: Dataflow
The handle resolves datasets by id, country code or name:
find_dataflow(c, "air quality").dataset("AT"). Raises LookupError listing
the candidates when nothing or more than one matches.
guide
Print a one-page cheat sheet of the helpers in the order a notebook uses them.
Call: easy.guide(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
show |
bool |
no | True |
Returns: str
Returns the text; prints it unless show=False. Search every method and helper
by keyword with reportnet_api.find(text).
import_dataframe
Import a DataFrame into one table of a dataset (import_file underneath). WRITES.
Call: easy.import_dataframe(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
dataflow_id |
int |
yes | ||
table_name |
str |
yes | ||
df |
pd.DataFrame |
yes | ||
delimiter |
str |
no | ',' |
|
**kwargs |
Any |
no |
Returns: dict[str, Any]
Writes a temporary <table_name>.csv with a header for EVERY field of the table
in schema order (fields missing from df are left empty; columns that are not
fields raise ValueError), values formatted by field type (dates YYYY-MM-DD,
datetimes UTC ISO, NA empty), and uploads it with delimiter. A value containing
the delimiter or a line break raises ValueError (how the backend reads quotes is
unverified). Other keyword arguments (replace, confirm, provider_id,
progress, ...) go to import_file; replace=True needs confirm=True.
The delimiter is always sent with the upload, so it overrides the dataset's own
setting. Live-tested once, on a sandbox dataset: a typed read, then
import_dataframe(..., delimiter="|", replace=True, confirm=True) and a second read
gave identical data. Other field types and datasets are not verified.
import_file
Upload a CSV (or other import file) into a dataset and wait until it is in.
Call: easy.import_file(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
dataflow_id |
int |
yes | ||
path |
str \| os.PathLike[str] |
yes | ||
table_schema_id |
str \| None |
no | None |
|
replace |
bool |
no | False |
|
confirm |
bool |
no | False |
|
check |
bool |
no | True |
|
provider_id |
int \| None |
no | None |
|
delimiter |
str \| None |
no | None |
|
timeout |
float |
no | 300.0 |
|
progress |
Progress |
no | None |
Returns: dict[str, Any]
Before uploading a .csv, the file is checked against the dataset schema
(check_import_file): the name must be a table name and the header must name
every field of that table, else ValueError lists the problems and nothing is
sent (check=False skips this; so does an unreadable schema).
replace=True deletes data, so it also needs confirm=True.
The file name must match a table name in the dataset (TestTable.csv for
table TestTable); otherwise Reportnet cancels the job ("File name does not
match any table name") and nothing is imported.
delimiter is the file's field separator; leave it None for the dataset's own
setting. A multi-column file whose separator differs from the dataset's is
cancelled ("headers ... do not match"): live on the sandbox the delimiter is |.
replace=True emptied the dataset's other tables too (live, 2026-11-07,
the sandbox: a one-table file left the second table empty), so re-import the tables
you want to keep afterwards.
Uploads with the async big-file import, waits for its job, and then
confirms through the dataset's import statistics. Returns those statistics
({table_id: {"numberOfRecordsImported": ..., ...}}). This WRITES to the
dataset; replace=True also deletes the existing data first. Raises
reportnet_api.jobs.JobError if the job fails or timeout seconds pass
(the upload may still finish later). progress=True shows one updating status
line; a callable gets event dicts. Ctrl-C while waiting only stops the waiting:
the import keeps running on the server and cannot be cancelled from here.
Live-tested notes:
- The file name must match a table name. Live-checked with Bearer and ApiKey.
is_data_lake
True when the dataflow is a data-lake one (bigData: true in its dataset listing).
Call: easy.is_data_lake(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataflow_id |
int |
yes |
Returns: bool
Data-lake dataflows keep validation results and table data in the lake, so the
old per-dataset routes answer an empty 200 there.
list_dataflows
All dataflows visible to the credential, one row each (id, name, status, ...).
Call: easy.list_dataflows(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
kind |
DataflowKind |
no | 'reporting' |
|
page_size |
int |
no | 200 |
Returns: pd.DataFrame
list_datasets
Datasets of a dataflow as a flat table: dataset_id, name, kind, provider_id.
Call: easy.list_datasets(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataflow_id |
int |
yes | ||
provider_id |
int \| None |
no | None |
Returns: pd.DataFrame
An unknown dataflow id answers HTTP 500 (ServerError, see explain()) and
no access answers 403 (live-tested). LookupError is a guard for an empty
200 body, which the notes say the backend can send when it swallows an
error; not reproduced on this route.
list_providers
Data providers of a group as a table: provider_id, code, label, group_id.
Call: easy.list_providers(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
group_id |
int |
no | 1 |
Returns: pd.DataFrame
A provider is a reporting country; provider_id is the providerId other
calls take and code its country code. Group 1 is the member
countries; client.representative.data_provider_groups() lists the groups.
list_tables
Tables defined in a dataset's schema: table_id and name.
Call: easy.list_tables(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes |
Returns: pd.DataFrame
read_all_records
Every table as {table name: list of row dicts}, without pandas (see read_records).
Call: easy.read_all_records(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
dataflow_id |
int |
yes | ||
table_schema_id |
str \| None |
no | None |
|
provider_id |
int \| None |
no | None |
|
page_size |
int |
no | 10000 |
|
progress |
Progress |
no | None |
Returns: dict[str, list[dict[str, Any]]]
read_many
One table from several dataset handles, stacked (see handles.read_many).
Call: easy.read_many(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
datasets |
Iterable[Dataset] |
yes | ||
table |
str |
yes | ||
**kwargs |
Any |
no |
Returns: pd.DataFrame
Adds dataset and country columns; sequential; datasets without rows for the
table are skipped with a RuntimeWarning. Needs ETL access, like read_tables().
read_records
One table as a list of dicts, without pandas (for FME and plain scripts).
Call: easy.read_records(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
dataflow_id |
int |
yes | ||
table_name |
str \| None |
no | None |
|
**kwargs |
Any |
no |
Returns: list[dict[str, Any]]
Same paging, de-duplication and warnings as read_tables; each row is a dict
{field name: text} (plus country_code when the backend sends one) and empty
cells are ''. With no table_name, the dataset must contain exactly one table with
data. Keyword arguments (table_schema_id, provider_id, page_size, progress)
are those of read_tables.
read_table
One table of a dataset as a DataFrame.
Call: easy.read_table(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
dataflow_id |
int |
yes | ||
table_name |
str \| None |
no | None |
|
**kwargs |
Any |
no |
Returns: pd.DataFrame
With no table_name, the dataset must contain exactly one table with data.
Extra keyword arguments go to read_tables, e.g. dtypes="schema" for typed columns.
Live-tested notes:
- Uses the synchronous ETL export, whose access is credential-dependent.
read_tables
Download a dataset's data as {table_name: DataFrame}.
Call: easy.read_tables(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
dataflow_id |
int |
yes | ||
table_schema_id |
str \| None |
no | None |
|
provider_id |
int \| None |
no | None |
|
page_size |
int |
no | 10000 |
|
dtypes |
Literal['schema'] \| None |
no | None |
|
progress |
Progress |
no | None |
Returns: dict[str, pd.DataFrame]
Pages through the synchronous ETL export until every row has been fetched. Note: ETL access is credential-dependent (an API key works; some Bearer users get 403) - see the README.
The backend's offset is a 0-based row offset (live-tested on production
and the sandbox), so pages are fetched at offsets 0,
page_size, 2 * page_size, ... Multi-table datasets are not verified. As a
guard, rows are de-duplicated by the backend's id_record, paging stops when
a page brings nothing new, and a RuntimeWarning is raised for duplicates, a
row count that differs from totalRecords, or tables of the schema missing
from the answer.
Data-lake caveat: for a dataflow with bigData: true this route answers 200
with 0 rows even when data exists (live-tested), so a result
with no rows at all raises a RuntimeWarning; use export_to_file() (job export)
for such a dataset.
Values arrive from the backend as text, empty cells as ''. With
dtypes="schema" columns are converted using the field types in the dataset
schema (see apply_schema_dtypes: integers, decimals, dates, datetimes and
booleans; everything else stays text; a column that does not fit stays text with
a warning). Live-checked on the sandbox for integer, decimal, date and datetime
text; boolean text is unverified. The default (None) keeps all columns as text.
progress=True shows one updating line with the page number and rows so far;
a callable receives an event dict per page (reportnet_api.jobs.progress_event).
Live-tested notes:
- Uses the synchronous ETL export, whose access is credential-dependent.
- On a data-lake dataflow (
bigData: true) the export answers 200 with 0 rows although rows exist, so an all-empty result warns; useexport_to_file().
validate_and_wait
Start a validation, wait until it finishes, return validation_errors().
Call: easy.validate_and_wait(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
dataflow_id |
int |
yes | ||
released |
bool |
no | False |
|
timeout |
float |
no | 600.0 |
|
poll_interval |
float |
no | 3.0 |
|
data_lake |
bool \| None |
no | None |
Returns: pd.DataFrame
data_lake is passed to validation_errors() (None: detect from bigData).
WRITES: replaces the dataset's validation results and takes a dataset lock.
The completion signal is the user notification the backend creates when a run
ends (VALIDATION_FINISHED_EVENT, or VALIDATION_RELEASE_FINISHED_EVENT with
released=True), read from /notification/findUserNotifications: the dataset
has no status field to poll (live, the sandbox). A run took
about 35-55 s there. Only the calling user's notifications are visible, and a
failed run has no event of its own here, so it ends as a JobError timeout.
Notification times are server-side, so a newer one than any seen before the
start counts; a run started by someone else at the same moment could be
mistaken for this one. Raises JobError after timeout seconds.
validation_errors
Failed validations of a dataset, one row per failing rule (what the UI shows).
Call: easy.validation_errors(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
dataflow_id |
int |
yes | ||
level_errors |
list[str] \| None |
no | None |
|
type_entities |
list[str] \| None |
no | None |
|
page_size |
int |
no | 100 |
|
data_lake |
bool \| None |
no | None |
Returns: pd.DataFrame
Columns: short_code, level, entity, table, field, message, records (number of
failing records), rule_id. Picks the data-lake route (list_group_validations_dl)
when the dataflow has bigData: true, else list_group_validations; the old
route answers an empty list on a lake dataset even when the UI shows failures.
Pass data_lake=True/False when the caller already knows (it skips the
bigData lookup, whose empty answer would read as not a lake); None detects it.
An empty frame means no failures, or a validation that has not run yet: this
does not start one. Needs a credential that may read validations (an ApiKey
got 403 on the sandbox).
validation_summary
Failures counted per table and level: table, level, rules, records.
Call: easy.validation_summary(...)
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
client |
ReportnetClient |
yes | ||
dataset_id |
int |
yes | ||
dataflow_id |
int |
yes |
Returns: pd.DataFrame
rules is the number of failing rules, records the sum of their failing
record counts (one record can fail several rules, so it is not a distinct
count). Built on validation_errors(), so it has the same lake handling and
does not start a validation. Empty frame: no failures, or none run yet.