vnbdigital-client 0.1.1

A Python client for accessing vnbdigital.de grid operator data via GraphQL

vnbdigital-client

A Python client library and CLI tool for accessing vnbdigital.de grid operator (Verteilnetzbetreiber) data. This package abstracts the GraphQL API and provides a simple, intuitive interface for looking up operators by their BDEW code.

Features

• Simple Python API for vnbdigital.de grid operator data
• Command-line interface (CLI) for quick lookups
• Typed dataclasses (Operator, Region) for structured results
• Batch lookups for multiple operators
• Built with modern Python tooling (uv, pyproject.toml)
• Dev container support for easy development
• Comprehensive test coverage

Installation

From PyPI (when published)

pip install vnbdigital-client

Oder mit uv:

uv add vnbdigital-client

From source with uv

# Clone the repository
git clone https://github.com/the78mole/vnbdigital-client.git
cd vnbdigital-client

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run directly (uv creates the venv and installs dependencies automatically)
uv run vnbdigital --help

Usage

Python API

from vnbdigital_client import VNBDigitalClient

client = VNBDigitalClient()

# Look up a grid operator by BDEW code / ID
operator = client.get_operator("179")
if operator:
    print(f"{operator.name} - {operator.postcode} {operator.city}")
    print(f"Website: {operator.website}")
    for region in operator.regions:
        print(f"  Region: {region.name}")

# Get detailed information (types, description, services, documents, ...)
details = client.get_operator_details("179")
if details:
    print(f"Typ: {', '.join(details.types)}")
    print(f"Beschreibung: {details.description}")
    print(f"Aufrufe: {details.clicks}")

# Batch lookup for multiple operators
results = client.get_operators(["179", "180", "181"])
for oid, op in results.items():
    if op:
        print(f"[{oid}] {op.name}")
    else:
        print(f"[{oid}] not found")

Command-Line Interface

The package includes a CLI tool for easy command-line access:

# Basic operator lookup
vnbdigital operator 179

# Detailed information
vnbdigital details 179

# JSON output
vnbdigital operator 179 --format json

# Batch lookup
vnbdigital batch 179 180 181

# Override API URL via environment variable
export VNBDIGITAL_API_URL="https://www.vnbdigital.de/gateway/graphql"
vnbdigital operator 179

Development

Using Dev Container

This project includes a dev container configuration for easy development:

1. Open the project in VS Code
2. Install the "Dev Containers" extension
3. Click "Reopen in Container" when prompted
4. The workspace is mounted into the container automatically
5. When you run the first uv command, it will create a .venv and install dependencies

Manual Setup

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run tests (uv automatically creates a .venv and installs all dependencies)
uv run --extra dev pytest

# Run linting
uv run --extra dev ruff check src/

# Format code
uv run --extra dev black src/

# Type checking
uv run --extra dev mypy src/vnbdigital_client/

Running Tests

# Run all tests
uv run --extra dev pytest

# Run with coverage
uv run --extra dev pytest --cov=vnbdigital_client --cov-report=html

# Run specific test file
uv run --extra dev pytest tests/test_client.py

Project Structure

vnbdigital-client/
├── .devcontainer/          # Dev container configuration
│   ├── Dockerfile
│   └── devcontainer.json
├── .github/
│   └── workflows/          # GitHub Actions workflows
│       ├── ci.yml         # Continuous integration
│       └── publish.yml    # PyPI publishing
├── src/
│   └── vnbdigital_client/  # Main package
│       ├── __init__.py
│       ├── client.py       # API client
│       └── cli.py          # CLI tool
├── tests/                  # Test suite
│   ├── test_client.py
│   └── test_cli.py
├── pyproject.toml          # Project configuration
├── renovate.json           # Renovate config
└── README.md

Configuration

Environment Variables

• VNBDIGITAL_API_URL: GraphQL endpoint URL (default: https://www.vnbdigital.de/gateway/graphql)

Renovate

This project uses Renovate for automated dependency updates. Configuration is in renovate.json.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Daniel Glaser

Acknowledgments

• Built with uv - A fast Python package installer
• CLI built with Click
• Data provided by vnbdigital.de