Dapla Toolbelt Datafangst

Python client library for the Kudoc — the metadata registry for data collections at Statistics Norway (SSB). Use it from Jupyter notebooks or Python scripts to browse published collections and manage draft collections programmatically.

Features

• Browse published collections — list, get by ID, search by name, search by Altinn questionnaire ID, and retrieve version history.
• Manage draft collections — create, read, update, delete, and publish drafts.
• Automatic authentication — tokens are fetched and refreshed transparently via dapla-auth-client.
• Environment-aware — automatically resolves the correct API host for DEV, QA, and TEST environments.

Requirements

• Python 3.12+
• A valid Dapla user account (for authentication)
• The DAPLA_ENVIRONMENT environment variable set when running on the Dapla platform

Installation

pip install dapla-toolbelt-datafangst

Quick Start

You can import using either the full package name or the shorter kudoc_client alias:

# Short alias (recommended)
from kudoc_client import Collections, Drafts

# Full package name (also works)
from dapla_toolbelt_datafangst import Collections, Drafts

List all published collections

import json
from kudoc_client import Collections

collections = Collections.list_collections()
print(json.dumps([c.to_dict() for c in collections], indent=2, default=str))

Get a single collection by ID

from dapla_toolbelt_datafangst import Collections

collection = Collections.get_collection(collection_id=42)
print(collection.name)
print(collection.to_json())

Search collections by name

from dapla_toolbelt_datafangst import Collections

results = Collections.search_by_name("Loennsstatistikk")
for c in results:
    print(f"{c.id}: {c.name}")

Search collections by Altinn questionnaire ID

from dapla_toolbelt_datafangst import Collections

results = Collections.search_by_altinn_id("RA-0329")
for c in results:
    print(f"{c.id}: {c.name}")

Get all versions of a collection

from dapla_toolbelt_datafangst import Collections

versions = Collections.get_versions(collection_id=42)
for v in versions:
    info = v.version_information
    print(f"Version {info.id} — status: {info.status}, updated: {info.last_updated_at}")

Working with Drafts

List your own drafts

import json
from dapla_toolbelt_datafangst import Drafts

my_drafts = Drafts.list_mine()
print(json.dumps([d.to_dict() for d in my_drafts], indent=2, default=str))

List drafts from all your teams

from dapla_toolbelt_datafangst import Drafts

team_drafts = Drafts.list_team_drafts()
for d in team_drafts:
    print(f"{d.id}: {d.name} (team: {d.dapla_team.display_name})")

Get a specific draft

from dapla_toolbelt_datafangst import Drafts

draft = Drafts.get(draft_id=123)
print(draft.to_json())

Create a new draft

from dapla_toolbelt_datafangst import (
    CollectionInstrument,
    Drafts,
    RequestCollection,
    ToolConfig,
    ToolAltinn,
)
from dapla_toolbelt_datafangst._generated.kudoc_client.models.altinn_form import AltinnForm

draft = Drafts.create(
    RequestCollection(
        name="My New Collection",
        dapla_team_uniform_name="team-my-team",
        spec_categ_data=False,
        collection_instrument=[
            CollectionInstrument(
                name="Altinn skjema",
                tool=ToolConfig(
                    actual_instance=ToolAltinn(
                        tool_type="skjemaAltinn",
                        forms=[AltinnForm(id="RA-0329", prefill=False)],
                    )
                ),
            )
        ],
    )
)
print(f"Created draft with ID: {draft.id}")

Update an existing draft

from dapla_toolbelt_datafangst import Drafts, RequestCollection

existing = Drafts.get(draft_id=123)

updated = Drafts.update(
    draft_id=123,
    draft=RequestCollection(
        name="Updated Collection Name",
        dapla_team_uniform_name=existing.dapla_team.uniform_name,
        spec_categ_data=existing.spec_categ_data,
        collection_instrument=existing.collection_instrument,
    ),
)
print(f"Updated: {updated.name}")

Publish a draft

from dapla_toolbelt_datafangst import Drafts

published = Drafts.publish(draft_id=123)
print(f"Published collection ID: {published.id}")

Delete a draft

from dapla_toolbelt_datafangst import Drafts

Drafts.delete(draft_id=123)

Data Models

RequestCollection

Used when creating or updating a draft.

ResponseCollection

Returned from all read operations. Contains all RequestCollection fields plus:

CollectionInstrument

Describes a single instrument within a collection.

Tool Types

ToolConfig wraps one of three tool types:

ToolAltinn — Altinn form-based collection:

• tool_type: "skjemaAltinn"
• forms: list of AltinnForm (each with id and prefill)

ToolBlaise — Blaise interview-based collection:

• tool_type: "blaise"
• name_acronym, survey_type (Panel / Tverrsnitt), interview_mode (CAPI, CATI, CAWI, PAPI, APP), volume

ToolAPI — API-based collection:

• tool_type: "api"
• api_name, description, api_url_test, api_url_prod, authentication_type (maskinporten, oauth2, api_key, basic, none), data_format (json, csv, xml, parquet), and more

Enums

Configuration

Environment Variables

When DAPLA_ENVIRONMENT is set, the library automatically resolves the correct API host:

Note: PROD environment is not yet available.

Authentication

Authentication is handled automatically via dapla-auth-client. The library fetches a personal access token with scopes all_groups and current_group for the kudoc audience. Tokens are refreshed on every API call.

If you get an Unauthorized error, try logging out and back in to your Dapla session.

Error Handling

All API errors are wrapped in DaplaClientError (also aliased as KudocClientError) with user-friendly messages:

from dapla_toolbelt_datafangst import Collections, DaplaClientError

try:
    collection = Collections.get_collection(collection_id=999999)
except DaplaClientError as e:
    print(e)  # "Not found. Check that the ID is correct and the resource exists."

API Reference

Collections (read-only)

Drafts (CRUD)

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, Dapla Toolbelt Datafangst is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project was generated from Statistics Norway's SSB PyPI Template.