')
+def company_details(name):
+ """Get company details."""
+ try:
+ companies = search(name, keyword_option="exact")
+ if not companies:
+ return jsonify({"error": "Not found"}), 404
+
+ details = get_details(companies[0])
+ return jsonify({
+ "name": details.name,
+ "capital": details.capital,
+ "currency": details.currency
+ })
+ except SearchError as e:
+ return jsonify({"error": str(e)}), 500
+
+if __name__ == '__main__':
+ app.run(debug=True)
+```
+
+---
+
+## Django
+
+### Django Management Command
+
+```python
+# myapp/management/commands/search_companies.py
+from django.core.management.base import BaseCommand
+from handelsregister import search
+
+class Command(BaseCommand):
+ help = 'Search for companies in the commercial register'
+
+ def add_arguments(self, parser):
+ parser.add_argument('query', type=str)
+ parser.add_argument('--state', type=str, default=None)
+ parser.add_argument('--limit', type=int, default=10)
+
+ def handle(self, *args, **options):
+ query = options['query']
+ states = [options['state']] if options['state'] else None
+ limit = options['limit']
+
+ companies = search(query, states=states)
+
+ self.stdout.write(f"Found {len(companies)} companies\n")
+ for company in companies[:limit]:
+ self.stdout.write(f" - {company.name}")
+```
+
+### Django Model Integration
+
+```python
+# models.py
+from django.db import models
+from handelsregister import search, get_details
+
+class Company(models.Model):
+ name = models.CharField(max_length=255)
+ court = models.CharField(max_length=100)
+ register_number = models.CharField(max_length=50)
+ capital = models.DecimalField(max_digits=15, decimal_places=2, null=True)
+ last_updated = models.DateTimeField(auto_now=True)
+
+ @classmethod
+ def create_from_register(cls, company_name):
+ """Create company from register data."""
+ companies = search(company_name, exact=True)
+ if not companies:
+ raise ValueError(f"Company not found: {company_name}")
+
+ details = get_details(companies[0])
+
+ return cls.objects.create(
+ name=details.name,
+ court=details.court,
+ register_number=details.register_number,
+ capital=float(details.capital) if details.capital else None
+ )
+
+ def refresh_from_register(self):
+ """Update company data from register."""
+ companies = search(self.name, exact=True)
+ if companies:
+ details = get_details(companies[0])
+ self.capital = float(details.capital) if details.capital else None
+ self.save()
+```
+
+---
+
+## Celery
+
+### Background Tasks
+
+```python
+# tasks.py
+from celery import Celery
+from handelsregister import search, get_details
+import time
+
+app = Celery('tasks', broker='redis://localhost:6379/0')
+
+@app.task(bind=True, max_retries=3)
+def search_companies_task(self, query, states=None):
+ """Search companies in background."""
+ try:
+ return search(query, states=states)
+ except Exception as e:
+ self.retry(countdown=60)
+
+@app.task
+def batch_search_task(keywords):
+ """Search multiple keywords with rate limiting."""
+ results = {}
+ for keyword in keywords:
+ results[keyword] = search(keyword)
+ time.sleep(60) # Rate limit
+ return results
+
+# Usage
+result = search_companies_task.delay("Bank", states=["BE"])
+companies = result.get(timeout=30)
+```
+
+---
+
+## SQLAlchemy
+
+### Store Results in Database
+
+```python
+from sqlalchemy import create_engine, Column, String, Float, DateTime
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+from datetime import datetime
+from handelsregister import search, get_details
+
+Base = declarative_base()
+engine = create_engine('sqlite:///companies.db')
+Session = sessionmaker(bind=engine)
+
+class Company(Base):
+ __tablename__ = 'companies'
+
+ id = Column(String, primary_key=True)
+ name = Column(String)
+ court = Column(String)
+ register_number = Column(String)
+ capital = Column(Float)
+ updated_at = Column(DateTime, default=datetime.utcnow)
+
+Base.metadata.create_all(engine)
+
+def save_company(company_name):
+ """Search and save company to database."""
+ session = Session()
+
+ companies = search(company_name, exact=True)
+ if not companies:
+ return None
+
+ details = get_details(companies[0])
+
+ company = Company(
+ id=f"{details.court}_{details.register_num}",
+ name=details.name,
+ court=details.court,
+ register_num=details.register_num,
+ capital=float(details.capital) if details.capital else None
+ )
+
+ session.merge(company)
+ session.commit()
+
+ return company
+```
+
+---
+
+## Jupyter Notebook
+
+### Interactive Analysis
+
+```python
+# Cell 1: Setup
+from handelsregister import search, get_details
+import pandas as pd
+import matplotlib.pyplot as plt
+
+# Cell 2: Search and explore
+companies = search("Bank", states=["BE", "HH", "BY"])
+# Convert Company objects to dicts for pandas
+df = pd.DataFrame([c.to_dict() for c in companies])
+df.head()
+
+# Cell 3: Visualize by state
+df['state'].value_counts().plot(kind='bar')
+plt.title('Banks by State')
+plt.xlabel('State')
+plt.ylabel('Count')
+plt.show()
+
+# Cell 4: Get details for top companies
+# Use Company objects directly (not DataFrame rows)
+for company in companies[:3]:
+ details = get_details(company)
+ print(f"{details.name}: {details.capital} {details.currency}")
+```
+
+---
+
+## CLI Scripts
+
+### Bash Integration
+
+```bash
+#!/bin/bash
+# search_and_notify.sh
+
+# Search for new companies
+results=$(handelsregister -s "Startup" --states BE --json)
+
+# Count results
+count=$(echo "$results" | jq 'length')
+
+if [ "$count" -gt 0 ]; then
+ echo "Found $count new startups in Berlin"
+
+ # Save to file with date
+ echo "$results" > "startups_$(date +%Y%m%d).json"
+
+ # Optional: Send notification
+ # curl -X POST "https://slack.com/webhook" -d "{\"text\": \"Found $count startups\"}"
+fi
+```
+
+### Python Script with Logging
+
+```python
+#!/usr/bin/env python3
+"""Daily company search script with logging."""
+
+import logging
+import json
+from datetime import datetime
+from handelsregister import search
+
+logging.basicConfig(
+ level=logging.INFO,
+ format='%(asctime)s - %(levelname)s - %(message)s',
+ handlers=[
+ logging.FileHandler('company_search.log'),
+ logging.StreamHandler()
+ ]
+)
+
+def main():
+ logging.info("Starting company search")
+
+ keywords = ["Bank", "FinTech", "InsurTech"]
+
+ all_results = {}
+ for keyword in keywords:
+ logging.info(f"Searching: {keyword}")
+ results = search(keyword, states=["BE"])
+ all_results[keyword] = results
+ logging.info(f"Found {len(results)} companies")
+
+ # Save results
+ filename = f"results_{datetime.now():%Y%m%d_%H%M%S}.json"
+ with open(filename, 'w') as f:
+ json.dump(all_results, f, indent=2)
+
+ logging.info(f"Results saved to {filename}")
+
+if __name__ == '__main__':
+ main()
+```
+
+---
+
+## See Also
+
+- [Simple Examples](simple.md) â Basic examples
+- [Advanced Examples](advanced.md) â Complex use cases
+- [API Reference](../api/index.md) â Technical documentation
+
diff --git a/docs/examples/simple.de.md b/docs/examples/simple.de.md
new file mode 100644
index 00000000..4eb5a443
--- /dev/null
+++ b/docs/examples/simple.de.md
@@ -0,0 +1,235 @@
+# Einfache Beispiele
+
+Grundlegende Beispiele zum Einstieg mit dem Handelsregister-Package.
+
+## Suchbeispiele
+
+### Einfache Suche
+
+```python
+from handelsregister import search
+
+# Suche nach Unternehmen mit "Deutsche Bahn"
+firmen = search("Deutsche Bahn")
+
+print(f"{len(firmen)} Unternehmen gefunden")
+for firma in firmen:
+ print(f" - {firma.name}")
+```
+
+### Suche mit Bundesland-Filter
+
+```python
+from handelsregister import search
+
+# Suche nach Banken in Berlin
+banken = search("Bank", states=["BE"])
+
+print(f"Banken in Berlin: {len(banken)}")
+```
+
+### Suche mit mehreren Filtern
+
+```python
+from handelsregister import search
+
+# Aktive GmbHs in Hamburg
+firmen = search(
+ keywords="Consulting",
+ states=["HH"],
+ register_type="HRB",
+ include_deleted=False
+)
+```
+
+### Exakte Namenssuche
+
+```python
+from handelsregister import search
+
+# Exakten Firmennamen suchen
+firmen = search("GASAG AG", keyword_option="exact")
+
+if firmen:
+ print(f"Gefunden: {firmen[0].name}")
+else:
+ print("Unternehmen nicht gefunden")
+```
+
+---
+
+## Mit Ergebnissen arbeiten
+
+### Auf Unternehmensdaten zugreifen
+
+```python
+from handelsregister import search
+
+firmen = search("Siemens AG", keyword_option="exact")
+
+if firmen:
+ firma = firmen[0]
+
+ print(f"Name: {firma.name}")
+ print(f"Gericht: {firma.court}")
+ print(f"Nummer: {firma.register_num}")
+ print(f"Status: {firma.status}")
+ print(f"Bundesland: {firma.state}")
+```
+
+### In Liste von Namen konvertieren
+
+```python
+from handelsregister import search
+
+firmen = search("Bank", states=["BE"])
+
+# Nur die Namen extrahieren
+namen = [f['name'] for f in firmen]
+print(namen)
+```
+
+### Ergebnisse in Python filtern
+
+```python
+from handelsregister import search
+
+firmen = search("Bank")
+
+# Nach bestimmten Kriterien filtern
+grosse_banken = [
+ f for f in firmen
+ if "AG" in f['name'] and f['status'] == 'aktuell eingetragen'
+]
+```
+
+---
+
+## Details abrufen
+
+### Grundlegende Details
+
+```python
+from handelsregister import search, get_details
+
+# Nach Unternehmen suchen
+firmen = search("GASAG AG", keyword_option="exact")
+
+if firmen:
+ # VollstÀndige Details abrufen
+ details = get_details(firmen[0])
+
+ print(f"Name: {details.name}")
+ print(f"Kapital: {details.capital} {details.currency}")
+```
+
+### Auf Adresse zugreifen
+
+```python
+from handelsregister import search, get_details
+
+firmen = search("GASAG AG", keyword_option="exact")
+details = get_details(firmen[0])
+
+if details.address:
+ print(f"StraĂe: {details.address.street}")
+ print(f"Ort: {details.address.postal_code} {details.address.city}")
+```
+
+### Vertreter auflisten
+
+```python
+from handelsregister import search, get_details
+
+firmen = search("Deutsche Bahn AG", keyword_option="exact")
+details = get_details(firmen[0])
+
+print("GeschĂ€ftsfĂŒhrung:")
+for vertreter in details.representatives:
+ print(f" - {vertreter.name}: {vertreter.role}")
+```
+
+---
+
+## CLI-Beispiele
+
+### Einfache CLI-Suche
+
+```bash
+# Einfache Suche
+handelsregister -s "Deutsche Bahn"
+
+# Suche in bestimmtem Bundesland
+handelsregister -s "Bank" --states BE
+
+# Mehrere BundeslÀnder
+handelsregister -s "Bank" --states BE,HH,BY
+```
+
+### Ausgabeformate
+
+```bash
+# Standardausgabe
+handelsregister -s "GASAG"
+
+# JSON-Ausgabe
+handelsregister -s "GASAG" --json
+
+# Kompakte Ausgabe
+handelsregister -s "GASAG" --compact
+```
+
+### Mit Details
+
+```bash
+# Unternehmensdetails abrufen
+handelsregister -s "GASAG AG" --exact --details
+```
+
+### In Datei speichern
+
+```bash
+# JSON in Datei speichern
+handelsregister -s "Bank" --states BE --json > berliner_banken.json
+
+# Ergebnisse zÀhlen
+handelsregister -s "Bank" --json | jq 'length'
+```
+
+---
+
+## Fehlerbehandlung
+
+### Einfache Fehlerbehandlung
+
+```python
+from handelsregister import search, SearchError
+
+try:
+ firmen = search("Bank")
+ print(f"{len(firmen)} Unternehmen gefunden")
+except SearchError as e:
+ print(f"Suche fehlgeschlagen: {e}")
+```
+
+### Auf leere Ergebnisse prĂŒfen
+
+```python
+from handelsregister import search
+
+firmen = search("xyz123nichtvorhanden")
+
+if not firmen:
+ print("Keine Unternehmen gefunden")
+else:
+ print(f"{len(firmen)} Unternehmen gefunden")
+```
+
+---
+
+## NĂ€chste Schritte
+
+- [Fortgeschrittene Beispiele](advanced.md) â Komplexere AnwendungsfĂ€lle
+- [Integrationsbeispiele](integrations.md) â Verwendung mit anderen Tools
+- [API-Referenz](../api/index.md) â VollstĂ€ndige Dokumentation
+
diff --git a/docs/examples/simple.md b/docs/examples/simple.md
new file mode 100644
index 00000000..979f00fc
--- /dev/null
+++ b/docs/examples/simple.md
@@ -0,0 +1,249 @@
+# Simple Examples
+
+Basic examples to get started with the Handelsregister package.
+
+## Search Examples
+
+### Basic Search
+
+```python
+from handelsregister import search
+
+# Search for companies containing "Deutsche Bahn"
+companies = search("Deutsche Bahn")
+
+print(f"Found {len(companies)} companies")
+for company in companies:
+ print(f" - {company.name}")
+```
+
+### Search with State Filter
+
+```python
+from handelsregister import search, State
+
+# Search for banks in Berlin (recommended: Enum)
+banks = search("Bank", states=[State.BE])
+
+# String-based API still works
+banks = search("Bank", states=["BE"])
+
+print(f"Banks in Berlin: {len(banks)}")
+```
+
+### Search with Multiple Filters
+
+```python
+from handelsregister import search, State, RegisterType
+
+# Active GmbHs in Hamburg (recommended: Enums)
+companies = search(
+ keywords="Consulting",
+ states=[State.HH],
+ register_type=RegisterType.HRB,
+ include_deleted=False
+)
+
+# String-based API still works
+companies = search(
+ keywords="Consulting",
+ states=["HH"],
+ register_type="HRB",
+ include_deleted=False
+)
+```
+
+### Exact Name Search
+
+```python
+from handelsregister import search, KeywordMatch
+
+# Find exact company name (recommended: Enum)
+companies = search("GASAG AG", keyword_option=KeywordMatch.EXACT)
+
+# String-based API still works
+companies = search("GASAG AG", keyword_option="exact")
+
+if companies:
+ print(f"Found: {companies[0].name}")
+else:
+ print("Company not found")
+```
+
+---
+
+## Working with Results
+
+### Accessing Company Data
+
+```python
+from handelsregister import search, KeywordMatch
+
+companies = search("Siemens AG", keyword_option=KeywordMatch.EXACT)
+
+if companies:
+ company = companies[0]
+
+ print(f"Name: {company.name}")
+ print(f"Court: {company.court}")
+ print(f"Number: {company.register_num}")
+ print(f"Status: {company.status}")
+ print(f"State: {company.state}")
+```
+
+### Converting to List of Names
+
+```python
+from handelsregister import search, State
+
+companies = search("Bank", states=[State.BE])
+
+# Extract just the names
+names = [c.name for c in companies]
+print(names)
+```
+
+### Filtering Results in Python
+
+```python
+from handelsregister import search
+
+companies = search("Bank")
+
+# Filter for specific criteria
+large_banks = [
+ c for c in companies
+ if "AG" in c.name and c.status == 'currently registered'
+]
+```
+
+---
+
+## Getting Details
+
+### Basic Details
+
+```python
+from handelsregister import search, get_details, KeywordMatch
+
+# Search for company (recommended: Enum)
+companies = search("GASAG AG", keyword_option=KeywordMatch.EXACT)
+
+if companies:
+ # Get full details
+ details = get_details(companies[0])
+
+ print(f"Name: {details.name}")
+ print(f"Capital: {details.capital} {details.currency}")
+```
+
+### Accessing Address
+
+```python
+from handelsregister import search, get_details, KeywordMatch
+
+companies = search("GASAG AG", keyword_option=KeywordMatch.EXACT)
+details = get_details(companies[0])
+
+if details.address:
+ print(f"Street: {details.address.street}")
+ print(f"City: {details.address.postal_code} {details.address.city}")
+```
+
+### Listing Representatives
+
+```python
+from handelsregister import search, get_details, KeywordMatch
+
+companies = search("Deutsche Bahn AG", keyword_option=KeywordMatch.EXACT)
+details = get_details(companies[0])
+
+print("Management:")
+for rep in details.representatives:
+ print(f" - {rep.name}: {rep.role}")
+```
+
+---
+
+## CLI Examples
+
+### Basic CLI Search
+
+```bash
+# Simple search
+handelsregister -s "Deutsche Bahn"
+
+# Search in specific state
+handelsregister -s "Bank" --states BE
+
+# Multiple states
+handelsregister -s "Bank" --states BE,HH,BY
+```
+
+### Output Formats
+
+```bash
+# Default output
+handelsregister -s "GASAG"
+
+# JSON output
+handelsregister -s "GASAG" --json
+
+# Compact output
+handelsregister -s "GASAG" --compact
+```
+
+### With Details
+
+```bash
+# Get company details
+handelsregister -s "GASAG AG" --exact --details
+```
+
+### Save to File
+
+```bash
+# Save JSON to file
+handelsregister -s "Bank" --states BE --json > berlin_banks.json
+
+# Count results
+handelsregister -s "Bank" --json | jq 'length'
+```
+
+---
+
+## Error Handling
+
+### Basic Error Handling
+
+```python
+from handelsregister import search, SearchError
+
+try:
+ companies = search("Bank")
+ print(f"Found {len(companies)} companies")
+except SearchError as e:
+ print(f"Search failed: {e}")
+```
+
+### Checking for Empty Results
+
+```python
+from handelsregister import search
+
+companies = search("xyz123nonexistent")
+
+if not companies:
+ print("No companies found")
+else:
+ print(f"Found {len(companies)} companies")
+```
+
+---
+
+## Next Steps
+
+- [Advanced Examples](advanced.md) â More complex use cases
+- [Integration Examples](integrations.md) â Using with other tools
+- [API Reference](../api/index.md) â Complete documentation
+
diff --git a/docs/guide/cache.de.md b/docs/guide/cache.de.md
new file mode 100644
index 00000000..ec873c89
--- /dev/null
+++ b/docs/guide/cache.de.md
@@ -0,0 +1,282 @@
+# Caching
+
+Das Handelsregister-Package enthÀlt ein intelligentes Caching-System, um die Last auf dem Registerportal zu reduzieren und die Leistung zu verbessern.
+
+## Ăbersicht
+
+```mermaid
+graph LR
+ A[Ihre Anwendung] --> B{Cache-PrĂŒfung}
+ B -->|Treffer| C[Gecachte Daten zurĂŒckgeben]
+ B -->|Miss| D[Vom Portal abrufen]
+ D --> E[Im Cache speichern]
+ E --> C
+```
+
+### Standardverhalten
+
+- **Cache aktiviert** standardmĂ€Ăig
+- **TTL (Time-To-Live):** 24 Stunden
+- **Speicherort:** `~/.cache/handelsregister/`
+- **Format:** JSON-Dateien
+
+---
+
+## Cache verwenden
+
+### Automatisches Caching
+
+Caching funktioniert automatisch:
+
+```python
+from handelsregister import search
+
+# Erster Aufruf: Ruft vom Portal ab, speichert im Cache
+ergebnisse1 = search("Deutsche Bank")
+
+# Zweiter Aufruf: Gibt gecachte Daten zurĂŒck (schneller)
+ergebnisse2 = search("Deutsche Bank")
+```
+
+### Cache umgehen
+
+```python
+# Cache fĂŒr diesen Aufruf ĂŒberspringen
+ergebnisse = search("Deutsche Bank", force_refresh=True)
+```
+
+### Cache löschen
+
+```python
+from handelsregister import clear_cache
+
+# Gesamten Cache löschen
+clear_cache()
+```
+
+Oder ĂŒber CLI:
+
+```bash
+handelsregister --clear-cache
+```
+
+---
+
+## Cache-Konfiguration
+
+### Benutzerdefinierte TTL
+
+```python
+from handelsregister import HandelsRegister, SearchCache
+
+# 1-Stunden-Cache
+cache = SearchCache(ttl_hours=1)
+hr = HandelsRegister(cache=cache)
+
+# 7-Tage-Cache
+cache = SearchCache(ttl_hours=168)
+hr = HandelsRegister(cache=cache)
+```
+
+### Benutzerdefiniertes Cache-Verzeichnis
+
+```python
+from handelsregister import SearchCache
+
+cache = SearchCache(
+ cache_dir="/pfad/zum/eigenen/cache",
+ ttl_hours=24
+)
+```
+
+Oder ĂŒber Umgebungsvariable:
+
+```bash
+export HANDELSREGISTER_CACHE_DIR=/tmp/hr-cache
+```
+
+### Caching deaktivieren
+
+```python
+from handelsregister import HandelsRegister
+
+# Kein Caching
+hr = HandelsRegister(cache=None)
+ergebnisse = hr.search("Bank")
+```
+
+---
+
+## Cache-Struktur
+
+Der Cache speichert Daten als JSON-Dateien:
+
+```
+~/.cache/handelsregister/
+âââ searches/
+â âââ a1b2c3d4.json # Suchergebnisse
+â âââ e5f6g7h8.json
+â âââ ...
+âââ details/
+â âââ HRB_12345_Berlin.json # Unternehmensdetails
+â âââ HRB_67890_Hamburg.json
+â âââ ...
+âââ meta.json # Cache-Metadaten
+```
+
+### Cache-Key-Generierung
+
+Cache-Keys werden aus Suchparametern generiert:
+
+```python
+# Diese erzeugen den gleichen Cache-Key:
+search("Bank", states=["BE"])
+search("Bank", states=["BE"])
+
+# Diese erzeugen unterschiedliche Cache-Keys:
+search("Bank", states=["BE"])
+search("Bank", states=["HH"])
+search("Bank", states=["BE"], include_deleted=False)
+```
+
+---
+
+## Cache-Eintrags-Format
+
+```json
+{
+ "timestamp": "2024-01-15T10:30:00Z",
+ "ttl_hours": 24,
+ "query": {
+ "keywords": "Bank",
+ "states": ["BE"],
+ "register_type": null
+ },
+ "results": [
+ {
+ "name": "Deutsche Bank AG",
+ "court": "Frankfurt am Main",
+ "register_num": "HRB 12345",
+ "status": "aktuell eingetragen"
+ }
+ ]
+}
+```
+
+---
+
+## Cache-Status prĂŒfen
+
+```python
+from handelsregister import SearchCache
+
+cache = SearchCache()
+
+# PrĂŒfen ob Eintrag existiert und gĂŒltig ist
+if cache.has_valid_entry("Bank", states=["BE"]):
+ print("Verwende gecachte Daten")
+else:
+ print("Rufe vom Portal ab")
+
+# Cache-Statistiken abrufen
+stats = cache.get_stats()
+print(f"EintrÀge gesamt: {stats['total']}")
+print(f"GĂŒltige EintrĂ€ge: {stats['valid']}")
+print(f"Abgelaufene EintrÀge: {stats['expired']}")
+print(f"Cache-GröĂe: {stats['size_mb']:.2f} MB")
+```
+
+---
+
+## Best Practices fĂŒr Caching
+
+### 1. Standard-Caching verwenden
+
+FĂŒr die meisten AnwendungsfĂ€lle ist der 24-Stunden-Cache angemessen:
+
+```python
+# Einfach search() verwenden - Caching ist automatisch
+ergebnisse = search("Bank")
+```
+
+### 2. KĂŒrzere TTL fĂŒr volatile Daten
+
+Wenn Sie aktuelle Daten benötigen (z.B. fĂŒr rechtliche Verfahren):
+
+```python
+cache = SearchCache(ttl_hours=1) # 1 Stunde
+hr = HandelsRegister(cache=cache)
+```
+
+### 3. LĂ€ngere TTL fĂŒr Analysen
+
+FĂŒr historische Analysen, wo AktualitĂ€t weniger kritisch ist:
+
+```python
+cache = SearchCache(ttl_hours=168) # 7 Tage
+hr = HandelsRegister(cache=cache)
+```
+
+### 4. Kein Cache fĂŒr Einzeloperationen
+
+```python
+# Einzelabfrage, kein Caching nötig
+ergebnisse = search("Spezifische Firma GmbH", force_refresh=True)
+```
+
+### 5. Periodische Cache-Bereinigung
+
+```python
+from handelsregister import SearchCache
+
+cache = SearchCache()
+cache.cleanup_expired() # Abgelaufene EintrÀge entfernen
+```
+
+---
+
+## Speicherplatz
+
+Der Cache kann ĂŒber die Zeit wachsen. Ăberwachen und bei Bedarf bereinigen:
+
+```python
+from handelsregister import SearchCache
+
+cache = SearchCache()
+
+# Cache-GröĂe abrufen
+stats = cache.get_stats()
+print(f"Cache-GröĂe: {stats['size_mb']:.2f} MB")
+
+# Abgelaufene EintrÀge bereinigen
+entfernt = cache.cleanup_expired()
+print(f"{entfernt} abgelaufene EintrÀge entfernt")
+
+# Oder alles löschen
+cache.clear()
+```
+
+---
+
+## Thread-Sicherheit
+
+Der Cache ist thread-sicher fĂŒr parallelen Zugriff:
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+from handelsregister import search
+
+suchbegriffe = ["Bank", "Versicherung", "AG", "GmbH"]
+
+with ThreadPoolExecutor(max_workers=4) as executor:
+ ergebnisse = list(executor.map(search, suchbegriffe))
+```
+
+---
+
+## Siehe auch
+
+- [API-Referenz: SearchCache](../api/classes.md) â Technische Details
+- [Als Library verwenden](library.md) â Allgemeine Library-Verwendung
+- [CLI-Optionen](cli.md) â Cache-bezogene CLI-Optionen
+
diff --git a/docs/guide/cache.md b/docs/guide/cache.md
new file mode 100644
index 00000000..b3731c36
--- /dev/null
+++ b/docs/guide/cache.md
@@ -0,0 +1,282 @@
+# Caching
+
+The Handelsregister package includes an intelligent caching system to reduce load on the register portal and improve performance.
+
+## Overview
+
+```mermaid
+graph LR
+ A[Your Application] --> B{Cache Check}
+ B -->|Hit| C[Return Cached Data]
+ B -->|Miss| D[Fetch from Portal]
+ D --> E[Store in Cache]
+ E --> C
+```
+
+### Default Behavior
+
+- **Cache enabled** by default
+- **TTL (Time-To-Live):** 24 hours
+- **Location:** `~/.cache/handelsregister/`
+- **Format:** JSON files
+
+---
+
+## Using the Cache
+
+### Automatic Caching
+
+Caching works automatically:
+
+```python
+from handelsregister import search
+
+# First call: fetches from portal, stores in cache
+results1 = search("Deutsche Bank")
+
+# Second call: returns cached data (faster)
+results2 = search("Deutsche Bank")
+```
+
+### Bypassing the Cache
+
+```python
+# Skip cache for this call
+results = search("Deutsche Bank", force_refresh=True)
+```
+
+### Clearing the Cache
+
+```python
+from handelsregister import clear_cache
+
+# Clear entire cache
+clear_cache()
+```
+
+Or via CLI:
+
+```bash
+handelsregister --clear-cache
+```
+
+---
+
+## Cache Configuration
+
+### Custom TTL
+
+```python
+from handelsregister import HandelsRegister, SearchCache
+
+# 1-hour cache
+cache = SearchCache(ttl_hours=1)
+hr = HandelsRegister(cache=cache)
+
+# 7-day cache
+cache = SearchCache(ttl_hours=168)
+hr = HandelsRegister(cache=cache)
+```
+
+### Custom Cache Directory
+
+```python
+from handelsregister import SearchCache
+
+cache = SearchCache(
+ cache_dir="/path/to/custom/cache",
+ ttl_hours=24
+)
+```
+
+Or via environment variable:
+
+```bash
+export HANDELSREGISTER_CACHE_DIR=/tmp/hr-cache
+```
+
+### Disable Caching
+
+```python
+from handelsregister import HandelsRegister
+
+# No caching at all
+hr = HandelsRegister(cache=None)
+results = hr.search("Bank")
+```
+
+---
+
+## Cache Structure
+
+The cache stores data as JSON files:
+
+```
+~/.cache/handelsregister/
+âââ searches/
+â âââ a1b2c3d4.json # Search results
+â âââ e5f6g7h8.json
+â âââ ...
+âââ details/
+â âââ HRB_12345_Berlin.json # Company details
+â âââ HRB_67890_Hamburg.json
+â âââ ...
+âââ meta.json # Cache metadata
+```
+
+### Cache Key Generation
+
+Cache keys are generated from search parameters:
+
+```python
+# These create the same cache key:
+search("Bank", states=["BE"])
+search("Bank", states=["BE"])
+
+# These create different cache keys:
+search("Bank", states=["BE"])
+search("Bank", states=["HH"])
+search("Bank", states=["BE"], include_deleted=False)
+```
+
+---
+
+## Cache Entry Format
+
+```json
+{
+ "timestamp": "2024-01-15T10:30:00Z",
+ "ttl_hours": 24,
+ "query": {
+ "keywords": "Bank",
+ "states": ["BE"],
+ "register_type": null
+ },
+ "results": [
+ {
+ "name": "Deutsche Bank AG",
+ "court": "Frankfurt am Main",
+ "register_num": "HRB 12345",
+ "status": "currently registered"
+ }
+ ]
+}
+```
+
+---
+
+## Checking Cache Status
+
+```python
+from handelsregister import SearchCache
+
+cache = SearchCache()
+
+# Check if entry exists and is valid
+if cache.has_valid_entry("Bank", states=["BE"]):
+ print("Using cached data")
+else:
+ print("Will fetch from portal")
+
+# Get cache statistics
+stats = cache.get_stats()
+print(f"Total entries: {stats['total']}")
+print(f"Valid entries: {stats['valid']}")
+print(f"Expired entries: {stats['expired']}")
+print(f"Cache size: {stats['size_mb']:.2f} MB")
+```
+
+---
+
+## Cache Best Practices
+
+### 1. Use Default Caching
+
+For most use cases, the default 24-hour cache is appropriate:
+
+```python
+# Just use search() - caching is automatic
+results = search("Bank")
+```
+
+### 2. Shorter TTL for Volatile Data
+
+If you need current data (e.g., for legal processes):
+
+```python
+cache = SearchCache(ttl_hours=1) # 1 hour
+hr = HandelsRegister(cache=cache)
+```
+
+### 3. Longer TTL for Analysis
+
+For historical analysis where freshness is less critical:
+
+```python
+cache = SearchCache(ttl_hours=168) # 7 days
+hr = HandelsRegister(cache=cache)
+```
+
+### 4. No Cache for One-Time Operations
+
+```python
+# Single query, no need to cache
+results = search("Specific Company GmbH", force_refresh=True)
+```
+
+### 5. Periodic Cache Cleanup
+
+```python
+from handelsregister import SearchCache
+
+cache = SearchCache()
+cache.cleanup_expired() # Remove expired entries
+```
+
+---
+
+## Disk Space
+
+The cache can grow over time. Monitor and clean as needed:
+
+```python
+from handelsregister import SearchCache
+
+cache = SearchCache()
+
+# Get cache size
+stats = cache.get_stats()
+print(f"Cache size: {stats['size_mb']:.2f} MB")
+
+# Clean expired entries
+removed = cache.cleanup_expired()
+print(f"Removed {removed} expired entries")
+
+# Or clear everything
+cache.clear()
+```
+
+---
+
+## Thread Safety
+
+The cache is thread-safe for concurrent access:
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+from handelsregister import search
+
+keywords = ["Bank", "Versicherung", "AG", "GmbH"]
+
+with ThreadPoolExecutor(max_workers=4) as executor:
+ results = list(executor.map(search, keywords))
+```
+
+---
+
+## See Also
+
+- [API Reference: SearchCache](../api/classes.md) â Technical details
+- [Using as Library](library.md) â General library usage
+- [CLI Options](cli.md) â Cache-related CLI options
+
diff --git a/docs/guide/cli.de.md b/docs/guide/cli.de.md
new file mode 100644
index 00000000..0448158f
--- /dev/null
+++ b/docs/guide/cli.de.md
@@ -0,0 +1,311 @@
+# Kommandozeile (CLI)
+
+Das Handelsregister-Package enthĂ€lt eine leistungsfĂ€hige Kommandozeilen-Schnittstelle fĂŒr schnelle Abfragen.
+
+## Grundlegende Verwendung
+
+```bash
+# Einfache Suche
+handelsregister -s "Deutsche Bahn"
+# Oder die kĂŒrzere Variante verwenden:
+hrg -s "Deutsche Bahn"
+
+# Mit uv
+uv run handelsregister -s "Deutsche Bahn"
+# Oder:
+uv run hrg -s "Deutsche Bahn"
+```
+
+---
+
+## Suchoptionen
+
+### `-s, --search`
+Der Suchbegriff (erforderlich):
+
+```bash
+handelsregister -s "Bank"
+handelsregister -s "Deutsche Bahn AG"
+```
+
+### `--states`
+Nach BundeslÀndern filtern (kommagetrennt):
+
+```bash
+# Ein Bundesland
+handelsregister -s "Bank" --states BE
+
+# Mehrere BundeslÀnder
+handelsregister -s "Bank" --states BE,HH,BY
+```
+
+### `--register-type`
+Nach Registerart filtern:
+
+```bash
+# Nur HRB (Kapitalgesellschaften)
+handelsregister -s "GmbH" --register-type HRB
+
+# Nur HRA (Personengesellschaften)
+handelsregister -s "KG" --register-type HRA
+```
+
+### `--exact`
+Exakte NamensĂŒbereinstimmung erfordern:
+
+```bash
+handelsregister -s "GASAG AG" --exact
+```
+
+### `--active-only`
+Nur aktuell eingetragene Unternehmen anzeigen:
+
+```bash
+handelsregister -s "Bank" --active-only
+```
+
+---
+
+## Ausgabeformate
+
+### Standardausgabe
+
+```bash
+handelsregister -s "GASAG"
+```
+
+```
+3 Unternehmen gefunden:
+
+1. GASAG AG
+ Gericht: Berlin (Charlottenburg)
+ Nummer: HRB 44343
+ Status: aktuell eingetragen
+
+2. GASAG Beteiligungs GmbH
+ Gericht: Berlin (Charlottenburg)
+ Nummer: HRB 87654
+ Status: aktuell eingetragen
+...
+```
+
+### JSON-Ausgabe
+
+```bash
+handelsregister -s "GASAG" --json
+```
+
+```json
+[
+ {
+ "name": "GASAG AG",
+ "court": "Berlin (Charlottenburg)",
+ "register_num": "HRB 44343",
+ "status": "aktuell eingetragen",
+ "state": "BE"
+ },
+ ...
+]
+```
+
+### Kompakte Ausgabe
+
+```bash
+handelsregister -s "GASAG" --compact
+```
+
+```
+GASAG AG | Berlin (Charlottenburg) | HRB 44343
+GASAG Beteiligungs GmbH | Berlin (Charlottenburg) | HRB 87654
+```
+
+---
+
+## Details abrufen
+
+### `--details`
+Erweiterte Informationen abrufen:
+
+```bash
+handelsregister -s "GASAG AG" --exact --details
+```
+
+```
+GASAG AG
+=========
+Gericht: Berlin (Charlottenburg)
+Nummer: HRB 44343
+Status: aktuell eingetragen
+
+Kapital: 306.977.800,00 EUR
+
+Adresse:
+ GASAG-Platz 1
+ 10963 Berlin
+
+Vertreter:
+ - Dr. Gerhard Holtmeier (Vorstandsvorsitzender)
+ - Stefan Michels (Vorstand)
+ - Jörg Simon (Vorstand)
+
+Unternehmensgegenstand:
+ Gegenstand des Unternehmens ist die Versorgung mit Energie...
+```
+
+### `--details --json`
+Details im JSON-Format:
+
+```bash
+handelsregister -s "GASAG AG" --exact --details --json
+```
+
+---
+
+## Caching-Optionen
+
+### `--no-cache`
+Cache ĂŒberspringen, immer frische Daten abrufen:
+
+```bash
+handelsregister -s "Bank" --no-cache
+```
+
+### `--clear-cache`
+Den gesamten Cache löschen:
+
+```bash
+handelsregister --clear-cache
+```
+
+---
+
+## Weitere Optionen
+
+### `--help`
+Hilfe anzeigen:
+
+```bash
+handelsregister --help
+```
+
+```
+usage: handelsregister [-h] [-s SEARCH] [--states STATES]
+ [--register-type TYPE] [--exact]
+ [--active-only] [--details] [--json]
+ [--compact] [--no-cache] [--clear-cache]
+
+Abfrage des deutschen Handelsregisters
+
+options:
+ -h, --help Hilfe anzeigen
+ -s, --search SEARCH Suchbegriff
+ --states STATES Nach BundeslÀndern filtern (kommagetrennt)
+ --register-type TYPE Nach Registerart filtern
+ --exact Exakte NamensĂŒbereinstimmung
+ --active-only Nur aktuell eingetragene
+ --details Unternehmensdetails abrufen
+ --json JSON-Ausgabe
+ --compact Kompakte Ausgabe
+ --no-cache Cache ĂŒberspringen
+ --clear-cache Cache löschen
+```
+
+### `--version`
+Version anzeigen:
+
+```bash
+handelsregister --version
+```
+
+---
+
+## Beispiele
+
+### Banken in Berlin suchen
+
+```bash
+handelsregister -s "Bank" --states BE --register-type HRB
+```
+
+### In JSON-Datei exportieren
+
+```bash
+handelsregister -s "Versicherung" --states BY --json > versicherungen_by.json
+```
+
+### Mit jq verarbeiten
+
+```bash
+handelsregister -s "Bank" --json | jq '.[].name'
+```
+
+### Durch BundeslÀnder iterieren
+
+```bash
+for bundesland in BE HH BY; do
+ echo "=== $bundesland ==="
+ handelsregister -s "Bank" --states $bundesland --compact
+ sleep 60 # Rate-Limit beachten
+done
+```
+
+### Details fĂŒr bestimmtes Unternehmen abrufen
+
+```bash
+handelsregister -s "Deutsche Bahn AG" --exact --details
+```
+
+---
+
+## Exit-Codes
+
+| Code | Bedeutung |
+|------|-----------|
+| 0 | Erfolg |
+| 1 | Keine Ergebnisse gefunden |
+| 2 | Verbindungsfehler |
+| 3 | Rate-Limit ĂŒberschritten |
+| 4 | UngĂŒltige Argumente |
+
+### Exit-Codes in Skripten verwenden
+
+```bash
+handelsregister -s "Bank" --states BE
+
+if [ $? -eq 0 ]; then
+ echo "Suche erfolgreich"
+elif [ $? -eq 1 ]; then
+ echo "Keine Ergebnisse gefunden"
+elif [ $? -eq 3 ]; then
+ echo "Rate-Limit - spÀter erneut versuchen"
+fi
+```
+
+---
+
+## Umgebungsvariablen
+
+| Variable | Beschreibung | Standard |
+|----------|--------------|----------|
+| `HANDELSREGISTER_CACHE_DIR` | Cache-Verzeichnis | `~/.cache/handelsregister` |
+| `HANDELSREGISTER_CACHE_TTL` | Cache-TTL in Stunden | `24` |
+| `HANDELSREGISTER_DEBUG` | Debug-Ausgabe aktivieren | `0` |
+
+```bash
+# Beispiel: Eigenes Cache-Verzeichnis
+export HANDELSREGISTER_CACHE_DIR=/tmp/hr-cache
+handelsregister -s "Bank"
+
+# Beispiel: Cache deaktivieren
+export HANDELSREGISTER_CACHE_TTL=0
+handelsregister -s "Bank"
+```
+
+---
+
+## Siehe auch
+
+- [Als Library verwenden](library.md) â Python-Integration
+- [Referenztabellen](../reference/states.md) â BundeslĂ€nder-Codes, Registerarten
+- [Beispiele](../examples/simple.md) â Weitere Beispiele
+
diff --git a/docs/guide/cli.md b/docs/guide/cli.md
new file mode 100644
index 00000000..c47159bc
--- /dev/null
+++ b/docs/guide/cli.md
@@ -0,0 +1,311 @@
+# Command Line (CLI)
+
+The Handelsregister package includes a powerful command-line interface for quick queries.
+
+## Basic Usage
+
+```bash
+# Simple search
+handelsregister -s "Deutsche Bahn"
+# Or use the shorter alias:
+hrg -s "Deutsche Bahn"
+
+# With uv
+uv run handelsregister -s "Deutsche Bahn"
+# Or:
+uv run hrg -s "Deutsche Bahn"
+```
+
+---
+
+## Search Options
+
+### `-s, --search`
+The search term (required):
+
+```bash
+handelsregister -s "Bank"
+handelsregister -s "Deutsche Bahn AG"
+```
+
+### `--states`
+Filter by states (comma-separated):
+
+```bash
+# Single state
+handelsregister -s "Bank" --states BE
+
+# Multiple states
+handelsregister -s "Bank" --states BE,HH,BY
+```
+
+### `--register-type`
+Filter by register type:
+
+```bash
+# Only HRB (corporations)
+handelsregister -s "GmbH" --register-type HRB
+
+# Only HRA (partnerships)
+handelsregister -s "KG" --register-type HRA
+```
+
+### `--exact`
+Require exact name match:
+
+```bash
+handelsregister -s "GASAG AG" --exact
+```
+
+### `--active-only`
+Only show currently registered companies:
+
+```bash
+handelsregister -s "Bank" --active-only
+```
+
+---
+
+## Output Formats
+
+### Default Output
+
+```bash
+handelsregister -s "GASAG"
+```
+
+```
+Found 3 companies:
+
+1. GASAG AG
+ Court: Berlin (Charlottenburg)
+ Number: HRB 44343
+ Status: currently registered
+
+2. GASAG Beteiligungs GmbH
+ Court: Berlin (Charlottenburg)
+ Number: HRB 87654
+ Status: currently registered
+...
+```
+
+### JSON Output
+
+```bash
+handelsregister -s "GASAG" --json
+```
+
+```json
+[
+ {
+ "name": "GASAG AG",
+ "register_court": "Berlin (Charlottenburg)",
+ "register_num": "HRB 44343",
+ "status": "currently registered",
+ "state": "BE"
+ },
+ ...
+]
+```
+
+### Compact Output
+
+```bash
+handelsregister -s "GASAG" --compact
+```
+
+```
+GASAG AG | Berlin (Charlottenburg) | HRB 44343
+GASAG Beteiligungs GmbH | Berlin (Charlottenburg) | HRB 87654
+```
+
+---
+
+## Fetching Details
+
+### `--details`
+Fetch extended information:
+
+```bash
+handelsregister -s "GASAG AG" --exact --details
+```
+
+```
+GASAG AG
+=========
+Court: Berlin (Charlottenburg)
+Number: HRB 44343
+Status: currently registered
+
+Capital: 306,977,800.00 EUR
+
+Address:
+ GASAG-Platz 1
+ 10963 Berlin
+
+Representatives:
+ - Dr. Gerhard Holtmeier (Vorstandsvorsitzender)
+ - Stefan Michels (Vorstand)
+ - Jörg Simon (Vorstand)
+
+Business Purpose:
+ Gegenstand des Unternehmens ist die Versorgung mit Energie...
+```
+
+### `--details --json`
+Details in JSON format:
+
+```bash
+handelsregister -s "GASAG AG" --exact --details --json
+```
+
+---
+
+## Caching Options
+
+### `--no-cache`
+Skip cache, always fetch fresh data:
+
+```bash
+handelsregister -s "Bank" --no-cache
+```
+
+### `--clear-cache`
+Clear the entire cache:
+
+```bash
+handelsregister --clear-cache
+```
+
+---
+
+## Other Options
+
+### `--help`
+Show help message:
+
+```bash
+handelsregister --help
+```
+
+```
+usage: handelsregister [-h] [-s SEARCH] [--states STATES]
+ [--register-type TYPE] [--exact]
+ [--active-only] [--details] [--json]
+ [--compact] [--no-cache] [--clear-cache]
+
+Query the German commercial register
+
+options:
+ -h, --help show this help message and exit
+ -s, --search SEARCH Search term
+ --states STATES Filter by states (comma-separated)
+ --register-type TYPE Filter by register type
+ --exact Exact name match
+ --active-only Only currently registered
+ --details Fetch company details
+ --json JSON output
+ --compact Compact output
+ --no-cache Skip cache
+ --clear-cache Clear cache
+```
+
+### `--version`
+Show version:
+
+```bash
+handelsregister --version
+```
+
+---
+
+## Examples
+
+### Search for Banks in Berlin
+
+```bash
+handelsregister -s "Bank" --states BE --register-type HRB
+```
+
+### Export to JSON File
+
+```bash
+handelsregister -s "Versicherung" --states BY --json > insurance_by.json
+```
+
+### Pipe to jq for Processing
+
+```bash
+handelsregister -s "Bank" --json | jq '.[].name'
+```
+
+### Loop Through States
+
+```bash
+for state in BE HH BY; do
+ echo "=== $state ==="
+ handelsregister -s "Bank" --states $state --compact
+ sleep 60 # Respect rate limit
+done
+```
+
+### Get Details for Specific Company
+
+```bash
+handelsregister -s "Deutsche Bahn AG" --exact --details
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | No results found |
+| 2 | Connection error |
+| 3 | Rate limit exceeded |
+| 4 | Invalid arguments |
+
+### Using Exit Codes in Scripts
+
+```bash
+handelsregister -s "Bank" --states BE
+
+if [ $? -eq 0 ]; then
+ echo "Search successful"
+elif [ $? -eq 1 ]; then
+ echo "No results found"
+elif [ $? -eq 3 ]; then
+ echo "Rate limit - try again later"
+fi
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HANDELSREGISTER_CACHE_DIR` | Cache directory | `~/.cache/handelsregister` |
+| `HANDELSREGISTER_CACHE_TTL` | Cache TTL in hours | `24` |
+| `HANDELSREGISTER_DEBUG` | Enable debug output | `0` |
+
+```bash
+# Example: Custom cache directory
+export HANDELSREGISTER_CACHE_DIR=/tmp/hr-cache
+handelsregister -s "Bank"
+
+# Example: Disable cache
+export HANDELSREGISTER_CACHE_TTL=0
+handelsregister -s "Bank"
+```
+
+---
+
+## See Also
+
+- [Using as Library](library.md) â Python integration
+- [Reference Tables](../reference/states.md) â State codes, register types
+- [Examples](../examples/simple.md) â More examples
+
diff --git a/docs/guide/details.de.md b/docs/guide/details.de.md
new file mode 100644
index 00000000..1c7f61d5
--- /dev/null
+++ b/docs/guide/details.de.md
@@ -0,0 +1,278 @@
+# Details abrufen
+
+Lernen Sie, wie Sie erweiterte Unternehmensinformationen ĂŒber die einfachen Suchergebnisse hinaus abrufen.
+
+## Ăbersicht
+
+Die einfache Suche liefert begrenzte Informationen. FĂŒr vollstĂ€ndige Details verwenden Sie die `get_details()`-Funktion:
+
+| Suchergebnis | Details |
+|--------------|---------|
+| Firmenname | â Plus historische Namen |
+| Registergericht | â |
+| Registernummer | â |
+| Status | â Plus Eintragungsdaten |
+| | **ZusÀtzlich:** |
+| | Kapital (Stammkapital/Grundkapital) |
+| | GeschÀftsadresse |
+| | Vertreter (GeschĂ€ftsfĂŒhrer, Vorstand) |
+| | Unternehmensgegenstand |
+| | Gesellschafter (bei Personengesellschaften) |
+| | VollstÀndige Historie |
+
+---
+
+## Grundlegende Verwendung
+
+```python
+from handelsregister import search, get_details
+
+# Zuerst nach dem Unternehmen suchen
+firmen = search("GASAG AG", keyword_option="exact")
+
+if firmen:
+ # Dann Details abrufen
+ details = get_details(firmen[0])
+
+ print(f"Firma: {details.name}")
+ print(f"Kapital: {details.capital} {details.currency}")
+```
+
+---
+
+## Das CompanyDetails-Objekt
+
+Die `get_details()`-Funktion gibt eine `CompanyDetails`-Dataclass zurĂŒck:
+
+### Grundinformationen
+
+```python
+details = get_details(firma)
+
+# Grundinfo
+print(details.name) # "GASAG AG"
+print(details.court) # "Berlin (Charlottenburg)"
+print(details.register_number) # "HRB 44343"
+print(details.register_type) # "HRB"
+print(details.status) # "aktuell eingetragen"
+```
+
+### Kapital
+
+```python
+# Stammkapital/Grundkapital
+print(details.capital) # "306977800.00"
+print(details.currency) # "EUR"
+
+# Formatierte Ausgabe
+if details.capital:
+ betrag = float(details.capital)
+ print(f"Kapital: {betrag:,.2f} {details.currency}")
+ # Ausgabe: Kapital: 306,977,800.00 EUR
+```
+
+### Adresse
+
+Die Adresse wird als `Address`-Objekt zurĂŒckgegeben:
+
+```python
+adresse = details.address
+
+print(adresse.street) # "GASAG-Platz 1"
+print(adresse.postal_code) # "10963"
+print(adresse.city) # "Berlin"
+print(adresse.country) # "Deutschland"
+
+# VollstÀndige Adresse
+print(adresse)
+# GASAG-Platz 1
+# 10963 Berlin
+# Deutschland
+```
+
+### Vertreter
+
+Vertreter (GeschĂ€ftsfĂŒhrer, Vorstandsmitglieder) werden als Liste zurĂŒckgegeben:
+
+```python
+for vertreter in details.representatives:
+ print(f"Name: {vertreter.name}")
+ print(f"Rolle: {vertreter.role}")
+ print(f"Geburtsdatum: {vertreter.birth_date}")
+ print(f"Ort: {vertreter.location}")
+ print("---")
+```
+
+**Ausgabe:**
+
+```
+Name: Dr. Gerhard Holtmeier
+Rolle: Vorstandsvorsitzender
+Geburtsdatum: 1960-05-15
+Ort: Berlin
+---
+Name: Stefan Michels
+Rolle: Vorstand
+Geburtsdatum: 1972-03-22
+Ort: Potsdam
+---
+```
+
+### Gesellschafter (Personengesellschaften)
+
+FĂŒr Personengesellschaften (KG, OHG, GbR) sind Gesellschafterinformationen verfĂŒgbar:
+
+```python
+if details.owners:
+ for gesellschafter in details.owners:
+ print(f"Name: {gesellschafter.name}")
+ print(f"Typ: {gesellschafter.owner_type}")
+ print(f"Anteil: {gesellschafter.share}")
+ print(f"Haftung: {gesellschafter.liability}")
+```
+
+### Unternehmensgegenstand
+
+```python
+print("Unternehmensgegenstand:")
+print(details.business_purpose)
+```
+
+### Historie
+
+Die vollstÀndige Historie der Registereintragungen:
+
+```python
+for eintrag in details.history:
+ print(f"Datum: {eintrag.date}")
+ print(f"Typ: {eintrag.entry_type}")
+ print(f"Inhalt: {eintrag.content[:100]}...")
+ print("---")
+```
+
+---
+
+## VollstÀndiges Beispiel
+
+```python
+from handelsregister import search, get_details
+
+def zeige_firmendetails(name: str):
+ """Zeigt vollstĂ€ndige Details fĂŒr ein Unternehmen an."""
+
+ # Suchen
+ firmen = search(name, keyword_option="exact")
+
+ if not firmen:
+ print(f"Kein Unternehmen gefunden: {name}")
+ return
+
+ # Details abrufen
+ details = get_details(firmen[0])
+
+ # Kopfzeile
+ print("=" * 60)
+ print(f" {details.name}")
+ print("=" * 60)
+
+ # Registrierung
+ print(f"\nRegister: {details.court}")
+ print(f"Nummer: {details.register_type} {details.register_number}")
+ print(f"Status: {details.status}")
+
+ # Kapital
+ if details.capital:
+ betrag = float(details.capital)
+ print(f"\nKapital: {betrag:,.2f} {details.currency}")
+
+ # Adresse
+ if details.address:
+ print(f"\nAdresse:")
+ print(f" {details.address.street}")
+ print(f" {details.address.postal_code} {details.address.city}")
+
+ # Vertreter
+ if details.representatives:
+ print(f"\nVertreter ({len(details.representatives)}):")
+ for v in details.representatives:
+ rolle = f" ({v.role})" if v.role else ""
+ print(f" âą {v.name}{rolle}")
+
+ # Unternehmensgegenstand
+ if details.business_purpose:
+ print(f"\nUnternehmensgegenstand:")
+ # KĂŒrzen wenn zu lang
+ zweck = details.business_purpose
+ if len(zweck) > 200:
+ zweck = zweck[:200] + "..."
+ print(f" {zweck}")
+
+# Verwendung
+zeige_firmendetails("GASAG AG")
+```
+
+---
+
+## Details-Caching
+
+Details werden separat von Suchergebnissen gecacht:
+
+```python
+# Erster Aufruf: Ruft vom Portal ab
+details1 = get_details(firma)
+
+# Zweiter Aufruf: Nutzt Cache
+details2 = get_details(firma)
+
+# Frischen Abruf erzwingen
+details3 = get_details(firma, force_refresh=True)
+```
+
+---
+
+## Stapelverarbeitung
+
+FĂŒr mehrere Unternehmen sequentiell mit Verzögerungen verarbeiten:
+
+```python
+import time
+from handelsregister import search, get_details
+
+firmen = search("Bank", states=["BE"])
+
+alle_details = []
+for i, firma in enumerate(firmen[:10]): # Limit zur Sicherheit
+ print(f"Rufe ab {i+1}/{len(firmen)}: {firma.name}")
+
+ details = get_details(firma)
+ alle_details.append(details)
+
+ # Rate-Limit beachten: 60/Stunde = 1/Minute
+ time.sleep(60)
+
+print(f"\nDetails fĂŒr {len(alle_details)} Unternehmen abgerufen")
+```
+
+---
+
+## Fehlerbehandlung
+
+```python
+from handelsregister import get_details, SearchError
+
+try:
+ details = get_details(firma)
+except SearchError as e:
+ print(f"Details konnten nicht abgerufen werden: {e}")
+ # Fallback auf Grundinfo aus Suchergebnis
+ print(f"Firma: {firma.name}")
+```
+
+---
+
+## Siehe auch
+
+- [API-Referenz: get_details()](../api/functions.md) â Technische Dokumentation
+- [Datenmodelle](../api/models.md) â CompanyDetails, Address, Representative
+- [Caching](cache.md) â Wie Caching funktioniert
+
diff --git a/docs/guide/details.md b/docs/guide/details.md
new file mode 100644
index 00000000..8bc37855
--- /dev/null
+++ b/docs/guide/details.md
@@ -0,0 +1,278 @@
+# Fetching Details
+
+Learn how to retrieve extended company information beyond basic search results.
+
+## Overview
+
+The basic search returns limited information. For complete details, use the `get_details()` function:
+
+| Search Result | Details |
+|---------------|---------|
+| Company name | â Plus historical names |
+| Register court | â |
+| Register number | â |
+| Status | â Plus registration dates |
+| | **Additional:** |
+| | Capital (Stammkapital/Grundkapital) |
+| | Business address |
+| | Representatives (directors, board) |
+| | Business purpose |
+| | Owners (for partnerships) |
+| | Complete history |
+
+---
+
+## Basic Usage
+
+```python
+from handelsregister import search, get_details
+
+# First, search for the company
+companies = search("GASAG AG", keyword_option="exact")
+
+if companies:
+ # Then fetch details
+ details = get_details(companies[0])
+
+ print(f"Company: {details.name}")
+ print(f"Capital: {details.capital} {details.currency}")
+```
+
+---
+
+## The CompanyDetails Object
+
+The `get_details()` function returns a `CompanyDetails` dataclass:
+
+### Basic Information
+
+```python
+details = get_details(company)
+
+# Basic info
+print(details.name) # "GASAG AG"
+print(details.court) # "Berlin (Charlottenburg)"
+print(details.register_num) # "HRB 44343 B"
+print(details.state) # "Berlin"
+print(details.status) # "currently registered"
+```
+
+### Capital
+
+```python
+# Share capital
+print(details.capital) # "306977800.00"
+print(details.currency) # "EUR"
+
+# Formatted output
+if details.capital:
+ amount = float(details.capital)
+ print(f"Capital: {amount:,.2f} {details.currency}")
+ # Output: Capital: 306,977,800.00 EUR
+```
+
+### Address
+
+The address is returned as an `Address` object:
+
+```python
+address = details.address
+
+print(address.street) # "GASAG-Platz 1"
+print(address.postal_code) # "10963"
+print(address.city) # "Berlin"
+print(address.country) # "Deutschland"
+
+# Full address
+print(address)
+# GASAG-Platz 1
+# 10963 Berlin
+# Deutschland
+```
+
+### Representatives
+
+Representatives (directors, board members) are returned as a list:
+
+```python
+for rep in details.representatives:
+ print(f"Name: {rep.name}")
+ print(f"Role: {rep.role}")
+ print(f"Birth date: {rep.birth_date}")
+ print(f"Location: {rep.location}")
+ print("---")
+```
+
+**Output:**
+
+```
+Name: Dr. Gerhard Holtmeier
+Role: Vorstandsvorsitzender
+Birth date: 1960-05-15
+Location: Berlin
+---
+Name: Stefan Michels
+Role: Vorstand
+Birth date: 1972-03-22
+Location: Potsdam
+---
+```
+
+### Owners (Partnerships)
+
+For partnerships (KG, OHG, GbR), owner information is available:
+
+```python
+if details.owners:
+ for owner in details.owners:
+ print(f"Name: {owner.name}")
+ print(f"Type: {owner.owner_type}")
+ print(f"Share: {owner.share}")
+ print(f"Liability: {owner.liability}")
+```
+
+### Business Purpose
+
+```python
+print("Business Purpose:")
+print(details.business_purpose)
+```
+
+### History
+
+The complete history of register entries:
+
+```python
+for entry in details.history:
+ print(f"Date: {entry.date}")
+ print(f"Type: {entry.entry_type}")
+ print(f"Content: {entry.content[:100]}...")
+ print("---")
+```
+
+---
+
+## Complete Example
+
+```python
+from handelsregister import search, get_details
+
+def show_company_details(name: str):
+ """Display complete details for a company."""
+
+ # Search
+ companies = search(name, keyword_option="exact")
+
+ if not companies:
+ print(f"No company found: {name}")
+ return
+
+ # Get details
+ details = get_details(companies[0])
+
+ # Header
+ print("=" * 60)
+ print(f" {details.name}")
+ print("=" * 60)
+
+ # Registration
+ print(f"\nRegister: {details.court}")
+ print(f"Number: {details.register_num}")
+ print(f"Status: {details.status}")
+
+ # Capital
+ if details.capital:
+ amount = float(details.capital)
+ print(f"\nCapital: {amount:,.2f} {details.currency}")
+
+ # Address
+ if details.address:
+ print(f"\nAddress:")
+ print(f" {details.address.street}")
+ print(f" {details.address.postal_code} {details.address.city}")
+
+ # Representatives
+ if details.representatives:
+ print(f"\nRepresentatives ({len(details.representatives)}):")
+ for rep in details.representatives:
+ role = f" ({rep.role})" if rep.role else ""
+ print(f" âą {rep.name}{role}")
+
+ # Business purpose
+ if details.purpose:
+ print(f"\nBusiness Purpose:")
+ # Truncate if too long
+ purpose = details.purpose
+ if len(purpose) > 200:
+ purpose = purpose[:200] + "..."
+ print(f" {purpose}")
+
+# Usage
+show_company_details("GASAG AG")
+```
+
+---
+
+## Caching Details
+
+Details are cached separately from search results:
+
+```python
+# First call: fetches from portal
+details1 = get_details(company)
+
+# Second call: uses cache
+details2 = get_details(company)
+
+# Force fresh fetch
+details3 = get_details(company, force_refresh=True)
+```
+
+---
+
+## Batch Processing
+
+For multiple companies, process sequentially with delays:
+
+```python
+import time
+from handelsregister import search, get_details
+
+companies = search("Bank", states=["BE"])
+
+all_details = []
+for i, company in enumerate(companies[:10]): # Limit for safety
+ print(f"Fetching {i+1}/{len(companies)}: {company.name}")
+
+ details = get_details(company)
+ all_details.append(details)
+
+ # Respect rate limit: 60/hour = 1/minute
+ time.sleep(60)
+
+print(f"\nFetched details for {len(all_details)} companies")
+```
+
+---
+
+## Error Handling
+
+```python
+from handelsregister import get_details, SearchError
+
+try:
+ details = get_details(company)
+except SearchError as e:
+ print(f"Could not fetch details: {e}")
+ # Fallback to basic info from search result
+ print(f"Company: {company.name}")
+```
+
+---
+
+## See Also
+
+- [API Reference: get_details()](../api/functions.md) â Technical documentation
+- [Data Models](../api/models.md) â CompanyDetails, Address, Representative
+- [Caching](cache.md) â How caching works
+
diff --git a/docs/guide/index.de.md b/docs/guide/index.de.md
new file mode 100644
index 00000000..270feb11
--- /dev/null
+++ b/docs/guide/index.de.md
@@ -0,0 +1,149 @@
+# Benutzerhandbuch
+
+Willkommen zum umfassenden Benutzerhandbuch fĂŒr das Handelsregister-Package. Dieses Handbuch behandelt alle Funktionen im Detail.
+
+## Ăbersicht
+
+Das Handelsregister-Package bietet zwei Hauptwege zur Abfrage des deutschen Handelsregisters:
+
+1. **Als Python-Library** â FĂŒr die Integration in Ihre Anwendungen
+2. **Als CLI-Tool** â FĂŒr schnelle Kommandozeilen-Abfragen
+
+---
+
+## Kapitel
+
+
+
+- :material-code-braces:{ .lg .middle } __Als Library verwenden__
+
+ ---
+
+ Lernen Sie, wie Sie Handelsregister als Python-Library in Ihren Anwendungen verwenden.
+
+ [:octicons-arrow-right-24: Library-Anleitung](library.md)
+
+- :material-console:{ .lg .middle } __Kommandozeile (CLI)__
+
+ ---
+
+ Nutzen Sie die Kommandozeilen-Schnittstelle fĂŒr schnelle Abfragen und Scripting.
+
+ [:octicons-arrow-right-24: CLI-Anleitung](cli.md)
+
+- :material-file-document-multiple:{ .lg .middle } __Details abrufen__
+
+ ---
+
+ Wie Sie erweiterte Unternehmensinformationen wie Kapital, Vertreter und mehr abrufen.
+
+ [:octicons-arrow-right-24: Details-Anleitung](details.md)
+
+- :material-cached:{ .lg .middle } __Caching__
+
+ ---
+
+ Verstehen und konfigurieren Sie den Caching-Mechanismus.
+
+ [:octicons-arrow-right-24: Caching-Anleitung](cache.md)
+
+
+
+---
+
+## Kernkonzepte
+
+### Datenstrukturen
+
+Das Package verwendet mehrere Datenstrukturen:
+
+| Struktur | Beschreibung |
+|----------|--------------|
+| `Company` | Grundlegende Unternehmensinformationen aus Suchergebnissen |
+| `CompanyDetails` | Erweiterte Informationen (Kapital, Vertreter, etc.) |
+| `Address` | Strukturierte Adressdaten |
+| `Representative` | GeschĂ€ftsfĂŒhrer, Vorstandsmitglieder, etc. |
+| `Owner` | Gesellschafter (bei Personengesellschaften) |
+
+### Suchablauf
+
+```mermaid
+sequenceDiagram
+ participant App as Ihre Anwendung
+ participant HR as HandelsRegister
+ participant Cache as SearchCache
+ participant Portal as handelsregister.de
+
+ App->>HR: search("Deutsche Bahn")
+ HR->>Cache: Cache prĂŒfen
+ alt Cache-Treffer
+ Cache-->>HR: Gecachte Ergebnisse
+ else Cache-Miss
+ HR->>Portal: HTTP-Anfrage
+ Portal-->>HR: HTML-Antwort
+ HR->>Cache: Ergebnisse speichern
+ end
+ HR-->>App: List[Company]
+```
+
+### Rate Limiting
+
+!!! warning "Wichtig"
+ Das Registerportal erlaubt maximal **60 Anfragen pro Stunde**. Das Package erzwingt dieses Limit nicht automatisch, daher sind Sie selbst dafĂŒr verantwortlich, innerhalb dieser Grenzen zu bleiben.
+
+---
+
+## Schnellreferenz
+
+### HĂ€ufigste Operationen
+
+=== "Suche"
+
+ ```python
+ from handelsregister import search
+
+ # Einfache Suche
+ firmen = search("Deutsche Bahn")
+
+ # Mit Filtern
+ firmen = search(
+ keywords="Bank",
+ states=["BE", "HH"],
+ register_type="HRB",
+ include_deleted=False
+ )
+ ```
+
+=== "Details abrufen"
+
+ ```python
+ from handelsregister import search, get_details
+
+ firmen = search("GASAG AG", keyword_option="exact")
+ if firmen:
+ details = get_details(firmen[0])
+ print(details.capital)
+ print(details.representatives)
+ ```
+
+=== "CLI"
+
+ ```bash
+ # Suche
+ handelsregister -s "Deutsche Bahn"
+
+ # Mit Filtern und JSON-Ausgabe
+ handelsregister -s "Bank" --states BE,HH --json
+
+ # Mit Details
+ handelsregister -s "GASAG AG" --exact --details
+ ```
+
+---
+
+## Siehe auch
+
+- [API-Referenz](../api/index.md) â Technische Dokumentation
+- [Beispiele](../examples/simple.md) â Praktische Code-Beispiele
+- [Referenztabellen](../reference/states.md) â BundeslĂ€nder-Codes, Registerarten, etc.
+
diff --git a/docs/guide/index.md b/docs/guide/index.md
new file mode 100644
index 00000000..7e2dbe71
--- /dev/null
+++ b/docs/guide/index.md
@@ -0,0 +1,149 @@
+# User Guide
+
+Welcome to the comprehensive user guide for the Handelsregister package. This guide covers all functionality in detail.
+
+## Overview
+
+The Handelsregister package provides two main ways to query the German commercial register:
+
+1. **As a Python Library** â For integration into your applications
+2. **As a CLI Tool** â For quick command-line queries
+
+---
+
+## Chapters
+
+
+
+- :material-code-braces:{ .lg .middle } __Using as Library__
+
+ ---
+
+ Learn how to use Handelsregister as a Python library in your applications.
+
+ [:octicons-arrow-right-24: Library Guide](library.md)
+
+- :material-console:{ .lg .middle } __Command Line (CLI)__
+
+ ---
+
+ Use the command-line interface for quick queries and scripting.
+
+ [:octicons-arrow-right-24: CLI Guide](cli.md)
+
+- :material-file-document-multiple:{ .lg .middle } __Fetching Details__
+
+ ---
+
+ How to retrieve extended company information like capital, representatives, and more.
+
+ [:octicons-arrow-right-24: Details Guide](details.md)
+
+- :material-cached:{ .lg .middle } __Caching__
+
+ ---
+
+ Understand and configure the caching mechanism.
+
+ [:octicons-arrow-right-24: Caching Guide](cache.md)
+
+
+
+---
+
+## Core Concepts
+
+### Data Structures
+
+The package uses several data structures:
+
+| Structure | Description |
+|-----------|-------------|
+| `Company` | Basic company information from search results |
+| `CompanyDetails` | Extended information (capital, representatives, etc.) |
+| `Address` | Structured address data |
+| `Representative` | Managing directors, board members, etc. |
+| `Owner` | Shareholders (for partnerships) |
+
+### Search Flow
+
+```mermaid
+sequenceDiagram
+ participant App as Your Application
+ participant HR as HandelsRegister
+ participant Cache as SearchCache
+ participant Portal as handelsregister.de
+
+ App->>HR: search("Deutsche Bahn")
+ HR->>Cache: Check cache
+ alt Cache hit
+ Cache-->>HR: Cached results
+ else Cache miss
+ HR->>Portal: HTTP request
+ Portal-->>HR: HTML response
+ HR->>Cache: Store results
+ end
+ HR-->>App: List[Company]
+```
+
+### Rate Limiting
+
+!!! warning "Important"
+ The register portal allows a maximum of **60 requests per hour**. The package does not automatically enforce this limit, so you are responsible for staying within these bounds.
+
+---
+
+## Quick Reference
+
+### Most Common Operations
+
+=== "Search"
+
+ ```python
+ from handelsregister import search
+
+ # Simple search
+ companies = search("Deutsche Bahn")
+
+ # With filters
+ companies = search(
+ keywords="Bank",
+ states=["BE", "HH"],
+ register_type="HRB",
+ include_deleted=False
+ )
+ ```
+
+=== "Get Details"
+
+ ```python
+ from handelsregister import search, get_details
+
+ companies = search("GASAG AG", keyword_option="exact")
+ if companies:
+ details = get_details(companies[0])
+ print(details.capital)
+ print(details.representatives)
+ ```
+
+=== "CLI"
+
+ ```bash
+ # Search
+ handelsregister -s "Deutsche Bahn"
+
+ # With filters and JSON output
+ handelsregister -s "Bank" --states BE,HH --json
+
+ # With details
+ handelsregister -s "GASAG AG" --exact --details
+ ```
+
+---
+
+## See Also
+
+- [API Reference](../api/index.md) â Technical documentation
+- [Examples](../examples/simple.md) â Practical code examples
+- [Reference Tables](../reference/states.md) â State codes, register types, etc.
+
diff --git a/docs/guide/library.de.md b/docs/guide/library.de.md
new file mode 100644
index 00000000..f123b04d
--- /dev/null
+++ b/docs/guide/library.de.md
@@ -0,0 +1,322 @@
+# Als Library verwenden
+
+Dieses Kapitel erklÀrt, wie Sie Handelsregister als Python-Library in Ihren Anwendungen verwenden.
+
+## Grundlegende Verwendung
+
+### Die `search()`-Funktion
+
+Die `search()`-Funktion ist der Haupteinstiegspunkt fĂŒr Unternehmenssuchen:
+
+```python
+from handelsregister import search
+
+# Einfache Suche
+firmen = search("Deutsche Bahn")
+
+# Ergebnisse verarbeiten
+for firma in firmen:
+ print(f"Name: {firma.name}")
+ print(f"Gericht: {firma.court}")
+ print(f"Nummer: {firma.register_num}")
+ print(f"Status: {firma.status}")
+ print("---")
+```
+
+### RĂŒckgabewert
+
+Die Funktion gibt eine Liste von `Company`-Objekten mit folgenden Attributen zurĂŒck:
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `name` | `str` | Firmenname |
+| `court` | `str` | Registergericht |
+| `register_num` | `str \| None` | Registernummer (z.B. "HRB 12345 B") |
+| `status` | `str` | Registrierungsstatus |
+| `state` | `str` | Bundesland (z.B. "Berlin") |
+| `status_normalized` | `str` | Normalisierter Status (z.B. "CURRENTLY_REGISTERED") |
+| `documents` | `str` | VerfĂŒgbare Dokumenttypen |
+| `history` | `List[HistoryEntry]` | Liste historischer EintrÀge |
+
+---
+
+## Suchparameter
+
+### Alle Parameter
+
+```python
+firmen = search(
+ keywords="Bank", # Suchbegriff (erforderlich)
+ states=["BE", "HH"], # Nach BundeslÀndern filtern
+ register_type="HRB", # Nach Registerart filtern
+ court="Berlin", # Spezifisches Registergericht
+ register_number="12345", # Spezifische Registernummer
+ include_deleted=False, # Nur aktuell eingetragene
+ exact=False, # Exakte NamensĂŒbereinstimmung
+ force_refresh=False, # Caching verwenden
+ similar_sounding=False, # Ăhnlich klingende Namen einschlieĂen
+)
+```
+
+### Parameter im Detail
+
+#### `keywords` (erforderlich)
+Der Suchbegriff fĂŒr Firmennamen:
+
+```python
+# TeilĂŒbereinstimmung
+search("Deutsche") # Findet "Deutsche Bahn", "Deutsche Bank", etc.
+
+# Mehrere Wörter
+search("Deutsche Bank AG")
+```
+
+#### `states`
+Nach deutschen BundeslÀndern filtern mit ISO-Codes:
+
+```python
+# Ein Bundesland
+search("Bank", states=["BE"])
+
+# Mehrere BundeslÀnder
+search("Bank", states=["BE", "HH", "BY"])
+```
+
+Siehe [BundeslĂ€nder-Codes](../reference/states.md) fĂŒr alle Codes.
+
+#### `register_type`
+Nach Registerart filtern:
+
+```python
+# Nur HRB (Kapitalgesellschaften)
+search("GmbH", register_type="HRB")
+
+# Nur HRA (Einzelunternehmen, Personengesellschaften)
+search("KG", register_type="HRA")
+```
+
+Siehe [Registerarten](../reference/registers.md) fĂŒr alle Arten.
+
+#### `only_active`
+Nach aktuell eingetragenen Unternehmen filtern:
+
+```python
+# Nur aktive Unternehmen
+search("Bank", include_deleted=False)
+
+# Gelöschte/fusionierte einschlieĂen
+search("Bank", include_deleted=True)
+```
+
+#### `exact`
+Exakte NamensĂŒbereinstimmung erfordern:
+
+```python
+# Nur exakte Ăbereinstimmung
+search("GASAG AG", keyword_option="exact")
+
+# TeilĂŒbereinstimmungen erlaubt (Standard)
+search("GASAG", exact=False)
+```
+
+---
+
+## Mit Ergebnissen arbeiten
+
+### Ergebnisse durchlaufen
+
+```python
+firmen = search("Deutsche Bahn")
+
+# Als Liste
+for firma in firmen:
+ verarbeite(firma)
+
+# Mit Index
+for i, firma in enumerate(firmen):
+ print(f"{i+1}. {firma.name}")
+
+# In Python filtern
+berliner_firmen = [
+ f for f in firmen
+ if f['state'] == 'BE'
+]
+```
+
+### Auf Ergebnisse prĂŒfen
+
+```python
+firmen = search("xyz123nichtvorhanden")
+
+if not firmen:
+ print("Keine Unternehmen gefunden")
+else:
+ print(f"{len(firmen)} Unternehmen gefunden")
+```
+
+### In DataFrame konvertieren
+
+```python
+import pandas as pd
+from handelsregister import search
+
+firmen = search("Bank", states=["BE"])
+
+# In DataFrame konvertieren
+df = pd.DataFrame(firmen)
+
+# Analysieren
+print(df.groupby('court').size())
+```
+
+---
+
+## Fortgeschrittene Verwendung
+
+### Die HandelsRegister-Klasse verwenden
+
+FĂŒr mehr Kontrolle verwenden Sie die `HandelsRegister`-Klasse direkt:
+
+```python
+from handelsregister import HandelsRegister
+
+# Instanz erstellen
+hr = HandelsRegister()
+
+# Suche mit voller Kontrolle
+ergebnisse = hr.search(
+ keywords="Bank",
+ register_type="HRB",
+ states=["BE"]
+)
+
+# Details abrufen
+if ergebnisse:
+ details = hr.get_details(ergebnisse[0])
+```
+
+### Benutzerdefinierte Cache-Konfiguration
+
+```python
+from handelsregister import HandelsRegister, SearchCache
+
+# Benutzerdefinierter Cache mit 1-Stunden-TTL
+cache = SearchCache(ttl_hours=1)
+
+hr = HandelsRegister(cache=cache)
+ergebnisse = hr.search("Bank")
+```
+
+### Ohne Caching
+
+```python
+# Cache fĂŒr diese Suche deaktivieren
+firmen = search("Bank", force_refresh=True)
+
+# Oder global
+hr = HandelsRegister(cache=None)
+```
+
+---
+
+## Fehlerbehandlung
+
+```python
+from handelsregister import (
+ search,
+ SearchError,
+ RateLimitError,
+ ConnectionError,
+ ParseError
+)
+
+try:
+ firmen = search("Bank")
+except RateLimitError:
+ print("Rate-Limit ĂŒberschritten (max 60/Stunde)")
+ # Warten und erneut versuchen
+except ConnectionError:
+ print("Verbindung zum Registerportal nicht möglich")
+except ParseError:
+ print("Fehler beim Parsen der Antwort")
+except SearchError as e:
+ print(f"Allgemeiner Suchfehler: {e}")
+```
+
+### Wiederholungslogik
+
+```python
+import time
+from handelsregister import search, RateLimitError
+
+def suche_mit_wiederholung(keywords, max_versuche=3):
+ for versuch in range(max_versuche):
+ try:
+ return search(keywords)
+ except RateLimitError:
+ if versuch < max_versuche - 1:
+ wartezeit = (versuch + 1) * 60 # 1, 2, 3 Minuten
+ print(f"Rate-limitiert, warte {wartezeit}s...")
+ time.sleep(wartezeit)
+ else:
+ raise
+```
+
+---
+
+## Best Practices
+
+### 1. Rate-Limits respektieren
+
+```python
+import time
+
+suchbegriffe = ["Bank", "Versicherung", "AG", ...]
+
+for keywords in suchbegriffe:
+ ergebnisse = search(keywords)
+ verarbeite(ergebnisse)
+ time.sleep(60) # 1 Minute zwischen Suchen warten
+```
+
+### 2. Caching nutzen
+
+```python
+# Cache ist standardmĂ€Ăig aktiviert
+# Ergebnisse werden 24 Stunden wiederverwendet
+
+firmen = search("Bank") # Erster Aufruf: Portal-Anfrage
+firmen = search("Bank") # Zweiter Aufruf: aus Cache
+```
+
+### 3. Server-seitig filtern
+
+```python
+# Gut: Auf dem Server filtern
+firmen = search("Bank", states=["BE"], register_type="HRB")
+
+# Weniger effizient: Client-seitig filtern
+firmen = search("Bank")
+berlin_hrb = [f for f in firmen if f['state'] == 'BE']
+```
+
+### 4. Leere Ergebnisse behandeln
+
+```python
+firmen = search(keywords)
+
+if not firmen:
+ logger.info(f"Keine Ergebnisse fĂŒr '{keywords}'")
+ return []
+
+# Verarbeitung fortsetzen
+```
+
+---
+
+## Siehe auch
+
+- [API-Referenz: search()](../api/functions.md) â Technische Details
+- [Details abrufen](details.md) â Erweiterte Informationen abrufen
+- [Beispiele](../examples/simple.md) â Code-Beispiele
+
diff --git a/docs/guide/library.md b/docs/guide/library.md
new file mode 100644
index 00000000..b42f4303
--- /dev/null
+++ b/docs/guide/library.md
@@ -0,0 +1,347 @@
+# Using as Library
+
+This chapter explains how to use Handelsregister as a Python library in your applications.
+
+## Basic Usage
+
+### The `search()` Function
+
+The `search()` function is the main entry point for company searches:
+
+```python
+from handelsregister import search
+
+# Simple search
+companies = search("Deutsche Bahn")
+
+# Process results
+for company in companies:
+ print(f"Name: {company.name}")
+ print(f"Court: {company.court}")
+ print(f"Number: {company.register_num}")
+ print(f"Status: {company.status}")
+ print("---")
+```
+
+### Return Value
+
+The function returns a list of `Company` objects with the following attributes:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | `str` | Company name |
+| `court` | `str` | Register court |
+| `register_num` | `str \| None` | Register number (e.g., "HRB 12345 B") |
+| `state` | `str` | State name (e.g., "Berlin") |
+| `status` | `str` | Registration status |
+| `status_normalized` | `str` | Normalized status (e.g., "CURRENTLY_REGISTERED") |
+| `documents` | `str` | Available document types |
+| `history` | `List[HistoryEntry]` | List of historical entries (name, location) |
+
+---
+
+## Search Parameters
+
+### All Parameters
+
+```python
+companies = search(
+ keywords="Bank", # Search term (required)
+ keyword_option="all", # How to match: "all", "min", or "exact"
+ states=["BE", "HH"], # Filter by states (can use State enum)
+ register_type="HRB", # Filter by register type (can use RegisterType enum)
+ register_number="12345", # Specific register number
+ include_deleted=False, # Only currently registered
+ similar_sounding=False, # Include similar-sounding names
+ results_per_page=100, # Results per page
+ force_refresh=False, # Use caching
+ debug=False, # Debug logging
+)
+```
+
+### Parameter Details
+
+#### `keywords` (required)
+The search term for company names:
+
+```python
+# Partial match
+search("Deutsche") # Finds "Deutsche Bahn", "Deutsche Bank", etc.
+
+# Multiple words
+search("Deutsche Bank AG")
+```
+
+#### `states`
+Filter by German federal states using ISO codes:
+
+```python
+from handelsregister import search, State
+
+# Single state (recommended: Enum)
+search("Bank", states=[State.BE])
+
+# Multiple states (recommended: Enums)
+search("Bank", states=[State.BE, State.HH, State.BY])
+
+# String-based API still works
+search("Bank", states=["BE"])
+search("Bank", states=["BE", "HH", "BY"])
+```
+
+See [State Codes](../reference/states.md) for all codes.
+
+#### `register_type`
+Filter by register type:
+
+```python
+from handelsregister import search, RegisterType
+
+# Only HRB (corporations) - recommended: Enum
+search("GmbH", register_type=RegisterType.HRB)
+
+# Only HRA (sole proprietors, partnerships)
+search("KG", register_type=RegisterType.HRA)
+
+# String-based API still works
+search("GmbH", register_type="HRB")
+```
+
+See [Register Types](../reference/registers.md) for all types.
+
+#### `keyword_option`
+How to match keywords:
+
+```python
+from handelsregister import search, KeywordMatch
+
+# All keywords must match (default) - recommended: Enum
+search("Deutsche Bank", keyword_option=KeywordMatch.ALL)
+
+# At least one keyword must match
+search("Deutsche Bank", keyword_option=KeywordMatch.MIN)
+
+# Exact name match
+search("GASAG AG", keyword_option=KeywordMatch.EXACT)
+
+# String-based API still works
+search("Deutsche Bank", keyword_option="all")
+search("GASAG AG", keyword_option="exact")
+```
+
+#### `include_deleted`
+Include deleted/historical entries:
+
+```python
+# Only currently registered (default)
+search("Bank", include_deleted=False)
+
+# Include deleted/merged companies
+search("Bank", include_deleted=True)
+```
+
+---
+
+## Working with Results
+
+### Iterating Results
+
+```python
+companies = search("Deutsche Bahn")
+
+# As list
+for company in companies:
+ process(company)
+
+# With index
+for i, company in enumerate(companies):
+ print(f"{i+1}. {company.name}")
+
+# Filter in Python
+berlin_companies = [
+ c for c in companies
+ if c.state == 'Berlin'
+]
+```
+
+### Checking for Results
+
+```python
+companies = search("xyz123nonexistent")
+
+if not companies:
+ print("No companies found")
+else:
+ print(f"Found {len(companies)} companies")
+```
+
+### Converting to DataFrame
+
+```python
+import pandas as pd
+from handelsregister import search
+
+from handelsregister import search, State
+
+companies = search("Bank", states=[State.BE])
+
+# Convert Company objects to dicts for pandas
+df = pd.DataFrame([c.to_dict() for c in companies])
+
+# Analyze
+print(df.groupby('court').size())
+```
+
+---
+
+## Advanced Usage
+
+### Using the HandelsRegister Class
+
+For more control, use the `HandelsRegister` class directly:
+
+```python
+from handelsregister import HandelsRegister, State, RegisterType
+
+# Create instance
+hr = HandelsRegister()
+
+# Search with full control (recommended: Enums)
+results = hr.search(
+ keywords="Bank",
+ register_type=RegisterType.HRB,
+ states=[State.BE]
+)
+
+# Get details
+if results:
+ details = hr.get_details(results[0])
+```
+
+### Custom Cache Configuration
+
+```python
+from handelsregister import HandelsRegister, SearchCache
+
+# Custom cache with 1-hour TTL
+cache = SearchCache(ttl_hours=1)
+
+hr = HandelsRegister(cache=cache)
+results = hr.search("Bank")
+```
+
+### Without Caching
+
+```python
+# Disable cache for this search
+companies = search("Bank", force_refresh=True)
+
+# Or globally
+hr = HandelsRegister(cache=None)
+```
+
+---
+
+## Error Handling
+
+```python
+from handelsregister import (
+ search,
+ SearchError,
+ RateLimitError,
+ ConnectionError,
+ ParseError
+)
+
+try:
+ companies = search("Bank")
+except RateLimitError:
+ print("Rate limit exceeded (max 60/hour)")
+ # Wait and retry
+except ConnectionError:
+ print("Could not connect to register portal")
+except ParseError:
+ print("Error parsing response")
+except SearchError as e:
+ print(f"General search error: {e}")
+```
+
+### Retry Logic
+
+```python
+import time
+from handelsregister import search, RateLimitError
+
+def search_with_retry(keywords, max_retries=3):
+ for attempt in range(max_retries):
+ try:
+ return search(keywords)
+ except RateLimitError:
+ if attempt < max_retries - 1:
+ wait_time = (attempt + 1) * 60 # 1, 2, 3 minutes
+ print(f"Rate limited, waiting {wait_time}s...")
+ time.sleep(wait_time)
+ else:
+ raise
+```
+
+---
+
+## Best Practices
+
+### 1. Respect Rate Limits
+
+```python
+import time
+
+keywords_list = ["Bank", "Versicherung", "AG", ...]
+
+for keywords in keywords_list:
+ results = search(keywords)
+ process(results)
+ time.sleep(60) # Wait 1 minute between searches
+```
+
+### 2. Use Caching
+
+```python
+# Cache is enabled by default
+# Results are reused for 24 hours
+
+companies = search("Bank") # First call: hits portal
+companies = search("Bank") # Second call: from cache
+```
+
+### 3. Filter Server-Side
+
+```python
+# Good: Filter on the server
+from handelsregister import search, State, RegisterType
+
+companies = search("Bank", states=[State.BE], register_type=RegisterType.HRB)
+
+# Less efficient: Filter client-side
+companies = search("Bank")
+berlin_hrb = [c for c in companies if c.state == 'Berlin']
+```
+
+### 4. Handle Empty Results
+
+```python
+companies = search(keywords)
+
+if not companies:
+ logger.info(f"No results for '{keywords}'")
+ return []
+
+# Continue processing
+```
+
+---
+
+## See Also
+
+- [API Reference: search()](../api/functions.md) â Technical details
+- [Fetching Details](details.md) â How to get extended information
+- [Examples](../examples/simple.md) â Code examples
+
diff --git a/docs/index.de.md b/docs/index.de.md
new file mode 100644
index 00000000..389821f7
--- /dev/null
+++ b/docs/index.de.md
@@ -0,0 +1,191 @@
+# Handelsregister
+
+
+
+- :material-rocket-launch:{ .lg .middle } __Schneller Einstieg__
+
+ ---
+
+ Installieren Sie das Package und starten Sie in wenigen Minuten mit der Abfrage des deutschen Handelsregisters.
+
+ [:octicons-arrow-right-24: Installation](installation.md)
+
+- :material-code-braces:{ .lg .middle } __Als Library__
+
+ ---
+
+ Integrieren Sie die Handelsregister-Abfrage in Ihre Python-Anwendungen mit einer einfachen API.
+
+ [:octicons-arrow-right-24: Library-Dokumentation](guide/library.md)
+
+- :material-console:{ .lg .middle } __Kommandozeile__
+
+ ---
+
+ Nutzen Sie das CLI-Tool fĂŒr schnelle Abfragen direkt aus dem Terminal.
+
+ [:octicons-arrow-right-24: CLI-Dokumentation](guide/cli.md)
+
+- :material-api:{ .lg .middle } __API-Referenz__
+
+ ---
+
+ VollstÀndige technische Dokumentation aller Klassen, Funktionen und Datenmodelle.
+
+ [:octicons-arrow-right-24: API-Referenz](api/index.md)
+
+
+
+---
+
+## Was ist Handelsregister?
+
+**Handelsregister** ist ein Python-Package fĂŒr das gemeinsame Registerportal der deutschen BundeslĂ€nder. Es ermöglicht die programmatische Abfrage des Handelsregisters â sowohl als **Kommandozeilen-Tool** als auch als **Library** in eigenen Anwendungen.
+
+```python
+from handelsregister import search
+
+# Unternehmen suchen
+unternehmen = search("Deutsche Bahn")
+
+for firma in unternehmen:
+ print(f"{firma.name} - {firma.register_num}")
+```
+
+### Funktionsumfang
+
+- :material-magnify: **Unternehmenssuche** â Suche nach Firmennamen, Registernummer oder Ort
+- :material-filter: **Flexible Filter** â Nach Bundesland, Registerart und Status filtern
+- :material-file-document: **Detailabruf** â Erweiterte Unternehmensinformationen abrufen
+- :material-cached: **Intelligentes Caching** â Automatische Zwischenspeicherung von Ergebnissen
+- :material-console: **CLI-Tool** â Kommandozeilen-Interface fĂŒr schnelle Abfragen
+- :material-code-json: **JSON-Export** â Maschinenlesbare Ausgabe fĂŒr Weiterverarbeitung
+
+---
+
+## Schnellbeispiel
+
+=== "Python"
+
+ ```python
+ from handelsregister import search, get_details
+
+ # Suche nach Banken in Berlin und Hamburg
+ banken = search(
+ keywords="Bank",
+ states=["BE", "HH"],
+ register_type="HRB"
+ )
+
+ print(f"Gefunden: {len(banken)} Unternehmen")
+
+ # Details zum ersten Ergebnis abrufen
+ if banken:
+ details = get_details(banken[0])
+ print(f"Firma: {details.name}")
+ print(f"Kapital: {details.capital} {details.currency}")
+ ```
+
+=== "Kommandozeile"
+
+ ```bash
+ # Einfache Suche
+ handelsregister -s "Deutsche Bahn"
+
+ # Mit JSON-Ausgabe
+ handelsregister -s "GASAG AG" --exact --json
+
+ # Mit Filtern
+ handelsregister -s "Bank" --states BE,HH --register-type HRB
+ ```
+
+---
+
+## Installation
+
+Die schnellste Methode zur Installation ist mit [uv](https://docs.astral.sh/uv/):
+
+```bash
+# Klonen und installieren
+git clone https://github.com/bundesAPI/handelsregister.git
+cd handelsregister
+uv sync
+```
+
+Oder direkt mit pip:
+
+```bash
+pip install git+https://github.com/bundesAPI/handelsregister.git
+```
+
+:material-arrow-right: [VollstÀndige Installationsanleitung](installation.md)
+
+---
+
+## Architektur
+
+Das Package besteht aus mehreren Schichten:
+
+```mermaid
+graph TB
+ A[CLI / Anwendung] --> B[Public API]
+ B --> C[HandelsRegister]
+ C --> D[SearchCache]
+ C --> E[ResultParser]
+ C --> F[DetailsParser]
+ D --> G[Dateisystem]
+ C --> H[mechanize Browser]
+ H --> I[handelsregister.de]
+```
+
+| Komponente | Beschreibung |
+|------------|--------------|
+| `search()` | Einfache API fĂŒr Unternehmenssuche |
+| `get_details()` | API fĂŒr Detailabruf |
+| `HandelsRegister` | Browser-Automatisierung |
+| `SearchCache` | TTL-basiertes Caching |
+| `ResultParser` | HTML-Parsing der Suchergebnisse |
+| `DetailsParser` | Parsing der Detailansichten |
+
+---
+
+## Rechtliche Hinweise
+
+!!! warning "NutzungsbeschrÀnkungen"
+
+ Es ist unzulĂ€ssig, mehr als **60 Abrufe pro Stunde** zu tĂ€tigen. Das Registerportal ist das Ziel automatisierter Massenabfragen, deren Frequenz hĂ€ufig die StraftatbestĂ€nde der **§§ 303a, b StGB** erfĂŒllt.
+
+Die Einsichtnahme in das Handelsregister ist gemÀà **§ 9 Abs. 1 HGB** jeder Person zu Informationszwecken gestattet.
+
+:material-arrow-right: [VollstÀndige rechtliche Hinweise](legal.md)
+
+---
+
+## UnterstĂŒtzung
+
+
+
+- :fontawesome-brands-github:{ .lg .middle } __GitHub Issues__
+
+ ---
+
+ Bugs melden und Features anfragen
+
+ [:octicons-arrow-right-24: Issues öffnen](https://github.com/bundesAPI/handelsregister/issues)
+
+- :material-source-pull:{ .lg .middle } __Beitragen__
+
+ ---
+
+ Pull Requests sind willkommen!
+
+ [:octicons-arrow-right-24: Repository](https://github.com/bundesAPI/handelsregister)
+
+
+
+---
+
+## Lizenz
+
+Dieses Projekt ist Teil der [bundesAPI](https://github.com/bundesAPI) Initiative und steht unter der MIT-Lizenz.
+
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..c10b5320
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,191 @@
+# Handelsregister
+
+
+
+- :material-rocket-launch:{ .lg .middle } __Quick Start__
+
+ ---
+
+ Install the package and start querying the German commercial register in minutes.
+
+ [:octicons-arrow-right-24: Installation](installation.md)
+
+- :material-code-braces:{ .lg .middle } __As Library__
+
+ ---
+
+ Integrate commercial register queries into your Python applications with a simple API.
+
+ [:octicons-arrow-right-24: Library Documentation](guide/library.md)
+
+- :material-console:{ .lg .middle } __Command Line__
+
+ ---
+
+ Use the CLI tool for quick queries directly from your terminal.
+
+ [:octicons-arrow-right-24: CLI Documentation](guide/cli.md)
+
+- :material-api:{ .lg .middle } __API Reference__
+
+ ---
+
+ Complete technical documentation of all classes, functions, and data models.
+
+ [:octicons-arrow-right-24: API Reference](api/index.md)
+
+
+
+---
+
+## What is Handelsregister?
+
+**Handelsregister** is a Python package for the shared commercial register portal of the German federal states. It enables programmatic access to the German commercial register â both as a **command-line tool** and as a **library** in your own applications.
+
+```python
+from handelsregister import search
+
+# Search for companies
+companies = search("Deutsche Bahn")
+
+for company in companies:
+ print(f"{company.name} - {company.register_num}")
+```
+
+### Features
+
+- :material-magnify: **Company Search** â Search by company name, register number, or location
+- :material-filter: **Flexible Filters** â Filter by state, register type, and status
+- :material-file-document: **Detail Fetching** â Retrieve extended company information
+- :material-cached: **Intelligent Caching** â Automatic caching of results
+- :material-console: **CLI Tool** â Command-line interface for quick queries
+- :material-code-json: **JSON Export** â Machine-readable output for further processing
+
+---
+
+## Quick Example
+
+=== "Python"
+
+ ```python
+ from handelsregister import search, get_details
+
+ # Search for banks in Berlin and Hamburg
+ banks = search(
+ keywords="Bank",
+ states=["BE", "HH"],
+ register_type="HRB"
+ )
+
+ print(f"Found: {len(banks)} companies")
+
+ # Get details for the first result
+ if banks:
+ details = get_details(banks[0])
+ print(f"Company: {details.name}")
+ print(f"Capital: {details.capital} {details.currency}")
+ ```
+
+=== "Command Line"
+
+ ```bash
+ # Simple search
+ handelsregister -s "Deutsche Bahn"
+
+ # With JSON output
+ handelsregister -s "GASAG AG" --exact --json
+
+ # With filters
+ handelsregister -s "Bank" --states BE,HH --register-type HRB
+ ```
+
+---
+
+## Installation
+
+The fastest installation method is with [uv](https://docs.astral.sh/uv/):
+
+```bash
+# Clone and install
+git clone https://github.com/bundesAPI/handelsregister.git
+cd handelsregister
+uv sync
+```
+
+Or directly with pip:
+
+```bash
+pip install git+https://github.com/bundesAPI/handelsregister.git
+```
+
+:material-arrow-right: [Complete Installation Guide](installation.md)
+
+---
+
+## Architecture
+
+The package consists of several layers:
+
+```mermaid
+graph TB
+ A[CLI / Application] --> B[Public API]
+ B --> C[HandelsRegister]
+ C --> D[SearchCache]
+ C --> E[ResultParser]
+ C --> F[DetailsParser]
+ D --> G[File System]
+ C --> H[mechanize Browser]
+ H --> I[handelsregister.de]
+```
+
+| Component | Description |
+|-----------|-------------|
+| `search()` | Simple API for company search |
+| `get_details()` | API for fetching details |
+| `HandelsRegister` | Browser automation |
+| `SearchCache` | TTL-based caching |
+| `ResultParser` | HTML parsing of search results |
+| `DetailsParser` | Parsing of detail views |
+
+---
+
+## Legal Notice
+
+!!! warning "Usage Restrictions"
+
+ It is not permitted to make more than **60 requests per hour**. The register portal is frequently targeted by automated mass queries, which often constitute criminal offenses under **§§ 303a, b StGB** (German Criminal Code).
+
+Access to the commercial register is permitted for informational purposes according to **§ 9 Abs. 1 HGB** (German Commercial Code).
+
+:material-arrow-right: [Complete Legal Notice](legal.md)
+
+---
+
+## Support
+
+
+
+- :fontawesome-brands-github:{ .lg .middle } __GitHub Issues__
+
+ ---
+
+ Report bugs and request features
+
+ [:octicons-arrow-right-24: Open Issues](https://github.com/bundesAPI/handelsregister/issues)
+
+- :material-source-pull:{ .lg .middle } __Contribute__
+
+ ---
+
+ Pull requests are welcome!
+
+ [:octicons-arrow-right-24: Repository](https://github.com/bundesAPI/handelsregister)
+
+
+
+---
+
+## License
+
+This project is part of the [bundesAPI](https://github.com/bundesAPI) initiative and is licensed under the MIT License.
+
diff --git a/docs/installation.de.md b/docs/installation.de.md
new file mode 100644
index 00000000..fb5ef3e5
--- /dev/null
+++ b/docs/installation.de.md
@@ -0,0 +1,219 @@
+# Installation
+
+Diese Anleitung beschreibt die Installation des Handelsregister-Packages auf verschiedenen Systemen.
+
+## Voraussetzungen
+
+- **Python 3.9** oder höher
+- **pip** oder **uv** als Paketmanager
+
+## Installation mit uv (Empfohlen)
+
+[uv](https://docs.astral.sh/uv/) ist ein moderner, schneller Python-Paketmanager. Er ist die empfohlene Methode zur Installation:
+
+```bash
+# Repository klonen
+git clone https://github.com/bundesAPI/handelsregister.git
+cd handelsregister
+
+# AbhÀngigkeiten installieren
+uv sync
+```
+
+Das Kommandozeilen-Tool ist dann verfĂŒgbar:
+
+```bash
+uv run handelsregister -s "Deutsche Bahn"
+```
+
+### Entwicklungsumgebung
+
+FĂŒr die Entwicklung mit zusĂ€tzlichen Werkzeugen:
+
+```bash
+# Mit EntwicklungsabhÀngigkeiten
+uv sync --extra dev
+
+# Tests ausfĂŒhren
+uv run pytest
+```
+
+### Dokumentation lokal bauen
+
+```bash
+# Mit DokumentationsabhÀngigkeiten
+uv sync --extra docs
+
+# Dokumentation starten
+uv run mkdocs serve
+```
+
+---
+
+## Installation mit pip
+
+### Direkt von GitHub
+
+```bash
+pip install git+https://github.com/bundesAPI/handelsregister.git
+```
+
+### In einem Virtual Environment
+
+```bash
+# Virtual Environment erstellen
+python -m venv venv
+
+# Aktivieren (Linux/macOS)
+source venv/bin/activate
+
+# Aktivieren (Windows)
+venv\Scripts\activate
+
+# Installieren
+pip install git+https://github.com/bundesAPI/handelsregister.git
+```
+
+### Aus lokalem Klon
+
+```bash
+# Repository klonen
+git clone https://github.com/bundesAPI/handelsregister.git
+cd handelsregister
+
+# Als editierbares Package installieren
+pip install -e .
+
+# Mit EntwicklungsabhÀngigkeiten
+pip install -e ".[dev]"
+```
+
+---
+
+## AbhÀngigkeiten
+
+Das Package hat folgende AbhÀngigkeiten:
+
+| Package | Version | Beschreibung |
+|---------|---------|--------------|
+| `mechanize` | â„0.4.8 | Browser-Automatisierung |
+| `beautifulsoup4` | â„4.11.0 | HTML-Parsing |
+
+### Optionale AbhÀngigkeiten
+
+=== "Entwicklung"
+
+ ```
+ black>=22.6.0 # Code-Formatierung
+ pytest>=7.0.0 # Testing
+ ```
+
+=== "Dokumentation"
+
+ ```
+ mkdocs>=1.5.0 # Dokumentationsgenerator
+ mkdocs-material>=9.5.0 # Material Theme
+ mkdocstrings[python]>=0.24.0 # API-Dokumentation
+ mkdocs-static-i18n>=1.2.0 # Internationalisierung
+ ```
+
+---
+
+## Systemspezifische Hinweise
+
+### macOS
+
+Auf macOS ist Python 3 in der Regel vorinstalliert. Falls nicht:
+
+```bash
+# Mit Homebrew
+brew install python
+
+# uv installieren
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Linux (Debian/Ubuntu)
+
+```bash
+# Python und pip installieren
+sudo apt update
+sudo apt install python3 python3-pip python3-venv
+
+# uv installieren
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Windows
+
+1. Python von [python.org](https://www.python.org/downloads/) herunterladen
+2. Bei der Installation "Add Python to PATH" aktivieren
+3. uv installieren:
+
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+---
+
+## ĂberprĂŒfung der Installation
+
+Nach der Installation können Sie die Installation ĂŒberprĂŒfen:
+
+=== "Als Modul"
+
+ ```bash
+ python -c "import handelsregister; print('Installation erfolgreich!')"
+ ```
+
+=== "CLI"
+
+ ```bash
+ handelsregister --help
+ ```
+
+=== "Mit uv"
+
+ ```bash
+ uv run python -c "import handelsregister; print('Installation erfolgreich!')"
+ ```
+
+---
+
+## HĂ€ufige Probleme
+
+### ModuleNotFoundError: No module named 'mechanize'
+
+Die AbhĂ€ngigkeiten wurden nicht korrekt installiert. FĂŒhren Sie erneut aus:
+
+```bash
+pip install mechanize beautifulsoup4
+```
+
+### SSL-Zertifikatsfehler
+
+Auf manchen Systemen gibt es Probleme mit SSL-Zertifikaten:
+
+```bash
+# macOS: Zertifikate installieren
+/Applications/Python\ 3.x/Install\ Certificates.command
+```
+
+### Permission Denied bei globaler Installation
+
+Verwenden Sie `--user` oder ein Virtual Environment:
+
+```bash
+pip install --user git+https://github.com/bundesAPI/handelsregister.git
+```
+
+---
+
+## NĂ€chste Schritte
+
+Nach erfolgreicher Installation:
+
+- :material-rocket-launch: [Schnellstart](quickstart.md) â Erste Schritte mit dem Package
+- :material-code-braces: [Library-Dokumentation](guide/library.md) â Integration in Python-Anwendungen
+- :material-console: [CLI-Dokumentation](guide/cli.md) â Nutzung der Kommandozeile
+
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 00000000..186e1436
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,219 @@
+# Installation
+
+This guide describes how to install the Handelsregister package on various systems.
+
+## Requirements
+
+- **Python 3.9** or higher
+- **pip** or **uv** as package manager
+
+## Installation with uv (Recommended)
+
+[uv](https://docs.astral.sh/uv/) is a modern, fast Python package manager. It's the recommended installation method:
+
+```bash
+# Clone the repository
+git clone https://github.com/bundesAPI/handelsregister.git
+cd handelsregister
+
+# Install dependencies
+uv sync
+```
+
+The command-line tool is then available:
+
+```bash
+uv run handelsregister -s "Deutsche Bahn"
+```
+
+### Development Environment
+
+For development with additional tools:
+
+```bash
+# With development dependencies
+uv sync --extra dev
+
+# Run tests
+uv run pytest
+```
+
+### Build Documentation Locally
+
+```bash
+# With documentation dependencies
+uv sync --extra docs
+
+# Start documentation server
+uv run mkdocs serve
+```
+
+---
+
+## Installation with pip
+
+### Directly from GitHub
+
+```bash
+pip install git+https://github.com/bundesAPI/handelsregister.git
+```
+
+### In a Virtual Environment
+
+```bash
+# Create virtual environment
+python -m venv venv
+
+# Activate (Linux/macOS)
+source venv/bin/activate
+
+# Activate (Windows)
+venv\Scripts\activate
+
+# Install
+pip install git+https://github.com/bundesAPI/handelsregister.git
+```
+
+### From Local Clone
+
+```bash
+# Clone repository
+git clone https://github.com/bundesAPI/handelsregister.git
+cd handelsregister
+
+# Install as editable package
+pip install -e .
+
+# With development dependencies
+pip install -e ".[dev]"
+```
+
+---
+
+## Dependencies
+
+The package has the following dependencies:
+
+| Package | Version | Description |
+|---------|---------|-------------|
+| `mechanize` | â„0.4.8 | Browser automation |
+| `beautifulsoup4` | â„4.11.0 | HTML parsing |
+
+### Optional Dependencies
+
+=== "Development"
+
+ ```
+ black>=22.6.0 # Code formatting
+ pytest>=7.0.0 # Testing
+ ```
+
+=== "Documentation"
+
+ ```
+ mkdocs>=1.5.0 # Documentation generator
+ mkdocs-material>=9.5.0 # Material theme
+ mkdocstrings[python]>=0.24.0 # API documentation
+ mkdocs-static-i18n>=1.2.0 # Internationalization
+ ```
+
+---
+
+## System-Specific Notes
+
+### macOS
+
+Python 3 is usually pre-installed on macOS. If not:
+
+```bash
+# With Homebrew
+brew install python
+
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Linux (Debian/Ubuntu)
+
+```bash
+# Install Python and pip
+sudo apt update
+sudo apt install python3 python3-pip python3-venv
+
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Windows
+
+1. Download Python from [python.org](https://www.python.org/downloads/)
+2. Enable "Add Python to PATH" during installation
+3. Install uv:
+
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+---
+
+## Verify Installation
+
+After installation, you can verify it:
+
+=== "As Module"
+
+ ```bash
+ python -c "import handelsregister; print('Installation successful!')"
+ ```
+
+=== "CLI"
+
+ ```bash
+ handelsregister --help
+ ```
+
+=== "With uv"
+
+ ```bash
+ uv run python -c "import handelsregister; print('Installation successful!')"
+ ```
+
+---
+
+## Common Issues
+
+### ModuleNotFoundError: No module named 'mechanize'
+
+Dependencies were not installed correctly. Run again:
+
+```bash
+pip install mechanize beautifulsoup4
+```
+
+### SSL Certificate Errors
+
+Some systems have issues with SSL certificates:
+
+```bash
+# macOS: Install certificates
+/Applications/Python\ 3.x/Install\ Certificates.command
+```
+
+### Permission Denied on Global Installation
+
+Use `--user` or a virtual environment:
+
+```bash
+pip install --user git+https://github.com/bundesAPI/handelsregister.git
+```
+
+---
+
+## Next Steps
+
+After successful installation:
+
+- :material-rocket-launch: [Quickstart](quickstart.md) â First steps with the package
+- :material-code-braces: [Library Documentation](guide/library.md) â Integration into Python applications
+- :material-console: [CLI Documentation](guide/cli.md) â Using the command line
+
diff --git a/docs/legal.de.md b/docs/legal.de.md
new file mode 100644
index 00000000..05b62e36
--- /dev/null
+++ b/docs/legal.de.md
@@ -0,0 +1,156 @@
+# Rechtliche Hinweise
+
+Diese Seite enthÀlt wichtige rechtliche Informationen zur Nutzung des Handelsregister-Packages.
+
+## NutzungsbeschrÀnkungen
+
+!!! danger "Wichtig: Rate-Limits"
+
+ Es ist **unzulÀssig**, mehr als **60 Abrufe pro Stunde** beim Handelsregisterportal zu tÀtigen.
+
+ Das Registerportal ist das Ziel automatisierter Massenabfragen, deren Frequenz hĂ€ufig die StraftatbestĂ€nde der **§§ 303a, b StGB** (Computersabotage) erfĂŒllt.
+
+## Rechtsgrundlage
+
+### Einsichtnahme (§ 9 Abs. 1 HGB)
+
+GemÀà **§ 9 Abs. 1 HGB** (Handelsgesetzbuch) ist die Einsichtnahme in das Handelsregister jeder Person zu Informationszwecken gestattet.
+
+> "Die Einsichtnahme in das Handelsregister sowie in die zum Handelsregister eingereichten Dokumente ist jedem zu Informationszwecken gestattet."
+
+### Datenschutz (DSGVO)
+
+Die aus dem Handelsregister erhaltenen Daten können personenbezogene Daten enthalten. Bei der Verwendung dieser Daten mĂŒssen Sie die **Datenschutz-Grundverordnung (DSGVO)** und das **Bundesdatenschutzgesetz (BDSG)** einhalten.
+
+Insbesondere:
+
+- Personenbezogene Daten dĂŒrfen nur fĂŒr legitime Zwecke verarbeitet werden
+- GrundsÀtze der Datenminimierung gelten
+- Betroffene haben Rechte bezĂŒglich ihrer Daten
+
+---
+
+## Nutzungsbedingungen von handelsregister.de
+
+Das Handelsregisterportal (handelsregister.de) hat eigene Nutzungsbedingungen, die zu beachten sind:
+
+1. **Keine Massenabfragen** - Automatisierter Abruf groĂer Datenmengen ist untersagt
+2. **Kein kommerzieller Weiterverkauf** - Daten dĂŒrfen nicht ohne Genehmigung kommerziell weiterverkauft oder verbreitet werden
+3. **Persönliche Haftung** - Nutzer haften persönlich fĂŒr ihre Nutzung des Portals
+
+---
+
+## Haftungsausschluss
+
+### Keine Garantie
+
+Dieses Package wird "wie besehen" ohne jegliche Garantie bereitgestellt. Die Autoren und Mitwirkenden:
+
+- Garantieren nicht die Richtigkeit, VollstÀndigkeit oder AktualitÀt der Daten
+- Haften nicht fĂŒr SchĂ€den, die aus der Nutzung dieses Packages entstehen
+- Garantieren nicht die VerfĂŒgbarkeit oder FunktionsfĂ€higkeit des Packages
+
+### Nutzerverantwortung
+
+Nutzer dieses Packages sind verantwortlich fĂŒr:
+
+- Einhaltung der Rate-Limits
+- Beachtung geltender Gesetze und Vorschriften
+- OrdnungsgemĂ€Ăen Umgang mit personenbezogenen Daten
+- Alle Konsequenzen ihrer Nutzung
+
+---
+
+## Verbotene Nutzungen
+
+Dieses Package darf **nicht** verwendet werden fĂŒr:
+
+1. **Massenhafte Datensammlung** - Systematische Erfassung aller oder groĂer Teile der Registerdaten
+2. **Denial of Service** - Aktionen, die die VerfĂŒgbarkeit des Portals beeintrĂ€chtigen könnten
+3. **Kommerzieller Datenweiterverkauf** - Verkauf von Registerdaten ohne Genehmigung
+4. **Stalking oder BelĂ€stigung** - Nutzung von Unternehmens- oder Personendaten fĂŒr schĂ€dliche Zwecke
+5. **Betrug** - Jegliche betrĂŒgerische oder tĂ€uschende Zwecke
+
+---
+
+## Best Practices
+
+FĂŒr eine verantwortungsvolle Nutzung dieses Packages:
+
+### Rate-Limits respektieren
+
+```python
+import time
+
+# Zwischen Anfragen warten
+for suchbegriff in suchbegriffe:
+ ergebnisse = search(suchbegriff)
+ time.sleep(60) # Max 60 Anfragen pro Stunde
+```
+
+### Caching nutzen
+
+```python
+# Caching ist standardmĂ€Ăig aktiviert
+ergebnisse = search("Bank") # Einmal abgerufen, 24h gecacht
+```
+
+### Anfragen minimieren
+
+```python
+# Gut: Server-seitig filtern
+firmen = search("Bank", states=["BE"], register_type="HRB")
+
+# Schlecht: Alles abrufen, lokal filtern
+alle_firmen = search("Bank") # Viel gröĂere Antwort
+gefiltert = [f for f in alle_firmen if f['state'] == 'BE']
+```
+
+---
+
+## Probleme melden
+
+Wenn Sie Probleme mit diesem Package entdecken, die zu Missbrauch fĂŒhren könnten, melden Sie diese bitte verantwortungsvoll:
+
+1. Ăffnen Sie ein GitHub-Issue (fĂŒr nicht-sicherheitsrelevante Probleme)
+2. Kontaktieren Sie die Maintainer direkt (fĂŒr Sicherheitsprobleme)
+
+---
+
+## Lizenz
+
+Dieses Package ist unter der **MIT-Lizenz** lizenziert.
+
+```
+MIT License
+
+Copyright (c) 2024 BundesAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+---
+
+## Kontakt
+
+FĂŒr Fragen zu rechtlichen Angelegenheiten:
+
+- **GitHub Issues**: [github.com/bundesAPI/handelsregister/issues](https://github.com/bundesAPI/handelsregister/issues)
+- **BundesAPI**: [github.com/bundesAPI](https://github.com/bundesAPI)
+
diff --git a/docs/legal.md b/docs/legal.md
new file mode 100644
index 00000000..cfa90d33
--- /dev/null
+++ b/docs/legal.md
@@ -0,0 +1,158 @@
+# Legal Notice
+
+This page contains important legal information regarding the use of the Handelsregister package.
+
+## Usage Restrictions
+
+!!! danger "Important: Rate Limits"
+
+ It is **not permitted** to make more than **60 requests per hour** to the commercial register portal.
+
+ The register portal is frequently targeted by automated mass queries, which often constitute criminal offenses under **§§ 303a, b StGB** (German Criminal Code - Computer Sabotage).
+
+## Legal Basis
+
+### Access Rights (§ 9 Abs. 1 HGB)
+
+According to **§ 9 Abs. 1 HGB** (German Commercial Code), access to the commercial register is permitted to any person for informational purposes.
+
+> "Die Einsichtnahme in das Handelsregister sowie in die zum Handelsregister eingereichten Dokumente ist jedem zu Informationszwecken gestattet."
+>
+> *Translation: Access to the commercial register and documents filed with it is permitted to everyone for informational purposes.*
+
+### Data Protection (GDPR)
+
+The data obtained from the commercial register may contain personal data. When using this data, you must comply with the **General Data Protection Regulation (GDPR)** and the **Bundesdatenschutzgesetz (BDSG)**.
+
+In particular:
+
+- Personal data may only be processed for legitimate purposes
+- Data minimization principles apply
+- Data subjects have rights regarding their data
+
+---
+
+## Terms of Use of handelsregister.de
+
+The commercial register portal (handelsregister.de) has its own terms of use that must be observed:
+
+1. **No mass queries** - Automated retrieval of large amounts of data is prohibited
+2. **No commercial redistribution** - Data may not be resold or redistributed commercially without authorization
+3. **Personal liability** - Users are personally responsible for their use of the portal
+
+---
+
+## Liability Disclaimer
+
+### No Warranty
+
+This package is provided "as is" without warranty of any kind. The authors and contributors:
+
+- Do not guarantee the accuracy, completeness, or timeliness of data
+- Are not liable for any damages resulting from use of this package
+- Do not guarantee the availability or functionality of the package
+
+### User Responsibility
+
+Users of this package are responsible for:
+
+- Complying with rate limits
+- Observing applicable laws and regulations
+- Proper handling of personal data
+- Any consequences of their use
+
+---
+
+## Prohibited Uses
+
+This package may **not** be used for:
+
+1. **Mass data harvesting** - Systematic collection of all or large portions of register data
+2. **Denial of Service** - Actions that could impair the portal's availability
+3. **Commercial data resale** - Selling register data without authorization
+4. **Stalking or harassment** - Using company or person data for harmful purposes
+5. **Fraud** - Any fraudulent or deceptive purposes
+
+---
+
+## Best Practices
+
+To use this package responsibly:
+
+### Respect Rate Limits
+
+```python
+import time
+
+# Wait between requests
+for keyword in keywords:
+ results = search(keyword)
+ time.sleep(60) # Max 60 requests per hour
+```
+
+### Use Caching
+
+```python
+# Caching is enabled by default
+results = search("Bank") # Fetched once, cached for 24h
+```
+
+### Minimize Requests
+
+```python
+# Good: Use server-side filtering
+companies = search("Bank", states=["BE"], register_type="HRB")
+
+# Bad: Fetch everything, filter locally
+all_companies = search("Bank") # Much larger response
+filtered = [c for c in all_companies if c['state'] == 'BE']
+```
+
+---
+
+## Reporting Issues
+
+If you discover any issues with this package that could lead to misuse, please report them responsibly:
+
+1. Open a GitHub issue (for non-security issues)
+2. Contact the maintainers directly (for security issues)
+
+---
+
+## License
+
+This package is licensed under the **MIT License**.
+
+```
+MIT License
+
+Copyright (c) 2024 BundesAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+---
+
+## Contact
+
+For questions regarding legal matters:
+
+- **GitHub Issues**: [github.com/bundesAPI/handelsregister/issues](https://github.com/bundesAPI/handelsregister/issues)
+- **BundesAPI**: [github.com/bundesAPI](https://github.com/bundesAPI)
+
diff --git a/docs/quickstart.de.md b/docs/quickstart.de.md
new file mode 100644
index 00000000..0c2458ae
--- /dev/null
+++ b/docs/quickstart.de.md
@@ -0,0 +1,190 @@
+# Schnellstart
+
+Starten Sie mit Handelsregister in nur wenigen Minuten.
+
+## Installation
+
+```bash
+git clone https://github.com/bundesAPI/handelsregister.git
+cd handelsregister
+uv sync
+```
+
+---
+
+## Erste Suche
+
+### Mit Python
+
+```python
+from handelsregister import search
+
+# Unternehmen suchen
+ergebnisse = search("Deutsche Bahn")
+
+# Ergebnisse ausgeben
+for firma in ergebnisse:
+ print(f"{firma.name}")
+ print(f" Register: {firma.court} {firma.register_num}")
+ print(f" Status: {firma.status}")
+ print()
+```
+
+**Ausgabe:**
+
+```
+Deutsche Bahn Aktiengesellschaft
+ Register: Berlin (Charlottenburg) HRB 50000
+ Status: aktuell eingetragen
+
+DB Fernverkehr Aktiengesellschaft
+ Register: Frankfurt am Main HRB 12345
+ Status: aktuell eingetragen
+...
+```
+
+### Mit CLI
+
+```bash
+# Suche nach "Deutsche Bahn"
+handelsregister -s "Deutsche Bahn"
+# Oder die kĂŒrzere Variante verwenden:
+hrg -s "Deutsche Bahn"
+
+# Als JSON-Ausgabe
+handelsregister -s "Deutsche Bahn" --json
+```
+
+---
+
+## Ergebnisse filtern
+
+### Nach Bundesland
+
+```python
+from handelsregister import search
+
+# Nur Berliner Unternehmen
+ergebnisse = search("Bank", states=["BE"])
+```
+
+```bash
+# CLI: Nur Berlin
+handelsregister -s "Bank" --states BE
+```
+
+### Nach Registerart
+
+```python
+# Nur Kapitalgesellschaften (HRB)
+ergebnisse = search("GmbH", register_type="HRB")
+```
+
+```bash
+# CLI
+handelsregister -s "GmbH" --register-type HRB
+```
+
+### Kombinierte Filter
+
+```python
+# Banken in Berlin oder Hamburg, nur HRB
+ergebnisse = search(
+ keywords="Bank",
+ states=["BE", "HH"],
+ register_type="HRB",
+ include_deleted=False
+)
+```
+
+---
+
+## Details abrufen
+
+```python
+from handelsregister import search, get_details
+
+# Suchen
+firmen = search("GASAG AG", keyword_option="exact")
+
+if firmen:
+ # Detailinformationen abrufen
+ details = get_details(firmen[0])
+
+ print(f"Firma: {details.name}")
+ print(f"Kapital: {details.capital} {details.currency}")
+ print(f"Adresse: {details.address}")
+
+ print("Vertreter:")
+ for vertreter in details.representatives:
+ print(f" - {vertreter.name} ({vertreter.role})")
+```
+
+---
+
+## Caching
+
+Das Package cached Ergebnisse automatisch:
+
+```python
+from handelsregister import search
+
+# Erste Suche: Fragt das Registerportal an
+ergebnisse1 = search("Deutsche Bank")
+
+# Zweite Suche: Nutzt Cache (schneller)
+ergebnisse2 = search("Deutsche Bank")
+
+# Frische Suche erzwingen (Cache umgehen)
+ergebnisse3 = search("Deutsche Bank", force_refresh=True)
+```
+
+Standard Cache-Dauer: **24 Stunden**
+
+---
+
+## Fehlerbehandlung
+
+```python
+from handelsregister import search, SearchError, RateLimitError
+
+try:
+ ergebnisse = search("Deutsche Bahn")
+except RateLimitError:
+ print("Zu viele Anfragen! Maximal 60 pro Stunde erlaubt.")
+except SearchError as e:
+ print(f"Suchfehler: {e}")
+```
+
+---
+
+## NĂ€chste Schritte
+
+
+
+- :material-book-open-variant:{ .lg .middle } __Benutzerhandbuch__
+
+ ---
+
+ Detaillierte Dokumentation aller Funktionen
+
+ [:octicons-arrow-right-24: Benutzerhandbuch](guide/index.md)
+
+- :material-api:{ .lg .middle } __API-Referenz__
+
+ ---
+
+ VollstÀndige technische Referenz
+
+ [:octicons-arrow-right-24: API-Referenz](api/index.md)
+
+- :material-code-braces:{ .lg .middle } __Beispiele__
+
+ ---
+
+ Praktische Code-Beispiele
+
+ [:octicons-arrow-right-24: Beispiele](examples/simple.md)
+
+
+
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 00000000..81c7e1ed
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,213 @@
+# Quickstart
+
+Get started with Handelsregister in just a few minutes.
+
+## Installation
+
+```bash
+git clone https://github.com/bundesAPI/handelsregister.git
+cd handelsregister
+uv sync
+```
+
+---
+
+## First Search
+
+### Using Python
+
+```python
+from handelsregister import search
+
+# Search for companies
+results = search("Deutsche Bahn")
+
+# Display results
+for company in results:
+ print(f"{company.name}")
+ print(f" Register: {company.court} {company.register_num}")
+ print(f" Status: {company.status}")
+ print()
+```
+
+**Output:**
+
+```
+Deutsche Bahn Aktiengesellschaft
+ Register: Berlin (Charlottenburg) HRB 50000
+ Status: currently registered
+
+DB Fernverkehr Aktiengesellschaft
+ Register: Frankfurt am Main HRB 12345
+ Status: currently registered
+...
+```
+
+### Using CLI
+
+```bash
+# Search for "Deutsche Bahn"
+handelsregister -s "Deutsche Bahn"
+# Or use the shorter alias:
+hrg -s "Deutsche Bahn"
+
+# As JSON output
+handelsregister -s "Deutsche Bahn" --json
+```
+
+---
+
+## Filtering Results
+
+### By State
+
+```python
+from handelsregister import search, State
+
+# Only Berlin companies (recommended: Enum for autocomplete)
+results = search("Bank", states=[State.BE])
+
+# String-based API still works
+results = search("Bank", states=["BE"])
+```
+
+```bash
+# CLI: Berlin only
+handelsregister -s "Bank" --states BE
+```
+
+### By Register Type
+
+```python
+from handelsregister import search, RegisterType
+
+# Only corporations (HRB) - recommended: Enum
+results = search("GmbH", register_type=RegisterType.HRB)
+
+# String-based API still works
+results = search("GmbH", register_type="HRB")
+```
+
+```bash
+# CLI
+handelsregister -s "GmbH" --register-type HRB
+```
+
+### Combined Filters
+
+```python
+from handelsregister import search, State, RegisterType
+
+# Banks in Berlin or Hamburg, only HRB, exclude deleted entries
+# Recommended: Enums for better IDE support
+results = search(
+ keywords="Bank",
+ states=[State.BE, State.HH],
+ register_type=RegisterType.HRB,
+ include_deleted=False
+)
+
+# String-based API still works
+results = search(
+ keywords="Bank",
+ states=["BE", "HH"],
+ register_type="HRB",
+ include_deleted=False
+)
+```
+
+---
+
+## Fetching Details
+
+```python
+from handelsregister import search, get_details, KeywordMatch
+
+# Search (recommended: Enum for autocomplete)
+companies = search("GASAG AG", keyword_option=KeywordMatch.EXACT)
+
+# String-based API still works
+companies = search("GASAG AG", keyword_option="exact")
+
+if companies:
+ # Fetch detailed information
+ details = get_details(companies[0])
+
+ print(f"Company: {details.name}")
+ print(f"Capital: {details.capital} {details.currency}")
+ print(f"Address: {details.address}")
+
+ print("Representatives:")
+ for rep in details.representatives:
+ print(f" - {rep.name} ({rep.role})")
+```
+
+---
+
+## Caching
+
+The package automatically caches results:
+
+```python
+from handelsregister import search
+
+# First search: requests the register portal
+results1 = search("Deutsche Bank")
+
+# Second search: uses cache (faster)
+results2 = search("Deutsche Bank")
+
+# Force fresh search (bypass cache)
+results3 = search("Deutsche Bank", force_refresh=True)
+```
+
+Default cache duration: **24 hours**
+
+---
+
+## Error Handling
+
+```python
+from handelsregister import search, NetworkError, FormError, ParseError
+
+try:
+ results = search("Deutsche Bahn")
+except NetworkError as e:
+ print(f"Network error: {e}")
+except FormError as e:
+ print(f"Form error: {e}")
+except ParseError as e:
+ print(f"Parse error: {e}")
+```
+
+---
+
+## Next Steps
+
+
+
+- :material-book-open-variant:{ .lg .middle } __User Guide__
+
+ ---
+
+ Detailed documentation for all features
+
+ [:octicons-arrow-right-24: User Guide](guide/index.md)
+
+- :material-api:{ .lg .middle } __API Reference__
+
+ ---
+
+ Complete technical reference
+
+ [:octicons-arrow-right-24: API Reference](api/index.md)
+
+- :material-code-braces:{ .lg .middle } __Examples__
+
+ ---
+
+ Practical code examples
+
+ [:octicons-arrow-right-24: Examples](examples/simple.md)
+
+
diff --git a/docs/reference/legal-forms.de.md b/docs/reference/legal-forms.de.md
new file mode 100644
index 00000000..622626fa
--- /dev/null
+++ b/docs/reference/legal-forms.de.md
@@ -0,0 +1,154 @@
+# Rechtsformen
+
+Diese Tabelle zeigt die gÀngigen deutschen Rechtsformen und ihre Eigenschaften.
+
+## Rechtsformen-Referenz
+
+### Kapitalgesellschaften (HRB)
+
+| AbkĂŒrzung | Name | Mindestkapital |
+|-----------|------|----------------|
+| GmbH | Gesellschaft mit beschrÀnkter Haftung | 25.000 ⏠|
+| UG | Unternehmergesellschaft (haftungsbeschrÀnkt) | 1 ⏠|
+| AG | Aktiengesellschaft | 50.000 ⏠|
+| SE | Societas Europaea | 120.000 ⏠|
+| KGaA | Kommanditgesellschaft auf Aktien | 50.000 ⏠|
+
+### Personengesellschaften (HRA)
+
+| AbkĂŒrzung | Name | Haftung |
+|-----------|------|---------|
+| e.K. | Eingetragener Kaufmann | Persönlich |
+| OHG | Offene Handelsgesellschaft | Persönlich |
+| KG | Kommanditgesellschaft | Gemischt |
+| GmbH & Co. KG | GmbH & Co. Kommanditgesellschaft | BeschrÀnkt |
+
+### Weitere Formen
+
+| AbkĂŒrzung | Name | Register |
+|-----------|------|----------|
+| eG | Eingetragene Genossenschaft | GnR |
+| PartG | Partnerschaftsgesellschaft | PR |
+| PartG mbB | Partnerschaftsgesellschaft mbB | PR |
+| e.V. | Eingetragener Verein | VR |
+
+---
+
+## Detaillierte Beschreibungen
+
+### GmbH (Gesellschaft mit beschrÀnkter Haftung)
+
+Die hÀufigste Kapitalgesellschaftsform in Deutschland.
+
+- **Mindestkapital:** 25.000 âŹ
+- **Haftung:** Auf Gesellschaftsvermögen beschrÀnkt
+- **FĂŒhrung:** GeschĂ€ftsfĂŒhrer
+- **Anteile:** GeschÀftsanteile (nicht börsenhandelbar)
+
+```python
+# Suche nach GmbHs
+firmen = search("Consulting GmbH", register_type="HRB")
+```
+
+### UG (Unternehmergesellschaft)
+
+Eine Sondervariante der GmbH fĂŒr GrĂŒnder mit wenig Kapital.
+
+- **Mindestkapital:** 1 âŹ
+- **Thesaurierungspflicht:** 25% des Jahresgewinns bis 25.000 ⏠erreicht
+- **Danach:** Umwandlung in regulÀre GmbH möglich
+
+```python
+firmen = search("UG", register_type="HRB")
+```
+
+### AG (Aktiengesellschaft)
+
+FĂŒr gröĂere Unternehmen, besonders solche, die Börsenkapital suchen.
+
+- **Mindestkapital:** 50.000 âŹ
+- **FĂŒhrung:** Vorstand + Aufsichtsrat
+- **Anteile:** Aktien (können börsengehandelt werden)
+
+```python
+firmen = search("AG", register_type="HRB")
+```
+
+### KG (Kommanditgesellschaft)
+
+Personengesellschaft mit persönlich haftenden und beschrÀnkt haftenden Gesellschaftern.
+
+- **KomplementÀr:** Persönlich haftender Gesellschafter
+- **Kommanditist:** BeschrÀnkt haftender Gesellschafter
+
+```python
+firmen = search("KG", register_type="HRA")
+```
+
+### GmbH & Co. KG
+
+Besondere Kommanditgesellschaft, bei der der KomplementÀr eine GmbH ist.
+
+- Kombiniert beschrÀnkte Haftung mit Personengesellschafts-Besteuerung
+- Sehr verbreitet in Deutschland
+
+```python
+firmen = search("GmbH & Co. KG", register_type="HRA")
+```
+
+---
+
+## Suchmuster
+
+### Nach Rechtsform
+
+```python
+from handelsregister import search
+
+# Nur GmbHs
+gmbhs = search("Suchbegriff GmbH", register_type="HRB")
+
+# Nur AGs
+ags = search("Suchbegriff AG", register_type="HRB")
+
+# Alle Kommanditgesellschaften
+kgs = search("KG", register_type="HRA")
+```
+
+### Mehrere Formen
+
+```python
+# Breit suchen, dann filtern
+alle_firmen = search("Mustermann")
+
+# Nach Suffix filtern
+gmbhs = [f for f in alle_firmen if "GmbH" in f['name']]
+ags = [f for f in alle_firmen if f['name'].endswith(" AG")]
+```
+
+---
+
+## Rechtsform-Statistiken
+
+UngefÀhre Anzahl aktiver Unternehmen in Deutschland:
+
+| Rechtsform | Anzahl | Anteil |
+|------------|--------|--------|
+| GmbH | ~1.200.000 | 48% |
+| UG | ~150.000 | 6% |
+| GmbH & Co. KG | ~200.000 | 8% |
+| KG | ~50.000 | 2% |
+| AG | ~15.000 | <1% |
+| e.K. | ~450.000 | 18% |
+| OHG | ~10.000 | <1% |
+| eG | ~20.000 | <1% |
+| e.V. | ~600.000 | - |
+
+---
+
+## Siehe auch
+
+- [Registerarten](registers.md) â HRA, HRB, etc.
+- [BundeslĂ€nder-Codes](states.md) â Deutsche BundeslĂ€nder-Codes
+- [API-Parameter](parameters.md) â Alle Suchparameter
+
diff --git a/docs/reference/legal-forms.md b/docs/reference/legal-forms.md
new file mode 100644
index 00000000..fdfe017a
--- /dev/null
+++ b/docs/reference/legal-forms.md
@@ -0,0 +1,154 @@
+# Legal Forms
+
+This table shows the common German legal forms (Rechtsformen) and their characteristics.
+
+## Legal Form Reference
+
+### Corporations (HRB)
+
+| Abbreviation | German Name | English Name | Min. Capital |
+|--------------|-------------|--------------|--------------|
+| GmbH | Gesellschaft mit beschrĂ€nkter Haftung | Limited liability company | âŹ25,000 |
+| UG | Unternehmergesellschaft (haftungsbeschrĂ€nkt) | Mini-GmbH | âŹ1 |
+| AG | Aktiengesellschaft | Stock corporation | âŹ50,000 |
+| SE | Societas Europaea | European company | âŹ120,000 |
+| KGaA | Kommanditgesellschaft auf Aktien | Partnership limited by shares | âŹ50,000 |
+
+### Partnerships (HRA)
+
+| Abbreviation | German Name | English Name | Liability |
+|--------------|-------------|--------------|-----------|
+| e.K. | Eingetragener Kaufmann | Sole proprietor | Personal |
+| OHG | Offene Handelsgesellschaft | General partnership | Personal |
+| KG | Kommanditgesellschaft | Limited partnership | Mixed |
+| GmbH & Co. KG | GmbH & Co. Kommanditgesellschaft | Special limited partnership | Limited |
+
+### Other Forms
+
+| Abbreviation | German Name | English Name | Register |
+|--------------|-------------|--------------|----------|
+| eG | Eingetragene Genossenschaft | Cooperative | GnR |
+| PartG | Partnerschaftsgesellschaft | Professional partnership | PR |
+| PartG mbB | Partnerschaftsgesellschaft mbB | Professional partnership (limited) | PR |
+| e.V. | Eingetragener Verein | Registered association | VR |
+
+---
+
+## Detailed Descriptions
+
+### GmbH (Limited Liability Company)
+
+The most common corporate form in Germany.
+
+- **Minimum capital:** âŹ25,000
+- **Liability:** Limited to company assets
+- **Governance:** GeschĂ€ftsfĂŒhrer (managing directors)
+- **Shares:** Anteile (not publicly tradable)
+
+```python
+# Search for GmbHs
+companies = search("Consulting GmbH", register_type="HRB")
+```
+
+### UG (Mini-GmbH)
+
+A special variant of the GmbH for founders with little capital.
+
+- **Minimum capital:** âŹ1
+- **Must retain:** 25% of annual profit until âŹ25,000 reached
+- **Then:** Can convert to regular GmbH
+
+```python
+companies = search("UG", register_type="HRB")
+```
+
+### AG (Stock Corporation)
+
+Used for larger companies, especially those seeking public capital.
+
+- **Minimum capital:** âŹ50,000
+- **Governance:** Vorstand (board) + Aufsichtsrat (supervisory board)
+- **Shares:** Aktien (can be publicly traded)
+
+```python
+companies = search("AG", register_type="HRB")
+```
+
+### KG (Limited Partnership)
+
+Partnership with general and limited partners.
+
+- **KomplementÀr:** General partner (unlimited liability)
+- **Kommanditist:** Limited partner (liability limited to contribution)
+
+```python
+companies = search("KG", register_type="HRA")
+```
+
+### GmbH & Co. KG
+
+Special limited partnership where the general partner is a GmbH.
+
+- Combines limited liability with partnership taxation
+- Very common in Germany
+
+```python
+companies = search("GmbH & Co. KG", register_type="HRA")
+```
+
+---
+
+## Search Patterns
+
+### By Legal Form
+
+```python
+from handelsregister import search
+
+# GmbHs only
+gmbhs = search("keyword GmbH", register_type="HRB")
+
+# AGs only
+ags = search("keyword AG", register_type="HRB")
+
+# All limited partnerships
+kgs = search("KG", register_type="HRA")
+```
+
+### Multiple Forms
+
+```python
+# Search broadly, then filter
+all_companies = search("Mustermann")
+
+# Filter by suffix
+gmbhs = [c for c in all_companies if "GmbH" in c['name']]
+ags = [c for c in all_companies if c['name'].endswith(" AG")]
+```
+
+---
+
+## Legal Form Statistics
+
+Approximate number of active companies in Germany:
+
+| Legal Form | Count | Percentage |
+|------------|-------|------------|
+| GmbH | ~1,200,000 | 48% |
+| UG | ~150,000 | 6% |
+| GmbH & Co. KG | ~200,000 | 8% |
+| KG | ~50,000 | 2% |
+| AG | ~15,000 | <1% |
+| e.K. | ~450,000 | 18% |
+| OHG | ~10,000 | <1% |
+| eG | ~20,000 | <1% |
+| e.V. | ~600,000 | - |
+
+---
+
+## See Also
+
+- [Register Types](registers.md) â HRA, HRB, etc.
+- [State Codes](states.md) â German state codes
+- [API Parameters](parameters.md) â All search parameters
+
diff --git a/docs/reference/parameters.de.md b/docs/reference/parameters.de.md
new file mode 100644
index 00000000..6ae6c101
--- /dev/null
+++ b/docs/reference/parameters.de.md
@@ -0,0 +1,244 @@
+# API-Parameter
+
+VollstĂ€ndige Referenz aller Parameter fĂŒr die `search()`-Funktion.
+
+## ParameterĂŒbersicht
+
+| Parameter | Typ | Standard | Beschreibung |
+|-----------|-----|----------|--------------|
+| `keywords` | `str` | Erforderlich | Suchbegriff fĂŒr Firmennamen |
+| `states` | `List[str]` | `None` | Nach BundeslÀndern filtern |
+| `register_type` | `str` | `None` | Nach Registerart filtern |
+| `court` | `str` | `None` | Spezifisches Registergericht |
+| `register_number` | `str` | `None` | Spezifische Registernummer |
+| `only_active` | `bool` | `False` | Nur aktuell eingetragene |
+| `exact` | `bool` | `False` | Exakte NamensĂŒbereinstimmung |
+| `similar_sounding` | `bool` | `False` | Ăhnlich klingende Namen einschlieĂen |
+| `use_cache` | `bool` | `True` | Gecachte Ergebnisse verwenden |
+
+---
+
+## Parameter im Detail
+
+### keywords (erforderlich)
+
+Der Hauptsuchbegriff. Sucht in Firmennamen.
+
+```python
+# Ein Wort
+search("Bank")
+
+# Mehrere Wörter
+search("Deutsche Bank AG")
+
+# Teilname
+search("Deutsche") # Findet "Deutsche Bahn", "Deutsche Bank", etc.
+```
+
+**Tipps:**
+
+- Verwenden Sie markante Wörter fĂŒr bessere Ergebnisse
+- Vermeiden Sie sehr hÀufige Wörter wie "GmbH" allein
+- FĂŒgen Sie die Rechtsform fĂŒr spezifischere Ergebnisse hinzu: "Mustermann GmbH"
+
+---
+
+### states
+
+Liste von BundeslÀnder-Codes zum Filtern der Ergebnisse. Siehe [BundeslÀnder-Codes](states.md).
+
+```python
+# Ein Bundesland
+search("Bank", states=["BE"])
+
+# Mehrere BundeslÀnder
+search("Bank", states=["BE", "HH", "BY"])
+
+# Alle BundeslÀnder (Standard - nicht angeben)
+search("Bank")
+```
+
+**Typ:** `List[str]` oder `None`
+
+**GĂŒltige Werte:** `BW`, `BY`, `BE`, `BB`, `HB`, `HH`, `HE`, `MV`, `NI`, `NW`, `RP`, `SL`, `SN`, `ST`, `SH`, `TH`
+
+---
+
+### register_type
+
+Nach Registerart filtern. Siehe [Registerarten](registers.md).
+
+```python
+# Nur Kapitalgesellschaften (GmbH, AG)
+search("Bank", register_type="HRB")
+
+# Nur Personengesellschaften (KG, OHG)
+search("Consulting", register_type="HRA")
+
+# Genossenschaften
+search("Wohnungsbau", register_type="GnR")
+```
+
+**Typ:** `str` oder `None`
+
+**GĂŒltige Werte:** `HRA`, `HRB`, `GnR`, `PR`, `VR`
+
+---
+
+### court
+
+Nach spezifischem Registergericht filtern.
+
+```python
+# Nur Berlin Charlottenburg
+search("Bank", court="Berlin (Charlottenburg)")
+
+# Nur MĂŒnchen
+search("Bank", court="MĂŒnchen")
+```
+
+**Typ:** `str` oder `None`
+
+**Hinweis:** Gerichtsnamen mĂŒssen exakt ĂŒbereinstimmen, wie sie im Register erscheinen.
+
+---
+
+### register_number
+
+Nach spezifischer Registernummer suchen.
+
+```python
+# Nach Registernummer suchen
+search("", register_number="HRB 12345")
+
+# Kombiniert mit Gericht
+search("",
+ court="Berlin (Charlottenburg)",
+ register_number="HRB 44343")
+```
+
+**Typ:** `str` oder `None`
+
+---
+
+### only_active
+
+Nur nach aktuell eingetragenen Unternehmen filtern.
+
+```python
+# Nur aktive Unternehmen
+search("Bank", include_deleted=False)
+
+# Gelöschte/fusionierte einschlieĂen (Standard)
+search("Bank", include_deleted=True)
+```
+
+**Typ:** `bool`
+
+**Standard:** `False`
+
+---
+
+### exact
+
+Exakte NamensĂŒbereinstimmung statt TeilĂŒbereinstimmung erfordern.
+
+```python
+# Exakte Ăbereinstimmung - findet nur "GASAG AG"
+search("GASAG AG", keyword_option="exact")
+
+# TeilĂŒbereinstimmung - findet "GASAG AG", "GASAG Beteiligungs GmbH", etc.
+search("GASAG", exact=False)
+```
+
+**Typ:** `bool`
+
+**Standard:** `False`
+
+---
+
+### similar_sounding
+
+Unternehmen mit Ă€hnlich klingenden Namen einschlieĂen (phonetische Suche).
+
+```python
+# Ăhnliche Namen einschlieĂen (Meyer, Meier, Mayer, etc.)
+search("MĂŒller", similar_sounding=True)
+```
+
+**Typ:** `bool`
+
+**Standard:** `False`
+
+**Hinweis:** Dies kann die Anzahl der Ergebnisse erheblich erhöhen.
+
+---
+
+### use_cache
+
+Ob gecachte Ergebnisse verwendet werden sollen.
+
+```python
+# Cache verwenden (Standard)
+search("Bank", force_refresh=False)
+
+# Immer frische Daten abrufen
+search("Bank", force_refresh=True)
+```
+
+**Typ:** `bool`
+
+**Standard:** `True`
+
+---
+
+## VollstÀndiges Beispiel
+
+```python
+from handelsregister import search
+
+# VollstÀndiges Beispiel mit allen Parametern
+firmen = search(
+ keywords="Bank", # Suche nach "Bank"
+ states=["BE", "HH"], # In Berlin und Hamburg
+ register_type="HRB", # Nur Kapitalgesellschaften
+ court=None, # Beliebiges Gericht
+ register_number=None, # Beliebige Nummer
+ include_deleted=False, # Nur aktive Unternehmen
+ exact=False, # TeilĂŒbereinstimmung OK
+ similar_sounding=False, # Keine phonetische Suche
+ force_refresh=False, # Cache verwenden
+)
+
+print(f"Gefunden: {len(firmen)} Unternehmen")
+```
+
+---
+
+## CLI-Entsprechung
+
+| Python-Parameter | CLI-Option |
+|------------------|------------|
+| `keywords` | `-s, --search` |
+| `states` | `--states` |
+| `register_type` | `--register-type` |
+| `only_active` | `--active-only` |
+| `exact` | `--exact` |
+| `force_refresh=True` | `--no-cache` |
+
+```bash
+handelsregister \
+ -s "Bank" \
+ --states BE,HH \
+ --register-type HRB \
+ --active-only
+```
+
+---
+
+## Siehe auch
+
+- [BundeslĂ€nder-Codes](states.md) â GĂŒltige BundeslĂ€nder-Codes
+- [Registerarten](registers.md) â GĂŒltige Registerarten
+- [Als Library verwenden](../guide/library.md) â Weitere Beispiele
+
diff --git a/docs/reference/parameters.md b/docs/reference/parameters.md
new file mode 100644
index 00000000..0bb237ed
--- /dev/null
+++ b/docs/reference/parameters.md
@@ -0,0 +1,307 @@
+# API Parameters
+
+Complete reference of all parameters for the `search()` function.
+
+## Parameter Overview
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `keywords` | `str` | Required | Search term for company names |
+| `keyword_option` | `KeywordMatch` or `str` | `"all"` | How to match keywords: "all", "min", or "exact" |
+| `states` | `List[State]` or `List[str]` | `None` | Filter by federal states |
+| `register_type` | `RegisterType` or `str` | `None` | Filter by register type |
+| `register_number` | `str` | `None` | Specific register number |
+| `include_deleted` | `bool` | `False` | Include deleted/historical entries |
+| `similar_sounding` | `bool` | `False` | Include similar-sounding names |
+| `results_per_page` | `int` | `100` | Number of results per page (10, 25, 50, 100) |
+| `force_refresh` | `bool` | `False` | Bypass cache and fetch fresh data |
+| `debug` | `bool` | `False` | Enable debug logging |
+
+---
+
+## Parameter Details
+
+### keywords (required)
+
+The main search term. Searches in company names.
+
+```python
+# Single word
+search("Bank")
+
+# Multiple words
+search("Deutsche Bank AG")
+
+# Partial name
+search("Deutsche") # Finds "Deutsche Bahn", "Deutsche Bank", etc.
+```
+
+**Tips:**
+
+- Use distinctive words for better results
+- Avoid very common words like "GmbH" alone
+- Add legal form for more specific results: "Mustermann GmbH"
+
+---
+
+### states
+
+List of state codes to filter results. See [State Codes](states.md).
+
+```python
+from handelsregister import search, State
+
+# Single state (recommended: Enum)
+search("Bank", states=[State.BE])
+
+# Multiple states (recommended: Enums)
+search("Bank", states=[State.BE, State.HH, State.BY])
+
+# String-based API still works
+search("Bank", states=["BE"])
+search("Bank", states=["BE", "HH", "BY"])
+
+# All states (default - don't specify)
+search("Bank")
+```
+
+**Type:** `List[State]` or `List[str]` or `None`
+
+**Valid values:** `BW`, `BY`, `BE`, `BB`, `HB`, `HH`, `HE`, `MV`, `NI`, `NW`, `RP`, `SL`, `SN`, `ST`, `SH`, `TH`
+
+**Recommended:** Use `State` enum for IDE autocomplete: `State.BE`, `State.HH`, etc.
+
+---
+
+### register_type
+
+Filter by register type. See [Register Types](registers.md).
+
+```python
+from handelsregister import search, RegisterType
+
+# Only corporations (GmbH, AG) - recommended: Enum
+search("Bank", register_type=RegisterType.HRB)
+
+# Only partnerships (KG, OHG)
+search("Consulting", register_type=RegisterType.HRA)
+
+# Cooperatives
+search("Wohnungsbau", register_type=RegisterType.GnR)
+
+# String-based API still works
+search("Bank", register_type="HRB")
+```
+
+**Type:** `RegisterType` or `str` or `None`
+
+**Valid values:** `HRA`, `HRB`, `GnR`, `PR`, `VR`
+
+**Recommended:** Use `RegisterType` enum for IDE autocomplete: `RegisterType.HRB`, `RegisterType.HRA`, etc.
+
+---
+
+### keyword_option
+
+How to match keywords in the search.
+
+```python
+from handelsregister import search, KeywordMatch
+
+# All keywords must match (default) - recommended: Enum
+search("Deutsche Bank", keyword_option=KeywordMatch.ALL)
+
+# At least one keyword must match
+search("Deutsche Bank", keyword_option=KeywordMatch.MIN)
+
+# Exact name match
+search("GASAG AG", keyword_option=KeywordMatch.EXACT)
+
+# String-based API still works
+search("Deutsche Bank", keyword_option="all")
+search("GASAG AG", keyword_option="exact")
+```
+
+**Type:** `KeywordMatch` or `str`
+
+**Default:** `"all"` or `KeywordMatch.ALL`
+
+**Valid values:** `"all"` / `KeywordMatch.ALL`, `"min"` / `KeywordMatch.MIN`, `"exact"` / `KeywordMatch.EXACT`
+
+**Recommended:** Use `KeywordMatch` enum for IDE autocomplete: `KeywordMatch.ALL`, `KeywordMatch.EXACT`, etc.
+
+---
+
+### register_number
+
+Search for a specific register number.
+
+```python
+# Find by register number
+search("", register_number="HRB 12345")
+
+# Combined with keywords
+search("GASAG", register_number="HRB 44343")
+```
+
+**Type:** `str` or `None`
+
+---
+
+### include_deleted
+
+Include deleted/historical entries in results.
+
+```python
+# Include deleted entries
+search("Bank", include_deleted=True)
+
+# Only currently registered (default)
+search("Bank", include_deleted=False)
+```
+
+**Type:** `bool`
+
+**Default:** `False`
+
+---
+
+### similar_sounding
+
+Include companies with similar-sounding names (phonetic search).
+
+```python
+# Include similar names (Meyer, Meier, Mayer, etc.)
+search("MĂŒller", similar_sounding=True)
+```
+
+**Type:** `bool`
+
+**Default:** `False`
+
+**Note:** This can significantly increase the number of results.
+
+---
+
+### results_per_page
+
+Number of results to return per page.
+
+```python
+# Get 50 results per page
+search("Bank", results_per_page=50)
+
+# Get maximum results (100)
+search("Bank", results_per_page=100)
+```
+
+**Type:** `int`
+
+**Default:** `100`
+
+**Valid values:** `10`, `25`, `50`, `100`
+
+---
+
+### force_refresh
+
+Bypass cache and fetch fresh data from the website.
+
+```python
+# Use cache (default)
+search("Bank", force_refresh=False)
+
+# Always fetch fresh data
+search("Bank", force_refresh=True)
+```
+
+**Type:** `bool`
+
+**Default:** `False`
+
+---
+
+### debug
+
+Enable debug logging for troubleshooting.
+
+```python
+# Enable debug output
+search("Bank", debug=True)
+```
+
+**Type:** `bool`
+
+**Default:** `False`
+
+---
+
+## Complete Example
+
+```python
+from handelsregister import search, State, KeywordMatch, RegisterType
+
+# Full example with all parameters (recommended: Enums)
+companies = search(
+ keywords="Bank", # Search for "Bank"
+ keyword_option=KeywordMatch.ALL, # All keywords must match
+ states=[State.BE, State.HH], # In Berlin and Hamburg
+ register_type=RegisterType.HRB, # Only corporations
+ register_number=None, # Any number
+ include_deleted=False, # Only active companies
+ similar_sounding=False, # No phonetic search
+ results_per_page=100, # Maximum results
+ force_refresh=False, # Use cache
+ debug=False, # No debug output
+)
+
+# String-based API still works
+companies = search(
+ keywords="Bank",
+ keyword_option="all",
+ states=["BE", "HH"],
+ register_type="HRB",
+ register_number=None,
+ include_deleted=False,
+ similar_sounding=False,
+ results_per_page=100,
+ force_refresh=False,
+ debug=False,
+)
+
+print(f"Found: {len(companies)} companies")
+```
+
+---
+
+## CLI Equivalent
+
+| Python Parameter | CLI Option |
+|-----------------|------------|
+| `keywords` | `-s, --schlagwoerter` |
+| `keyword_option` | `-so, --schlagwortOptionen` |
+| `states` | `--states` |
+| `register_type` | `--register-type` |
+| `register_number` | `--register-number` |
+| `include_deleted` | `--include-deleted` |
+| `similar_sounding` | `--similar-sounding` |
+| `results_per_page` | `--results-per-page` |
+| `force_refresh=True` | `-f, --force` |
+| `debug=True` | `-d, --debug` |
+
+```bash
+handelsregister \
+ -s "Bank" \
+ --states BE,HH \
+ --register-type HRB \
+ --schlagwortOptionen all
+```
+
+---
+
+## See Also
+
+- [State Codes](states.md) â Valid state codes
+- [Register Types](registers.md) â Valid register types
+- [Using as Library](../guide/library.md) â More examples
+
diff --git a/docs/reference/registers.de.md b/docs/reference/registers.de.md
new file mode 100644
index 00000000..9e41c396
--- /dev/null
+++ b/docs/reference/registers.de.md
@@ -0,0 +1,140 @@
+# Registerarten
+
+Diese Tabelle zeigt die verschiedenen Registerarten im deutschen Handelsregistersystem.
+
+## Registerarten-Referenz
+
+| Code | Name | Typische Rechtsformen |
+|------|------|----------------------|
+| `HRA` | Handelsregister Abteilung A | Einzelkaufleute, Personengesellschaften (OHG, KG) |
+| `HRB` | Handelsregister Abteilung B | Kapitalgesellschaften (GmbH, AG, SE, KGaA) |
+| `GnR` | Genossenschaftsregister | Genossenschaften (eG) |
+| `PR` | Partnerschaftsregister | Partnerschaftsgesellschaften (PartG) |
+| `VR` | Vereinsregister | Eingetragene Vereine (e.V.) |
+
+---
+
+## Detaillierte Beschreibungen
+
+### HRA (Abteilung A)
+
+**Handelsregister Abteilung A** enthÀlt:
+
+- **Einzelkaufleute** (e.K., e.Kfm., e.Kfr.)
+- **OHG** (Offene Handelsgesellschaften)
+- **KG** (Kommanditgesellschaften)
+- **GmbH & Co. KG** (Besondere Kommanditgesellschaften)
+- **EWIV** (EuropÀische wirtschaftliche Interessenvereinigungen)
+
+```python
+# Suche nach Personengesellschaften
+firmen = search("KG", register_type="HRA")
+```
+
+### HRB (Abteilung B)
+
+**Handelsregister Abteilung B** enthÀlt:
+
+- **GmbH** (Gesellschaften mit beschrÀnkter Haftung)
+- **AG** (Aktiengesellschaften)
+- **SE** (EuropÀische Gesellschaften)
+- **KGaA** (Kommanditgesellschaften auf Aktien)
+- **UG (haftungsbeschrÀnkt)** (Unternehmergesellschaften)
+
+```python
+# Suche nach Kapitalgesellschaften
+firmen = search("GmbH", register_type="HRB")
+```
+
+### GnR (Genossenschaftsregister)
+
+**Genossenschaftsregister** enthÀlt:
+
+- **eG** (Eingetragene Genossenschaften)
+- **SCE** (EuropÀische Genossenschaften)
+
+```python
+# Suche nach Genossenschaften
+firmen = search("Genossenschaft", register_type="GnR")
+```
+
+### PR (Partnerschaftsregister)
+
+**Partnerschaftsregister** enthÀlt:
+
+- **PartG** (Partnerschaftsgesellschaften)
+- **PartG mbB** (Partnerschaftsgesellschaften mit beschrÀnkter Berufshaftung)
+
+Ăblich fĂŒr RechtsanwĂ€lte, Steuerberater, Ărzte, Architekten.
+
+```python
+# Suche nach Partnerschaftsgesellschaften
+firmen = search("RechtsanwÀlte", register_type="PR")
+```
+
+### VR (Vereinsregister)
+
+**Vereinsregister** enthÀlt:
+
+- **e.V.** (Eingetragene Vereine)
+
+```python
+# Suche nach Vereinen
+firmen = search("Verein", register_type="VR")
+```
+
+---
+
+## Verwendungsbeispiele
+
+### Python
+
+```python
+from handelsregister import search
+
+# Nur HRB (Kapitalgesellschaften)
+kapitalgesellschaften = search("Bank", register_type="HRB")
+
+# Nur HRA (Personengesellschaften)
+personengesellschaften = search("Consulting", register_type="HRA")
+
+# Suche ĂŒber alle Registerarten
+# (register_type nicht angeben)
+alle_arten = search("Mustermann")
+```
+
+### CLI
+
+```bash
+# Nur HRB
+handelsregister -s "Bank" --register-type HRB
+
+# Nur HRA
+handelsregister -s "KG" --register-type HRA
+
+# Genossenschaften
+handelsregister -s "Wohnungsbau" --register-type GnR
+```
+
+---
+
+## Statistiken
+
+UngefÀhre Verteilung der EintrÀge in Deutschland:
+
+| Register | UngefÀhre Anzahl | Anteil |
+|----------|------------------|--------|
+| HRB | ~1.500.000 | ~60% |
+| HRA | ~700.000 | ~28% |
+| GnR | ~20.000 | ~1% |
+| PR | ~15.000 | ~1% |
+| VR | ~250.000 | ~10% |
+
+---
+
+## Siehe auch
+
+- [BundeslĂ€nder-Codes](states.md) â Deutsche BundeslĂ€nder-Codes
+- [Rechtsformen](legal-forms.md) â GmbH, AG, etc.
+- [API-Parameter](parameters.md) â Alle Suchparameter
+
diff --git a/docs/reference/registers.md b/docs/reference/registers.md
new file mode 100644
index 00000000..fdec7433
--- /dev/null
+++ b/docs/reference/registers.md
@@ -0,0 +1,140 @@
+# Register Types
+
+This table shows the different register types available in the German commercial register system.
+
+## Register Type Reference
+
+| Code | German Name | English Name | Typical Legal Forms |
+|------|-------------|--------------|---------------------|
+| `HRA` | Handelsregister Abteilung A | Commercial Register Section A | Sole proprietors, partnerships (OHG, KG) |
+| `HRB` | Handelsregister Abteilung B | Commercial Register Section B | Corporations (GmbH, AG, SE, KGaA) |
+| `GnR` | Genossenschaftsregister | Cooperative Register | Cooperatives (eG) |
+| `PR` | Partnerschaftsregister | Partnership Register | Professional partnerships (PartG) |
+| `VR` | Vereinsregister | Association Register | Registered associations (e.V.) |
+
+---
+
+## Detailed Descriptions
+
+### HRA (Section A)
+
+**Commercial Register Section A** contains:
+
+- **Einzelkaufleute** (Sole proprietors)
+- **OHG** (General partnerships)
+- **KG** (Limited partnerships)
+- **GmbH & Co. KG** (Special limited partnerships)
+- **EWIV** (European Economic Interest Groupings)
+
+```python
+# Search for partnerships
+companies = search("KG", register_type="HRA")
+```
+
+### HRB (Section B)
+
+**Commercial Register Section B** contains:
+
+- **GmbH** (Limited liability companies)
+- **AG** (Stock corporations)
+- **SE** (European companies)
+- **KGaA** (Partnerships limited by shares)
+- **UG (haftungsbeschrÀnkt)** (Mini-GmbH)
+
+```python
+# Search for corporations
+companies = search("GmbH", register_type="HRB")
+```
+
+### GnR (Cooperative Register)
+
+**Cooperative Register** contains:
+
+- **eG** (Registered cooperatives)
+- **SCE** (European cooperatives)
+
+```python
+# Search for cooperatives
+companies = search("Genossenschaft", register_type="GnR")
+```
+
+### PR (Partnership Register)
+
+**Partnership Register** contains:
+
+- **PartG** (Professional partnerships)
+- **PartG mbB** (Professional partnerships with limited liability)
+
+Common for lawyers, accountants, doctors, architects.
+
+```python
+# Search for professional partnerships
+companies = search("RechtsanwÀlte", register_type="PR")
+```
+
+### VR (Association Register)
+
+**Association Register** contains:
+
+- **e.V.** (Registered associations)
+
+```python
+# Search for associations
+companies = search("Verein", register_type="VR")
+```
+
+---
+
+## Usage Examples
+
+### Python
+
+```python
+from handelsregister import search
+
+# Only HRB (corporations)
+corporations = search("Bank", register_type="HRB")
+
+# Only HRA (partnerships)
+partnerships = search("Consulting", register_type="HRA")
+
+# Search across register types
+# (don't specify register_type)
+all_types = search("Mustermann")
+```
+
+### CLI
+
+```bash
+# Only HRB
+handelsregister -s "Bank" --register-type HRB
+
+# Only HRA
+handelsregister -s "KG" --register-type HRA
+
+# Cooperatives
+handelsregister -s "Wohnungsbau" --register-type GnR
+```
+
+---
+
+## Statistics
+
+Approximate distribution of entries in Germany:
+
+| Register | Approximate Entries | Percentage |
+|----------|---------------------|------------|
+| HRB | ~1,500,000 | ~60% |
+| HRA | ~700,000 | ~28% |
+| GnR | ~20,000 | ~1% |
+| PR | ~15,000 | ~1% |
+| VR | ~250,000 | ~10% |
+
+---
+
+## See Also
+
+- [State Codes](states.md) â German state codes
+- [Legal Forms](legal-forms.md) â GmbH, AG, etc.
+- [API Parameters](parameters.md) â All search parameters
+
diff --git a/docs/reference/states.de.md b/docs/reference/states.de.md
new file mode 100644
index 00000000..f58b53ef
--- /dev/null
+++ b/docs/reference/states.de.md
@@ -0,0 +1,114 @@
+# BundeslÀnder-Codes
+
+Diese Tabelle zeigt die ISO 3166-2:DE Codes fĂŒr deutsche BundeslĂ€nder, die im `states`-Parameter verwendet werden.
+
+## BundeslÀnder-Referenz
+
+| Code | Bundesland | Hauptstadt |
+|------|------------|------------|
+| `BW` | Baden-WĂŒrttemberg | Stuttgart |
+| `BY` | Bayern | MĂŒnchen |
+| `BE` | Berlin | Berlin |
+| `BB` | Brandenburg | Potsdam |
+| `HB` | Bremen | Bremen |
+| `HH` | Hamburg | Hamburg |
+| `HE` | Hessen | Wiesbaden |
+| `MV` | Mecklenburg-Vorpommern | Schwerin |
+| `NI` | Niedersachsen | Hannover |
+| `NW` | Nordrhein-Westfalen | DĂŒsseldorf |
+| `RP` | Rheinland-Pfalz | Mainz |
+| `SL` | Saarland | SaarbrĂŒcken |
+| `SN` | Sachsen | Dresden |
+| `ST` | Sachsen-Anhalt | Magdeburg |
+| `SH` | Schleswig-Holstein | Kiel |
+| `TH` | ThĂŒringen | Erfurt |
+
+---
+
+## Verwendungsbeispiele
+
+### Python
+
+```python
+from handelsregister import search
+
+# Suche in Berlin
+firmen = search("Bank", states=["BE"])
+
+# Suche in mehreren BundeslÀndern
+firmen = search("Bank", states=["BE", "HH", "BY"])
+
+# Alle GroĂstĂ€dte
+grossstaedte = ["BE", "HH", "BY", "NW", "HE"]
+firmen = search("Bank", states=grossstaedte)
+```
+
+### CLI
+
+```bash
+# Ein Bundesland
+handelsregister -s "Bank" --states BE
+
+# Mehrere BundeslÀnder
+handelsregister -s "Bank" --states BE,HH,BY
+```
+
+---
+
+## Bundesland-Gruppen
+
+### Stadtstaaten
+
+```python
+STADTSTAATEN = ["BE", "HH", "HB"]
+```
+
+### Ostdeutschland (ehemalige DDR)
+
+```python
+OSTDEUTSCHE_LAENDER = ["BE", "BB", "MV", "SN", "ST", "TH"]
+```
+
+### Westdeutschland
+
+```python
+WESTDEUTSCHE_LAENDER = ["BW", "BY", "HB", "HH", "HE", "NI", "NW", "RP", "SL", "SH"]
+```
+
+### SĂŒddeutschland
+
+```python
+SUEDDEUTSCHE_LAENDER = ["BW", "BY"]
+```
+
+### Norddeutschland
+
+```python
+NORDDEUTSCHE_LAENDER = ["HB", "HH", "MV", "NI", "SH"]
+```
+
+---
+
+## Karte
+
+```
+ SH
+ HH
+HB MV
+ NI BB BE
+ ST
+ NW SN
+ TH
+ HE
+ RP BY
+SL BW
+```
+
+---
+
+## Siehe auch
+
+- [Registerarten](registers.md) â HRA, HRB, etc.
+- [Rechtsformen](legal-forms.md) â GmbH, AG, etc.
+- [API-Parameter](parameters.md) â Alle Suchparameter
+
diff --git a/docs/reference/states.md b/docs/reference/states.md
new file mode 100644
index 00000000..da6f4fb3
--- /dev/null
+++ b/docs/reference/states.md
@@ -0,0 +1,114 @@
+# State Codes
+
+This table shows the ISO 3166-2:DE codes for German federal states used in the `states` parameter.
+
+## State Code Reference
+
+| Code | State (German) | State (English) |
+|------|----------------|-----------------|
+| `BW` | Baden-WĂŒrttemberg | Baden-WĂŒrttemberg |
+| `BY` | Bayern | Bavaria |
+| `BE` | Berlin | Berlin |
+| `BB` | Brandenburg | Brandenburg |
+| `HB` | Bremen | Bremen |
+| `HH` | Hamburg | Hamburg |
+| `HE` | Hessen | Hesse |
+| `MV` | Mecklenburg-Vorpommern | Mecklenburg-Western Pomerania |
+| `NI` | Niedersachsen | Lower Saxony |
+| `NW` | Nordrhein-Westfalen | North Rhine-Westphalia |
+| `RP` | Rheinland-Pfalz | Rhineland-Palatinate |
+| `SL` | Saarland | Saarland |
+| `SN` | Sachsen | Saxony |
+| `ST` | Sachsen-Anhalt | Saxony-Anhalt |
+| `SH` | Schleswig-Holstein | Schleswig-Holstein |
+| `TH` | ThĂŒringen | Thuringia |
+
+---
+
+## Usage Examples
+
+### Python
+
+```python
+from handelsregister import search
+
+# Search in Berlin
+companies = search("Bank", states=["BE"])
+
+# Search in multiple states
+companies = search("Bank", states=["BE", "HH", "BY"])
+
+# All major cities
+major_cities = ["BE", "HH", "BY", "NW", "HE"]
+companies = search("Bank", states=major_cities)
+```
+
+### CLI
+
+```bash
+# Single state
+handelsregister -s "Bank" --states BE
+
+# Multiple states
+handelsregister -s "Bank" --states BE,HH,BY
+```
+
+---
+
+## State Groups
+
+### City-States
+
+```python
+CITY_STATES = ["BE", "HH", "HB"]
+```
+
+### Eastern Germany (former GDR)
+
+```python
+EASTERN_STATES = ["BE", "BB", "MV", "SN", "ST", "TH"]
+```
+
+### Western Germany
+
+```python
+WESTERN_STATES = ["BW", "BY", "HB", "HH", "HE", "NI", "NW", "RP", "SL", "SH"]
+```
+
+### Southern Germany
+
+```python
+SOUTHERN_STATES = ["BW", "BY"]
+```
+
+### Northern Germany
+
+```python
+NORTHERN_STATES = ["HB", "HH", "MV", "NI", "SH"]
+```
+
+---
+
+## Map
+
+```
+ SH
+ HH
+HB MV
+ NI BB BE
+ ST
+ NW SN
+ TH
+ HE
+ RP BY
+SL BW
+```
+
+---
+
+## See Also
+
+- [Register Types](registers.md) â HRA, HRB, etc.
+- [Legal Forms](legal-forms.md) â GmbH, AG, etc.
+- [API Parameters](parameters.md) â All search parameters
+
diff --git a/handelsregister.py b/handelsregister.py
index 03ccc1af..eb658b61 100755
--- a/handelsregister.py
+++ b/handelsregister.py
@@ -1,221 +1,27 @@
#!/usr/bin/env python3
"""
-bundesAPI/handelsregister is the command-line interface for the shared register of companies portal for the German federal states.
-You can query, download, automate and much more, without using a web browser.
-"""
-
-import argparse
-import tempfile
-import mechanize
-import re
-import pathlib
-import sys
-from bs4 import BeautifulSoup
-import urllib.parse
-
-# Dictionaries to map arguments to values
-schlagwortOptionen = {
- "all": 1,
- "min": 2,
- "exact": 3
-}
-
-class HandelsRegister:
- def __init__(self, args):
- self.args = args
- self.browser = mechanize.Browser()
-
- self.browser.set_debug_http(args.debug)
- self.browser.set_debug_responses(args.debug)
- # self.browser.set_debug_redirects(True)
-
- self.browser.set_handle_robots(False)
- self.browser.set_handle_equiv(True)
- self.browser.set_handle_gzip(True)
- self.browser.set_handle_refresh(False)
- self.browser.set_handle_redirect(True)
- self.browser.set_handle_referer(True)
-
- self.browser.addheaders = [
- (
- "User-Agent",
- "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.5 Safari/605.1.15",
- ),
- ( "Accept-Language", "en-GB,en;q=0.9" ),
- ( "Accept-Encoding", "gzip, deflate, br" ),
- (
- "Accept",
- "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
- ),
- ( "Connection", "keep-alive" ),
- ]
-
- self.cachedir = pathlib.Path(tempfile.gettempdir()) / "handelsregister_cache"
- self.cachedir.mkdir(parents=True, exist_ok=True)
-
- def open_startpage(self):
- self.browser.open("https://www.handelsregister.de", timeout=10)
-
- def companyname2cachename(self, companyname):
- return self.cachedir / companyname
-
- def search_company(self):
- cachename = self.companyname2cachename(self.args.schlagwoerter)
- if self.args.force==False and cachename.exists():
- with open(cachename, "r") as f:
- html = f.read()
- if not self.args.json:
- print("return cached content for %s" % self.args.schlagwoerter)
- else:
- # TODO implement token bucket to abide by rate limit
- # Use an atomic counter: https://gist.github.com/benhoyt/8c8a8d62debe8e5aa5340373f9c509c7
- self.browser.select_form(name="naviForm")
- self.browser.form.new_control('hidden', 'naviForm:erweiterteSucheLink', {'value': 'naviForm:erweiterteSucheLink'})
- self.browser.form.new_control('hidden', 'target', {'value': 'erweiterteSucheLink'})
- response_search = self.browser.submit()
-
- if self.args.debug == True:
- print(self.browser.title())
-
- self.browser.select_form(name="form")
-
- self.browser["form:schlagwoerter"] = self.args.schlagwoerter
- so_id = schlagwortOptionen.get(self.args.schlagwortOptionen)
-
- self.browser["form:schlagwortOptionen"] = [str(so_id)]
+Compatibility shim for backward compatibility.
- response_result = self.browser.submit()
+This file maintains backward compatibility with the old single-file structure.
+All imports are re-exported from the new package structure.
- if self.args.debug == True:
- print(self.browser.title())
-
- html = response_result.read().decode("utf-8")
- with open(cachename, "w") as f:
- f.write(html)
-
- # TODO catch the situation if there's more than one company?
- # TODO get all documents attached to the exact company
- # TODO parse useful information out of the PDFs
- return get_companies_in_searchresults(html)
-
-
-
-def parse_result(result):
- cells = []
- for cellnum, cell in enumerate(result.find_all('td')):
- cells.append(cell.text.strip())
- d = {}
- d['court'] = cells[1]
-
- # Extract register number: HRB, HRA, VR, GnR followed by numbers (e.g. HRB 12345, VR 6789)
- # Also capture suffix letter if present (e.g. HRB 12345 B), but avoid matching start of words (e.g. " Formerly")
- reg_match = re.search(r'(HRA|HRB|GnR|VR|PR)\s*\d+(\s+[A-Z])?(?!\w)', d['court'])
- d['register_num'] = reg_match.group(0) if reg_match else None
-
- d['name'] = cells[2]
- d['state'] = cells[3]
- d['status'] = cells[4].strip() # Original value for backward compatibility
- d['statusCurrent'] = cells[4].strip().upper().replace(' ', '_') # Transformed value
-
- # Ensure consistent register number suffixes (e.g. ' B' for Berlin HRB, ' HB' for Bremen) which might be implicit
- if d['register_num']:
- suffix_map = {
- 'Berlin': {'HRB': ' B'},
- 'Bremen': {'HRA': ' HB', 'HRB': ' HB', 'GnR': ' HB', 'VR': ' HB', 'PR': ' HB'}
- }
- reg_type = d['register_num'].split()[0]
- suffix = suffix_map.get(d['state'], {}).get(reg_type)
- if suffix and not d['register_num'].endswith(suffix):
- d['register_num'] += suffix
- d['documents'] = cells[5] # todo: get the document links
- d['history'] = []
- hist_start = 8
-
- for i in range(hist_start, len(cells), 3):
- if i + 1 >= len(cells):
- break
- if "Branches" in cells[i] or "Niederlassungen" in cells[i]:
- break
- d['history'].append((cells[i], cells[i+1])) # (name, location)
-
- return d
-
-def pr_company_info(c):
- for tag in ('name', 'court', 'register_num', 'district', 'state', 'statusCurrent'):
- print('%s: %s' % (tag, c.get(tag, '-')))
- print('history:')
- for name, loc in c.get('history'):
- print(name, loc)
-
-def get_companies_in_searchresults(html):
- soup = BeautifulSoup(html, 'html.parser')
- grid = soup.find('table', role='grid')
-
- results = []
- for result in grid.find_all('tr'):
- a = result.get('data-ri')
- if a is not None:
- index = int(a)
-
- d = parse_result(result)
- results.append(d)
- return results
-
-def parse_args():
- parser = argparse.ArgumentParser(description='A handelsregister CLI')
- parser.add_argument(
- "-d",
- "--debug",
- help="Enable debug mode and activate logging",
- action="store_true"
- )
- parser.add_argument(
- "-f",
- "--force",
- help="Force a fresh pull and skip the cache",
- action="store_true"
- )
- parser.add_argument(
- "-s",
- "--schlagwoerter",
- help="Search for the provided keywords",
- required=True,
- default="Gasag AG" # TODO replace default with a generic search term
- )
- parser.add_argument(
- "-so",
- "--schlagwortOptionen",
- help="Keyword options: all=contain all keywords; min=contain at least one keyword; exact=contain the exact company name.",
- choices=["all", "min", "exact"],
- default="all"
- )
- parser.add_argument(
- "-j",
- "--json",
- help="Return response as JSON",
- action="store_true"
- )
- args = parser.parse_args()
+DEPRECATED: This file will be removed in a future version.
+Please update your imports to use the new package structure:
+ from handelsregister import search, HandelsRegister, SearchOptions
+"""
+from __future__ import annotations
- # Enable debugging if wanted
- if args.debug == True:
- import logging
- logger = logging.getLogger("mechanize")
- logger.addHandler(logging.StreamHandler(sys.stdout))
- logger.setLevel(logging.DEBUG)
+import warnings
- return args
+# Issue deprecation warning
+warnings.warn(
+ "Importing from handelsregister.py directly is deprecated. "
+ "Please use 'from handelsregister import ...' instead. "
+ "The old single-file structure will be removed in a future version.",
+ DeprecationWarning,
+ stacklevel=2,
+)
-if __name__ == "__main__":
- import json
- args = parse_args()
- h = HandelsRegister(args)
- h.open_startpage()
- companies = h.search_company()
- if companies is not None:
- if args.json:
- print(json.dumps(companies))
- else:
- for c in companies:
- pr_company_info(c)
+# Re-export everything from the new package structure
+from handelsregister import * # noqa: F403, E402
diff --git a/handelsregister/__init__.py b/handelsregister/__init__.py
new file mode 100644
index 00000000..8f7f9973
--- /dev/null
+++ b/handelsregister/__init__.py
@@ -0,0 +1,116 @@
+"""Python client for the German Handelsregister (commercial register).
+
+This package provides both a CLI tool and a library interface to search the
+Handelsregister portal without using a browser. Built as part of the bundesAPI
+initiative to make German government data more accessible.
+"""
+
+from __future__ import annotations
+
+# Import all public API components for backward compatibility
+from .cache import SearchCache
+
+# Import public API functions
+from .cli import get_details, pr_company_details, pr_company_info, search, search_batch
+from .client import HandelsRegister
+from .constants import (
+ KEYWORD_OPTIONS,
+ REGISTER_TYPES,
+ RESULTS_PER_PAGE_OPTIONS,
+ STATE_CODES,
+ SUFFIX_MAP,
+ KeywordMatch,
+ RegisterType,
+ State,
+ build_url,
+ schlagwortOptionen,
+)
+from .exceptions import (
+ CacheError,
+ FormError,
+ HandelsregisterError,
+ NetworkError,
+ ParseError,
+ PartialResultError,
+)
+from .models import (
+ Address,
+ CacheEntry,
+ Company,
+ CompanyDetails,
+ HistoryEntry,
+ Owner,
+ Representative,
+ SearchOptions,
+)
+from .parser import (
+ DetailsParser,
+ ResultParser,
+ get_companies_in_searchresults,
+ parse_result,
+)
+from .settings import (
+ BASE_URL,
+ DEFAULT_CACHE_TTL_SECONDS,
+ DETAILS_CACHE_TTL_SECONDS,
+ MAX_RETRIES,
+ RATE_LIMIT_CALLS,
+ RATE_LIMIT_PERIOD,
+ REQUEST_TIMEOUT,
+ RETRY_WAIT_MAX,
+ RETRY_WAIT_MIN,
+ Settings,
+ settings,
+)
+
+# Package metadata
+__version__ = "0.3.0"
+__all__ = [
+ "BASE_URL",
+ "DEFAULT_CACHE_TTL_SECONDS",
+ "DETAILS_CACHE_TTL_SECONDS",
+ "KEYWORD_OPTIONS",
+ "KeywordMatch",
+ "MAX_RETRIES",
+ "RATE_LIMIT_CALLS",
+ "RATE_LIMIT_PERIOD",
+ "RegisterType",
+ "REGISTER_TYPES",
+ "REQUEST_TIMEOUT",
+ "RESULTS_PER_PAGE_OPTIONS",
+ "RETRY_WAIT_MAX",
+ "RETRY_WAIT_MIN",
+ "State",
+ "STATE_CODES",
+ "SUFFIX_MAP",
+ # Main classes
+ "Address",
+ "CacheEntry",
+ "CacheError",
+ "Company",
+ "CompanyDetails",
+ "DetailsParser",
+ "FormError",
+ "HandelsRegister",
+ "HandelsregisterError",
+ "HistoryEntry",
+ "NetworkError",
+ "Owner",
+ "ParseError",
+ "PartialResultError",
+ "Representative",
+ "ResultParser",
+ "SearchCache",
+ "SearchOptions",
+ "Settings",
+ "build_url",
+ "get_companies_in_searchresults",
+ "get_details",
+ "parse_result",
+ "pr_company_details",
+ "pr_company_info",
+ "schlagwortOptionen",
+ "search",
+ "search_batch",
+ "settings",
+]
diff --git a/handelsregister/cache.py b/handelsregister/cache.py
new file mode 100644
index 00000000..1144b9a7
--- /dev/null
+++ b/handelsregister/cache.py
@@ -0,0 +1,148 @@
+"""Caching layer using DiskCache for the Handelsregister package."""
+
+import hashlib
+import logging
+import pathlib
+import tempfile
+from typing import Optional
+
+import diskcache
+
+from .settings import DEFAULT_CACHE_TTL_SECONDS, DETAILS_CACHE_TTL_SECONDS, settings
+
+logger = logging.getLogger(__name__)
+
+
+class SearchCache:
+ """Caches search results and company details using DiskCache.
+
+ Uses DiskCache for efficient, thread-safe caching with automatic TTL
+ expiration. Different TTLs for search results (1h default) vs details
+ (24h default) since details change less frequently.
+ """
+
+ def __init__(
+ self,
+ cache_dir: Optional[pathlib.Path] = None,
+ ttl_seconds: int = DEFAULT_CACHE_TTL_SECONDS,
+ details_ttl_seconds: int = DETAILS_CACHE_TTL_SECONDS,
+ ) -> None:
+ """Initialize the cache.
+
+ Args:
+ cache_dir: Directory to store cache files. Defaults to settings.cache_dir
+ or temp directory if not configured.
+ ttl_seconds: Time-to-live for search result cache entries in seconds.
+ details_ttl_seconds: Time-to-live for details cache entries in seconds.
+ """
+ self.ttl_seconds = ttl_seconds
+ self.details_ttl_seconds = details_ttl_seconds
+
+ # Use provided cache_dir, settings.cache_dir, or temp directory
+ if cache_dir is not None:
+ self.cache_dir = cache_dir
+ elif settings.cache_dir:
+ self.cache_dir = pathlib.Path(settings.cache_dir)
+ else:
+ self.cache_dir = pathlib.Path(tempfile.gettempdir()) / "handelsregister_cache"
+ # Initialize DiskCache with size limit (500MB default)
+ self._cache = diskcache.Cache(
+ str(self.cache_dir),
+ size_limit=500 * 1024 * 1024,
+ )
+
+ def _get_cache_key(self, query: str, options: str) -> str:
+ """Generate a safe cache key by hashing the query parameters."""
+ key_data = f"{query}|{options}"
+ return hashlib.sha256(key_data.encode("utf-8")).hexdigest()
+
+ def _get_cache_path(self, query: str, options: str) -> pathlib.Path:
+ """Get the cache file path for a query (for backward compatibility)."""
+ cache_key = self._get_cache_key(query, options)
+ return self.cache_dir / f"{cache_key}.json"
+
+ def get(self, query: str, options: str) -> Optional[str]:
+ """Returns cached HTML if available and not expired.
+
+ Args:
+ query: Search query string (or cache key for details).
+ options: Search options string.
+
+ Returns:
+ Cached HTML content, or None if not cached or expired.
+
+ DiskCache handles expiration automatically based on the TTL set
+ when the entry was stored.
+ """
+ cache_key = self._get_cache_key(query, options)
+ return self._cache.get(cache_key, default=None)
+
+ def set(self, query: str, options: str, html: str) -> None:
+ """Caches HTML content with automatic TTL.
+
+ Args:
+ query: Search query string.
+ options: Search options string.
+ html: HTML content to cache.
+ """
+ cache_key = self._get_cache_key(query, options)
+ # Use longer TTL for details cache
+ ttl = self.details_ttl_seconds if query.startswith("details:") else self.ttl_seconds
+ try:
+ self._cache.set(cache_key, html, expire=ttl)
+ except Exception as e:
+ logger.warning("Failed to write cache: %s", e)
+
+ def clear(self, details_only: bool = False) -> int:
+ """Deletes all cache entries.
+
+ Args:
+ details_only: If True, only delete details cache entries.
+ Note: With DiskCache this clears all entries as we
+ cannot efficiently filter by key prefix.
+
+ Returns:
+ Number of entries deleted.
+ """
+ if details_only:
+ # For details_only, we need to iterate and delete matching keys
+ count = 0
+ for key in list(self._cache):
+ # Keys starting with details prefix have "details:" in query
+ # Since we hash keys, we need to track this differently
+ # For simplicity, we just clear all when details_only is True
+ try:
+ del self._cache[key]
+ count += 1
+ except KeyError:
+ pass
+ return count
+ count = len(self._cache)
+ self._cache.clear()
+ return count
+
+ def get_stats(self) -> dict:
+ """Returns cache statistics.
+
+ Returns:
+ Dict with total_files, search_files, details_files, and
+ total_size_bytes.
+ """
+ return {
+ "total_files": len(self._cache),
+ "search_files": len(self._cache), # DiskCache doesn't distinguish
+ "details_files": 0, # Would need metadata tracking
+ "total_size_bytes": self._cache.volume(),
+ }
+
+ def close(self) -> None:
+ """Closes the cache connection."""
+ self._cache.close()
+
+ def __enter__(self) -> "SearchCache":
+ """Context manager entry."""
+ return self
+
+ def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+ """Context manager exit."""
+ self.close()
diff --git a/handelsregister/cli.py b/handelsregister/cli.py
new file mode 100644
index 00000000..a4836668
--- /dev/null
+++ b/handelsregister/cli.py
@@ -0,0 +1,523 @@
+"""Command-line interface for the Handelsregister package."""
+
+import argparse
+import json
+import logging
+import sys
+from typing import Literal, Optional, Union
+
+from .client import HandelsRegister
+from .constants import (
+ REGISTER_TYPES,
+ RESULTS_PER_PAGE_OPTIONS,
+ STATE_CODES,
+ KeywordMatch,
+ RegisterType,
+ State,
+)
+from .exceptions import (
+ CacheError,
+ FormError,
+ HandelsregisterError,
+ NetworkError,
+ ParseError,
+)
+from .models import Company, CompanyDetails, SearchOptions
+
+
+def pr_company_info(c: Company) -> None:
+ """Prints company information to stdout.
+
+ Args:
+ c: Company object containing company information.
+ """
+ print(f"name: {c.name}")
+ print(f"court: {c.court}")
+ print(f"register_num: {c.register_num or '-'}")
+ print(f"state: {c.state}")
+ print(f"statusCurrent: {c.status_normalized or '-'}")
+ print(f"documents: {c.documents}")
+ print("history:")
+ for entry in c.history:
+ print(f"{entry.name} {entry.location}")
+
+
+def parse_args() -> argparse.Namespace:
+ """Parses command-line arguments.
+
+ Returns:
+ Parsed arguments namespace.
+ """
+ state_codes_help = ", ".join(f"{k}={v}" for k, v in sorted(STATE_CODES.items()))
+
+ parser = argparse.ArgumentParser(
+ description="A handelsregister CLI for the German commercial register",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=f"""
+Examples:
+ %(prog)s -s "Deutsche Bahn" -so all
+ %(prog)s -s "GASAG AG" -so exact --json
+ %(prog)s -s "Munich" --states BE,BY --register-type HRB
+ %(prog)s -s "Bank" --include-deleted --similar-sounding
+
+State codes: {state_codes_help}
+ """,
+ )
+
+ # General options
+ parser.add_argument(
+ "-d", "--debug", help="Enable debug mode and activate logging", action="store_true"
+ )
+ parser.add_argument(
+ "-f", "--force", help="Force a fresh pull and skip the cache", action="store_true"
+ )
+ parser.add_argument("-j", "--json", help="Return response as JSON", action="store_true")
+
+ # Search parameters
+ search_group = parser.add_argument_group("Search parameters")
+ search_group.add_argument(
+ "-s",
+ "--schlagwoerter",
+ help="Search for the provided keywords (required)",
+ required=True,
+ metavar="KEYWORDS",
+ )
+ search_group.add_argument(
+ "-so",
+ "--schlagwortOptionen",
+ help="Keyword matching: all=all keywords; min=at least one; exact=exact name",
+ choices=["all", "min", "exact"],
+ default="all",
+ metavar="OPTION",
+ )
+ search_group.add_argument(
+ "--states",
+ help="Comma-separated list of state codes to filter by (e.g., BE,BY,HH)",
+ metavar="CODES",
+ )
+ search_group.add_argument(
+ "--register-type",
+ dest="register_type",
+ help="Filter by register type",
+ choices=REGISTER_TYPES,
+ metavar="TYPE",
+ )
+ search_group.add_argument(
+ "--register-number",
+ dest="register_number",
+ help="Search for a specific register number",
+ metavar="NUMBER",
+ )
+ search_group.add_argument(
+ "--include-deleted",
+ dest="include_deleted",
+ help="Include deleted/historical entries in results",
+ action="store_true",
+ )
+ search_group.add_argument(
+ "--similar-sounding",
+ dest="similar_sounding",
+ help="Use phonetic/similarity search (Kölner Phonetik)",
+ action="store_true",
+ )
+ search_group.add_argument(
+ "--results-per-page",
+ dest="results_per_page",
+ help="Number of results per page",
+ type=int,
+ choices=RESULTS_PER_PAGE_OPTIONS,
+ default=100,
+ metavar="N",
+ )
+
+ # Detail options
+ detail_group = parser.add_argument_group("Detail options")
+ detail_group.add_argument(
+ "--details", help="Fetch detailed information for each company result", action="store_true"
+ )
+ detail_group.add_argument(
+ "--detail-type",
+ dest="detail_type",
+ help="Type of details to fetch: SI=structured, AD=printout, UT=owners",
+ choices=["SI", "AD", "UT"],
+ default="SI",
+ metavar="TYPE",
+ )
+
+ args = parser.parse_args()
+
+ if args.debug:
+ logging.basicConfig(
+ level=logging.DEBUG,
+ format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+ stream=sys.stdout,
+ )
+ mechanize_logger = logging.getLogger("mechanize")
+ mechanize_logger.setLevel(logging.DEBUG)
+ else:
+ logging.basicConfig(level=logging.WARNING, format="%(levelname)s: %(message)s")
+
+ return args
+
+
+def search(
+ keywords: str,
+ keyword_option: Union[KeywordMatch, Literal["all", "min", "exact"]] = "all",
+ states: Optional[list[Union[State, str]]] = None,
+ register_type: Optional[Union[RegisterType, Literal["HRA", "HRB", "GnR", "PR", "VR"]]] = None,
+ register_number: Optional[str] = None,
+ include_deleted: bool = False,
+ similar_sounding: bool = False,
+ results_per_page: Literal[10, 25, 50, 100] = 100,
+ force_refresh: bool = False,
+ debug: bool = False,
+) -> list[Company]:
+ """Durchsucht das Handelsregister nach Unternehmen.
+
+ Dies ist die Haupt-API fĂŒr die programmatische Nutzung des Packages.
+
+ Args:
+ keywords: Suchbegriffe (erforderlich).
+ keyword_option: Suchmodus - "all" (alle Begriffe), "min" (mindestens einer),
+ "exact" (exakter Firmenname). Standard: "all".
+ Can be KeywordMatch enum or string.
+ states: Liste von Bundesland-Codes zum Filtern (z.B. ["BE", "BY", "HH"]).
+ Can be State enum values or strings.
+ register_type: Registerart-Filter (HRA, HRB, GnR, PR, VR).
+ Can be RegisterType enum or string.
+ register_number: Spezifische Registernummer suchen.
+ include_deleted: Auch gelöschte EintrÀge anzeigen.
+ similar_sounding: Phonetische Suche (Kölner Phonetik) verwenden.
+ results_per_page: Ergebnisse pro Seite (10, 25, 50, 100). Standard: 100.
+ force_refresh: Cache ignorieren und neue Daten abrufen.
+ debug: Debug-Logging aktivieren.
+
+ Returns:
+ Liste von Dictionaries mit Unternehmensdaten. Jedes Dictionary enthÀlt:
+ - name: Firmenname
+ - court: Registergericht
+ - register_num: Registernummer (z.B. "HRB 12345 B")
+ - state: Bundesland
+ - status: Aktueller Status
+ - statusCurrent: Normalisierter Status (z.B. "CURRENTLY_REGISTERED")
+ - documents: VerfĂŒgbare Dokumente
+ - history: Liste von (Name, Ort) Tupeln mit historischen EintrÀgen
+
+ Raises:
+ NetworkError: Bei Netzwerkfehlern.
+ FormError: Wenn die Website-Struktur sich geÀndert hat.
+ ParseError: Bei Fehlern beim Parsen der Ergebnisse.
+
+ Beispiel:
+ >>> from handelsregister import search, State, KeywordMatch, RegisterType
+ >>>
+ >>> # Einfache Suche
+ >>> companies = search("Deutsche Bahn")
+ >>>
+ >>> # Mit Filtern (string-basiert)
+ >>> banks = search("Bank", states=["BE", "HH"], register_type="HRB")
+ >>>
+ >>> # Mit Filtern (enum-basiert, mit AutovervollstÀndigung)
+ >>> banks = search("Bank", states=[State.BE, State.HH], register_type=RegisterType.HRB)
+ >>>
+ >>> for company in banks:
+ ... print(f"{company['name']} - {company['register_num']}")
+ """
+ # Configure logging if debug mode
+ if debug:
+ logging.basicConfig(
+ level=logging.DEBUG, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+ )
+
+ # Build args namespace for HandelsRegister
+ # Convert Enums to strings for backward compatibility
+ keyword_option_str = (
+ keyword_option.value if isinstance(keyword_option, KeywordMatch) else keyword_option
+ )
+ states_str = (
+ ",".join(s.value if isinstance(s, State) else s for s in states) if states else None
+ )
+ register_type_str = (
+ register_type.value if isinstance(register_type, RegisterType) else register_type
+ )
+
+ args = argparse.Namespace(
+ debug=debug,
+ force=force_refresh,
+ json=False,
+ schlagwoerter=keywords,
+ schlagwortOptionen=keyword_option_str,
+ states=states_str,
+ register_type=register_type_str,
+ register_number=register_number,
+ include_deleted=include_deleted,
+ similar_sounding=similar_sounding,
+ results_per_page=results_per_page,
+ )
+
+ hr = HandelsRegister(args)
+ hr.open_startpage()
+ return hr.search_company()
+
+
+def search_batch(
+ keywords_list: list[str],
+ states: Optional[list[Union[State, str]]] = None,
+ register_type: Optional[Union[RegisterType, str]] = None,
+ show_progress: Optional[bool] = None,
+ continue_on_error: bool = True,
+ raise_partial: bool = False,
+ **kwargs,
+) -> dict[str, list[Company]]:
+ """Performs multiple searches with progress indicators and error recovery.
+
+ Useful for batch processing multiple keywords or search terms.
+
+ Args:
+ keywords_list: List of keywords to search for.
+ states: List of state codes to filter by.
+ register_type: Register type filter.
+ show_progress: Show progress bar (auto-detected if None).
+ continue_on_error: Continue processing other keywords if one fails.
+ raise_partial: Raise PartialResultError if any searches fail.
+ **kwargs: Additional arguments passed to search().
+
+ Returns:
+ Dictionary mapping keywords to their search results.
+
+ Raises:
+ PartialResultError: If raise_partial=True and some searches failed.
+
+ Example:
+ >>> from handelsregister import search_batch, PartialResultError
+ >>>
+ >>> keywords = ["Bank", "Versicherung", "Immobilien"]
+ >>> try:
+ ... results = search_batch(keywords, states=["BE", "HH"])
+ ... except PartialResultError as e:
+ ... print(f"Some searches failed: {len(e.failed)}")
+ ... results = e.successful
+ >>> for keyword, companies in results.items():
+ ... print(f"{keyword}: {len(companies)} companies")
+ """
+ import logging
+ import sys
+
+ from tqdm import tqdm
+
+ from .exceptions import HandelsregisterError, PartialResultError
+
+ logger = logging.getLogger(__name__)
+
+ # Auto-detect if we should show progress
+ if show_progress is None:
+ show_progress = sys.stdout.isatty() and len(keywords_list) > 1
+
+ results: dict[str, list[Company]] = {}
+ failed: list[tuple[str, Exception]] = []
+ iterator = tqdm(keywords_list, desc="Searching", unit="keyword", disable=not show_progress)
+
+ for keyword in iterator:
+ if show_progress:
+ iterator.set_postfix(keyword=keyword[:30])
+ try:
+ results[keyword] = search(keyword, states=states, register_type=register_type, **kwargs)
+ except HandelsregisterError as e:
+ logger.exception("Failed to search for '%s'", keyword)
+ if not continue_on_error:
+ raise
+ failed.append((keyword, e))
+ results[keyword] = []
+ except Exception as e:
+ # Unexpected error
+ logger.exception("Unexpected error searching for '%s'", keyword)
+ if not continue_on_error:
+ raise
+ failed.append((keyword, e))
+ results[keyword] = []
+
+ # Raise partial result error if requested and there were failures
+ if raise_partial and failed:
+ error_msg = (
+ f"Batch search completed with {len(failed)} failures out of {len(keywords_list)} total"
+ )
+ raise PartialResultError(
+ error_msg,
+ successful=results,
+ failed=failed,
+ )
+
+ return results
+
+
+def get_details(
+ company: Company,
+ detail_type: Literal["SI", "AD", "UT", "CD", "HD", "VĂ"] = "SI",
+ force_refresh: bool = False,
+ debug: bool = False,
+) -> CompanyDetails:
+ """Ruft detaillierte Unternehmensinformationen ab.
+
+ Diese Funktion ruft erweiterte Informationen zu einem Unternehmen ab,
+ das zuvor ĂŒber search() gefunden wurde.
+
+ Args:
+ company: Unternehmen-Dictionary aus den Suchergebnissen.
+ detail_type: Art der Details:
+ - "SI": Strukturierter Registerinhalt (empfohlen)
+ - "AD": Aktueller Abdruck
+ - "UT": UnternehmenstrÀger
+ force_refresh: Cache ignorieren.
+ debug: Debug-Logging aktivieren.
+
+ Returns:
+ CompanyDetails mit allen verfĂŒgbaren Informationen.
+
+ Beispiel:
+ >>> from handelsregister import search, get_details
+ >>>
+ >>> # Erst suchen
+ >>> companies = search("GASAG AG", keyword_option="exact")
+ >>>
+ >>> # Dann Details abrufen
+ >>> if companies:
+ ... details = get_details(companies[0])
+ ... print(f"Kapital: {details.capital} {details.currency}")
+ ... print(f"Rechtsform: {details.legal_form}")
+ """
+ if debug:
+ logging.basicConfig(
+ level=logging.DEBUG, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+ )
+
+ hr = HandelsRegister(debug=debug)
+ hr.open_startpage()
+
+ register_num = company.register_num or ""
+ name = company.name
+
+ if register_num:
+ search_opts = SearchOptions(
+ keywords=name,
+ keyword_option="exact",
+ )
+ else:
+ search_opts = SearchOptions(
+ keywords=name,
+ keyword_option="all",
+ )
+
+ hr.search_with_options(search_opts, force_refresh=force_refresh)
+ company.row_index = 0
+ return hr.get_company_details(company, detail_type, force_refresh)
+
+
+def pr_company_details(details: CompanyDetails) -> None:
+ """Prints detailed company information to stdout.
+
+ Args:
+ details: CompanyDetails object with all information.
+ """
+ print(f"{'=' * 60}")
+ print(f"Firma: {details.name}")
+ print(f"Registernummer: {details.register_num}")
+ print(f"Gericht: {details.court}")
+ print(f"Bundesland: {details.state}")
+ print(f"Status: {details.status}")
+
+ if details.legal_form:
+ print(f"Rechtsform: {details.legal_form}")
+
+ if details.capital:
+ currency = details.currency or "EUR"
+ print(f"Kapital: {details.capital} {currency}")
+
+ if details.address:
+ print(f"Adresse: {details.address}")
+
+ if details.purpose:
+ print(f"Gegenstand: {details.purpose[:100]}{'...' if len(details.purpose) > 100 else ''}")
+
+ if details.representatives:
+ print("Vertretung:")
+ for rep in details.representatives:
+ loc = f" ({rep.location})" if rep.location else ""
+ print(f" - {rep.role}: {rep.name}{loc}")
+
+ if details.owners:
+ print("Gesellschafter:")
+ for owner in details.owners:
+ share = f" - {owner.share}" if owner.share else ""
+ print(f" - {owner.name}{share}")
+
+ if details.registration_date:
+ print(f"Eingetragen: {details.registration_date}")
+
+ print()
+
+
+def main() -> int: # noqa: PLR0912
+ """Main entry point for the CLI.
+
+ Returns:
+ Exit code (0 for success, non-zero for errors).
+ """
+ args = parse_args()
+
+ try:
+ hr = HandelsRegister(args)
+ hr.open_startpage()
+
+ fetch_details = getattr(args, "details", False)
+ detail_type = getattr(args, "detail_type", "SI")
+
+ if fetch_details:
+ search_opts = hr._build_search_options()
+ companies_details = hr.search_with_details(
+ search_opts,
+ fetch_details=True,
+ detail_type=detail_type,
+ force_refresh=getattr(args, "force", False),
+ show_progress=not args.json, # Show progress unless JSON output
+ )
+
+ if companies_details:
+ if args.json:
+ print(json.dumps([d.to_dict() for d in companies_details]))
+ else:
+ for details in companies_details:
+ pr_company_details(details)
+ else:
+ companies = hr.search_company()
+
+ if companies:
+ if args.json:
+ print(json.dumps(companies))
+ else:
+ for c in companies:
+ pr_company_info(c)
+
+ return 0 # noqa: TRY300
+ except NetworkError as e:
+ print(f"Network error: {e}", file=sys.stderr)
+ if args.debug and e.original_error:
+ print(f"Original error: {e.original_error}", file=sys.stderr)
+ return 1
+
+ except FormError as e:
+ print(f"Form error: {e}", file=sys.stderr)
+ return 2
+
+ except ParseError as e:
+ print(f"Parse error: {e}", file=sys.stderr)
+ if args.debug and e.html_snippet:
+ print(f"HTML snippet: {e.html_snippet}", file=sys.stderr)
+ return 3
+
+ except CacheError as e:
+ print(f"Cache error: {e}", file=sys.stderr)
+ return 4
+
+ except HandelsregisterError as e:
+ print(f"Error: {e}", file=sys.stderr)
+ return 1
diff --git a/handelsregister/client.py b/handelsregister/client.py
new file mode 100644
index 00000000..8d3609f9
--- /dev/null
+++ b/handelsregister/client.py
@@ -0,0 +1,656 @@
+"""Main client class for interacting with the Handelsregister portal."""
+
+import argparse
+import contextlib
+import logging
+import pathlib
+import sys
+import urllib.error
+from typing import Literal, Optional
+
+import mechanize
+from ratelimit import limits, sleep_and_retry
+from tenacity import (
+ before_sleep_log,
+ retry,
+ retry_if_exception_type,
+ stop_after_attempt,
+ wait_exponential,
+)
+from tqdm import tqdm
+
+from .cache import SearchCache
+from .constants import KEYWORD_OPTIONS, RESULTS_PER_PAGE_OPTIONS, STATE_CODES
+from .exceptions import FormError, NetworkError, ParseError, PartialResultError
+from .models import Company, CompanyDetails, SearchOptions
+from .parser import DetailsParser, ResultParser
+from .settings import (
+ BASE_URL,
+ MAX_RETRIES,
+ RATE_LIMIT_CALLS,
+ RATE_LIMIT_PERIOD,
+ REQUEST_TIMEOUT,
+ RETRY_WAIT_MAX,
+ RETRY_WAIT_MIN,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _with_retry_and_rate_limit(func):
+ """Decorator that applies rate limiting and retry logic to a method.
+
+ Combines rate limiting (60 calls/hour) with exponential backoff retry
+ logic for network operations. This decorator stack is reused across
+ all network operations in HandelsRegister.
+ """
+ return sleep_and_retry(
+ limits(calls=RATE_LIMIT_CALLS, period=RATE_LIMIT_PERIOD)(
+ retry(
+ stop=stop_after_attempt(MAX_RETRIES),
+ wait=wait_exponential(multiplier=1, min=RETRY_WAIT_MIN, max=RETRY_WAIT_MAX),
+ retry=retry_if_exception_type(urllib.error.URLError),
+ before_sleep=before_sleep_log(logger, logging.WARNING),
+ reraise=True,
+ )(func)
+ )
+ )
+
+
+class HandelsRegister:
+ """Browser-Automatisierung fĂŒr die Handelsregister-Suche.
+
+ Verwaltet die Interaktion mit der Handelsregister-Website, Navigation,
+ Formular-Ăbermittlung und Ergebnis-Abruf.
+
+ Beispiel:
+ >>> hr = HandelsRegister(debug=False)
+ >>> hr.open_startpage()
+ >>> results = hr.search_with_options(SearchOptions(keywords="Bank", states=["BE"]))
+ """
+
+ def __init__(
+ self,
+ args: Optional[argparse.Namespace] = None,
+ cache: Optional[SearchCache] = None,
+ debug: bool = False,
+ ) -> None:
+ """Initialisiert den HandelsRegister-Client.
+
+ Args:
+ args: CLI-Argumente (optional, fĂŒr RĂŒckwĂ€rtskompatibilitĂ€t).
+ cache: Cache-Instanz (optional, wird automatisch erstellt).
+ debug: Debug-Logging aktivieren.
+ """
+ self.args = args
+ self.cache = cache or SearchCache()
+ self._debug = debug if args is None else getattr(args, "debug", False)
+ self.browser = self._create_browser(debug=self._debug)
+
+ @classmethod
+ def from_options(
+ cls,
+ options: SearchOptions,
+ cache: Optional[SearchCache] = None,
+ debug: bool = False,
+ ) -> "HandelsRegister":
+ """Erstellt einen Client mit SearchOptions.
+
+ Args:
+ options: Suchoptionen.
+ cache: Cache-Instanz (optional).
+ debug: Debug-Logging aktivieren.
+
+ Returns:
+ Konfigurierte HandelsRegister-Instanz.
+ """
+ instance = cls(args=None, cache=cache, debug=debug)
+ instance._default_options = options
+ return instance
+
+ def _create_browser(self, debug: bool = False) -> mechanize.Browser:
+ """Creates and configures a mechanize browser instance.
+
+ Args:
+ debug: Enable debug output for HTTP requests.
+
+ Returns:
+ Configured Browser instance.
+ """
+ browser = mechanize.Browser()
+
+ browser.set_debug_http(debug)
+ browser.set_debug_responses(debug)
+
+ browser.set_handle_robots(False)
+ browser.set_handle_equiv(True)
+ browser.set_handle_gzip(True)
+ browser.set_handle_refresh(False)
+ browser.set_handle_redirect(True)
+ browser.set_handle_referer(True)
+
+ browser.addheaders = [
+ (
+ "User-Agent",
+ "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+ "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.5 Safari/605.1.15",
+ ),
+ ("Accept-Language", "en-GB,en;q=0.9"),
+ ("Accept-Encoding", "gzip, deflate, br"),
+ ("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"),
+ ("Connection", "keep-alive"),
+ ]
+
+ return browser
+
+ # Backward compatibility: expose cachedir
+ @property
+ def cachedir(self) -> pathlib.Path:
+ """Gets the cache directory path."""
+ return self.cache.cache_dir
+
+ @_with_retry_and_rate_limit
+ def open_startpage(self) -> None:
+ """Opens the Handelsregister start page with automatic retries.
+
+ Uses exponential backoff for retries on network failures.
+ Rate limited to 60 requests per hour per portal terms of service.
+
+ Raises:
+ NetworkError: If the connection fails after all retry attempts.
+ """
+ try:
+ self.browser.open(str(BASE_URL), timeout=REQUEST_TIMEOUT)
+ except urllib.error.URLError as e:
+ error_msg = (
+ f"Failed to connect to {BASE_URL}: {e.reason}. "
+ f"Please check your internet connection and try again."
+ )
+ raise NetworkError(
+ error_msg,
+ original_error=e,
+ ) from e
+ except mechanize.BrowserStateError as e:
+ error_msg = f"Browser state error while opening {BASE_URL}: {e}"
+ raise NetworkError(
+ error_msg,
+ original_error=e,
+ ) from e
+
+ def _build_search_options(self) -> SearchOptions:
+ """Builds SearchOptions from command-line arguments.
+
+ Returns:
+ SearchOptions instance with all search parameters.
+ """
+ states = None
+ if hasattr(self.args, "states") and self.args.states:
+ states = [s.strip().upper() for s in self.args.states.split(",")]
+
+ return SearchOptions(
+ keywords=self.args.schlagwoerter,
+ keyword_option=self.args.schlagwortOptionen,
+ states=states,
+ register_type=getattr(self.args, "register_type", None),
+ register_number=getattr(self.args, "register_number", None),
+ include_deleted=getattr(self.args, "include_deleted", False),
+ similar_sounding=getattr(self.args, "similar_sounding", False),
+ results_per_page=getattr(self.args, "results_per_page", 100),
+ )
+
+ def search_with_options(
+ self,
+ options: SearchOptions,
+ force_refresh: bool = False,
+ ) -> list[Company]:
+ """FĂŒhrt eine Suche mit SearchOptions durch.
+
+ Args:
+ options: Suchoptionen.
+ force_refresh: Cache ignorieren.
+
+ Returns:
+ Liste von Dictionaries mit Unternehmensdaten.
+
+ Raises:
+ NetworkError: Bei Netzwerkfehlern.
+ FormError: Bei Formular-Problemen.
+ ParseError: Bei Parse-Fehlern.
+ """
+ cache_key = options.cache_key()
+
+ # Try to load from cache
+ if not force_refresh:
+ cached_html = self.cache.get(cache_key, "")
+ if cached_html is not None:
+ logger.info("Cache-Treffer fĂŒr: %s", options.keywords)
+ return ResultParser.parse_search_results(cached_html)
+
+ # Fetch fresh data from website
+ html = self._fetch_search_results(options)
+
+ # Save to cache
+ self.cache.set(cache_key, "", html)
+
+ return ResultParser.parse_search_results(html)
+
+ def search_company(self) -> list[Company]:
+ """Sucht nach Unternehmen basierend auf CLI-Argumenten.
+
+ Hinweis: FĂŒr programmatische Nutzung wird search_with_options() empfohlen.
+
+ Returns:
+ Liste von Dictionaries mit Unternehmensdaten.
+
+ Raises:
+ NetworkError: Bei Netzwerkfehlern.
+ FormError: Bei Formular-Problemen.
+ ParseError: Bei Parse-Fehlern.
+ """
+ if self.args is None:
+ error_msg = "search_company() benötigt args. Nutze search_with_options() stattdessen."
+ raise ValueError(error_msg)
+
+ search_opts = self._build_search_options()
+ force_refresh = getattr(self.args, "force", False)
+ return self.search_with_options(search_opts, force_refresh=force_refresh)
+
+ def _fetch_search_results(self, search_opts: SearchOptions) -> str:
+ """Fetches search results from the website.
+
+ Args:
+ search_opts: Search options specifying all search parameters.
+
+ Returns:
+ HTML content of search results page.
+
+ Raises:
+ NetworkError: If network requests fail.
+ FormError: If form selection or submission fails.
+ """
+ self._navigate_to_search()
+ return self._submit_search(search_opts)
+
+ @_with_retry_and_rate_limit
+ def _navigate_to_search(self) -> None:
+ """Navigates from start page to extended search form with retries.
+
+ Uses exponential backoff for retries on network failures.
+ Rate limited to 60 requests per hour per portal terms of service.
+
+ Raises:
+ FormError: If navigation form is not found.
+ NetworkError: If form submission fails after all retries.
+ """
+ try:
+ self.browser.select_form(name="naviForm")
+ except mechanize.FormNotFoundError as e:
+ current_url = self.browser.geturl() if hasattr(self.browser, "geturl") else "unknown"
+ error_msg = (
+ f"Navigation form 'naviForm' not found on page {current_url}. "
+ f"The website structure may have changed: {e}"
+ )
+ raise FormError(
+ error_msg,
+ original_error=e,
+ ) from e
+
+ self.browser.form.new_control(
+ "hidden", "naviForm:erweiterteSucheLink", {"value": "naviForm:erweiterteSucheLink"}
+ )
+ self.browser.form.new_control("hidden", "target", {"value": "erweiterteSucheLink"})
+
+ try:
+ self.browser.submit()
+ except urllib.error.URLError as e:
+ error_msg = f"Failed to submit navigation form: {e.reason}"
+ raise NetworkError(
+ error_msg,
+ original_error=e,
+ ) from e
+
+ logger.debug("Page title after navigation: %s", self.browser.title())
+
+ @_with_retry_and_rate_limit
+ def _submit_search(self, search_opts: SearchOptions) -> str: # noqa: PLR0912, PLR0915
+ """Submits the search form and returns results HTML with retries.
+
+ Uses exponential backoff for retries on network failures.
+ Rate limited to 60 requests per hour per portal terms of service.
+
+ Args:
+ search_opts: Search options specifying all search parameters.
+
+ Returns:
+ HTML content of search results page.
+
+ Raises:
+ FormError: If search form is not found.
+ NetworkError: If form submission fails after all retries.
+ """
+ try:
+ self.browser.select_form(name="form")
+ except mechanize.FormNotFoundError as e:
+ current_url = self.browser.geturl() if hasattr(self.browser, "geturl") else "unknown"
+ error_msg = (
+ f"Search form 'form' not found on page {current_url}. "
+ f"The website structure may have changed: {e}"
+ )
+ raise FormError(
+ error_msg,
+ original_error=e,
+ ) from e
+
+ self.browser["form:schlagwoerter"] = search_opts.keywords
+ option_id = KEYWORD_OPTIONS.get(search_opts.keyword_option)
+ self.browser["form:schlagwortOptionen"] = [str(option_id)]
+
+ if search_opts.states:
+ for state_code in search_opts.states:
+ if state_code in STATE_CODES:
+ try:
+ state_name = STATE_CODES[state_code]
+ control_name = f"form:{state_name}_input"
+ self.browser.form.find_control(control_name).value = ["on"]
+ logger.debug("Enabled state filter: %s (%s)", state_code, state_name)
+ except mechanize.ControlNotFoundError:
+ logger.warning("State control not found: %s", control_name)
+
+ if search_opts.register_type:
+ try:
+ self.browser["form:registerArt_input"] = [search_opts.register_type]
+ logger.debug("Set register type: %s", search_opts.register_type)
+ except mechanize.ControlNotFoundError:
+ logger.warning("Register type control not found")
+
+ if search_opts.register_number:
+ try:
+ self.browser["form:registerNummer"] = search_opts.register_number
+ logger.debug("Set register number: %s", search_opts.register_number)
+ except mechanize.ControlNotFoundError:
+ logger.warning("Register number control not found")
+
+ if search_opts.include_deleted:
+ try:
+ self.browser.form.find_control("form:auchGeloeschte_input").value = ["on"]
+ logger.debug("Enabled include deleted option")
+ except mechanize.ControlNotFoundError:
+ logger.warning("Include deleted control not found")
+
+ if search_opts.similar_sounding:
+ try:
+ self.browser.form.find_control(
+ "form:aenlichLautendeSchlagwoerterBoolChkbox_input"
+ ).value = ["on"]
+ logger.debug("Enabled similar sounding option")
+ except mechanize.ControlNotFoundError:
+ logger.warning("Similar sounding control not found")
+
+ if search_opts.results_per_page in RESULTS_PER_PAGE_OPTIONS:
+ try:
+ self.browser["form:ergebnisseProSeite_input"] = [str(search_opts.results_per_page)]
+ logger.debug("Set results per page: %d", search_opts.results_per_page)
+ except mechanize.ControlNotFoundError:
+ logger.warning("Results per page control not found")
+
+ try:
+ response = self.browser.submit()
+ except urllib.error.URLError as e:
+ error_msg = f"Failed to submit search form: {e.reason}"
+ raise NetworkError(error_msg, original_error=e) from e
+
+ logger.debug("Page title after search: %s", self.browser.title())
+
+ return response.read().decode("utf-8")
+
+ # =========================================================================
+ # Detail Fetching Methods
+ # =========================================================================
+
+ def get_company_details(
+ self,
+ company: Company,
+ detail_type: Literal["SI", "AD", "UT", "CD", "HD", "VĂ"] = "SI",
+ force_refresh: bool = False,
+ fallback_types: Optional[list[Literal["SI", "AD", "UT", "CD", "HD", "VĂ"]]] = None,
+ ) -> CompanyDetails:
+ """Fetches detailed company information with optional fallback strategies.
+
+ Args:
+ company: Company dict from search results (must contain row_index).
+ detail_type: Type of details to fetch:
+ - "SI": Strukturierter Registerinhalt (structured, recommended)
+ - "AD": Aktueller Abdruck (current printout)
+ - "UT": UnternehmenstrÀger (company owners)
+ force_refresh: Skip cache and fetch fresh data.
+ fallback_types: List of alternative detail types to try if primary fails.
+ If None, defaults to ["AD", "UT"] for graceful degradation.
+
+ Returns:
+ CompanyDetails with all available information.
+
+ Raises:
+ NetworkError: If the request fails after all retries and fallbacks.
+ ParseError: If parsing fails for all attempted types.
+ ValueError: If company dict is missing required fields.
+ """
+ valid_types = ["SI", "AD", "UT", "CD", "HD", "VĂ"]
+ if detail_type not in valid_types:
+ error_msg = f"Invalid detail_type: {detail_type}. Must be one of {valid_types}"
+ raise ValueError(error_msg)
+
+ # Default fallback types if not specified
+ if fallback_types is None:
+ fallback_types = ["AD", "UT"]
+
+ # Try primary detail type first
+ types_to_try = [detail_type] + [
+ ft for ft in fallback_types if ft != detail_type and ft in valid_types
+ ]
+ last_error: Optional[Exception] = None
+
+ for attempt_type in types_to_try:
+ cache_key = f"details:{attempt_type}:{company.register_num or ''}:{company.court}"
+
+ try:
+ if not force_refresh:
+ cached_html = self.cache.get(cache_key, "")
+ if cached_html is not None:
+ logger.info("Cache hit for details: %s", cache_key)
+ return self._parse_details(cached_html, company, attempt_type)
+
+ html = self._fetch_detail_page(company, attempt_type)
+ self.cache.set(cache_key, "", html)
+
+ return self._parse_details(html, company, attempt_type)
+
+ except (NetworkError, ParseError) as e:
+ last_error = e
+ if attempt_type != types_to_try[-1]: # Not the last attempt
+ logger.warning(
+ "Failed to fetch %s details for %s, trying fallback: %s",
+ attempt_type,
+ company.name or "unknown",
+ e,
+ )
+ else:
+ # Last attempt failed, re-raise with context
+ raise
+ except Exception as e:
+ last_error = e
+ if attempt_type != types_to_try[-1]:
+ logger.warning(
+ "Unexpected error fetching %s details for %s, trying fallback: %s",
+ attempt_type,
+ company.name or "unknown",
+ e,
+ )
+ else:
+ raise
+
+ # Should never reach here, but just in case
+ if last_error:
+ raise last_error
+ error_msg = "Failed to fetch company details after all attempts"
+ raise NetworkError(error_msg)
+
+ @_with_retry_and_rate_limit
+ def _fetch_detail_page(self, company: Company, detail_type: str) -> str:
+ """Fetches a detail page for a company with retries.
+
+ The Handelsregister uses JSF/PrimeFaces which requires specific
+ form parameters. We reconstruct these based on the search results.
+ Uses exponential backoff for retries on network failures.
+ Rate limited to 60 requests per hour per portal terms of service.
+
+ Args:
+ company: Company dict with at least 'row_index' from search.
+ detail_type: Type of detail page (SI, AD, UT, etc.).
+
+ Returns:
+ HTML content of the detail page.
+ """
+ row_index = company.row_index or 0
+
+ detail_type_mapping = {
+ "AD": "ergebnissForm:selectedSuchErgebnisFormTable:{row}:j_idt161:0:fade",
+ "CD": "ergebnissForm:selectedSuchErgebnisFormTable:{row}:j_idt161:1:fade",
+ "HD": "ergebnissForm:selectedSuchErgebnisFormTable:{row}:j_idt161:2:fade",
+ "UT": "ergebnissForm:selectedSuchErgebnisFormTable:{row}:j_idt161:4:fade",
+ "VĂ": "ergebnissForm:selectedSuchErgebnisFormTable:{row}:j_idt161:5:fade",
+ "SI": "ergebnissForm:selectedSuchErgebnisFormTable:{row}:j_idt161:6:fade",
+ }
+
+ control_name = detail_type_mapping.get(detail_type, detail_type_mapping["SI"])
+ control_name = control_name.format(row=row_index)
+
+ try:
+ self.browser.select_form(name="ergebnissForm")
+ self.browser.form.new_control("hidden", control_name, {"value": control_name})
+ response = self.browser.submit()
+ return response.read().decode("utf-8")
+
+ except mechanize.FormNotFoundError as e:
+ error_msg = (
+ f"Results form not found. Unable to fetch {detail_type} details for "
+ f"{company.name} ({company.register_num or 'N/A'}). "
+ f"The website structure may have changed or the search results page is no longer available."
+ )
+ raise FormError(
+ error_msg,
+ original_error=e,
+ ) from e
+ except urllib.error.URLError as e:
+ error_msg = f"Failed to fetch detail page: {e.reason}"
+ raise NetworkError(error_msg, original_error=e) from e
+
+ def _parse_details(self, html: str, company: Company, detail_type: str) -> CompanyDetails:
+ """Parses detail HTML into CompanyDetails.
+
+ Args:
+ html: HTML content of detail page.
+ company: Base company info from search.
+ detail_type: Type of detail page.
+
+ Returns:
+ Parsed CompanyDetails.
+ """
+ if detail_type == "SI":
+ return DetailsParser.parse_si(html, company)
+ if detail_type == "AD":
+ return DetailsParser.parse_ad(html, company)
+ if detail_type == "UT":
+ return DetailsParser.parse_ut(html, company)
+ return DetailsParser.parse_si(html, company)
+
+ def search_with_details(
+ self,
+ options: SearchOptions,
+ fetch_details: bool = True,
+ detail_type: Literal["SI", "AD", "UT", "CD", "HD", "VĂ"] = "SI",
+ force_refresh: bool = False,
+ show_progress: Optional[bool] = None,
+ continue_on_error: bool = True,
+ raise_partial: bool = False,
+ ) -> list[CompanyDetails]:
+ """Searches for companies and optionally fetches details.
+
+ Args:
+ options: Search options.
+ fetch_details: Whether to fetch details for each result.
+ detail_type: Type of details to fetch (SI, AD, UT).
+ force_refresh: Skip cache.
+ show_progress: Show progress bar (auto-detected if None based on TTY).
+ continue_on_error: Continue processing other companies if one fails.
+ raise_partial: Raise PartialResultError if any failures occur.
+
+ Returns:
+ List of CompanyDetails with full information.
+
+ Raises:
+ PartialResultError: If raise_partial=True and some operations failed.
+ """
+ companies = self.search_with_options(options, force_refresh=force_refresh)
+
+ if not fetch_details:
+ return [CompanyDetails.from_company(c) for c in companies]
+
+ # Auto-detect if we should show progress (only if TTY and more than 1 item)
+ if show_progress is None:
+ show_progress = sys.stdout.isatty() and len(companies) > 1
+
+ results: list[CompanyDetails] = []
+ failed: list[tuple[Company, Exception]] = []
+ iterator = tqdm(
+ companies, desc="Fetching details", unit="company", disable=not show_progress
+ )
+
+ for i, company in enumerate(iterator):
+ company.row_index = i
+ company_name = company.name
+ if show_progress:
+ iterator.set_postfix(name=company_name[:30])
+
+ try:
+ details = self.get_company_details(
+ company, detail_type=detail_type, force_refresh=force_refresh
+ )
+ results.append(details)
+ except (NetworkError, ParseError) as e:
+ if not continue_on_error:
+ raise
+
+ logger.warning(
+ "Failed to fetch details for %s (%s): %s",
+ company_name,
+ company.register_num or "N/A",
+ e,
+ )
+
+ # Try fallback: use basic company info
+ try:
+ fallback = CompanyDetails.from_company(company)
+ results.append(fallback)
+ except Exception:
+ logger.exception("Failed to create fallback for %s", company_name)
+ failed.append((company, e))
+ except Exception as e:
+ # Unexpected error
+ logger.exception("Unexpected error fetching details for %s", company_name)
+ if not continue_on_error:
+ raise
+ failed.append((company, e))
+ # Still try to add basic info
+ with contextlib.suppress(Exception):
+ results.append(CompanyDetails.from_company(company))
+
+ # Raise partial result error if requested and there were failures
+ if raise_partial and failed:
+ error_msg = f"Batch operation completed with {len(failed)} failures out of {len(companies)} total"
+ raise PartialResultError(
+ error_msg,
+ successful=results,
+ failed=failed,
+ )
+
+ return results
diff --git a/handelsregister/constants.py b/handelsregister/constants.py
new file mode 100644
index 00000000..15d5f566
--- /dev/null
+++ b/handelsregister/constants.py
@@ -0,0 +1,145 @@
+"""Constants and configuration for the Handelsregister package."""
+
+from enum import Enum
+from typing import Optional
+
+from yarl import URL
+
+
+class State(str, Enum):
+ """German federal states (BundeslÀnder).
+
+ Usage:
+ >>> from handelsregister import State
+ >>> search("Bank", states=[State.BE, State.HH])
+ """
+
+ BW = "BW" # Baden-WĂŒrttemberg
+ BY = "BY" # Bayern
+ BE = "BE" # Berlin
+ BR = "BR" # Brandenburg
+ HB = "HB" # Bremen
+ HH = "HH" # Hamburg
+ HE = "HE" # Hessen
+ MV = "MV" # Mecklenburg-Vorpommern
+ NI = "NI" # Niedersachsen
+ NW = "NW" # Nordrhein-Westfalen
+ RP = "RP" # Rheinland-Pfalz
+ SL = "SL" # Saarland
+ SN = "SN" # Sachsen
+ ST = "ST" # Sachsen-Anhalt
+ SH = "SH" # Schleswig-Holstein
+ TH = "TH" # ThĂŒringen
+
+ @property
+ def name_de(self) -> str:
+ """Returns the German name of the state."""
+ return STATE_CODES[self.value]
+
+ def __str__(self) -> str:
+ return self.value
+
+
+class KeywordMatch(str, Enum):
+ """Keyword matching options for search.
+
+ Usage:
+ >>> from handelsregister import KeywordMatch
+ >>> search("Bank", keyword_option=KeywordMatch.EXACT)
+ """
+
+ ALL = "all" # All keywords must match
+ MIN = "min" # At least one keyword must match
+ EXACT = "exact" # Exact name match
+
+ @property
+ def form_value(self) -> int:
+ """Returns the form value for this option."""
+ return KEYWORD_OPTIONS[self.value]
+
+ def __str__(self) -> str:
+ return self.value
+
+
+class RegisterType(str, Enum):
+ """Register types in the Handelsregister.
+
+ Usage:
+ >>> from handelsregister import RegisterType
+ >>> search("Bank", register_type=RegisterType.HRB)
+ """
+
+ HRA = "HRA" # Handelsregister A (Partnerships)
+ HRB = "HRB" # Handelsregister B (Corporations)
+ GnR = "GnR" # Genossenschaftsregister (Cooperatives)
+ PR = "PR" # Partnerschaftsregister (Partnerships)
+ VR = "VR" # Vereinsregister (Associations)
+
+ def __str__(self) -> str:
+ return self.value
+
+
+# Mapping of keyword option names to form values
+KEYWORD_OPTIONS: dict[str, int] = {"all": 1, "min": 2, "exact": 3}
+
+# Mapping of states to register type suffixes
+SUFFIX_MAP: dict[str, dict[str, str]] = {
+ "Berlin": {"HRB": " B"},
+ "Bremen": {"HRA": " HB", "HRB": " HB", "GnR": " HB", "VR": " HB", "PR": " HB"},
+}
+
+# German state codes for filtering (bundesland parameters)
+STATE_CODES: dict[str, str] = {
+ "BW": "Baden-WĂŒrttemberg",
+ "BY": "Bayern",
+ "BE": "Berlin",
+ "BR": "Brandenburg",
+ "HB": "Bremen",
+ "HH": "Hamburg",
+ "HE": "Hessen",
+ "MV": "Mecklenburg-Vorpommern",
+ "NI": "Niedersachsen",
+ "NW": "Nordrhein-Westfalen",
+ "RP": "Rheinland-Pfalz",
+ "SL": "Saarland",
+ "SN": "Sachsen",
+ "ST": "Sachsen-Anhalt",
+ "SH": "Schleswig-Holstein",
+ "TH": "ThĂŒringen",
+}
+
+# Register types
+REGISTER_TYPES: list[str] = ["HRA", "HRB", "GnR", "PR", "VR"]
+
+# Results per page options (must be one of these values)
+RESULTS_PER_PAGE_OPTIONS: list[int] = [10, 25, 50, 100]
+
+# For backward compatibility
+schlagwortOptionen = KEYWORD_OPTIONS # noqa: N816
+
+
+def build_url(path: str = "", base_url: Optional[URL] = None, **query_params) -> URL:
+ """Builds a URL from BASE_URL with path and optional query parameters.
+
+ Uses yarl for safe URL construction with proper encoding.
+
+ Args:
+ path: Path to append to BASE_URL (e.g., "rp_web/erweitertesuche.xhtml").
+ base_url: Base URL to use (defaults to settings.base_url_parsed).
+ **query_params: Query parameters to add to the URL.
+
+ Returns:
+ yarl.URL object with the constructed URL.
+
+ Example:
+ >>> url = build_url("rp_web/search", q="Bank", page="1")
+ >>> str(url)
+ 'https://www.handelsregister.de/rp_web/search?q=Bank&page=1'
+ """
+ from .settings import settings
+
+ url_base = base_url if base_url is not None else settings.base_url_parsed
+ url = url_base / path if path else url_base
+ if query_params:
+ url = url.with_query(query_params)
+ return url
diff --git a/handelsregister/exceptions.py b/handelsregister/exceptions.py
new file mode 100644
index 00000000..a158683f
--- /dev/null
+++ b/handelsregister/exceptions.py
@@ -0,0 +1,53 @@
+"""Exception classes for the Handelsregister package."""
+
+from typing import Optional
+
+
+class HandelsregisterError(Exception):
+ """Base exception for all Handelsregister errors."""
+
+
+class NetworkError(HandelsregisterError):
+ """Raised when a network request fails."""
+
+ def __init__(self, message: str, original_error: Optional[Exception] = None):
+ super().__init__(message)
+ self.original_error = original_error
+
+
+class ParseError(HandelsregisterError):
+ """Raised when HTML parsing fails."""
+
+ def __init__(self, message: str, html_snippet: Optional[str] = None):
+ super().__init__(message)
+ self.html_snippet = html_snippet
+
+
+class FormError(HandelsregisterError):
+ """Raised when form interaction fails."""
+
+ def __init__(self, message: str, original_error: Optional[Exception] = None):
+ super().__init__(message)
+ self.original_error = original_error
+
+
+class CacheError(HandelsregisterError):
+ """Raised when cache operations fail."""
+
+
+class PartialResultError(HandelsregisterError):
+ """Raised when a batch operation completes with some failures.
+
+ This exception contains information about which operations succeeded
+ and which failed, allowing for graceful degradation.
+ """
+
+ def __init__(
+ self,
+ message: str,
+ successful: list,
+ failed: list[tuple[object, Exception]],
+ ):
+ super().__init__(message)
+ self.successful = successful
+ self.failed = failed # List of (item, exception) tuples
diff --git a/handelsregister/models.py b/handelsregister/models.py
new file mode 100644
index 00000000..f96cecc4
--- /dev/null
+++ b/handelsregister/models.py
@@ -0,0 +1,330 @@
+"""Data models for the Handelsregister package using Pydantic."""
+
+import time
+from dataclasses import dataclass
+from typing import Any, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from .constants import (
+ RESULTS_PER_PAGE_OPTIONS,
+ STATE_CODES,
+ KeywordMatch,
+ RegisterType,
+ State,
+)
+from .settings import DEFAULT_CACHE_TTL_SECONDS
+
+
+@dataclass
+class CacheEntry:
+ """Represents a cached search result with metadata.
+
+ Note: Kept as dataclass for internal use only. Not part of public API.
+ """
+
+ query: str
+ options: str
+ timestamp: float
+ html: str
+
+ def is_expired(self, ttl_seconds: int = DEFAULT_CACHE_TTL_SECONDS) -> bool:
+ """Checks if the cache entry has expired.
+
+ Args:
+ ttl_seconds: Time-to-live in seconds.
+
+ Returns:
+ True if expired, False otherwise.
+ """
+ return (time.time() - self.timestamp) > ttl_seconds
+
+ def to_dict(self) -> dict:
+ """Converts to dictionary for JSON serialization."""
+ return {
+ "query": self.query,
+ "options": self.options,
+ "timestamp": self.timestamp,
+ "html": self.html,
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict) -> "CacheEntry":
+ """Creates a CacheEntry from a dictionary."""
+ return cls(
+ query=data["query"],
+ options=data["options"],
+ timestamp=data["timestamp"],
+ html=data["html"],
+ )
+
+
+class SearchOptions(BaseModel):
+ """Encapsulates all search parameters for the Handelsregister.
+
+ Uses Pydantic for validation and serialization.
+
+ Attributes:
+ keywords: Search keywords (schlagwoerter).
+ keyword_option: How to match keywords (all, min, exact). Can be KeywordMatch enum or string.
+ states: List of state codes to filter by (e.g., ['BE', 'HH']). Can be State enum or string.
+ register_type: Register type filter (HRA, HRB, GnR, PR, VR). Can be RegisterType enum or string.
+ register_number: Specific register number to search for.
+ include_deleted: Include deleted/historical entries.
+ similar_sounding: Use phonetic/similarity search.
+ results_per_page: Number of results per page (10, 25, 50, 100). Must be in RESULTS_PER_PAGE_OPTIONS.
+ """
+
+ model_config = ConfigDict(frozen=False, validate_assignment=True)
+
+ keywords: str = Field(..., min_length=1, description="Search keywords")
+ keyword_option: Union[str, KeywordMatch] = Field(default="all", pattern="^(all|min|exact)$")
+ states: Optional[list[Union[str, State]]] = Field(
+ default=None, description="State codes to filter by"
+ )
+ register_type: Optional[Union[str, RegisterType]] = Field(
+ default=None, pattern="^(HRA|HRB|GnR|PR|VR)$"
+ )
+ register_number: Optional[str] = None
+ include_deleted: bool = False
+ similar_sounding: bool = False
+ results_per_page: int = Field(default=100, ge=10, le=100)
+
+ @field_validator("keyword_option", mode="before")
+ @classmethod
+ def validate_keyword_option(cls, v: Union[str, KeywordMatch]) -> str:
+ """Accepts both KeywordMatch enum and string."""
+ if isinstance(v, KeywordMatch):
+ return v.value
+ return v
+
+ @field_validator("states", mode="before")
+ @classmethod
+ def validate_states(cls, v: Optional[list[Union[str, State]]]) -> Optional[list[str]]:
+ """Validates state codes against known values. Accepts both State enum and string."""
+ if v is None:
+ return None
+ valid_codes = set(STATE_CODES.keys())
+ result = []
+ for state in v:
+ # Extract value from enum if needed
+ state_value = state.value if isinstance(state, State) else state
+ state_upper = state_value.upper()
+ if state_upper not in valid_codes:
+ error_msg = (
+ f"Invalid state code: {state_value}. "
+ f"Valid: {', '.join(sorted(valid_codes))}"
+ )
+ raise ValueError(error_msg)
+ result.append(state_upper)
+ return result
+
+ @field_validator("register_type", mode="before")
+ @classmethod
+ def validate_register_type(cls, v: Optional[Union[str, RegisterType]]) -> Optional[str]:
+ """Accepts both RegisterType enum and string."""
+ if v is None:
+ return None
+ if isinstance(v, RegisterType):
+ return v.value
+ return v
+
+ @field_validator("results_per_page")
+ @classmethod
+ def validate_results_per_page(cls, v: int) -> int:
+ """Validates results_per_page is a valid option."""
+ if v not in RESULTS_PER_PAGE_OPTIONS:
+ error_msg = f"results_per_page must be one of {RESULTS_PER_PAGE_OPTIONS}"
+ raise ValueError(error_msg)
+ return v
+
+ def cache_key(self) -> str:
+ """Generates a unique key for caching based on all options."""
+ parts = [
+ self.keywords,
+ self.keyword_option,
+ ",".join(sorted(self.states or [])),
+ self.register_type or "",
+ self.register_number or "",
+ str(self.include_deleted),
+ str(self.similar_sounding),
+ str(self.results_per_page),
+ ]
+ return "|".join(parts)
+
+
+class HistoryEntry(BaseModel):
+ """Represents a historical name/location entry for a company."""
+
+ model_config = ConfigDict(frozen=True)
+
+ name: str
+ location: str
+
+
+class Address(BaseModel):
+ """Represents a business address with validation."""
+
+ model_config = ConfigDict(frozen=False)
+
+ street: Optional[str] = None
+ postal_code: Optional[str] = Field(default=None, pattern=r"^\d{5}$|^$|None")
+ city: Optional[str] = None
+ country: str = "Deutschland"
+
+ @field_validator("postal_code", mode="before")
+ @classmethod
+ def validate_postal_code(cls, v: Any) -> Optional[str]:
+ """Allow None or valid German postal codes."""
+ if v is None or v == "":
+ return None
+ if isinstance(v, str) and len(v) == 5 and v.isdigit():
+ return v
+ # Be lenient - just return as-is for non-standard codes
+ return str(v) if v else None
+
+ def __str__(self) -> str:
+ """Formats address as string."""
+ parts = []
+ if self.street:
+ parts.append(self.street)
+ if self.postal_code and self.city:
+ parts.append(f"{self.postal_code} {self.city}")
+ elif self.city:
+ parts.append(self.city)
+ if self.country and self.country != "Deutschland":
+ parts.append(self.country)
+ return ", ".join(parts) if parts else ""
+
+ def to_dict(self) -> dict:
+ """Convert to dictionary (for backward compatibility)."""
+ return self.model_dump()
+
+
+class Representative(BaseModel):
+ """Represents a company representative (GeschĂ€ftsfĂŒhrer, Vorstand, etc.)."""
+
+ model_config = ConfigDict(frozen=False)
+
+ name: str = Field(..., min_length=1, description="Name of the representative")
+ role: str = Field(..., description="Role (e.g., GeschĂ€ftsfĂŒhrer, Vorstand)")
+ location: Optional[str] = None
+ birth_date: Optional[str] = None
+ restrictions: Optional[str] = None # e.g., "einzelvertretungsberechtigt"
+
+ def to_dict(self) -> dict:
+ """Converts to dictionary (for backward compatibility)."""
+ return self.model_dump()
+
+
+class Owner(BaseModel):
+ """Represents a company owner/shareholder (Gesellschafter)."""
+
+ model_config = ConfigDict(frozen=False)
+
+ name: str = Field(..., min_length=1, description="Name of the owner")
+ share: Optional[str] = None # e.g., "50%", "25.000 EUR"
+ owner_type: Optional[str] = None # e.g., "Kommanditist", "Gesellschafter"
+ location: Optional[str] = None
+
+ def to_dict(self) -> dict:
+ """Converts to dictionary (for backward compatibility)."""
+ return self.model_dump()
+
+
+class CompanyDetails(BaseModel):
+ """Extended company information from detail views.
+
+ Contains all information available from the Handelsregister detail
+ views (AD, SI, UT). Uses Pydantic for validation and serialization.
+ """
+
+ model_config = ConfigDict(frozen=False, validate_assignment=True)
+
+ # Basic identification (from search results)
+ name: str = Field(..., description="Company name")
+ register_num: str = Field(default="", description="Register number (e.g., HRB 12345 B)")
+ court: str = Field(default="", description="Registration court")
+ state: str = Field(default="", description="Federal state")
+ status: str = Field(default="", description="Registration status")
+
+ # Extended information (from detail views)
+ legal_form: Optional[str] = Field(default=None, description="Legal form (AG, GmbH, KG, etc.)")
+ capital: Optional[str] = Field(default=None, description="Share capital / Stammkapital")
+ currency: Optional[str] = Field(default=None, description="Currency (EUR, etc.)")
+ address: Optional[Address] = None
+ purpose: Optional[str] = Field(
+ default=None, description="Business purpose / Unternehmensgegenstand"
+ )
+ representatives: list[Representative] = Field(default_factory=list)
+ owners: list[Owner] = Field(default_factory=list)
+ registration_date: Optional[str] = Field(default=None, description="Registration date")
+ last_update: Optional[str] = Field(default=None, description="Last update date")
+ deletion_date: Optional[str] = Field(default=None, description="Deletion date (if deleted)")
+
+ # Additional metadata
+ raw_data: Optional[dict] = Field(default=None, repr=False, exclude=True)
+
+ def to_dict(self) -> dict:
+ """Converts to dictionary for JSON serialization (backward compatibility)."""
+ # Pydantic's model_dump() automatically handles nested models
+ return self.model_dump(exclude={"raw_data"}, mode="python")
+
+ @classmethod
+ def from_company(cls, company: Union["Company", dict[str, Any]]) -> "CompanyDetails":
+ """Creates CompanyDetails from a Company search result or dict.
+
+ Args:
+ company: Company object or dict with company information.
+
+ Returns:
+ CompanyDetails with basic information from the company.
+ """
+ if isinstance(company, dict):
+ # Backward compatibility: accept dict
+ return cls(
+ name=company.get("name", ""),
+ register_num=company.get("register_num", "") or "",
+ court=company.get("court", ""),
+ state=company.get("state", ""),
+ status=company.get("status", ""),
+ )
+ # Company object
+ return cls(
+ name=company.name,
+ register_num=company.register_num or "",
+ court=company.court,
+ state=company.state,
+ status=company.status,
+ )
+
+
+class Company(BaseModel):
+ """Represents a company record from the Handelsregister.
+
+ This is the primary model for search results. It provides validation
+ and type safety while maintaining backward compatibility with dict access.
+ """
+
+ model_config = ConfigDict(frozen=False, populate_by_name=True)
+
+ court: str
+ name: str
+ state: str
+ status: str
+ status_normalized: str = Field(default="", alias="statusCurrent")
+ documents: str
+ register_num: Optional[str] = None
+ history: list[HistoryEntry] = Field(default_factory=list)
+ row_index: Optional[int] = Field(default=None, exclude=True) # Internal use for detail fetching
+
+ def to_dict(self) -> dict:
+ """Converts to dictionary for backward compatibility."""
+ data = self.model_dump(by_alias=True, exclude={"row_index"})
+ # Convert history from HistoryEntry objects to tuples for backward compatibility
+ data["history"] = [(h.name, h.location) for h in self.history]
+ return data
+
+ def get(self, key: str, default: Any = None) -> Any:
+ """Dict-like access for backward compatibility."""
+ return getattr(self, key, default)
diff --git a/handelsregister/parser.py b/handelsregister/parser.py
new file mode 100644
index 00000000..68286375
--- /dev/null
+++ b/handelsregister/parser.py
@@ -0,0 +1,591 @@
+"""HTML parsing layer for the Handelsregister package."""
+
+import re
+from typing import Any, Optional, Union
+
+from bs4 import BeautifulSoup
+from bs4.element import Tag
+from dateutil import parser as dateutil_parser
+from dateutil.parser import ParserError
+
+from .constants import SUFFIX_MAP
+from .exceptions import ParseError
+from .models import Address, Company, CompanyDetails, HistoryEntry, Owner, Representative
+
+
+class DetailsParser:
+ """Parses detail view HTML (SI, AD, UT) into CompanyDetails objects."""
+
+ # Common patterns for extracting data
+ CAPITAL_PATTERN = re.compile(
+ r"(?:Stamm|Grund)kapital[:\s]*([0-9.,]+)\s*(EUR|âŹ|DM)?", re.IGNORECASE
+ )
+ DATE_PATTERN = re.compile(r"\d{1,2}\.\d{1,2}\.\d{4}")
+
+ @classmethod
+ def parse_date(cls, text: str, output_format: str = "%d.%m.%Y") -> Optional[str]:
+ """Parses a date from text using dateutil.
+
+ Handles German date formats (DD.MM.YYYY) and various other formats.
+ Returns the date in a normalized format.
+
+ Args:
+ text: Text containing a date.
+ output_format: Output format for the date string.
+
+ Returns:
+ Normalized date string, or None if no date found.
+ """
+ # First try to find a German-style date pattern
+ date_match = cls.DATE_PATTERN.search(text)
+ if date_match:
+ date_str = date_match.group(0)
+ try:
+ # Parse with dayfirst=True for German DD.MM.YYYY format
+ parsed = dateutil_parser.parse(date_str, dayfirst=True)
+ return parsed.strftime(output_format)
+ except (ParserError, ValueError):
+ # If dateutil fails, return the original match
+ return date_str
+
+ # Try dateutil on the entire text as fallback
+ try:
+ parsed = dateutil_parser.parse(text, dayfirst=True, fuzzy=True)
+ return parsed.strftime(output_format)
+ except (ParserError, ValueError):
+ return None
+
+ @classmethod
+ def parse_si(
+ cls, html: str, base_info: Optional[Union[Company, dict[str, Any]]] = None
+ ) -> CompanyDetails:
+ """Parses structured register content (SI - Strukturierter Registerinhalt).
+
+ Args:
+ html: HTML content of the SI detail view.
+ base_info: Optional base company info from search results (Company or dict).
+
+ Returns:
+ CompanyDetails with parsed information.
+ """
+ soup = BeautifulSoup(html, "html.parser")
+
+ # Initialize with base info or empty
+ if base_info:
+ if isinstance(base_info, dict):
+ # Backward compatibility: accept dict
+ details = CompanyDetails(
+ name=base_info.get("name", ""),
+ register_num=base_info.get("register_num", "") or "",
+ court=base_info.get("court", ""),
+ state=base_info.get("state", ""),
+ status=base_info.get("status", ""),
+ )
+ else:
+ # Company object
+ details = CompanyDetails(
+ name=base_info.name,
+ register_num=base_info.register_num or "",
+ court=base_info.court,
+ state=base_info.state,
+ status=base_info.status,
+ )
+ else:
+ details = CompanyDetails(
+ name="",
+ register_num="",
+ court="",
+ state="",
+ status="",
+ )
+
+ # Parse structured content - typically in tables or definition lists
+ details = cls._parse_si_tables(soup, details)
+ return cls._parse_si_sections(soup, details)
+
+ @classmethod
+ def _parse_si_tables(cls, soup: BeautifulSoup, details: CompanyDetails) -> CompanyDetails:
+ """Extracts data from SI tables."""
+ tables = soup.find_all("table")
+
+ for table in tables:
+ rows = table.find_all("tr")
+ for row in rows:
+ cells = row.find_all(["td", "th"])
+ if len(cells) >= 2:
+ label = cells[0].get_text(strip=True).lower()
+ value = cells[1].get_text(strip=True)
+
+ details = cls._map_field(label, value, details)
+
+ return details
+
+ @classmethod
+ def _parse_si_sections(cls, soup: BeautifulSoup, details: CompanyDetails) -> CompanyDetails:
+ """Extracts data from SI sections (divs, panels, etc.)."""
+ for div in soup.find_all(["div", "span", "p"]):
+ text = div.get_text(strip=True)
+
+ if details.capital is None:
+ capital_match = cls.CAPITAL_PATTERN.search(text)
+ if capital_match:
+ details.capital = capital_match.group(1)
+ if capital_match.group(2):
+ details.currency = capital_match.group(2).replace("âŹ", "EUR")
+
+ if details.legal_form is None:
+ details.legal_form = cls._extract_legal_form(text)
+
+ reps = cls._extract_representatives(div)
+ if reps:
+ details.representatives.extend(reps)
+
+ return details
+
+ @classmethod
+ def _map_field(cls, label: str, value: str, details: CompanyDetails) -> CompanyDetails: # noqa: PLR0912
+ """Maps a label-value pair to the appropriate CompanyDetails field."""
+ if not value:
+ return details
+
+ if any(x in label for x in ["firma", "name"]) and not details.name:
+ details.name = value
+ elif "rechtsform" in label:
+ details.legal_form = value
+ elif "sitz" in label or "geschÀftsanschrift" in label:
+ details.address = cls._parse_address(value)
+ elif "kapital" in label:
+ amount_pattern = re.match(r"([0-9.,]+)\s*(EUR|âŹ|DM)?", value)
+ if amount_pattern:
+ details.capital = amount_pattern.group(1).strip()
+ if amount_pattern.group(2):
+ details.currency = amount_pattern.group(2).replace("âŹ", "EUR")
+ else:
+ details.capital = value
+ elif "gegenstand" in label or "unternehmensgegenstand" in label:
+ details.purpose = value
+ elif "registernummer" in label or "aktenzeichen" in label:
+ if not details.register_num:
+ details.register_num = value
+ elif "eintrag" in label and "datum" in label:
+ details.registration_date = cls.parse_date(value) or value
+ elif "lösch" in label:
+ details.deletion_date = cls.parse_date(value) or value
+ elif "Ă€nderung" in label or "aktualisiert" in label:
+ details.last_update = cls.parse_date(value) or value
+
+ return details
+
+ @classmethod
+ def _parse_address(cls, text: str) -> Address:
+ """Parses an address string into an Address object."""
+ plz_city_match = re.search(r"(\d{5})\s+(.+?)(?:,|$)", text)
+
+ if plz_city_match:
+ postal_code = plz_city_match.group(1)
+ city = plz_city_match.group(2).strip()
+ street_part = text[: plz_city_match.start()].strip().rstrip(",")
+ return Address(
+ street=street_part if street_part else None,
+ postal_code=postal_code,
+ city=city,
+ )
+ return Address(city=text)
+
+ @classmethod
+ def _extract_legal_form(cls, text: str) -> Optional[str]:
+ """Extracts legal form from text.
+
+ Order matters: more specific forms (like GmbH & Co. KG) must be
+ checked before less specific ones (like GmbH or KG).
+ """
+ legal_forms = [
+ ("GmbH & Co. KG", "GmbH & Co. KG"),
+ ("GmbH & Co. OHG", "GmbH & Co. OHG"),
+ ("UG (haftungsbeschrÀnkt) & Co. KG", "UG & Co. KG"),
+ ("EuropÀische Aktiengesellschaft", "SE"),
+ ("Aktiengesellschaft", "AG"),
+ ("Gesellschaft mit beschrÀnkter Haftung", "GmbH"),
+ ("UG (haftungsbeschrÀnkt)", "UG"),
+ ("Kommanditgesellschaft", "KG"),
+ ("Offene Handelsgesellschaft", "OHG"),
+ ("Eingetragene Genossenschaft", "eG"),
+ ("Eingetragener Verein", "e.V."),
+ ("Partnerschaftsgesellschaft", "PartG"),
+ ("Einzelkaufmann", "e.K."),
+ ("Einzelkauffrau", "e.Kfr."),
+ ]
+
+ text_lower = text.lower()
+ for full_name, abbreviation in legal_forms:
+ if full_name.lower() in text_lower:
+ return full_name
+ if f" {abbreviation}" in text or text.endswith(abbreviation):
+ return full_name
+ if abbreviation in text and "&" in abbreviation:
+ return full_name
+
+ return None
+
+ @classmethod
+ def _extract_representatives(cls, element: Tag) -> list[Representative]:
+ """Extracts representative information from an element."""
+ representatives = []
+ text = element.get_text()
+
+ role_patterns = [
+ (r"GeschĂ€ftsfĂŒhrer(?:in)?[:\s]+([^,;]+)", "GeschĂ€ftsfĂŒhrer"),
+ (r"Vorstand[:\s]+([^,;]+)", "Vorstand"),
+ (r"Prokurist(?:in)?[:\s]+([^,;]+)", "Prokurist"),
+ (r"Inhaber(?:in)?[:\s]+([^,;]+)", "Inhaber"),
+ (
+ r"Persönlich haftende(?:r)? Gesellschafter(?:in)?[:\s]+([^,;]+)",
+ "Persönlich haftender Gesellschafter",
+ ),
+ ]
+
+ for pattern, role in role_patterns:
+ matches = re.finditer(pattern, text, re.IGNORECASE)
+ for match in matches:
+ name = match.group(1).strip()
+ if name and len(name) > 2:
+ location = None
+ loc_match = re.search(r"\(([^)]+)\)", name)
+ if loc_match:
+ location = loc_match.group(1)
+ name = name[: loc_match.start()].strip()
+
+ representatives.append(
+ Representative(
+ name=name,
+ role=role,
+ location=location,
+ )
+ )
+
+ return representatives
+
+ @classmethod
+ def parse_ad(
+ cls, html: str, base_info: Optional[Union[Company, dict[str, Any]]] = None
+ ) -> CompanyDetails:
+ """Parses current printout (AD - Aktueller Abdruck).
+
+ The AD view contains the current state of the register entry as
+ formatted text rather than structured tables.
+
+ Args:
+ html: HTML content of the AD detail view.
+ base_info: Optional base company info from search results.
+
+ Returns:
+ CompanyDetails with parsed information.
+ """
+ soup = BeautifulSoup(html, "html.parser")
+
+ details = CompanyDetails(
+ name=base_info.get("name", "") if base_info else "",
+ register_num=base_info.get("register_num", "") if base_info else "",
+ court=base_info.get("court", "") if base_info else "",
+ state=base_info.get("state", "") if base_info else "",
+ status=base_info.get("status", "") if base_info else "",
+ )
+
+ content_div = soup.find("div", class_=re.compile(r"content|abdruck|register", re.I))
+ if content_div is None:
+ content_div = soup.find("body")
+
+ if content_div:
+ text = content_div.get_text()
+
+ details.legal_form = cls._extract_legal_form(text)
+
+ capital_match = cls.CAPITAL_PATTERN.search(text)
+ if capital_match:
+ details.capital = capital_match.group(1)
+ if capital_match.group(2):
+ details.currency = capital_match.group(2).replace("âŹ", "EUR")
+
+ purpose_match = re.search(
+ r"Gegenstand(?:\s+des\s+Unternehmens)?[:\s]*(.+?)(?:Stammkapital|Grundkapital|GeschĂ€ftsfĂŒhrer|Vorstand|Vertretung|$)",
+ text,
+ re.IGNORECASE | re.DOTALL,
+ )
+ if purpose_match:
+ details.purpose = purpose_match.group(1).strip()
+
+ details.representatives = cls._extract_representatives_from_text(text)
+ details = cls._parse_si_tables(soup, details)
+
+ return details
+
+ @classmethod
+ def parse_ut(
+ cls, html: str, base_info: Optional[Union[Company, dict[str, Any]]] = None
+ ) -> CompanyDetails:
+ """Parses company owner information (UT - UnternehmenstrÀger).
+
+ The UT view focuses on ownership and shareholder information.
+
+ Args:
+ html: HTML content of the UT detail view.
+ base_info: Optional base company info from search results.
+
+ Returns:
+ CompanyDetails with owner information.
+ """
+ soup = BeautifulSoup(html, "html.parser")
+
+ if base_info:
+ if isinstance(base_info, dict):
+ details = CompanyDetails(
+ name=base_info.get("name", ""),
+ register_num=base_info.get("register_num", "") or "",
+ court=base_info.get("court", ""),
+ state=base_info.get("state", ""),
+ status=base_info.get("status", ""),
+ )
+ else:
+ details = CompanyDetails(
+ name=base_info.name,
+ register_num=base_info.register_num or "",
+ court=base_info.court,
+ state=base_info.state,
+ status=base_info.status,
+ )
+ else:
+ details = CompanyDetails(
+ name="",
+ register_num="",
+ court="",
+ state="",
+ status="",
+ )
+
+ details = cls._parse_si_tables(soup, details)
+ text = soup.get_text()
+ details.owners = cls._extract_owners(text)
+ details.representatives = cls._extract_representatives_from_text(text)
+
+ return details
+
+ @classmethod
+ def _extract_representatives_from_text(cls, text: str) -> list[Representative]:
+ """Extracts all representatives from free-form text."""
+ representatives = []
+ seen_names = set()
+
+ patterns = [
+ (
+ r"GeschĂ€ftsfĂŒhrer(?:in)?[:\s]*([A-ZĂĂĂ][a-zĂ€Ă¶ĂŒĂ]+(?:\s+[A-ZĂĂĂ][a-zĂ€Ă¶ĂŒĂ]+)+)",
+ "GeschĂ€ftsfĂŒhrer",
+ ),
+ (r"Vorstand[:\s]*([A-ZĂĂĂ][a-zĂ€Ă¶ĂŒĂ]+(?:\s+[A-ZĂĂĂ][a-zĂ€Ă¶ĂŒĂ]+)+)", "Vorstand"),
+ (r"Prokurist(?:in)?[:\s]*([A-ZĂĂĂ][a-zĂ€Ă¶ĂŒĂ]+(?:\s+[A-ZĂĂĂ][a-zĂ€Ă¶ĂŒĂ]+)+)", "Prokurist"),
+ (
+ r"Persönlich\s+haftende[r]?\s+Gesellschafter(?:in)?[:\s]*([A-ZĂĂĂ][^\n,;]+)",
+ "Persönlich haftender Gesellschafter",
+ ),
+ ]
+
+ for pattern, role in patterns:
+ for match in re.finditer(pattern, text):
+ name = match.group(1).strip()
+ name = re.sub(r"\s*\([^)]*\)\s*", "", name).strip()
+ name = re.sub(r"\s+", " ", name)
+
+ if name and len(name) > 3 and name not in seen_names:
+ seen_names.add(name)
+ location = None
+ full_match = match.group(0)
+ loc_match = re.search(r"\(([^)]+)\)", full_match)
+ if loc_match:
+ location = loc_match.group(1)
+
+ representatives.append(
+ Representative(
+ name=name,
+ role=role,
+ location=location,
+ )
+ )
+
+ return representatives
+
+ @classmethod
+ def _extract_owners(cls, text: str) -> list[Owner]:
+ """Extracts owner/shareholder information from text."""
+ owners = []
+ seen_names = set()
+
+ owner_patterns = [
+ (
+ r"Gesellschafter[:\s]+([^,\n]+?)(?:[,\s]+(?:Anteil|Einlage)[:\s]*([0-9.,]+\s*(?:EUR|âŹ|%)))?(?:\n|$|,)",
+ "Gesellschafter",
+ ),
+ (
+ r"Kommanditist(?:in)?[:\s]+([^,\n]+?)(?:[,\s]+(?:Anteil|Einlage|Haftsumme)[:\s]*([0-9.,]+\s*(?:EUR|âŹ|%)))?(?:\n|$|,)",
+ "Kommanditist",
+ ),
+ (r"KomplementÀr(?:in)?[:\s]+([^,\n]+)", "KomplementÀr"),
+ ]
+
+ for pattern, owner_type in owner_patterns:
+ for match in re.finditer(pattern, text, re.IGNORECASE):
+ name = match.group(1).strip()
+ name = re.sub(r"\s+", " ", name)
+ share = None
+ if len(match.groups()) > 1 and match.group(2):
+ share = match.group(2).strip()
+
+ if name and len(name) > 2 and name not in seen_names:
+ seen_names.add(name)
+ owners.append(
+ Owner(
+ name=name,
+ share=share,
+ owner_type=owner_type,
+ )
+ )
+
+ return owners
+
+
+class ResultParser:
+ """Parses HTML search results into structured company data."""
+
+ @staticmethod
+ def parse_search_results(html: str) -> list[Company]:
+ """Extracts company records from search results HTML.
+
+ Args:
+ html: HTML content of the search results page.
+
+ Returns:
+ List of Company objects with company information.
+ """
+ soup = BeautifulSoup(html, "html.parser")
+ grid = soup.find("table", role="grid")
+
+ results: list[Company] = []
+ if grid is None:
+ return results
+
+ for row in grid.find_all("tr"):
+ data_ri = row.get("data-ri")
+ if data_ri is not None:
+ company_data = ResultParser.parse_result_row(row)
+ results.append(Company.model_validate(company_data))
+
+ return results
+
+ @staticmethod
+ def parse_result_row(row: Tag) -> dict[str, Any]:
+ """Parses a single search result row into a company dictionary.
+
+ This returns a dict that can be validated into a Company model.
+ Use parse_search_results() to get Company objects directly.
+
+ Args:
+ row: BeautifulSoup Tag representing a table row.
+
+ Returns:
+ Dictionary containing company information (ready for Company.model_validate).
+
+ Raises:
+ ParseError: If the result row has unexpected structure.
+ """
+ cells: list[str] = [cell.text.strip() for cell in row.find_all("td")]
+
+ if len(cells) < 6:
+ error_msg = f"Expected at least 6 cells in result row, got {len(cells)}"
+ raise ParseError(
+ error_msg,
+ html_snippet=str(row)[:500],
+ )
+
+ court = cells[1]
+ state = cells[3]
+ status = cells[4].strip()
+
+ # Extract register number
+ register_num = ResultParser._extract_register_number(court, state)
+
+ # Parse history entries
+ history_tuples = ResultParser._parse_history(cells)
+ history = [HistoryEntry(name=name, location=location) for name, location in history_tuples]
+
+ return {
+ "court": court,
+ "register_num": register_num,
+ "name": cells[2],
+ "state": state,
+ "status": status,
+ "statusCurrent": status.upper().replace(" ", "_"),
+ "documents": cells[5],
+ "history": history,
+ }
+
+ @staticmethod
+ def _extract_register_number(court: str, state: str) -> Optional[str]:
+ """Extracts and normalizes the register number from court string.
+
+ Args:
+ court: Court field containing the register number.
+ state: State, used to add appropriate suffix.
+
+ Returns:
+ Normalized register number, or None if not found.
+ """
+ reg_match = re.search(r"(HRA|HRB|GnR|VR|PR)\s*\d+(\s+[A-Z])?(?!\w)", court)
+
+ if not reg_match:
+ return None
+
+ register_num = reg_match.group(0)
+ reg_type = register_num.split()[0]
+ suffix = SUFFIX_MAP.get(state, {}).get(reg_type)
+ if suffix and not register_num.endswith(suffix):
+ register_num += suffix
+
+ return register_num
+
+ @staticmethod
+ def _parse_history(cells: list[str]) -> list[tuple[str, str]]:
+ """Parses history entries from cell data.
+
+ Args:
+ cells: List of cell text content.
+
+ Returns:
+ List of (name, location) tuples.
+ """
+ history: list[tuple[str, str]] = []
+ hist_start = 8
+
+ for i in range(hist_start, len(cells), 3):
+ if i + 1 >= len(cells):
+ break
+ if "Branches" in cells[i] or "Niederlassungen" in cells[i]:
+ break
+ history.append((cells[i], cells[i + 1]))
+
+ return history
+
+
+# Backward-compatible function aliases
+def parse_result(result: Tag) -> Company:
+ """Parses a single search result row into a Company object.
+
+ Deprecated: Use ResultParser.parse_result_row() and Company.model_validate() instead.
+ """
+ data = ResultParser.parse_result_row(result)
+ return Company.model_validate(data)
+
+
+def get_companies_in_searchresults(html: str) -> list[Company]:
+ """Extracts company records from search results HTML.
+
+ Deprecated: Use ResultParser.parse_search_results() instead.
+ """
+ return ResultParser.parse_search_results(html)
diff --git a/handelsregister/settings.py b/handelsregister/settings.py
new file mode 100644
index 00000000..f46e46e1
--- /dev/null
+++ b/handelsregister/settings.py
@@ -0,0 +1,81 @@
+"""Settings and configuration management using pydantic-settings."""
+
+from typing import Optional
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from yarl import URL
+
+
+class Settings(BaseSettings):
+ """Centralized configuration for the Handelsregister client.
+
+ All settings can be overridden via environment variables with the
+ HRG_ prefix. For example:
+
+ export HRG_CACHE_TTL_SECONDS=7200
+ export HRG_DEBUG=true
+ export HRG_CACHE_DIR=/tmp/hr-cache
+
+ Attributes:
+ cache_ttl_seconds: TTL for search result cache (default: 1 hour).
+ details_ttl_seconds: TTL for details cache (default: 24 hours).
+ base_url: Base URL for the Handelsregister portal.
+ request_timeout: HTTP request timeout in seconds.
+ max_retries: Maximum retry attempts for failed requests.
+ retry_wait_min: Minimum wait between retries in seconds.
+ retry_wait_max: Maximum wait between retries in seconds.
+ rate_limit_calls: Maximum requests per rate limit period.
+ rate_limit_period: Rate limit period in seconds (default: 1 hour).
+ cache_dir: Optional custom cache directory path.
+ debug: Enable debug logging.
+ """
+
+ model_config = SettingsConfigDict(
+ env_prefix="HRG_",
+ case_sensitive=False,
+ env_file=".env",
+ env_file_encoding="utf-8",
+ extra="ignore",
+ )
+
+ # Cache settings
+ cache_ttl_seconds: int = Field(default=3600, description="TTL for search cache in seconds")
+ details_ttl_seconds: int = Field(default=86400, description="TTL for details cache in seconds")
+ cache_dir: Optional[str] = Field(default=None, description="Custom cache directory path")
+
+ # Network settings
+ base_url: str = Field(default="https://www.handelsregister.de", description="Base URL")
+ request_timeout: int = Field(default=10, ge=1, le=60, description="Request timeout in seconds")
+
+ # Retry settings
+ max_retries: int = Field(default=3, ge=1, le=10, description="Maximum retry attempts")
+ retry_wait_min: int = Field(default=2, ge=1, description="Minimum retry wait in seconds")
+ retry_wait_max: int = Field(default=10, ge=1, description="Maximum retry wait in seconds")
+
+ # Rate limiting (per portal terms of service: max 60 requests/hour)
+ rate_limit_calls: int = Field(default=60, ge=1, description="Max requests per period")
+ rate_limit_period: int = Field(default=3600, description="Rate limit period in seconds")
+
+ # Debug settings
+ debug: bool = Field(default=False, description="Enable debug logging")
+
+ @property
+ def base_url_parsed(self) -> URL:
+ """Returns base_url as a yarl.URL object."""
+ return URL(self.base_url)
+
+
+# Initialize global settings (can be overridden by environment variables)
+settings = Settings()
+
+# Backward-compatible constants (use settings.xxx for new code)
+DEFAULT_CACHE_TTL_SECONDS: int = settings.cache_ttl_seconds
+DETAILS_CACHE_TTL_SECONDS: int = settings.details_ttl_seconds
+BASE_URL: URL = settings.base_url_parsed
+REQUEST_TIMEOUT: int = settings.request_timeout
+MAX_RETRIES: int = settings.max_retries
+RETRY_WAIT_MIN: int = settings.retry_wait_min
+RETRY_WAIT_MAX: int = settings.retry_wait_max
+RATE_LIMIT_CALLS: int = settings.rate_limit_calls
+RATE_LIMIT_PERIOD: int = settings.rate_limit_period
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 00000000..5bea98a3
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,194 @@
+site_name: Handelsregister Documentation
+site_description: Python package for the German commercial register portal
+site_author: BundesAPI Contributors
+site_url: https://bundesapi.github.io/handelsregister
+
+repo_name: bundesAPI/handelsregister
+repo_url: https://github.com/bundesAPI/handelsregister
+
+copyright: Copyright © 2025 BundesAPI Contributors
+
+theme:
+ name: material
+ language: en
+ palette:
+ - scheme: default
+ primary: indigo
+ accent: blue
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+ - scheme: slate
+ primary: indigo
+ accent: blue
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
+ font:
+ text: Fira Sans
+ code: Fira Code
+ features:
+ - navigation.tabs
+ - navigation.tabs.sticky
+ - navigation.sections
+ - navigation.expand
+ - navigation.path
+ - navigation.top
+ - navigation.footer
+ - search.suggest
+ - search.highlight
+ - content.code.copy
+ - content.code.annotate
+ - content.tabs.link
+ - toc.follow
+ icon:
+ repo: fontawesome/brands/github
+ logo: material/file-document-multiple
+
+plugins:
+ - search
+ - i18n:
+ docs_structure: suffix
+ fallback_to_default: true
+ reconfigure_material: true
+ reconfigure_search: true
+ languages:
+ - locale: en
+ default: true
+ name: English
+ build: true
+ - locale: de
+ name: Deutsch
+ build: true
+ nav_translations:
+ Home: Startseite
+ Getting Started: Erste Schritte
+ Installation: Installation
+ Quickstart: Schnellstart
+ User Guide: User Guide
+ Overview: Ăbersicht
+ Using as Library: Als Library verwenden
+ Command Line (CLI): Kommandozeile (CLI)
+ Fetching Details: Unternehmensdetails abrufen
+ Caching: Caching
+ API Reference: Quellcodebeschreibung
+ Public Functions: Ăffentliche Funktionen
+ Classes: Klassen
+ Data Models: Datenmodelle
+ Exceptions: Exceptions
+ Reference Tables: Referenztabellen
+ State Codes: BundeslÀnder-Codes
+ Register Types: Registerarten
+ Legal Forms: Rechtsformen
+ API Parameters: API-Parameter
+ Examples: Beispiele
+ Simple: Einfache
+ Advanced: Fortgeschritten
+ Integrations: Integrationen
+ Legal Notice: Rechtliche Hinweise
+ Changelog: Changelog
+ - mkdocstrings:
+ default_handler: python
+ handlers:
+ python:
+ paths: ["."]
+ options:
+ docstring_style: google
+ show_source: true
+ show_root_heading: true
+ show_root_full_path: false
+ show_symbol_type_heading: true
+ show_symbol_type_toc: true
+ members_order: source
+ show_signature_annotations: true
+ separate_signature: true
+ signature_crossrefs: true
+ merge_init_into_class: true
+ docstring_section_style: spacy
+ heading_level: 2
+
+markdown_extensions:
+ - abbr
+ - admonition
+ - attr_list
+ - def_list
+ - footnotes
+ - md_in_html
+ - tables
+ - toc:
+ permalink: true
+ title: On this page
+ - pymdownx.arithmatex:
+ generic: true
+ - pymdownx.betterem:
+ smart_enable: all
+ - pymdownx.caret
+ - pymdownx.details
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+ - pymdownx.highlight:
+ anchor_linenums: true
+ line_spans: __span
+ pygments_lang_class: true
+ - pymdownx.inlinehilite
+ - pymdownx.keys
+ - pymdownx.magiclink:
+ repo_url_shorthand: true
+ user: bundesAPI
+ repo: handelsregister
+ - pymdownx.mark
+ - pymdownx.smartsymbols
+ - pymdownx.superfences:
+ custom_fences:
+ - name: mermaid
+ class: mermaid
+ format: !!python/name:pymdownx.superfences.fence_code_format
+ - pymdownx.tabbed:
+ alternate_style: true
+ - pymdownx.tasklist:
+ custom_checkbox: true
+ - pymdownx.tilde
+
+extra:
+ social:
+ - icon: fontawesome/brands/github
+ link: https://github.com/bundesAPI
+ name: BundesAPI on GitHub
+ generator: false
+ alternate:
+ - name: English
+ link: /handelsregister/
+ lang: en
+ - name: Deutsch
+ link: /handelsregister/de/
+ lang: de
+
+nav:
+ - Home: index.md
+ - Getting Started:
+ - Installation: installation.md
+ - Quickstart: quickstart.md
+ - User Guide:
+ - Overview: guide/index.md
+ - Using as Library: guide/library.md
+ - Command Line (CLI): guide/cli.md
+ - Fetching Details: guide/details.md
+ - Caching: guide/cache.md
+ - API Reference:
+ - Overview: api/index.md
+ - Public Functions: api/functions.md
+ - Classes: api/classes.md
+ - Data Models: api/models.md
+ - Exceptions: api/exceptions.md
+ - Reference Tables:
+ - State Codes: reference/states.md
+ - Register Types: reference/registers.md
+ - Legal Forms: reference/legal-forms.md
+ - API Parameters: reference/parameters.md
+ - Examples:
+ - Simple Examples: examples/simple.md
+ - Advanced: examples/advanced.md
+ - Integrations: examples/integrations.md
+ - Legal Notice: legal.md
+ - Changelog: changelog.md
diff --git a/poetry.lock b/poetry.lock
deleted file mode 100644
index 4538f8b5..00000000
--- a/poetry.lock
+++ /dev/null
@@ -1,508 +0,0 @@
-[[package]]
-name = "beautifulsoup4"
-version = "4.11.1"
-description = "Screen-scraping library"
-category = "main"
-optional = false
-python-versions = ">=3.6.0"
-
-[package.dependencies]
-soupsieve = ">1.2"
-
-[package.extras]
-html5lib = ["html5lib"]
-lxml = ["lxml"]
-
-[[package]]
-name = "black"
-version = "22.6.0"
-description = "The uncompromising code formatter."
-category = "dev"
-optional = false
-python-versions = ">=3.6.2"
-
-[package.dependencies]
-click = ">=8.0.0"
-dataclasses = {version = ">=0.6", markers = "python_version < \"3.7\""}
-mypy-extensions = ">=0.4.3"
-pathspec = ">=0.9.0"
-platformdirs = ">=2"
-tomli = {version = ">=1.1.0", markers = "python_full_version < \"3.11.0a7\""}
-typed-ast = {version = ">=1.4.2", markers = "python_version < \"3.8\" and implementation_name == \"cpython\""}
-typing-extensions = {version = ">=3.10.0.0", markers = "python_version < \"3.10\""}
-
-[package.extras]
-colorama = ["colorama (>=0.4.3)"]
-d = ["aiohttp (>=3.7.4)"]
-jupyter = ["ipython (>=7.8.0)", "tokenize-rt (>=3.2.0)"]
-uvloop = ["uvloop (>=0.15.2)"]
-
-[[package]]
-name = "certifi"
-version = "2022.6.15"
-description = "Python package for providing Mozilla's CA Bundle."
-category = "main"
-optional = false
-python-versions = ">=3.6"
-
-[[package]]
-name = "charset-normalizer"
-version = "2.0.12"
-description = "The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet."
-category = "main"
-optional = false
-python-versions = ">=3.5.0"
-
-[package.extras]
-unicode_backport = ["unicodedata2"]
-
-[[package]]
-name = "click"
-version = "8.0.4"
-description = "Composable command line interface toolkit"
-category = "dev"
-optional = false
-python-versions = ">=3.6"
-
-[package.dependencies]
-colorama = {version = "*", markers = "platform_system == \"Windows\""}
-importlib-metadata = {version = "*", markers = "python_version < \"3.8\""}
-
-[[package]]
-name = "colorama"
-version = "0.4.5"
-description = "Cross-platform colored terminal text."
-category = "dev"
-optional = false
-python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
-
-[[package]]
-name = "dataclasses"
-version = "0.8"
-description = "A backport of the dataclasses module for Python 3.6"
-category = "dev"
-optional = false
-python-versions = ">=3.6, <3.7"
-
-[[package]]
-name = "html5lib"
-version = "1.1"
-description = "HTML parser based on the WHATWG HTML specification"
-category = "main"
-optional = false
-python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
-
-[package.dependencies]
-six = ">=1.9"
-webencodings = "*"
-
-[package.extras]
-lxml = ["lxml"]
-genshi = ["genshi"]
-chardet = ["chardet (>=2.2)"]
-all = ["lxml", "chardet (>=2.2)", "genshi"]
-
-[[package]]
-name = "idna"
-version = "3.3"
-description = "Internationalized Domain Names in Applications (IDNA)"
-category = "main"
-optional = false
-python-versions = ">=3.5"
-
-[[package]]
-name = "importlib-metadata"
-version = "4.8.3"
-description = "Read metadata from Python packages"
-category = "dev"
-optional = false
-python-versions = ">=3.6"
-
-[package.dependencies]
-typing-extensions = {version = ">=3.6.4", markers = "python_version < \"3.8\""}
-zipp = ">=0.5"
-
-[package.extras]
-docs = ["sphinx", "jaraco.packaging (>=8.2)", "rst.linker (>=1.9)"]
-perf = ["ipython"]
-testing = ["pytest (>=6)", "pytest-checkdocs (>=2.4)", "pytest-flake8", "pytest-cov", "pytest-enabler (>=1.0.1)", "packaging", "pep517", "pyfakefs", "flufl.flake8", "pytest-perf (>=0.9.2)", "pytest-black (>=0.3.7)", "pytest-mypy", "importlib-resources (>=1.3)"]
-
-[[package]]
-name = "lxml"
-version = "4.9.1"
-description = "Powerful and Pythonic XML processing library combining libxml2/libxslt with the ElementTree API."
-category = "main"
-optional = false
-python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, != 3.4.*"
-
-[package.extras]
-cssselect = ["cssselect (>=0.7)"]
-html5 = ["html5lib"]
-htmlsoup = ["beautifulsoup4"]
-source = ["Cython (>=0.29.7)"]
-
-[[package]]
-name = "mechanicalsoup"
-version = "1.1.0"
-description = "A Python library for automating interaction with websites"
-category = "main"
-optional = false
-python-versions = ">=3.6"
-
-[package.dependencies]
-beautifulsoup4 = ">=4.7"
-lxml = "*"
-requests = ">=2.22.0"
-
-[[package]]
-name = "mechanize"
-version = "0.4.8"
-description = "Stateful, programmatic web browsing"
-category = "main"
-optional = false
-python-versions = "*"
-
-[package.dependencies]
-html5lib = ">=0.999999999"
-
-[package.extras]
-binarytest = ["lxml", "html5-parser"]
-fast = ["html5-parser (>=0.4.4)"]
-test = ["twisted", "service-identity", "six", "html5lib"]
-
-[[package]]
-name = "mypy-extensions"
-version = "0.4.3"
-description = "Experimental type system extensions for programs checked with the mypy typechecker."
-category = "dev"
-optional = false
-python-versions = "*"
-
-[[package]]
-name = "pathspec"
-version = "0.9.0"
-description = "Utility library for gitignore style pattern matching of file paths."
-category = "dev"
-optional = false
-python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,>=2.7"
-
-[[package]]
-name = "platformdirs"
-version = "2.4.0"
-description = "A small Python module for determining appropriate platform-specific dirs, e.g. a \"user data dir\"."
-category = "dev"
-optional = false
-python-versions = ">=3.6"
-
-[package.extras]
-test = ["pytest-mock (>=3.6)", "pytest-cov (>=2.7)", "pytest (>=6)", "appdirs (==1.4.4)"]
-docs = ["sphinx-autodoc-typehints (>=1.12)", "proselint (>=0.10.2)", "furo (>=2021.7.5b38)", "Sphinx (>=4)"]
-
-[[package]]
-name = "requests"
-version = "2.27.1"
-description = "Python HTTP for Humans."
-category = "main"
-optional = false
-python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*"
-
-[package.dependencies]
-certifi = ">=2017.4.17"
-charset-normalizer = {version = ">=2.0.0,<2.1.0", markers = "python_version >= \"3\""}
-idna = {version = ">=2.5,<4", markers = "python_version >= \"3\""}
-urllib3 = ">=1.21.1,<1.27"
-
-[package.extras]
-socks = ["PySocks (>=1.5.6,!=1.5.7)", "win-inet-pton"]
-use_chardet_on_py3 = ["chardet (>=3.0.2,<5)"]
-
-[[package]]
-name = "six"
-version = "1.16.0"
-description = "Python 2 and 3 compatibility utilities"
-category = "main"
-optional = false
-python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*"
-
-[[package]]
-name = "soupsieve"
-version = "2.3.2.post1"
-description = "A modern CSS selector implementation for Beautiful Soup."
-category = "main"
-optional = false
-python-versions = ">=3.6"
-
-[[package]]
-name = "tomli"
-version = "1.2.3"
-description = "A lil' TOML parser"
-category = "dev"
-optional = false
-python-versions = ">=3.6"
-
-[[package]]
-name = "typed-ast"
-version = "1.5.4"
-description = "a fork of Python 2 and 3 ast modules with type comment support"
-category = "dev"
-optional = false
-python-versions = ">=3.6"
-
-[[package]]
-name = "typing-extensions"
-version = "4.1.1"
-description = "Backported and Experimental Type Hints for Python 3.6+"
-category = "dev"
-optional = false
-python-versions = ">=3.6"
-
-[[package]]
-name = "urllib3"
-version = "1.26.11"
-description = "HTTP library with thread-safe connection pooling, file post, and more."
-category = "main"
-optional = false
-python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, <4"
-
-[package.extras]
-brotli = ["brotlicffi (>=0.8.0)", "brotli (>=1.0.9)", "brotlipy (>=0.6.0)"]
-secure = ["pyOpenSSL (>=0.14)", "cryptography (>=1.3.4)", "idna (>=2.0.0)", "certifi", "ipaddress"]
-socks = ["PySocks (>=1.5.6,!=1.5.7,<2.0)"]
-
-[[package]]
-name = "webencodings"
-version = "0.5.1"
-description = "Character encoding aliases for legacy web content"
-category = "main"
-optional = false
-python-versions = "*"
-
-[[package]]
-name = "zipp"
-version = "3.6.0"
-description = "Backport of pathlib-compatible object wrapper for zip files"
-category = "dev"
-optional = false
-python-versions = ">=3.6"
-
-[package.extras]
-docs = ["sphinx", "jaraco.packaging (>=8.2)", "rst.linker (>=1.9)"]
-testing = ["pytest (>=4.6)", "pytest-checkdocs (>=2.4)", "pytest-flake8", "pytest-cov", "pytest-enabler (>=1.0.1)", "jaraco.itertools", "func-timeout", "pytest-black (>=0.3.7)", "pytest-mypy"]
-
-[metadata]
-lock-version = "1.1"
-python-versions = ">3.6.2,<4"
-content-hash = "5996eb819fc4927b783b41546d165d92235ed12738ae3760bae1db571d1bb693"
-
-[metadata.files]
-beautifulsoup4 = [
- {file = "beautifulsoup4-4.11.1-py3-none-any.whl", hash = "sha256:58d5c3d29f5a36ffeb94f02f0d786cd53014cf9b3b3951d42e0080d8a9498d30"},
- {file = "beautifulsoup4-4.11.1.tar.gz", hash = "sha256:ad9aa55b65ef2808eb405f46cf74df7fcb7044d5cbc26487f96eb2ef2e436693"},
-]
-black = [
- {file = "black-22.6.0-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:f586c26118bc6e714ec58c09df0157fe2d9ee195c764f630eb0d8e7ccce72e69"},
- {file = "black-22.6.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:b270a168d69edb8b7ed32c193ef10fd27844e5c60852039599f9184460ce0807"},
- {file = "black-22.6.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:6797f58943fceb1c461fb572edbe828d811e719c24e03375fd25170ada53825e"},
- {file = "black-22.6.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c85928b9d5f83b23cee7d0efcb310172412fbf7cb9d9ce963bd67fd141781def"},
- {file = "black-22.6.0-cp310-cp310-win_amd64.whl", hash = "sha256:f6fe02afde060bbeef044af7996f335fbe90b039ccf3f5eb8f16df8b20f77666"},
- {file = "black-22.6.0-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:cfaf3895a9634e882bf9d2363fed5af8888802d670f58b279b0bece00e9a872d"},
- {file = "black-22.6.0-cp36-cp36m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:94783f636bca89f11eb5d50437e8e17fbc6a929a628d82304c80fa9cd945f256"},
- {file = "black-22.6.0-cp36-cp36m-win_amd64.whl", hash = "sha256:2ea29072e954a4d55a2ff58971b83365eba5d3d357352a07a7a4df0d95f51c78"},
- {file = "black-22.6.0-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:e439798f819d49ba1c0bd9664427a05aab79bfba777a6db94fd4e56fae0cb849"},
- {file = "black-22.6.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:187d96c5e713f441a5829e77120c269b6514418f4513a390b0499b0987f2ff1c"},
- {file = "black-22.6.0-cp37-cp37m-win_amd64.whl", hash = "sha256:074458dc2f6e0d3dab7928d4417bb6957bb834434516f21514138437accdbe90"},
- {file = "black-22.6.0-cp38-cp38-macosx_10_9_universal2.whl", hash = "sha256:a218d7e5856f91d20f04e931b6f16d15356db1c846ee55f01bac297a705ca24f"},
- {file = "black-22.6.0-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:568ac3c465b1c8b34b61cd7a4e349e93f91abf0f9371eda1cf87194663ab684e"},
- {file = "black-22.6.0-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:6c1734ab264b8f7929cef8ae5f900b85d579e6cbfde09d7387da8f04771b51c6"},
- {file = "black-22.6.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c9a3ac16efe9ec7d7381ddebcc022119794872abce99475345c5a61aa18c45ad"},
- {file = "black-22.6.0-cp38-cp38-win_amd64.whl", hash = "sha256:b9fd45787ba8aa3f5e0a0a98920c1012c884622c6c920dbe98dbd05bc7c70fbf"},
- {file = "black-22.6.0-cp39-cp39-macosx_10_9_universal2.whl", hash = "sha256:7ba9be198ecca5031cd78745780d65a3f75a34b2ff9be5837045dce55db83d1c"},
- {file = "black-22.6.0-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:a3db5b6409b96d9bd543323b23ef32a1a2b06416d525d27e0f67e74f1446c8f2"},
- {file = "black-22.6.0-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:560558527e52ce8afba936fcce93a7411ab40c7d5fe8c2463e279e843c0328ee"},
- {file = "black-22.6.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b154e6bbde1e79ea3260c4b40c0b7b3109ffcdf7bc4ebf8859169a6af72cd70b"},
- {file = "black-22.6.0-cp39-cp39-win_amd64.whl", hash = "sha256:4af5bc0e1f96be5ae9bd7aaec219c901a94d6caa2484c21983d043371c733fc4"},
- {file = "black-22.6.0-py3-none-any.whl", hash = "sha256:ac609cf8ef5e7115ddd07d85d988d074ed00e10fbc3445aee393e70164a2219c"},
- {file = "black-22.6.0.tar.gz", hash = "sha256:6c6d39e28aed379aec40da1c65434c77d75e65bb59a1e1c283de545fb4e7c6c9"},
-]
-certifi = [
- {file = "certifi-2022.6.15-py3-none-any.whl", hash = "sha256:fe86415d55e84719d75f8b69414f6438ac3547d2078ab91b67e779ef69378412"},
- {file = "certifi-2022.6.15.tar.gz", hash = "sha256:84c85a9078b11105f04f3036a9482ae10e4621616db313fe045dd24743a0820d"},
-]
-charset-normalizer = [
- {file = "charset-normalizer-2.0.12.tar.gz", hash = "sha256:2857e29ff0d34db842cd7ca3230549d1a697f96ee6d3fb071cfa6c7393832597"},
- {file = "charset_normalizer-2.0.12-py3-none-any.whl", hash = "sha256:6881edbebdb17b39b4eaaa821b438bf6eddffb4468cf344f09f89def34a8b1df"},
-]
-click = [
- {file = "click-8.0.4-py3-none-any.whl", hash = "sha256:6a7a62563bbfabfda3a38f3023a1db4a35978c0abd76f6c9605ecd6554d6d9b1"},
- {file = "click-8.0.4.tar.gz", hash = "sha256:8458d7b1287c5fb128c90e23381cf99dcde74beaf6c7ff6384ce84d6fe090adb"},
-]
-colorama = [
- {file = "colorama-0.4.5-py2.py3-none-any.whl", hash = "sha256:854bf444933e37f5824ae7bfc1e98d5bce2ebe4160d46b5edf346a89358e99da"},
- {file = "colorama-0.4.5.tar.gz", hash = "sha256:e6c6b4334fc50988a639d9b98aa429a0b57da6e17b9a44f0451f930b6967b7a4"},
-]
-dataclasses = [
- {file = "dataclasses-0.8-py3-none-any.whl", hash = "sha256:0201d89fa866f68c8ebd9d08ee6ff50c0b255f8ec63a71c16fda7af82bb887bf"},
- {file = "dataclasses-0.8.tar.gz", hash = "sha256:8479067f342acf957dc82ec415d355ab5edb7e7646b90dc6e2fd1d96ad084c97"},
-]
-html5lib = [
- {file = "html5lib-1.1-py2.py3-none-any.whl", hash = "sha256:0d78f8fde1c230e99fe37986a60526d7049ed4bf8a9fadbad5f00e22e58e041d"},
- {file = "html5lib-1.1.tar.gz", hash = "sha256:b2e5b40261e20f354d198eae92afc10d750afb487ed5e50f9c4eaf07c184146f"},
-]
-idna = [
- {file = "idna-3.3-py3-none-any.whl", hash = "sha256:84d9dd047ffa80596e0f246e2eab0b391788b0503584e8945f2368256d2735ff"},
- {file = "idna-3.3.tar.gz", hash = "sha256:9d643ff0a55b762d5cdb124b8eaa99c66322e2157b69160bc32796e824360e6d"},
-]
-importlib-metadata = [
- {file = "importlib_metadata-4.8.3-py3-none-any.whl", hash = "sha256:65a9576a5b2d58ca44d133c42a241905cc45e34d2c06fd5ba2bafa221e5d7b5e"},
- {file = "importlib_metadata-4.8.3.tar.gz", hash = "sha256:766abffff765960fcc18003801f7044eb6755ffae4521c8e8ce8e83b9c9b0668"},
-]
-lxml = [
- {file = "lxml-4.9.1-cp27-cp27m-macosx_10_15_x86_64.whl", hash = "sha256:98cafc618614d72b02185ac583c6f7796202062c41d2eeecdf07820bad3295ed"},
- {file = "lxml-4.9.1-cp27-cp27m-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:c62e8dd9754b7debda0c5ba59d34509c4688f853588d75b53c3791983faa96fc"},
- {file = "lxml-4.9.1-cp27-cp27m-manylinux_2_5_x86_64.manylinux1_x86_64.whl", hash = "sha256:21fb3d24ab430fc538a96e9fbb9b150029914805d551deeac7d7822f64631dfc"},
- {file = "lxml-4.9.1-cp27-cp27m-win32.whl", hash = "sha256:86e92728ef3fc842c50a5cb1d5ba2bc66db7da08a7af53fb3da79e202d1b2cd3"},
- {file = "lxml-4.9.1-cp27-cp27m-win_amd64.whl", hash = "sha256:4cfbe42c686f33944e12f45a27d25a492cc0e43e1dc1da5d6a87cbcaf2e95627"},
- {file = "lxml-4.9.1-cp27-cp27mu-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:dad7b164905d3e534883281c050180afcf1e230c3d4a54e8038aa5cfcf312b84"},
- {file = "lxml-4.9.1-cp27-cp27mu-manylinux_2_5_x86_64.manylinux1_x86_64.whl", hash = "sha256:a614e4afed58c14254e67862456d212c4dcceebab2eaa44d627c2ca04bf86837"},
- {file = "lxml-4.9.1-cp310-cp310-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_24_i686.whl", hash = "sha256:f9ced82717c7ec65a67667bb05865ffe38af0e835cdd78728f1209c8fffe0cad"},
- {file = "lxml-4.9.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl", hash = "sha256:d9fc0bf3ff86c17348dfc5d322f627d78273eba545db865c3cd14b3f19e57fa5"},
- {file = "lxml-4.9.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_24_x86_64.whl", hash = "sha256:e5f66bdf0976ec667fc4594d2812a00b07ed14d1b44259d19a41ae3fff99f2b8"},
- {file = "lxml-4.9.1-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:fe17d10b97fdf58155f858606bddb4e037b805a60ae023c009f760d8361a4eb8"},
- {file = "lxml-4.9.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:8caf4d16b31961e964c62194ea3e26a0e9561cdf72eecb1781458b67ec83423d"},
- {file = "lxml-4.9.1-cp310-cp310-win32.whl", hash = "sha256:4780677767dd52b99f0af1f123bc2c22873d30b474aa0e2fc3fe5e02217687c7"},
- {file = "lxml-4.9.1-cp310-cp310-win_amd64.whl", hash = "sha256:b122a188cd292c4d2fcd78d04f863b789ef43aa129b233d7c9004de08693728b"},
- {file = "lxml-4.9.1-cp311-cp311-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_24_i686.whl", hash = "sha256:be9eb06489bc975c38706902cbc6888f39e946b81383abc2838d186f0e8b6a9d"},
- {file = "lxml-4.9.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_24_x86_64.whl", hash = "sha256:f1be258c4d3dc609e654a1dc59d37b17d7fef05df912c01fc2e15eb43a9735f3"},
- {file = "lxml-4.9.1-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:927a9dd016d6033bc12e0bf5dee1dde140235fc8d0d51099353c76081c03dc29"},
- {file = "lxml-4.9.1-cp35-cp35m-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:9232b09f5efee6a495a99ae6824881940d6447debe272ea400c02e3b68aad85d"},
- {file = "lxml-4.9.1-cp35-cp35m-manylinux_2_5_x86_64.manylinux1_x86_64.whl", hash = "sha256:04da965dfebb5dac2619cb90fcf93efdb35b3c6994fea58a157a834f2f94b318"},
- {file = "lxml-4.9.1-cp35-cp35m-win32.whl", hash = "sha256:4d5bae0a37af799207140652a700f21a85946f107a199bcb06720b13a4f1f0b7"},
- {file = "lxml-4.9.1-cp35-cp35m-win_amd64.whl", hash = "sha256:4878e667ebabe9b65e785ac8da4d48886fe81193a84bbe49f12acff8f7a383a4"},
- {file = "lxml-4.9.1-cp36-cp36m-macosx_10_15_x86_64.whl", hash = "sha256:1355755b62c28950f9ce123c7a41460ed9743c699905cbe664a5bcc5c9c7c7fb"},
- {file = "lxml-4.9.1-cp36-cp36m-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_24_i686.whl", hash = "sha256:bcaa1c495ce623966d9fc8a187da80082334236a2a1c7e141763ffaf7a405067"},
- {file = "lxml-4.9.1-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6eafc048ea3f1b3c136c71a86db393be36b5b3d9c87b1c25204e7d397cee9536"},
- {file = "lxml-4.9.1-cp36-cp36m-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_24_x86_64.whl", hash = "sha256:13c90064b224e10c14dcdf8086688d3f0e612db53766e7478d7754703295c7c8"},
- {file = "lxml-4.9.1-cp36-cp36m-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:206a51077773c6c5d2ce1991327cda719063a47adc02bd703c56a662cdb6c58b"},
- {file = "lxml-4.9.1-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.whl", hash = "sha256:e8f0c9d65da595cfe91713bc1222af9ecabd37971762cb830dea2fc3b3bb2acf"},
- {file = "lxml-4.9.1-cp36-cp36m-musllinux_1_1_aarch64.whl", hash = "sha256:8f0a4d179c9a941eb80c3a63cdb495e539e064f8054230844dcf2fcb812b71d3"},
- {file = "lxml-4.9.1-cp36-cp36m-musllinux_1_1_x86_64.whl", hash = "sha256:830c88747dce8a3e7525defa68afd742b4580df6aa2fdd6f0855481e3994d391"},
- {file = "lxml-4.9.1-cp36-cp36m-win32.whl", hash = "sha256:1e1cf47774373777936c5aabad489fef7b1c087dcd1f426b621fda9dcc12994e"},
- {file = "lxml-4.9.1-cp36-cp36m-win_amd64.whl", hash = "sha256:5974895115737a74a00b321e339b9c3f45c20275d226398ae79ac008d908bff7"},
- {file = "lxml-4.9.1-cp37-cp37m-macosx_10_15_x86_64.whl", hash = "sha256:1423631e3d51008871299525b541413c9b6c6423593e89f9c4cfbe8460afc0a2"},
- {file = "lxml-4.9.1-cp37-cp37m-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_24_i686.whl", hash = "sha256:2aaf6a0a6465d39b5ca69688fce82d20088c1838534982996ec46633dc7ad6cc"},
- {file = "lxml-4.9.1-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl", hash = "sha256:9f36de4cd0c262dd9927886cc2305aa3f2210db437aa4fed3fb4940b8bf4592c"},
- {file = "lxml-4.9.1-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_24_x86_64.whl", hash = "sha256:ae06c1e4bc60ee076292e582a7512f304abdf6c70db59b56745cca1684f875a4"},
- {file = "lxml-4.9.1-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:57e4d637258703d14171b54203fd6822fda218c6c2658a7d30816b10995f29f3"},
- {file = "lxml-4.9.1-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.whl", hash = "sha256:6d279033bf614953c3fc4a0aa9ac33a21e8044ca72d4fa8b9273fe75359d5cca"},
- {file = "lxml-4.9.1-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:a60f90bba4c37962cbf210f0188ecca87daafdf60271f4c6948606e4dabf8785"},
- {file = "lxml-4.9.1-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:6ca2264f341dd81e41f3fffecec6e446aa2121e0b8d026fb5130e02de1402785"},
- {file = "lxml-4.9.1-cp37-cp37m-win32.whl", hash = "sha256:27e590352c76156f50f538dbcebd1925317a0f70540f7dc8c97d2931c595783a"},
- {file = "lxml-4.9.1-cp37-cp37m-win_amd64.whl", hash = "sha256:eea5d6443b093e1545ad0210e6cf27f920482bfcf5c77cdc8596aec73523bb7e"},
- {file = "lxml-4.9.1-cp38-cp38-macosx_10_15_x86_64.whl", hash = "sha256:f05251bbc2145349b8d0b77c0d4e5f3b228418807b1ee27cefb11f69ed3d233b"},
- {file = "lxml-4.9.1-cp38-cp38-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_24_i686.whl", hash = "sha256:487c8e61d7acc50b8be82bda8c8d21d20e133c3cbf41bd8ad7eb1aaeb3f07c97"},
- {file = "lxml-4.9.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl", hash = "sha256:8d1a92d8e90b286d491e5626af53afef2ba04da33e82e30744795c71880eaa21"},
- {file = "lxml-4.9.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_24_x86_64.whl", hash = "sha256:b570da8cd0012f4af9fa76a5635cd31f707473e65a5a335b186069d5c7121ff2"},
- {file = "lxml-4.9.1-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:5ef87fca280fb15342726bd5f980f6faf8b84a5287fcc2d4962ea8af88b35130"},
- {file = "lxml-4.9.1-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.whl", hash = "sha256:93e414e3206779ef41e5ff2448067213febf260ba747fc65389a3ddaa3fb8715"},
- {file = "lxml-4.9.1-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:6653071f4f9bac46fbc30f3c7838b0e9063ee335908c5d61fb7a4a86c8fd2036"},
- {file = "lxml-4.9.1-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:32a73c53783becdb7eaf75a2a1525ea8e49379fb7248c3eeefb9412123536387"},
- {file = "lxml-4.9.1-cp38-cp38-win32.whl", hash = "sha256:1a7c59c6ffd6ef5db362b798f350e24ab2cfa5700d53ac6681918f314a4d3b94"},
- {file = "lxml-4.9.1-cp38-cp38-win_amd64.whl", hash = "sha256:1436cf0063bba7888e43f1ba8d58824f085410ea2025befe81150aceb123e345"},
- {file = "lxml-4.9.1-cp39-cp39-macosx_10_15_x86_64.whl", hash = "sha256:4beea0f31491bc086991b97517b9683e5cfb369205dac0148ef685ac12a20a67"},
- {file = "lxml-4.9.1-cp39-cp39-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_24_i686.whl", hash = "sha256:41fb58868b816c202e8881fd0f179a4644ce6e7cbbb248ef0283a34b73ec73bb"},
- {file = "lxml-4.9.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl", hash = "sha256:bd34f6d1810d9354dc7e35158aa6cc33456be7706df4420819af6ed966e85448"},
- {file = "lxml-4.9.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_24_x86_64.whl", hash = "sha256:edffbe3c510d8f4bf8640e02ca019e48a9b72357318383ca60e3330c23aaffc7"},
- {file = "lxml-4.9.1-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:6d949f53ad4fc7cf02c44d6678e7ff05ec5f5552b235b9e136bd52e9bf730b91"},
- {file = "lxml-4.9.1-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.whl", hash = "sha256:079b68f197c796e42aa80b1f739f058dcee796dc725cc9a1be0cdb08fc45b000"},
- {file = "lxml-4.9.1-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:9c3a88d20e4fe4a2a4a84bf439a5ac9c9aba400b85244c63a1ab7088f85d9d25"},
- {file = "lxml-4.9.1-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:4e285b5f2bf321fc0857b491b5028c5f276ec0c873b985d58d7748ece1d770dd"},
- {file = "lxml-4.9.1-cp39-cp39-win32.whl", hash = "sha256:ef72013e20dd5ba86a8ae1aed7f56f31d3374189aa8b433e7b12ad182c0d2dfb"},
- {file = "lxml-4.9.1-cp39-cp39-win_amd64.whl", hash = "sha256:10d2017f9150248563bb579cd0d07c61c58da85c922b780060dcc9a3aa9f432d"},
- {file = "lxml-4.9.1-pp37-pypy37_pp73-macosx_10_15_x86_64.whl", hash = "sha256:0538747a9d7827ce3e16a8fdd201a99e661c7dee3c96c885d8ecba3c35d1032c"},
- {file = "lxml-4.9.1-pp37-pypy37_pp73-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_24_i686.whl", hash = "sha256:0645e934e940107e2fdbe7c5b6fb8ec6232444260752598bc4d09511bd056c0b"},
- {file = "lxml-4.9.1-pp37-pypy37_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_24_x86_64.whl", hash = "sha256:6daa662aba22ef3258934105be2dd9afa5bb45748f4f702a3b39a5bf53a1f4dc"},
- {file = "lxml-4.9.1-pp38-pypy38_pp73-macosx_10_15_x86_64.whl", hash = "sha256:603a464c2e67d8a546ddaa206d98e3246e5db05594b97db844c2f0a1af37cf5b"},
- {file = "lxml-4.9.1-pp38-pypy38_pp73-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_24_i686.whl", hash = "sha256:c4b2e0559b68455c085fb0f6178e9752c4be3bba104d6e881eb5573b399d1eb2"},
- {file = "lxml-4.9.1-pp38-pypy38_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_24_x86_64.whl", hash = "sha256:0f3f0059891d3254c7b5fb935330d6db38d6519ecd238ca4fce93c234b4a0f73"},
- {file = "lxml-4.9.1-pp39-pypy39_pp73-manylinux_2_12_i686.manylinux2010_i686.manylinux_2_24_i686.whl", hash = "sha256:c852b1530083a620cb0de5f3cd6826f19862bafeaf77586f1aef326e49d95f0c"},
- {file = "lxml-4.9.1-pp39-pypy39_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_24_x86_64.whl", hash = "sha256:287605bede6bd36e930577c5925fcea17cb30453d96a7b4c63c14a257118dbb9"},
- {file = "lxml-4.9.1.tar.gz", hash = "sha256:fe749b052bb7233fe5d072fcb549221a8cb1a16725c47c37e42b0b9cb3ff2c3f"},
-]
-mechanicalsoup = [
- {file = "MechanicalSoup-1.1.0-py3-none-any.whl", hash = "sha256:0685465c449018f8bce9055b74cf60fbec2ada8391c03aa179586edc6b5a5ee8"},
- {file = "MechanicalSoup-1.1.0.tar.gz", hash = "sha256:2be8ad9b7571990fce16d0f99a741779921510eb133d3a4dfdeccb2ff2cd00e5"},
-]
-mechanize = [
- {file = "mechanize-0.4.8-py2.py3-none-any.whl", hash = "sha256:961fd171b5eb37a7578fce62ba81ba85803dff3c5ba4ac24f6f569ae27198439"},
- {file = "mechanize-0.4.8.tar.gz", hash = "sha256:5e86ac0777357e006eb04cd28f7ed9f811d48dffa603d3891ac6d2b92280dc91"},
-]
-mypy-extensions = [
- {file = "mypy_extensions-0.4.3-py2.py3-none-any.whl", hash = "sha256:090fedd75945a69ae91ce1303b5824f428daf5a028d2f6ab8a299250a846f15d"},
- {file = "mypy_extensions-0.4.3.tar.gz", hash = "sha256:2d82818f5bb3e369420cb3c4060a7970edba416647068eb4c5343488a6c604a8"},
-]
-pathspec = [
- {file = "pathspec-0.9.0-py2.py3-none-any.whl", hash = "sha256:7d15c4ddb0b5c802d161efc417ec1a2558ea2653c2e8ad9c19098201dc1c993a"},
- {file = "pathspec-0.9.0.tar.gz", hash = "sha256:e564499435a2673d586f6b2130bb5b95f04a3ba06f81b8f895b651a3c76aabb1"},
-]
-platformdirs = [
- {file = "platformdirs-2.4.0-py3-none-any.whl", hash = "sha256:8868bbe3c3c80d42f20156f22e7131d2fb321f5bc86a2a345375c6481a67021d"},
- {file = "platformdirs-2.4.0.tar.gz", hash = "sha256:367a5e80b3d04d2428ffa76d33f124cf11e8fff2acdaa9b43d545f5c7d661ef2"},
-]
-requests = [
- {file = "requests-2.27.1-py2.py3-none-any.whl", hash = "sha256:f22fa1e554c9ddfd16e6e41ac79759e17be9e492b3587efa038054674760e72d"},
- {file = "requests-2.27.1.tar.gz", hash = "sha256:68d7c56fd5a8999887728ef304a6d12edc7be74f1cfa47714fc8b414525c9a61"},
-]
-six = [
- {file = "six-1.16.0-py2.py3-none-any.whl", hash = "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"},
- {file = "six-1.16.0.tar.gz", hash = "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926"},
-]
-soupsieve = [
- {file = "soupsieve-2.3.2.post1-py3-none-any.whl", hash = "sha256:3b2503d3c7084a42b1ebd08116e5f81aadfaea95863628c80a3b774a11b7c759"},
- {file = "soupsieve-2.3.2.post1.tar.gz", hash = "sha256:fc53893b3da2c33de295667a0e19f078c14bf86544af307354de5fcf12a3f30d"},
-]
-tomli = [
- {file = "tomli-1.2.3-py3-none-any.whl", hash = "sha256:e3069e4be3ead9668e21cb9b074cd948f7b3113fd9c8bba083f48247aab8b11c"},
- {file = "tomli-1.2.3.tar.gz", hash = "sha256:05b6166bff487dc068d322585c7ea4ef78deed501cc124060e0f238e89a9231f"},
-]
-typed-ast = [
- {file = "typed_ast-1.5.4-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:669dd0c4167f6f2cd9f57041e03c3c2ebf9063d0757dc89f79ba1daa2bfca9d4"},
- {file = "typed_ast-1.5.4-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:211260621ab1cd7324e0798d6be953d00b74e0428382991adfddb352252f1d62"},
- {file = "typed_ast-1.5.4-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:267e3f78697a6c00c689c03db4876dd1efdfea2f251a5ad6555e82a26847b4ac"},
- {file = "typed_ast-1.5.4-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:c542eeda69212fa10a7ada75e668876fdec5f856cd3d06829e6aa64ad17c8dfe"},
- {file = "typed_ast-1.5.4-cp310-cp310-win_amd64.whl", hash = "sha256:a9916d2bb8865f973824fb47436fa45e1ebf2efd920f2b9f99342cb7fab93f72"},
- {file = "typed_ast-1.5.4-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:79b1e0869db7c830ba6a981d58711c88b6677506e648496b1f64ac7d15633aec"},
- {file = "typed_ast-1.5.4-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a94d55d142c9265f4ea46fab70977a1944ecae359ae867397757d836ea5a3f47"},
- {file = "typed_ast-1.5.4-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:183afdf0ec5b1b211724dfef3d2cad2d767cbefac291f24d69b00546c1837fb6"},
- {file = "typed_ast-1.5.4-cp36-cp36m-win_amd64.whl", hash = "sha256:639c5f0b21776605dd6c9dbe592d5228f021404dafd377e2b7ac046b0349b1a1"},
- {file = "typed_ast-1.5.4-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:cf4afcfac006ece570e32d6fa90ab74a17245b83dfd6655a6f68568098345ff6"},
- {file = "typed_ast-1.5.4-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ed855bbe3eb3715fca349c80174cfcfd699c2f9de574d40527b8429acae23a66"},
- {file = "typed_ast-1.5.4-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:6778e1b2f81dfc7bc58e4b259363b83d2e509a65198e85d5700dfae4c6c8ff1c"},
- {file = "typed_ast-1.5.4-cp37-cp37m-win_amd64.whl", hash = "sha256:0261195c2062caf107831e92a76764c81227dae162c4f75192c0d489faf751a2"},
- {file = "typed_ast-1.5.4-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:2efae9db7a8c05ad5547d522e7dbe62c83d838d3906a3716d1478b6c1d61388d"},
- {file = "typed_ast-1.5.4-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:7d5d014b7daa8b0bf2eaef684295acae12b036d79f54178b92a2b6a56f92278f"},
- {file = "typed_ast-1.5.4-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:370788a63915e82fd6f212865a596a0fefcbb7d408bbbb13dea723d971ed8bdc"},
- {file = "typed_ast-1.5.4-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:4e964b4ff86550a7a7d56345c7864b18f403f5bd7380edf44a3c1fb4ee7ac6c6"},
- {file = "typed_ast-1.5.4-cp38-cp38-win_amd64.whl", hash = "sha256:683407d92dc953c8a7347119596f0b0e6c55eb98ebebd9b23437501b28dcbb8e"},
- {file = "typed_ast-1.5.4-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:4879da6c9b73443f97e731b617184a596ac1235fe91f98d279a7af36c796da35"},
- {file = "typed_ast-1.5.4-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:3e123d878ba170397916557d31c8f589951e353cc95fb7f24f6bb69adc1a8a97"},
- {file = "typed_ast-1.5.4-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ebd9d7f80ccf7a82ac5f88c521115cc55d84e35bf8b446fcd7836eb6b98929a3"},
- {file = "typed_ast-1.5.4-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:98f80dee3c03455e92796b58b98ff6ca0b2a6f652120c263efdba4d6c5e58f72"},
- {file = "typed_ast-1.5.4-cp39-cp39-win_amd64.whl", hash = "sha256:0fdbcf2fef0ca421a3f5912555804296f0b0960f0418c440f5d6d3abb549f3e1"},
- {file = "typed_ast-1.5.4.tar.gz", hash = "sha256:39e21ceb7388e4bb37f4c679d72707ed46c2fbf2a5609b8b8ebc4b067d977df2"},
-]
-typing-extensions = [
- {file = "typing_extensions-4.1.1-py3-none-any.whl", hash = "sha256:21c85e0fe4b9a155d0799430b0ad741cdce7e359660ccbd8b530613e8df88ce2"},
- {file = "typing_extensions-4.1.1.tar.gz", hash = "sha256:1a9462dcc3347a79b1f1c0271fbe79e844580bb598bafa1ed208b94da3cdcd42"},
-]
-urllib3 = [
- {file = "urllib3-1.26.11-py2.py3-none-any.whl", hash = "sha256:c33ccba33c819596124764c23a97d25f32b28433ba0dedeb77d873a38722c9bc"},
- {file = "urllib3-1.26.11.tar.gz", hash = "sha256:ea6e8fb210b19d950fab93b60c9009226c63a28808bc8386e05301e25883ac0a"},
-]
-webencodings = [
- {file = "webencodings-0.5.1-py2.py3-none-any.whl", hash = "sha256:a0af1213f3c2226497a97e2b3aa01a7e4bee4f403f95be16fc9acd2947514a78"},
- {file = "webencodings-0.5.1.tar.gz", hash = "sha256:b36a1c245f2d304965eb4e0a82848379241dc04b865afcc4aab16748587e1923"},
-]
-zipp = [
- {file = "zipp-3.6.0-py3-none-any.whl", hash = "sha256:9fe5ea21568a0a70e50f273397638d39b03353731e6cbbb3fd8502a33fec40bc"},
- {file = "zipp-3.6.0.tar.gz", hash = "sha256:71c644c5369f4a6e07636f0aa966270449561fcea2e3d6747b8d23efaa9d7832"},
-]
diff --git a/pyproject.toml b/pyproject.toml
index acf7d2c4..b784a319 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,38 +1,117 @@
-[[source]]
-url = "https://pypi.org/simple"
-verify_ssl = true
-name = "pypi"
+[project]
+name = "handelsregister"
+version = "0.3.0"
+description = "Python-Package fĂŒr das deutsche Handelsregister"
+readme = "README.md"
+license = "MIT"
+authors = [
+ { name = "BundesAPI", email = "kontakt@bund.dev" },
+ { name = "maximiliancw", email = "wunderkind-serie0f@icloud.com" }
+]
+keywords = ["handelsregister", "germany", "commercial-register", "cli", "api"]
+requires-python = ">=3.9"
-[tool.poetry.dependencies]
-python = ">3.6.2,<4"
-mechanize = "*"
-mechanicalsoup = "*"
+dependencies = [
+ "mechanize>=0.4.8",
+ "beautifulsoup4>=4.11.0",
+ "diskcache>=5.6.0",
+ "pydantic>=2.0.0",
+ "pydantic-settings>=2.0.0",
+ "tenacity>=8.2.0",
+ "ratelimit>=2.2.1",
+ "python-dateutil>=2.8.0",
+ "yarl>=1.9.0",
+ "tqdm>=4.66.0",
+]
-[tool.poetry.dev-dependencies]
-black = "^22.6.0"
+[project.optional-dependencies]
+dev = [
+ "ruff>=0.6.0",
+ "pytest>=7.0.0",
+ "pre-commit>=3.0.0",
+]
+docs = [
+ "mkdocs>=1.5.0",
+ "mkdocs-material>=9.5.0",
+ "mkdocstrings[python]>=0.24.0",
+ "mkdocs-static-i18n>=1.2.0",
+]
-[tool.poetry]
-name = "handelsregister"
-version = "0.1.0"
-description = ""
-authors = ["BundesAPI "]
+[project.urls]
+Homepage = "https://github.com/bundesAPI/handelsregister"
+Repository = "https://github.com/bundesAPI/handelsregister"
+Issues = "https://github.com/bundesAPI/handelsregister/issues"
+
+[project.scripts]
+handelsregister = "handelsregister.cli:main"
+hrg = "handelsregister.cli:main"
[build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"
-
-[tool.tox]
-legacy_tox_ini = """
-[tox]
-envlist = py36,py37,py38,py310
-isolated_build = True
-
-[tox:.package]
-basepython = python3
-
-[testenv]
-deps = pytest
-usedevelop = true
-commands =
- pytest
-"""
\ No newline at end of file
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+ "ruff>=0.6.0",
+ "pytest>=7.0.0",
+ "pre-commit>=3.0.0",
+]
+
+[tool.pytest.ini_options]
+markers = [
+ "integration: marks tests that hit live API (deselect with '-m \"not integration\"')",
+ "slow: marks tests as slow running (deselect with '-m \"not slow\"')",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = [
+ "E", # pycodestyle errors
+ "W", # pycodestyle warnings
+ "F", # pyflakes
+ "I", # isort (import sorting)
+ "N", # pep8-naming
+ "UP", # pyupgrade
+ "B", # flake8-bugbear
+ "C4", # flake8-comprehensions
+ "DTZ", # flake8-datetimez
+ "T10", # flake8-debugger
+ "EM", # flake8-errmsg
+ "ISC", # flake8-implicit-str-concat
+ "ICN", # flake8-import-conventions
+ "PIE", # flake8-pie
+ "PT", # flake8-pytest-style
+ "Q", # flake8-quotes
+ "RSE", # flake8-raise
+ "RET", # flake8-return
+ "SIM", # flake8-simplify
+ "TID", # flake8-tidy-imports
+ "ARG", # flake8-unused-arguments
+ "PTH", # flake8-use-pathlib
+ "ERA", # eradicate (commented-out code)
+ "PD", # pandas-vet
+ "PGH", # pygrep-hooks
+ "PL", # Pylint
+ "TRY", # tryceratops
+ "NPY", # NumPy-specific rules
+ "RUF", # Ruff-specific rules
+]
+ignore = [
+ "E501", # line too long (handled by formatter)
+ "PLR0913", # too-many-arguments (can be too strict)
+ "PLR2004", # magic-value-used-in-comparison (too strict for constants)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"] # Allow unused imports in __init__.py
+"test_*.py" = ["ARG", "S101", "PLR2004"] # Allow unused arguments, assert, and magic values in tests
+"conftest.py" = ["ARG", "F401"] # Allow unused arguments and imports in conftest
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
diff --git a/test_handelsregister.py b/test_handelsregister.py
index fa1951a6..7e54bc54 100644
--- a/test_handelsregister.py
+++ b/test_handelsregister.py
@@ -1,57 +1,1190 @@
-import pytest
-from handelsregister import get_companies_in_searchresults,HandelsRegister
+"""Tests for the handelsregister module.
+
+Unit tests run without network access and use mocked responses.
+Integration tests hit the live API and are marked with @pytest.mark.integration.
+
+â ïž CRITICAL RATE LIMIT WARNING:
+ The integration tests make exactly 60 API requests (the rate limit per hour).
+ Each test makes 3 requests: open_startpage + navigate + submit_search.
+ With 20 tests total (16 parametrized + 4 others), this hits the limit exactly.
+
+ The ratelimit library will automatically sleep when the limit is reached, but:
+ - Tests will be very slow (potentially >1 hour)
+ - No safety margin for retries or re-runs
+ - Risk of hitting limit if tests run multiple times
+
+ Recommendations:
+ - Run only a subset: pytest -m integration -k "test_search_function"
+ - Remove force_refresh=True to use cached results
+ - Reduce parametrized test cases (currently 16, could be 8-10)
+ - Add delays between test runs
+ - Consider using a shared test cache
+"""
+
import argparse
+import time
+
+import pytest
+
+from handelsregister import (
+ BASE_URL,
+ DEFAULT_CACHE_TTL_SECONDS,
+ REGISTER_TYPES,
+ STATE_CODES,
+ SUFFIX_MAP,
+ Address,
+ CacheEntry,
+ Company,
+ CompanyDetails,
+ DetailsParser,
+ HandelsRegister,
+ HistoryEntry,
+ Owner,
+ Representative,
+ SearchCache,
+ SearchOptions,
+ Settings,
+ build_url,
+ get_companies_in_searchresults,
+ get_details,
+ search,
+ settings,
+)
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def sample_search_html():
+ """Sample HTML response from a search result."""
+ return ''
+
+
+@pytest.fixture
+def mock_args():
+ """Create mock arguments for HandelsRegister."""
+ return argparse.Namespace(
+ debug=False, force=False, schlagwoerter="Test Company", schlagwortOptionen="all", json=False
+ )
+
+
+@pytest.fixture
+def temp_cache_dir(tmp_path):
+ """Create a temporary cache directory."""
+ cache_dir = tmp_path / "handelsregister_cache"
+ cache_dir.mkdir()
+ return cache_dir
+
+
+# =============================================================================
+# Unit Tests - Parsing
+# =============================================================================
+
+
+class TestParseSearchResults:
+ """Unit tests for HTML parsing functions."""
+
+ def test_parse_search_result_gasag(self, sample_search_html):
+ """Test parsing a search result for GASAG AG."""
+ result = get_companies_in_searchresults(sample_search_html)
+
+ assert len(result) == 1
+ company = result[0]
+
+ assert company.name == "GASAG AG"
+ assert company.state == "Berlin"
+ assert company.register_num == "HRB 44343 B"
+ assert company.status == "currently registered"
+ assert company.status_normalized == "CURRENTLY_REGISTERED"
+ assert len(company.history) == 1
+ assert company.history[0].name == "1.) Gasag Berliner Gaswerke Aktiengesellschaft"
+ assert company.history[0].location == "1.) Berlin"
+
+ def test_parse_empty_html(self):
+ """Test parsing empty HTML returns empty list."""
+ result = get_companies_in_searchresults("")
+ assert result == []
+
+ def test_parse_no_grid_table(self):
+ """Test parsing HTML without grid table returns empty list."""
+ html = ""
+ result = get_companies_in_searchresults(html)
+ assert result == []
+
+
+class TestDetailsParser:
+ """Unit tests for DetailsParser (SI/AD/UT parsing)."""
+
+ @pytest.fixture
+ def sample_si_html(self):
+ """Sample HTML from structured register content (SI)."""
+ return """
+
+
+
+ | Firma: | GASAG AG |
+ | Rechtsform: | Aktiengesellschaft |
+ | Sitz: | Berlin |
+ | GeschÀftsanschrift: | GASAG-Platz 1, 10965 Berlin |
+ | Stammkapital: | 307.200.000,00 EUR |
+ | Gegenstand: | Versorgung der Bevölkerung mit Gas und anderen Energien |
+ | Registernummer: | HRB 44343 B |
+
+ Vorstand: Dr. Gerhard Holtmeier (Berlin)
+
+
+ """
+
+ @pytest.fixture
+ def sample_si_gmbh_html(self):
+ """Sample HTML for a GmbH."""
+ return """
+
+
+
+ | Firma: | Test GmbH |
+ | Rechtsform: | Gesellschaft mit beschrÀnkter Haftung |
+ | Stammkapital: | 25.000 EUR |
+
+ GeschĂ€ftsfĂŒhrer: Max Mustermann
+
+
+ """
+
+ def test_parse_si_basic(self, sample_si_html):
+ """Test parsing basic SI content."""
+ details = DetailsParser.parse_si(sample_si_html)
+
+ assert details.name == "GASAG AG"
+ assert details.legal_form == "Aktiengesellschaft"
+ assert "307.200.000" in details.capital
+ assert details.currency == "EUR"
+
+ def test_parse_si_with_base_info(self, sample_si_html):
+ """Test parsing SI with base company info."""
+ base_info = {
+ "name": "GASAG AG",
+ "register_num": "HRB 44343 B",
+ "court": "Amtsgericht Berlin",
+ "state": "Berlin",
+ "status": "aktuell",
+ }
+ details = DetailsParser.parse_si(sample_si_html, base_info)
+
+ assert details.court == "Amtsgericht Berlin"
+ assert details.state == "Berlin"
+ assert details.status == "aktuell"
+
+ def test_parse_si_address(self, sample_si_html):
+ """Test parsing address from SI."""
+ details = DetailsParser.parse_si(sample_si_html)
+
+ assert details.address is not None
+ assert details.address.street == "GASAG-Platz 1"
+ assert details.address.postal_code == "10965"
+ assert details.address.city == "Berlin"
+
+ def test_parse_si_purpose(self, sample_si_html):
+ """Test parsing company purpose from SI."""
+ details = DetailsParser.parse_si(sample_si_html)
+
+ assert details.purpose is not None
+ assert "Versorgung" in details.purpose
+ assert "Gas" in details.purpose
+
+ def test_parse_si_representatives(self, sample_si_html):
+ """Test parsing representatives from SI."""
+ details = DetailsParser.parse_si(sample_si_html)
+
+ assert len(details.representatives) >= 1
+ vorstand = next((r for r in details.representatives if r.role == "Vorstand"), None)
+ assert vorstand is not None
+ assert "Holtmeier" in vorstand.name
+
+ def test_parse_si_gmbh(self, sample_si_gmbh_html):
+ """Test parsing GmbH company."""
+ details = DetailsParser.parse_si(sample_si_gmbh_html)
+
+ assert details.name == "Test GmbH"
+ assert details.legal_form == "Gesellschaft mit beschrÀnkter Haftung"
+ assert "25.000" in details.capital
+ assert details.currency == "EUR"
+
+ def test_parse_si_gmbh_geschaeftsfuehrer(self, sample_si_gmbh_html):
+ """Test parsing GeschĂ€ftsfĂŒhrer from GmbH."""
+ details = DetailsParser.parse_si(sample_si_gmbh_html)
+
+ gf = next((r for r in details.representatives if r.role == "GeschĂ€ftsfĂŒhrer"), None)
+ assert gf is not None
+ assert "Mustermann" in gf.name
+
+ def test_parse_address_full(self):
+ """Test _parse_address with full address."""
+ addr = DetailsParser._parse_address("MusterstraĂe 123, 10115 Berlin")
+
+ assert addr.street == "MusterstraĂe 123"
+ assert addr.postal_code == "10115"
+ assert addr.city == "Berlin"
+
+ def test_parse_address_city_only(self):
+ """Test _parse_address with city only."""
+ addr = DetailsParser._parse_address("Hamburg")
+
+ assert addr.city == "Hamburg"
+ assert addr.street is None
+ assert addr.postal_code is None
+
+ def test_extract_legal_form_ag(self):
+ """Test extracting Aktiengesellschaft."""
+ result = DetailsParser._extract_legal_form("Eine Aktiengesellschaft")
+ assert result == "Aktiengesellschaft"
+
+ def test_extract_legal_form_gmbh(self):
+ """Test extracting GmbH."""
+ result = DetailsParser._extract_legal_form("Test GmbH")
+ assert result == "Gesellschaft mit beschrÀnkter Haftung"
+
+ def test_extract_legal_form_kg(self):
+ """Test extracting Kommanditgesellschaft."""
+ result = DetailsParser._extract_legal_form("Muster GmbH & Co. KG")
+ assert result == "GmbH & Co. KG"
+
+ def test_extract_legal_form_none(self):
+ """Test no legal form found."""
+ result = DetailsParser._extract_legal_form("Some random text")
+ assert result is None
+
+ def test_parse_date_german_format(self):
+ """Test parsing German date format DD.MM.YYYY."""
+ result = DetailsParser.parse_date("15.03.2024")
+ assert result == "15.03.2024"
+
+ def test_parse_date_in_text(self):
+ """Test parsing date embedded in text."""
+ result = DetailsParser.parse_date("Eingetragen am 01.01.2020 in Berlin")
+ assert result == "01.01.2020"
+
+ def test_parse_date_invalid(self):
+ """Test that invalid text returns None."""
+ result = DetailsParser.parse_date("No date here")
+ assert result is None
+
+ def test_parse_date_various_formats(self):
+ """Test that various German dates are parsed correctly."""
+ # Day first format
+ result = DetailsParser.parse_date("5.1.2023")
+ assert result == "05.01.2023"
+
+ # Full date
+ result = DetailsParser.parse_date("31.12.2022")
+ assert result == "31.12.2022"
+
+ def test_parse_empty_html(self):
+ """Test parsing empty HTML."""
+ details = DetailsParser.parse_si("")
+
+ assert details.name == ""
+ assert details.capital is None
+ assert details.representatives == []
+
+
+# =============================================================================
+# Unit Tests - Data Classes
+# =============================================================================
+
+
+class TestDataClasses:
+ """Unit tests for dataclass functionality."""
+
+ def test_history_entry_creation(self):
+ """Test creating a HistoryEntry."""
+ entry = HistoryEntry(name="Old Name", location="Old Location")
+ assert entry.name == "Old Name"
+ assert entry.location == "Old Location"
+
+ def test_company_to_dict(self):
+ """Test Company.to_dict() method."""
+ company = Company(
+ court="Test Court",
+ name="Test Company",
+ state="Berlin",
+ status="active",
+ status_normalized="ACTIVE",
+ documents="AD",
+ register_num="HRB 12345",
+ history=[HistoryEntry(name="Old", location="Berlin")],
+ )
+
+ d = company.to_dict()
+
+ assert d["court"] == "Test Court"
+ assert d["name"] == "Test Company"
+ assert d["state"] == "Berlin"
+ assert d["register_num"] == "HRB 12345"
+ assert d["statusCurrent"] == "ACTIVE"
+ assert d["history"] == [("Old", "Berlin")]
+
+ def test_cache_entry_not_expired(self):
+ """Test CacheEntry.is_expired() returns False for fresh entry."""
+ entry = CacheEntry(query="test", options="all", timestamp=time.time(), html="")
+ assert not entry.is_expired()
+
+ def test_cache_entry_expired(self):
+ """Test CacheEntry.is_expired() returns True for old entry."""
+ entry = CacheEntry(
+ query="test",
+ options="all",
+ timestamp=time.time() - DEFAULT_CACHE_TTL_SECONDS - 1,
+ html="",
+ )
+ assert entry.is_expired()
+
+ def test_cache_entry_serialization(self):
+ """Test CacheEntry to_dict and from_dict."""
+ original = CacheEntry(
+ query="test query", options="exact", timestamp=1234567890.0, html="test"
+ )
+
+ serialized = original.to_dict()
+ restored = CacheEntry.from_dict(serialized)
+
+ assert restored.query == original.query
+ assert restored.options == original.options
+ assert restored.timestamp == original.timestamp
+ assert restored.html == original.html
+
+ def test_search_options_cache_key(self):
+ """Test SearchOptions.cache_key() generates unique keys."""
+ opts1 = SearchOptions(keywords="test", keyword_option="all")
+ opts2 = SearchOptions(keywords="test", keyword_option="all")
+ opts3 = SearchOptions(keywords="test", keyword_option="exact")
+ opts4 = SearchOptions(keywords="test", keyword_option="all", states=["BE"])
+
+ assert opts1.cache_key() == opts2.cache_key()
+ assert opts1.cache_key() != opts3.cache_key()
+ assert opts1.cache_key() != opts4.cache_key()
+
+ def test_search_options_defaults(self):
+ """Test SearchOptions default values."""
+ opts = SearchOptions(keywords="test")
+
+ assert opts.keyword_option == "all"
+ assert opts.states is None
+ assert opts.register_type is None
+ assert opts.register_number is None
+ assert opts.include_deleted is False
+ assert opts.similar_sounding is False
+ assert opts.results_per_page == 100
+
+
+class TestPydanticValidation:
+ """Unit tests for Pydantic validation on models."""
+
+ def test_search_options_keyword_validation(self):
+ """Test that empty keywords are rejected."""
+ import pytest
+ from pydantic import ValidationError
+
+ with pytest.raises(ValidationError):
+ SearchOptions(keywords="")
+
+ def test_search_options_keyword_option_validation(self):
+ """Test that invalid keyword_option values are rejected."""
+ import pytest
+ from pydantic import ValidationError
+
+ with pytest.raises(ValidationError):
+ SearchOptions(keywords="test", keyword_option="invalid")
+
+ def test_search_options_states_validation(self):
+ """Test that invalid state codes are rejected."""
+ import pytest
+ from pydantic import ValidationError
+
+ with pytest.raises(ValidationError):
+ SearchOptions(keywords="test", states=["INVALID"])
+
+ def test_search_options_states_normalized(self):
+ """Test that state codes are normalized to uppercase."""
+ opts = SearchOptions(keywords="test", states=["be", "hh"])
+ assert opts.states == ["BE", "HH"]
+
+ def test_search_options_register_type_validation(self):
+ """Test that invalid register types are rejected."""
+ import pytest
+ from pydantic import ValidationError
+
+ with pytest.raises(ValidationError):
+ SearchOptions(keywords="test", register_type="INVALID")
+
+ def test_search_options_results_per_page_validation(self):
+ """Test that invalid results_per_page values are rejected."""
+ import pytest
+ from pydantic import ValidationError
+
+ with pytest.raises(ValidationError):
+ SearchOptions(keywords="test", results_per_page=999)
+
+ def test_representative_name_required(self):
+ """Test that Representative requires a name."""
+ import pytest
+ from pydantic import ValidationError
+
+ with pytest.raises(ValidationError):
+ Representative(name="", role="GeschĂ€ftsfĂŒhrer")
+
+ def test_owner_name_required(self):
+ """Test that Owner requires a name."""
+ import pytest
+ from pydantic import ValidationError
+
+ with pytest.raises(ValidationError):
+ Owner(name="")
+
+ def test_company_details_from_dict(self):
+ """Test creating CompanyDetails from model_validate."""
+ data = {
+ "name": "Test GmbH",
+ "register_num": "HRB 12345",
+ "court": "Berlin",
+ "state": "Berlin",
+ "status": "active",
+ }
+ details = CompanyDetails.model_validate(data)
+ assert details.name == "Test GmbH"
+ assert details.register_num == "HRB 12345"
+
+ def test_address_model_dump(self):
+ """Test Address model_dump for JSON serialization."""
+ addr = Address(street="Test 1", postal_code="12345", city="Berlin")
+ dumped = addr.model_dump()
+ assert dumped["street"] == "Test 1"
+ assert dumped["postal_code"] == "12345"
+ assert dumped["city"] == "Berlin"
+
+
+class TestAddress:
+ """Unit tests for Address dataclass."""
+
+ def test_address_str_full(self):
+ """Test Address.__str__() with all fields."""
+ addr = Address(
+ street="MusterstraĂe 123", postal_code="10115", city="Berlin", country="Deutschland"
+ )
+ assert str(addr) == "MusterstraĂe 123, 10115 Berlin"
+
+ def test_address_str_minimal(self):
+ """Test Address.__str__() with minimal fields."""
+ addr = Address(city="Hamburg")
+ assert str(addr) == "Hamburg"
+
+ def test_address_str_empty(self):
+ """Test Address.__str__() with no fields."""
+ addr = Address()
+ assert str(addr) == ""
+
+ def test_address_str_foreign(self):
+ """Test Address.__str__() with foreign country."""
+ addr = Address(city="Wien", country="Ăsterreich")
+ assert str(addr) == "Wien, Ăsterreich"
+
+ def test_address_to_dict(self):
+ """Test Address.to_dict()."""
+ addr = Address(street="Test 1", postal_code="12345", city="Berlin")
+ d = addr.to_dict()
+ assert d["street"] == "Test 1"
+ assert d["postal_code"] == "12345"
+ assert d["city"] == "Berlin"
+ assert d["country"] == "Deutschland"
+
+
+class TestRepresentative:
+ """Unit tests for Representative dataclass."""
+
+ def test_representative_creation(self):
+ """Test creating a Representative."""
+ rep = Representative(
+ name="Max Mustermann",
+ role="GeschĂ€ftsfĂŒhrer",
+ location="Berlin",
+ restrictions="einzelvertretungsberechtigt",
+ )
+ assert rep.name == "Max Mustermann"
+ assert rep.role == "GeschĂ€ftsfĂŒhrer"
+ assert rep.location == "Berlin"
+ assert rep.restrictions == "einzelvertretungsberechtigt"
+
+ def test_representative_to_dict(self):
+ """Test Representative.to_dict()."""
+ rep = Representative(name="Test", role="Vorstand")
+ d = rep.to_dict()
+ assert d["name"] == "Test"
+ assert d["role"] == "Vorstand"
+ assert d["location"] is None
+
+
+class TestOwner:
+ """Unit tests for Owner dataclass."""
+
+ def test_owner_creation(self):
+ """Test creating an Owner."""
+ owner = Owner(
+ name="Holding GmbH", share="100%", owner_type="Gesellschafter", location="MĂŒnchen"
+ )
+ assert owner.name == "Holding GmbH"
+ assert owner.share == "100%"
+ assert owner.owner_type == "Gesellschafter"
+
+ def test_owner_to_dict(self):
+ """Test Owner.to_dict()."""
+ owner = Owner(name="Test GmbH", share="50.000 EUR")
+ d = owner.to_dict()
+ assert d["name"] == "Test GmbH"
+ assert d["share"] == "50.000 EUR"
+
+
+class TestCompanyDetails:
+ """Unit tests for CompanyDetails dataclass."""
+
+ def test_company_details_creation(self):
+ """Test creating CompanyDetails with all fields."""
+ details = CompanyDetails(
+ name="GASAG AG",
+ register_num="HRB 44343 B",
+ court="Amtsgericht Berlin (Charlottenburg)",
+ state="Berlin",
+ status="aktuell",
+ legal_form="Aktiengesellschaft",
+ capital="307.200.000",
+ currency="EUR",
+ address=Address(street="GASAG-Platz 1", postal_code="10965", city="Berlin"),
+ purpose="Versorgung mit Energie",
+ representatives=[Representative(name="Dr. Gerhard Holtmeier", role="Vorstand")],
+ )
+ assert details.name == "GASAG AG"
+ assert details.legal_form == "Aktiengesellschaft"
+ assert details.capital == "307.200.000"
+ assert len(details.representatives) == 1
+
+ def test_company_details_to_dict(self):
+ """Test CompanyDetails.to_dict()."""
+ details = CompanyDetails(
+ name="Test GmbH",
+ register_num="HRB 12345",
+ court="Amtsgericht Berlin",
+ state="Berlin",
+ status="aktuell",
+ legal_form="GmbH",
+ capital="25.000",
+ currency="EUR",
+ )
+ d = details.to_dict()
+ assert d["name"] == "Test GmbH"
+ assert d["legal_form"] == "GmbH"
+ assert d["capital"] == "25.000"
+ assert d["representatives"] == []
+ assert d["owners"] == []
+
+ def test_company_details_from_company(self):
+ """Test CompanyDetails.from_company() class method."""
+ company = {
+ "name": "GASAG AG",
+ "register_num": "HRB 44343 B",
+ "court": "Berlin Amtsgericht",
+ "state": "Berlin",
+ "status": "aktuell",
+ }
+ details = CompanyDetails.from_company(company)
+ assert details.name == "GASAG AG"
+ assert details.register_num == "HRB 44343 B"
+ assert details.legal_form is None # Not set from basic company
+
+ def test_company_details_defaults(self):
+ """Test CompanyDetails default values."""
+ details = CompanyDetails(
+ name="Test",
+ register_num="HRB 1",
+ court="AG Berlin",
+ state="Berlin",
+ status="aktuell",
+ )
+ assert details.legal_form is None
+ assert details.capital is None
+ assert details.address is None
+ assert details.representatives == []
+ assert details.owners == []
+
+
+# =============================================================================
+# Unit Tests - Configuration
+# =============================================================================
+
+
+class TestConfiguration:
+ """Unit tests for configuration constants."""
+
+ def test_state_codes_complete(self):
+ """Test that all 16 German states are defined."""
+ assert len(STATE_CODES) == 16
+ assert "BE" in STATE_CODES # Berlin
+ assert "BY" in STATE_CODES # Bayern
+ assert "NW" in STATE_CODES # Nordrhein-Westfalen
+
+ def test_register_types(self):
+ """Test that all register types are defined."""
+ assert "HRA" in REGISTER_TYPES
+ assert "HRB" in REGISTER_TYPES
+ assert "GnR" in REGISTER_TYPES
+ assert "VR" in REGISTER_TYPES
+ assert "PR" in REGISTER_TYPES
+
+
+class TestSettings:
+ """Unit tests for pydantic-settings configuration."""
+
+ def test_settings_instance_exists(self):
+ """Test that global settings instance exists."""
+ assert settings is not None
+ assert isinstance(settings, Settings)
+
+ def test_settings_default_values(self):
+ """Test that default settings values are correct."""
+ s = Settings()
+ assert s.cache_ttl_seconds == 3600
+ assert s.details_ttl_seconds == 86400
+ assert s.request_timeout == 10
+ assert s.max_retries == 3
+ assert s.rate_limit_calls == 60
+ assert s.rate_limit_period == 3600
+ assert s.debug is False
+
+ def test_settings_base_url_parsed(self):
+ """Test that base_url_parsed returns a yarl URL."""
+ from yarl import URL
+
+ s = Settings()
+ assert isinstance(s.base_url_parsed, URL)
+ assert str(s.base_url_parsed) == "https://www.handelsregister.de"
+
+ def test_settings_env_prefix(self):
+ """Test that settings uses correct env prefix."""
+ assert Settings.model_config.get("env_prefix") == "HRG_"
+
+ def test_settings_custom_values(self):
+ """Test creating Settings with custom values."""
+ s = Settings(
+ cache_ttl_seconds=7200,
+ max_retries=5,
+ debug=True,
+ )
+ assert s.cache_ttl_seconds == 7200
+ assert s.max_retries == 5
+ assert s.debug is True
+
+ def test_settings_cache_dir(self):
+ """Test that cache_dir defaults to None."""
+ s = Settings()
+ assert s.cache_dir is None
+
+
+class TestURLHandling:
+ """Unit tests for URL construction using yarl."""
+
+ def test_base_url_is_yarl_url(self):
+ """Test that BASE_URL is a yarl URL object."""
+ from yarl import URL
+
+ assert isinstance(BASE_URL, URL)
+ assert str(BASE_URL) == "https://www.handelsregister.de"
+
+ def test_build_url_basic(self):
+ """Test build_url with just a path."""
+ url = build_url("rp_web/search")
+ assert str(url) == "https://www.handelsregister.de/rp_web/search"
+
+ def test_build_url_with_query_params(self):
+ """Test build_url with query parameters."""
+ url = build_url("rp_web/search", q="Bank", page="1")
+ url_str = str(url)
+ assert "https://www.handelsregister.de/rp_web/search" in url_str
+ assert "q=Bank" in url_str
+ assert "page=1" in url_str
+
+ def test_build_url_empty_path(self):
+ """Test build_url with empty path returns base URL."""
+ url = build_url()
+ assert str(url) == "https://www.handelsregister.de"
+
+
+# =============================================================================
+# Unit Tests - Cache
+# =============================================================================
+
+
+class TestCache:
+ """Unit tests for caching functionality."""
+
+ def test_cache_key_generation(self, temp_cache_dir):
+ """Test that cache keys are deterministic."""
+ cache = SearchCache(cache_dir=temp_cache_dir)
+
+ key1 = cache._get_cache_key("Test", "all")
+ key2 = cache._get_cache_key("Test", "all")
+ key3 = cache._get_cache_key("Test", "exact")
+
+ assert key1 == key2 # Same inputs = same key
+ assert key1 != key3 # Different options = different key
+ cache.close()
+
+ def test_cache_key_is_hash(self, temp_cache_dir):
+ """Test that cache keys are valid hex hashes."""
+ cache = SearchCache(cache_dir=temp_cache_dir)
+
+ key = cache._get_cache_key("Company with spaces / special chars!", "all")
+
+ # Should be a 64-character hex string (SHA-256)
+ assert len(key) == 64
+ assert all(c in "0123456789abcdef" for c in key)
+ cache.close()
+
+ def test_cache_get_set(self, temp_cache_dir):
+ """Test cache get/set operations."""
+ cache = SearchCache(cache_dir=temp_cache_dir)
+
+ # Initially empty
+ assert cache.get("test", "all") is None
+
+ # Set value
+ cache.set("test", "all", "cached")
+
+ # Get returns the value
+ assert cache.get("test", "all") == "cached"
+ cache.close()
+
+ def test_cache_ttl_expiration(self, temp_cache_dir):
+ """Test that expired cache entries are not returned."""
+ cache = SearchCache(cache_dir=temp_cache_dir, ttl_seconds=0)
+
+ cache.set("test", "all", "cached")
+ time.sleep(0.1) # Wait for expiration
+
+ # Expired entry should return None
+ assert cache.get("test", "all") is None
+ cache.close()
+
+ def test_cache_details_ttl(self, temp_cache_dir):
+ """Test that details cache uses longer TTL."""
+ cache = SearchCache(
+ cache_dir=temp_cache_dir,
+ ttl_seconds=0, # Search TTL expired
+ details_ttl_seconds=3600, # Details TTL not expired
+ )
+
+ # Set a details cache entry
+ cache.set("details:SI:HRB123", "", "details")
+ time.sleep(0.1)
+
+ # Details should still be available (longer TTL)
+ assert cache.get("details:SI:HRB123", "") == "details"
+
+ # But search cache would be expired
+ cache.set("search", "all", "search")
+ time.sleep(0.1)
+ assert cache.get("search", "all") is None
+ cache.close()
+
+ def test_cache_clear(self, temp_cache_dir):
+ """Test clearing the cache."""
+ cache = SearchCache(cache_dir=temp_cache_dir)
+
+ # Add some entries
+ cache.set("search1", "all", "1")
+ cache.set("search2", "all", "2")
+ cache.set("details:SI:HRB1", "", "d1")
+
+ # Clear all
+ count = cache.clear()
+ assert count == 3
+
+ # Verify all cleared
+ assert cache.get("search1", "all") is None
+ assert cache.get("details:SI:HRB1", "") is None
+
+ cache.close()
+
+ def test_cache_clear_details_only(self, temp_cache_dir):
+ """Test clearing only details cache.
+
+ Note: With DiskCache, details_only=True clears all entries
+ since we can't efficiently filter by key content after hashing.
+ """
+ cache = SearchCache(cache_dir=temp_cache_dir)
+
+ # Add entries
+ cache.set("search1", "all", "search")
+ cache.set("details:SI:HRB1", "", "details")
+
+ # Clear details only - with DiskCache this clears all entries
+ count = cache.clear(details_only=True)
+ assert count >= 1 # At least some entries cleared
+
+ # With DiskCache, all entries are cleared when details_only=True
+ # This is a limitation of the hash-based key storage
+ cache.close()
+
+ def test_cache_stats(self, temp_cache_dir):
+ """Test cache statistics."""
+ cache = SearchCache(cache_dir=temp_cache_dir)
+
+ # Add entries
+ cache.set("search1", "all", "search")
+ cache.set("details:SI:HRB1", "", "details")
+ cache.set("details:AD:HRB2", "", "details2")
+
+ stats = cache.get_stats()
+
+ assert stats["total_files"] == 3
+ # Note: DiskCache doesn't distinguish between search and details entries
+ assert stats["search_files"] == 3 # All counted as search with DiskCache
+ assert stats["details_files"] == 0 # DiskCache doesn't track this
+ assert stats["total_size_bytes"] > 0
+
+ cache.close()
+
+
+# =============================================================================
+# Unit Tests - Suffix Map
+# =============================================================================
+
+
+class TestSuffixMap:
+ """Unit tests for register number suffix handling."""
+
+ def test_berlin_suffix(self):
+ """Test Berlin HRB suffix mapping."""
+ assert SUFFIX_MAP["Berlin"]["HRB"] == " B"
+
+ def test_bremen_suffix(self):
+ """Test Bremen suffix mapping."""
+ assert SUFFIX_MAP["Bremen"]["HRB"] == " HB"
+ assert SUFFIX_MAP["Bremen"]["HRA"] == " HB"
+ assert SUFFIX_MAP["Bremen"]["VR"] == " HB"
+
+
+# =============================================================================
+# Unit Tests - Public API
+# =============================================================================
+
+
+class TestPublicAPI:
+ """Unit tests for the public search() function."""
+
+ def test_search_function_exists(self):
+ """Test that the search function is importable."""
+ assert callable(search)
+
+ def test_search_options_from_parameters(self):
+ """Test that SearchOptions can be created with all parameters."""
+ opts = SearchOptions(
+ keywords="Test",
+ keyword_option="exact",
+ states=["BE", "HH"],
+ register_type="HRB",
+ register_number="12345",
+ include_deleted=True,
+ similar_sounding=True,
+ results_per_page=50,
+ )
+
+ assert opts.keywords == "Test"
+ assert opts.keyword_option == "exact"
+ assert opts.states == ["BE", "HH"]
+ assert opts.register_type == "HRB"
+ assert opts.register_number == "12345"
+ assert opts.include_deleted is True
+ assert opts.similar_sounding is True
+ assert opts.results_per_page == 50
+
+
+class TestHandelsRegisterClass:
+ """Unit tests for HandelsRegister class initialization."""
+
+ def test_init_without_args(self):
+ """Test that HandelsRegister can be initialized without args."""
+ hr = HandelsRegister(debug=False)
+ assert hr.args is None
+ assert hr.cache is not None
+ assert hr.browser is not None
+
+ def test_init_with_debug(self):
+ """Test that debug flag is stored correctly."""
+ hr = HandelsRegister(debug=True)
+ assert hr._debug is True
+
+ def test_init_with_custom_cache(self, temp_cache_dir):
+ """Test that custom cache is used."""
+ cache = SearchCache(cache_dir=temp_cache_dir)
+ hr = HandelsRegister(cache=cache)
+ assert hr.cache is cache
+
+ def test_from_options_classmethod(self):
+ """Test the from_options class method."""
+ opts = SearchOptions(keywords="Test")
+ hr = HandelsRegister.from_options(opts, debug=True)
+
+ assert hr._debug is True
+ assert hasattr(hr, "_default_options")
+ assert hr._default_options.keywords == "Test"
+
+ def test_search_company_requires_args(self):
+ """Test that search_company raises error without args."""
+ hr = HandelsRegister()
+
+ with pytest.raises(ValueError, match="benötigt args"):
+ hr.search_company()
+
+ def test_get_company_details_invalid_type(self):
+ """Test that invalid detail_type raises ValueError."""
+ hr = HandelsRegister(debug=False)
+ company = {"name": "Test", "register_num": "HRB 123"}
+
+ with pytest.raises(ValueError, match="Invalid detail_type"):
+ hr.get_company_details(company, detail_type="INVALID")
+
+
+class TestDetailsParserAD:
+ """Unit tests for DetailsParser AD (Aktueller Abdruck) parsing."""
+
+ @pytest.fixture
+ def sample_ad_html(self):
+ """Sample HTML from current printout (AD)."""
+ return """
+
+
+
+
Aktueller Abdruck
+
Firma: Test GmbH
+
Rechtsform: Gesellschaft mit beschrÀnkter Haftung
+
Sitz: Berlin
+
Stammkapital: 50.000,00 EUR
+
Gegenstand des Unternehmens: Entwicklung von Software
+
GeschĂ€ftsfĂŒhrer: Hans Schmidt (Berlin), einzelvertretungsberechtigt
+
+
UnternehmenstrÀger
+
Gesellschafter: Holding AG, Anteil: 100%
+
GeschĂ€ftsfĂŒhrer: Maria MĂŒller
+