Skip to content

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).

Back to index

Functions

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; use export_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.