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
Validation / Registry spirit_safe SpiritSafe source config, registry discovery, query hydration, and caching
Wikibase Contracts wikibase Package-owned Wikibase datatype registry access and runtime normalization helpers
Transform bottler Transform data into Wikidata format
Deliver shipper Submit data to Wikibase-compatible APIs
Registry / Orchestration spirit_safe SpiritSafe registry and profile artifact orchestration
Utilities auth Authentication for Wikidata and OSM
sitelinks Manage Wikipedia sitelinks
sparql Query Wikidata with SPARQL
Profiles profiles Profile loading and validation
Ontology spirit_safe Data Distillery semantics materialized through SpiritSafe artifacts

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()
print(profiles)

📖 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 - transform_entity_for_write() - Convert raw entity JSON into shipper-ready payloads - fetch_property_labels() - Get property labels

Mash Formatters

Convert templates to different output formats.

Key classes: - QSV1Formatter - Format as QuickStatements V1

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()
  • resolve_profile_path(), resolve_query_ref()
  • LookupCache, LookupFetcher

Wikibase

Expose package-owned Wikibase runtime contracts and datatype registry helpers.

Key classes/functions:

  • WikibaseDatatypeSpec
  • load_wikibase_datatype_registry()
  • get_wikibase_datatype_spec()
  • list_wikibase_datatypes()

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)

Spirit Safe

Own profile/materialization orchestration for Data Distillery semantics in runtime artifacts.

Key functions:

  • export_entity_profile_json_documents()
  • hydrate_value_lists_from_cache()

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

Legacy module notice and contract direction for superseded YAML-era profile surfaces.

Current runtime owners: - spirit_safe - JSON profile artifacts and loading - still_charger - packet assembly/charging - fermenter - validation/coercion/conformance - wizard - interactive runtime

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