Skip to content

Reportnet API Python client: reference

Generated by scripts/generate_docs.py (scripts/regen_docs.sh). Do not edit by hand; change the code, scripts/docs_caveats.py or the generator and regenerate.

Look up any function to see its arguments, the ReportNet rights it needs and the caveats found by live testing. Argument lists and roles come from the code and spec/api-docs.json; the "Live-tested notes" come from a small hand-kept file (scripts/docs_caveats.py) that only repeats facts recorded in docs/live_testing_notes.md.

ApiKey or Bearer?

ReportNet accepts two kinds of credential, and they are not interchangeable:

  • ApiKey: a dataflow-scoped key issued to a reporting provider. It carries Reporter-level access only and works only for its own dataflow (403 elsewhere). It cannot satisfy a rule that needs a user-level dataflow role such as DATAFLOW_CUSTODIAN or DATAFLOW_STEWARD.
  • Bearer: the JWT of a logged-in user. It carries that user's actual roles on each dataflow.

A higher role is not always better: the ETL endpoints returned 403 for a Custodian/Steward Bearer credential while an ApiKey worked (see the notes on those methods). A dead or revoked ApiKey shows up as a 500 "401 UNAUTHORIZED" on any call; list_datasets is a quick way to check.

"Allowed roles" tables are what the API spec declares per dataset type; for methods whose spec states none (including hand-written ones) the page says "Not stated in the API spec". The /private/* operations in the spec are not on this client (they are unreachable through the gateway), see removed private endpoints.

Every resource method also exists on AsyncReportnetClient, called with await.

Pages

Dataflow (hand-written)

  • create_dataflow: create a dataflow and return its new id.
  • dataflow_datasets: the dataflow with its datasets (designDatasets, reportingDatasets, dataCollections, euDatasets, `re...
  • dataflows: dataflows visible to the logged user.
  • delete_dataflow: delete a dataflow with its design datasets, documents and representatives.

Dataset Schema

Datasets

Dataset Snapshot

EU Datasets

Release receipts

Reference dataset (hand-written)

  • set_updatable: Lock or unlock a reference dataset (PUT /referenceDataset/{datasetId}).

Representative (hand-written)

User (hand-written)

Validation (hand-written)

Notebook helpers (reportnet_api.easy)

  • apply_schema_dtypes: Convert columns to the types the dataset schema declares.
  • check_access: Read-only self-check of a credential: which kind, alive, dataflow reachable.
  • check_import_file: Read-only pre-check of an import file; returns the problems found (empty = ok).
  • connect: Build a client from arguments or environment variables.
  • connect_interactive: Like connect(), but asks for the credential with a hidden prompt.
  • demo_client: A client that answers from built-in fictional data: no network, no credential.
  • export_table: Export one table (by name) to dest as csv/xlsx/..., waiting for the file.
  • export_to_file: Export a dataset as a ZIP of CSV (or Parquet) files at dest.
  • export_validations: Save a dataset's validation failures as a CSV at dest and return the path.
  • find_dataflow: One dataflow handle by id or name text (see handles.find_dataflow).
  • guide: Print a one-page cheat sheet of the helpers in the order a notebook uses them.
  • import_dataframe: Import a DataFrame into one table of a dataset (import_file underneath). WRITES.
  • import_file: Upload a CSV (or other import file) into a dataset and wait until it is in.
  • is_data_lake: True when the dataflow is a data-lake one (bigData: true in its dataset listing).
  • list_dataflows: All dataflows visible to the credential, one row each (id, name, status, ...).
  • list_datasets: Datasets of a dataflow as a flat table: dataset_id, name, kind, provider_id.
  • list_providers: Data providers of a group as a table: provider_id, code, label, group_id.
  • list_tables: Tables defined in a dataset's schema: table_id and name.
  • read_all_records: Every table as {table name: list of row dicts}, without pandas (see read_records).
  • read_many: One table from several dataset handles, stacked (see handles.read_many).
  • read_records: One table as a list of dicts, without pandas (for FME and plain scripts).
  • read_table: One table of a dataset as a DataFrame.
  • read_tables: Download a dataset's data as {table_name: DataFrame}.
  • validate_and_wait: Start a validation, wait until it finishes, return validation_errors().
  • validation_errors: Failed validations of a dataset, one row per failing rule (what the UI shows).
  • validation_summary: Failures counted per table and level: table, level, rules, records.

Job polling (reportnet_api.jobs)

  • async_wait_for_job: Async twin of wait_for_job().
  • download_url_of: The downloadUrl of a finished export job.
  • import_statistics_changed: True if get_import_related_statistics() shows a new import since before.
  • job_id_of: The job id of a job-start answer: its jobId, else parsed from the pollingUrl.
  • polling_url_of: The pollingUrl of a job-start answer (or the string itself).
  • progress_event: The dict a progress callback receives.
  • progress_scope: Resolve a progress argument to a callback (or None) for the duration of a wait.
  • wait_for_job: Poll a job's pollingUrl until FINISHED and return the last answer.

Handles (reportnet_api.handles)