Skip to content

Getting Started

This guide will help you set up and start using Huwise Utils Python.

Prerequisites

  • Python 3.12 or higher
  • Your Huwise domain URL (optional if using data.bs.ch)
  • A Huwise API key

Installation

pip install huwise-utils-py

uv add huwise-utils-py

Configuration

Environment Variables

The library uses the following environment variables:

Variable Required Description
HUWISE_API_KEY Yes API key for Automation API authentication
HUWISE_DOMAIN No Your Huwise domain (defaults to data.bs.ch)
HUWISE_API_TYPE No API version (defaults to automation/v1.0)

Setting Up

export HUWISE_API_KEY="your-api-key"
export HUWISE_API_TYPE="automation/v1.0"  # Optional

For non-default portals, also set:

export HUWISE_DOMAIN="your-portal.example.org"

Create a .env file in your project root:

HUWISE_API_KEY=your-api-key
HUWISE_API_TYPE=automation/v1.0

Add HUWISE_DOMAIN=your-portal.example.org only when not using data.bs.ch.

from huwise_utils_py import HuwiseConfig

config = HuwiseConfig(
    api_key="your-api-key",
    domain="data.bs.ch",
    api_type="automation/v1.0",
)

Basic Usage

Creating a Dataset Instance

from huwise_utils_py import HuwiseDataset

# Create from a dataset ID
dataset = HuwiseDataset.from_id("100123")

Reading Metadata

# Get individual fields
title = dataset.get_title()
description = dataset.get_description()
keywords = dataset.get_keywords()

# Get all metadata
metadata = dataset.get_metadata()

Updating Metadata

# Update a single field (publishes automatically)
dataset.set_title("New Title")

# Update without publishing
dataset.set_title("New Title", publish=False)

# Chain multiple updates
dataset.set_title("Title", publish=False).set_description("Description", publish=False).set_keywords(
    ["tag1", "tag2"], publish=False
).publish()

Using Custom Configuration

from huwise_utils_py import HuwiseConfig, HuwiseDataset

# Create custom config
config = HuwiseConfig(
    api_key="different-key",
    domain="other.domain.com",
)

# Use with dataset
dataset = HuwiseDataset.from_id("100123", config=config)

Bulk Operations

For working with multiple datasets:

from huwise_utils_py import bulk_get_metadata, bulk_get_metadata_async

# Synchronous
metadata = bulk_get_metadata(dataset_ids=["100123", "100456", "100789"])

# Asynchronous (much faster for many datasets)
import asyncio


async def fetch_all():
    return await bulk_get_metadata_async(dataset_ids=["100123", "100456", "100789"])


metadata = asyncio.run(fetch_all())

Logging

Initialize stdlib logging (Airflow-friendly) for your application:

from huwise_utils_py import init_logger, get_logger

# Initialize once at app startup
init_logger()

# Get a logger for your module
logger = get_logger(__name__)
logger.info("Starting data sync", dataset_count=10)

Next Steps