dapla-toolbelt-datafangst 0.0.2

Dapla Toolbelt Datafangst

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

List all published collections

import json
from dapla_toolbelt_datafangst 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.

Field	Type	Required	Description
name	str	Yes	Name of the collection
dapla_team_uniform_name	str	Yes	Dapla team uniform name (e.g. team-my-team)
spec_categ_data	bool	Yes	Whether the collection contains special category data
collection_instrument	list[CollectionInstrument]	Yes	List of collection instruments
assignment_type	AssignmentType	No	Stat (statistical) or Marked (commercial)
relevant_docs	list[RelevantDoc]	No	Links to relevant documents (DPIA, vedtak, etc.)
reporting_unit_type	list[str]	No	Reporting unit types
statistics_register_id	str	No	Statistics register identifier
information_provider	list[str]	No	Information provider codes (KLASS #712)
valid_from	datetime	No	Validity start date
valid_until	datetime	No	Validity end date
sample_plan	SamplePlan	No	Sampling plan details
period_plan	PeriodPlan	No	Period plan configuration

ResponseCollection

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

Field	Type	Description
id	str	Unique collection identifier
dapla_team	Team	Full team object (uniform_name, display_name, section_name)
version_information	VersionInformation	Version ID, status, timestamps, and author

CollectionInstrument

Describes a single instrument within a collection.

Field	Type	Description
id	str	Unique identifier
name	str	Human-readable name
instrument_source	str	Information provider for this instrument
instrument_frequency	str	Frequency: Engangs, Aar, Halvaar, Kvartal, Termin, Maaned, Uke, Dag, Kontinuerlig
ext_contact	list[InstrumentContact]	External contact persons
int_contact	list[InstrumentContact]	Internal SSB contact persons
tool	ToolConfig	Collection tool configuration (one of ToolAltinn, ToolBlaise, or ToolAPI)

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

Enum	Values
Status	DRAFT, PUBLISHED, ARCHIVED
AssignmentType	Stat, Marked
RelevantDocType	dpia, registermelding, vedtak, other_vedtak, delivery_agreement, cooperation_agreement, other_agreement

Configuration

Environment Variables

Variable	Description	Default
DAPLA_ENVIRONMENT	Dapla lifecycle environment (DEV, QA, TEST)	Not set (uses localhost)
KUDOC_HOST	Manual override for the Kudoc API URL	http://localhost:8080

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

Environment	API Host
DEV	https://dev-collection-gateway.intern.test.ssb.no/kudoc
QA	https://qa-collection-gateway.intern.test.ssb.no/kudoc
TEST	https://test-collection-gateway.intern.test.ssb.no/kudoc

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

HTTP Status	Message
400	Problem with supplied data (includes field-level validation details)
401	Authentication problem — token may have expired
403	Forbidden — no access to the resource
404	Not found — check the ID
405	Operation not allowed for current resource state
409	Conflict with existing data

API Reference

Collections (read-only)

Method	Description
Collections.list_collections()	List all published collections
Collections.get_collection(collection_id)	Get a single collection by ID
Collections.search_by_name(name)	Search by name (partial match)
Collections.search_by_altinn_id(altinn_questionnaire_id)	Search by Altinn questionnaire ID
Collections.get_versions(collection_id)	Get all versions of a collection

Drafts (CRUD)

Method	Description
Drafts.list_mine()	List the current user's drafts
Drafts.list_team_drafts()	List drafts from all teams the user belongs to
Drafts.get(draft_id)	Get a draft by ID
Drafts.create(draft)	Create a new draft
Drafts.update(draft_id, draft)	Update an existing draft
Drafts.delete(draft_id)	Delete a draft
Drafts.publish(draft_id)	Publish a draft as a collection

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.