Skip to content

API Reference

Overview

The GKC library is organized into modules corresponding to stages of the data distillery workflow. Each module provides Python functions and classes for loading, transforming, validating, and delivering data to knowledge systems like Wikidata.

This reference documents the library API - functions and classes you import and use in Python code. For command-line usage, see the CLI Reference.

Module Organization

GKC modules are grouped by their role in the distillery pipeline:

Stage Module Purpose
Mash mash Load data from Wikidata and other sources
mash_formatters Convert templates to output formats
Packet Fill still_charger Fill curation packet scaffolds with concrete source values
Barreling Transform cooperage Convert charged packet data into shippable operation plans
Validation / Registry spirit_safe SpiritSafe source config, registry discovery, query hydration, and caching
Transform bottler Transform data into Wikidata format
Deliver shipper Submit data to Wikibase-compatible APIs
Registry / Orchestration wikibase Foundation audit/init and profile-driven write planning orchestration
Utilities auth Authentication for Wikidata and OSM
sitelinks Manage Wikipedia sitelinks
sparql Query Wikidata with SPARQL
Profiles profiles YAML profile loading and validation
Ontology ontology Two-layer ontology extraction from Data Distillery Wikibase

Quick Reference by Task

Load a Wikidata Item

from gkc.mash import WikibaseLoader

loader = WikibaseLoader()
template = loader.load("Q42")

📖 Mash Module Documentation

Format as QuickStatements

from gkc.mash import WikibaseLoader
from gkc.mash_formatters import QSV1Formatter

loader = WikibaseLoader()
template = loader.load("Q42")

formatter = QSV1Formatter()
qs_text = formatter.format(template, for_new_item=True)

📖 Mash Formatters Documentation

Discover and Load SpiritSafe Profiles

import gkc

# default mode is GitHub: skybristol/SpiritSafe@main
profiles = gkc.list_profiles()
metadata = gkc.get_profile_metadata("TribalGovernmentUS")
print(metadata.version)

📖 SpiritSafe Module Documentation

Query Wikidata with SPARQL

from gkc.sparql import SPARQLQuery

executor = SPARQLQuery()
results = executor.query("""
    SELECT ?item ?itemLabel WHERE {
      ?item wdt:P31 wd:Q5 .
      SERVICE wikibase:label { bd:serviceParam wikibase:language "en" . }
    }
    LIMIT 10
""")

📖 SPARQL Module Documentation

Authenticate with Wikidata

from gkc.auth import WikiverseAuth

auth = WikiverseAuth()
auth.login(username="YourUsername", password="YourPassword")

📖 Authentication Documentation

Core Modules

Mash

Load data from Wikidata and other sources as templates for processing.

Key classes: - WikibaseLoader - Load Wikidata items - WikibaseItemTemplate - Manipulate loaded data

Key functions: - strip_entity_identifiers() - Prepare for new item creation - fetch_property_labels() - Get property labels

Mash Formatters

Convert templates to different output formats.

Key classes: - QSV1Formatter - Format as QuickStatements V1

Cooperage

Convert charged curation packet content into shippable write operations.

Key functions:

  • barrel_curation_packet_to_wikibase_plan() - Build operation plans from charged packets
  • BarrelPlanReport and BarrelIssue - Structured barreling diagnostics
  • fetch_entity_rdf() - Get entity RDF data
  • fetch_schema_specification() - Get EntitySchema ShEx
  • fetch_entity_schema_json() - Get EntitySchema JSON
  • fetch_entity_schema_metadata() - Get EntitySchema label/description metadata
  • get_entity_uri() - Build canonical entity URI
  • validate_entity_reference() - Validate ID format (Q, P, L, E)

Still Charger

Fill curation packet scaffolds with concrete values from source payloads.

Key classes/functions:

  • charge_curation_packet() - Apply source values to packet entities
  • ChargeReport and ChargeIssue - Structured charging diagnostics

Spirit Safe

Configure SpiritSafe source mode, discover profile registrants, resolve profile/query references, and hydrate/cache SPARQL-driven allowed-items lists.

Key classes/functions:

  • SpiritSafeSourceConfig
  • set_spirit_safe_source(), get_spirit_safe_source()
  • list_profiles(), profile_exists(), get_profile_metadata()
  • resolve_profile_path(), resolve_query_ref()
  • hydrate_profile_lookups(), LookupCache, LookupFetcher

Bottler

Transform data into Wikidata item structure.

Key classes:

  • DataTypeTransformer - Build Wikibase datavalues by datatype
  • SnakBuilder - Create snak structures from transformed values
  • ClaimBuilder - Build statement objects with qualifiers/references
  • Distillate - Load and hold mapping configuration for transformation flows

Shipper

Submit data to Wikibase via the API.

Key classes: - WikidataShipper - Submit QuickStatements or JSON to Wikidata - WikibaseShipper - Primary write interface for Wikibase item/property operations - CommonsShipper - Wikimedia Commons submission (planned) - OpenStreetMapShipper - OSM submission (planned)

Wikibase

Audit and initialize foundation ontology definitions for Data Distillery, and orchestrate packet-to-write planning.

Key functions:

  • load_foundation_profiles()
  • audit_wikibase_foundation()
  • init_wikibase_foundation()
  • build_wikibase_write_plan()

Ontology

Extract ontology index and full profile graph data from Data Distillery Wikibase.

Key functions:

  • fetch_ontology_index()
  • fetch_profile_ids()
  • fetch_profile_graph()
  • resolve_statement_guidance()

Utility Modules

Authentication

Manage credentials for Wikidata, Wikipedia, Wikimedia Commons, and OpenStreetMap.

Key classes: - WikiverseAuth - Wikidata/Wikipedia authentication - OpenStreetMapAuth - OSM authentication

Documentation coming soon

Manage and validate Wikipedia sitelinks for Wikidata items.

Key functions: - validate_sitelink() - Check if Wikipedia page exists - get_sitelink_url() - Build Wikipedia URL from title

Documentation coming soon

SPARQL

Query Wikidata and other SPARQL endpoints.

Key classes: - SPARQLQuery - Execute queries and handle results

Key functions: - execute_sparql() - Run raw SPARQL queries

Profiles

YAML-first profiles for validation and form schema generation.

Key classes: - ProfileLoader - Load YAML profiles - ProfileValidator - Validate Wikidata items - FormSchemaGenerator - Build form schemas

Package Configuration

Language Settings

import gkc

# Set single language
gkc.set_languages("en")

# Set multiple languages
gkc.set_languages(["en", "es", "fr"])

# Get current setting
languages = gkc.get_languages()

Many modules use the package-level language configuration for filtering labels, descriptions, and other multilingual content.

See Also