brreg-wrapper 0.2.3__tar.gz → 0.3.0__tar.gz

brreg_wrapper-0.3.0/.gitattributes

@@ -0,0 +1,11 @@
+# Auto detect text files and ensure they use LF line endings
+* text=auto eol=lf
+
+# Explicitly declare files that will always have LF line endings
+*.py text eol=lf
+*.toml text eol=lf
+*.md text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+.gitignore text eol=lf
+LICENSE text eol=lf

brreg_wrapper-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+
+      - name: Check formatting with Ruff
+        run: ruff format --check .
+
+      - name: Lint with Ruff
+        run: ruff check .
+
+      - name: Run tests
+        run: pytest

brreg_wrapper-0.3.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,41 @@
+name: Publish Python Package to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies including dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]  # Installs package + dev dependencies (like ruff, pytest)
+          pip install build twine # Still need build and twine for publishing steps
+
+      - name: Check formatting with Ruff
+        run: ruff format --check .
+
+      - name: Lint with Ruff
+        run: ruff check .
+
+      - name: Run tests
+        run: pytest
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

brreg_wrapper-0.3.0/.gitignore

@@ -0,0 +1,22 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.test_venv
+test_venv/
+
+# IDE directories
+.vscode/
+.idea/
+
+# Test artifacts
+.pytest_cache/
+
+# Downloaded schema
+openapi.json

brreg_wrapper-0.3.0/.python-version

@@ -0,0 +1 @@
+3.13

{brreg_wrapper-0.2.3/src/brreg_wrapper.egg-info → brreg_wrapper-0.3.0}/PKG-INFO

@@ -1,35 +1,34 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: brreg-wrapper
-Version: 0.2.3
+Version: 0.3.0
 Summary: A Python wrapper for the Brønnøysund Register Centre (Brreg) API.
-Author-email: Sondre Dyrnes <sondre@villdyr.no>
-License-Expression: MIT
 Project-URL: Homepage, https://github.com/sondreal/brreg-wrapper
 Project-URL: Repository, https://github.com/sondreal/brreg-wrapper
+Author-email: Sondre Dyrnes <sondre@villdyr.no>
+License-Expression: MIT
+License-File: LICENSE
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
-Classifier: Operating System :: OS Independent
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-License-File: LICENSE
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: pydantic<3.0,>=2.0
 Requires-Dist: tenacity<10.0,>=8.2
+Provides-Extra: all
+Requires-Dist: h2<5.0,>=4.0; extra == 'all'
 Provides-Extra: dev
-Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
-Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == "dev"
-Requires-Dist: pytest-httpx<1.0,>=0.29; extra == "dev"
-Requires-Dist: ruff==0.11.2; extra == "dev"
-Requires-Dist: datamodel-code-generator[http]<1.0,>=0.25; extra == "dev"
+Requires-Dist: datamodel-code-generator[http]<1.0,>=0.25; extra == 'dev'
+Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx<1.0,>=0.29; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.11.2; extra == 'dev'
 Provides-Extra: http2
-Requires-Dist: h2<5.0,>=4.0; extra == "http2"
-Provides-Extra: all
-Requires-Dist: h2<5.0,>=4.0; extra == "all"
-Dynamic: license-file
+Requires-Dist: h2<5.0,>=4.0; extra == 'http2'
+Description-Content-Type: text/markdown
 
 # 🔥 Brreg Wrapper
 
@@ -129,8 +128,8 @@ async def main():
     # Second request uses cache
     entity2 = await client.get_enhet("923609016")
     
-    # Clear specific cache entries
-    client.clear_cache(pattern="enhet_")
+    # Clear specific cache entries (keys are request paths + query string)
+    client.clear_cache(pattern="/enheter/923609016")
     
     # Get cache statistics
     cache_info = client.get_cache_info()
@@ -140,14 +139,22 @@ async def main():
 ### Error Handling & Retry Logic
 
 ```python
-from brreg_wrapper import BrregClient, BrregAPIError, BrregRateLimitError
+from brreg_wrapper import (
+    BrregAPIError,
+    BrregClient,
+    BrregRateLimitError,
+    BrregResourceNotFoundError,
+)
 
 async def main():
-    # Configure with automatic retries for transient errors
-    client = BrregClient(max_retries=3)
+    # Transient errors (5xx, 429, timeouts, connection errors) are retried
+    # with exponential backoff, honouring the server's Retry-After header.
+    client = BrregClient(max_retries=3)  # up to 4 attempts in total
     
     try:
-        entity = await client.get_enhet("invalid_org_nr")  # Will raise exception
+        entity = await client.get_enhet("999999999")  # Will raise exception
+    except BrregResourceNotFoundError:
+        print("No such organization")
     except BrregRateLimitError:
         # Handle rate limit specifically
         print("Rate limit exceeded, try again later")
@@ -164,12 +171,12 @@ from brreg_wrapper import BrregClient
 async def main():
     client = BrregClient()
     
-    # Fetch multiple entities in parallel
+    # Fetch multiple entities concurrently (at most 10 requests in flight)
     org_numbers = ["923609016", "998463718", "913492978"]
-    results = await client.get_multiple_enheter(org_numbers)
+    results = await client.get_multiple_enheter(org_numbers, max_concurrency=10)
     
     for org_nr, entity in results.items():
-        if isinstance(entity, Exception):
+        if isinstance(entity, BrregAPIError):
             print(f"Error fetching {org_nr}: {entity}")
         else:
             print(f"{org_nr}: {entity.navn}")
@@ -192,13 +199,12 @@ async def main():
 We use pytest for testing. To run the tests:
 
 ```bash
+# Using UV (recommended)
+uv run --extra dev pytest
+
 # Using pip
 pip install -e ".[dev]"
 pytest
-
-# Using UV (recommended)
-uv pip install -e ".[dev]"
-pytest
 ```
 
 To test the package installation locally before publishing:

{brreg_wrapper-0.2.3 → brreg_wrapper-0.3.0}/README.md

@@ -96,8 +96,8 @@ async def main():
     # Second request uses cache
     entity2 = await client.get_enhet("923609016")
     
-    # Clear specific cache entries
-    client.clear_cache(pattern="enhet_")
+    # Clear specific cache entries (keys are request paths + query string)
+    client.clear_cache(pattern="/enheter/923609016")
     
     # Get cache statistics
     cache_info = client.get_cache_info()
@@ -107,14 +107,22 @@ async def main():
 ### Error Handling & Retry Logic
 
 ```python
-from brreg_wrapper import BrregClient, BrregAPIError, BrregRateLimitError
+from brreg_wrapper import (
+    BrregAPIError,
+    BrregClient,
+    BrregRateLimitError,
+    BrregResourceNotFoundError,
+)
 
 async def main():
-    # Configure with automatic retries for transient errors
-    client = BrregClient(max_retries=3)
+    # Transient errors (5xx, 429, timeouts, connection errors) are retried
+    # with exponential backoff, honouring the server's Retry-After header.
+    client = BrregClient(max_retries=3)  # up to 4 attempts in total
     
     try:
-        entity = await client.get_enhet("invalid_org_nr")  # Will raise exception
+        entity = await client.get_enhet("999999999")  # Will raise exception
+    except BrregResourceNotFoundError:
+        print("No such organization")
     except BrregRateLimitError:
         # Handle rate limit specifically
         print("Rate limit exceeded, try again later")
@@ -131,12 +139,12 @@ from brreg_wrapper import BrregClient
 async def main():
     client = BrregClient()
     
-    # Fetch multiple entities in parallel
+    # Fetch multiple entities concurrently (at most 10 requests in flight)
     org_numbers = ["923609016", "998463718", "913492978"]
-    results = await client.get_multiple_enheter(org_numbers)
+    results = await client.get_multiple_enheter(org_numbers, max_concurrency=10)
     
     for org_nr, entity in results.items():
-        if isinstance(entity, Exception):
+        if isinstance(entity, BrregAPIError):
             print(f"Error fetching {org_nr}: {entity}")
         else:
             print(f"{org_nr}: {entity.navn}")
@@ -159,13 +167,12 @@ async def main():
 We use pytest for testing. To run the tests:
 
 ```bash
+# Using UV (recommended)
+uv run --extra dev pytest
+
 # Using pip
 pip install -e ".[dev]"
 pytest
-
-# Using UV (recommended)
-uv pip install -e ".[dev]"
-pytest
 ```
 
 To test the package installation locally before publishing:

brreg_wrapper-0.3.0/examples/README.md

@@ -0,0 +1,57 @@
+# Brreg Wrapper Examples
+
+This directory contains example scripts that demonstrate how to use the `brreg-wrapper` package to interact with the Brønnøysund Register Centre API.
+
+## Available Examples
+
+- `sample.py`: A comprehensive example demonstrating basic usage, caching, batch operations, error handling, and search functionality.
+
+## Running the Examples
+
+Before running the examples, ensure you have installed the package:
+
+```bash
+# Using pip
+pip install -e ..
+
+# Using UV (recommended)
+uv pip install -e ..
+```
+
+Then run an example with:
+
+```bash
+# Using Python
+python sample.py
+
+# Or with UV's Python (if installed)
+uv python sample.py
+```
+
+## Creating Your Own Examples
+
+Feel free to add your own examples to this directory. Here's a simple template to get started:
+
+```python
+#!/usr/bin/env python3
+import asyncio
+from brreg_wrapper import BrregClient
+
+async def main():
+    # Create a client
+    async with BrregClient() as client:
+        # Your code here
+        # For example:
+        org_nr = "923609016"  # Equinor ASA
+        entity = await client.get_enhet(org_nr)
+        print(f"Company name: {entity.navn}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Notes
+
+- The examples assume you're running them from within the `examples` directory.
+- Remember to always close the client using `await client.close()` or use it as an async context manager with `async with BrregClient() as client:`
+- The Brreg API has rate limits, so be mindful when making many requests in quick succession. 

brreg_wrapper-0.3.0/examples/sample.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+Sample script to demonstrate the Brreg API wrapper.
+
+This script shows how to use the BrregClient with various configurations to access
+Norwegian business registry data from Brønnøysund Register Centre (Brreg).
+
+Usage:
+    python examples/sample.py
+
+Requirements:
+    pip install -e .  # Install the package in development mode
+    # or
+    uv pip install -e .  # Using UV installer
+"""
+
+import asyncio
+import json
+import logging
+from datetime import timedelta
+
+from brreg_wrapper import (
+    BrregAPIError,
+    BrregClient,
+    BrregRateLimitError,
+    BrregResourceNotFoundError,
+)
+
+# Set up logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger("brreg_sample")
+
+
+async def main():
+    """Main function to demonstrate BrregClient features."""
+    # Example organization numbers
+    org_numbers = [
+        "923609016",  # Equinor ASA
+        "914594685",  # KPMG AS
+        "982463718",  # Microsoft Norge AS
+        "999999999",  # Invalid/non-existent
+    ]
+
+    # Create a client with caching, rate limiting, and retry logic
+    logger.info("Initializing BrregClient with caching and rate limiting")
+    client = BrregClient(
+        timeout=15.0,
+        cache_ttl=timedelta(minutes=5),
+        rate_limit=1.0,  # 1 request per second
+        max_retries=2,
+        logger=logger,
+    )
+
+    try:
+        # 1. Basic usage - Get a single entity
+        logger.info("\n1. Getting information for a single entity (Equinor ASA)")
+        try:
+            equinor = await client.get_enhet(org_numbers[0])
+            print(f"Company Name: {equinor.navn}")
+            print(f"Organization Number: {equinor.organisasjonsnummer}")
+            print(f"Business Type: {equinor.organisasjonsform.beskrivelse}")
+            print(f"Registration Date: {equinor.registreringsdatoEnhetsregisteret}")
+
+            # Optional: serialize to JSON
+            print("\nJSON representation:")
+            equinor_dict = equinor.model_dump(
+                mode="json", by_alias=True, exclude_none=True
+            )
+            print(
+                json.dumps(equinor_dict, indent=2, ensure_ascii=False)[:500] + "...\n"
+            )
+        except BrregAPIError as e:
+            print(f"Error fetching Equinor data: {e}")
+            if e.response_json:
+                print(f"API response: {e.response_json}")
+
+        # 2. Caching demonstration
+        logger.info("\n2. Demonstrating caching")
+        logger.info("First request (will hit API):")
+        start_time = asyncio.get_event_loop().time()
+        await client.get_enhet(
+            org_numbers[1]
+        )  # Just make the request, don't need to store result
+        first_request_time = asyncio.get_event_loop().time() - start_time
+        print(f"First request took {first_request_time:.4f} seconds")
+
+        logger.info("Second request (should use cache):")
+        start_time = asyncio.get_event_loop().time()
+        await client.get_enhet(
+            org_numbers[1]
+        )  # Just make the request, don't need to store result
+        second_request_time = asyncio.get_event_loop().time() - start_time
+        print(f"Second request took {second_request_time:.4f} seconds")
+        print(f"Cache info: {client.get_cache_info()}")
+
+        # 3. Batch operations
+        logger.info("\n3. Getting multiple entities in parallel")
+        results = await client.get_multiple_enheter(
+            [org_numbers[0], org_numbers[1], org_numbers[2]]
+        )
+        for org_nr, entity in results.items():
+            if isinstance(entity, BrregAPIError):
+                print(f"❌ {org_nr}: Error - {entity}")
+            else:
+                print(f"✅ {org_nr}: {entity.navn}")
+
+        # 4. Error handling
+        logger.info("\n4. Error handling demonstration")
+        try:
+            await client.get_enhet(org_numbers[3])  # Invalid org number
+        except BrregResourceNotFoundError as e:
+            print(f"✅ Correct exception raised: {type(e).__name__}")
+            print(f"  Message: {e}")
+            print(f"  Status code: {e.status_code}")
+            print(f"  Request URL: {e.request_url}")
+        except BrregAPIError as e:
+            print(f"❌ Wrong exception type: {type(e).__name__}")
+
+        # 5. Searching
+        logger.info("\n5. Searching for organizations")
+        search_results = await client.search_enheter(navn="Microsoft")
+        print(
+            f"Found {search_results.page.totalElements:.0f} "
+            "organizations matching 'Microsoft'"
+        )
+        for i, org in enumerate(search_results.field_embedded.enheter[:3], 1):
+            print(f"  {i}. {org.navn} ({org.organisasjonsnummer})")
+
+        # 6. Looking up code lists
+        logger.info("\n6. Getting organization forms")
+        org_forms = await client.get_organisasjonsformer()
+        org_forms_sample = list(org_forms.field_embedded.organisasjonsformer)[:3]
+        print(
+            f"Found {len(org_forms.field_embedded.organisasjonsformer)} "
+            "organization forms"
+        )
+        for form in org_forms_sample:
+            print(f"  • {form.kode}: {form.beskrivelse}")
+
+    except BrregRateLimitError as e:
+        print(f"Rate limit exceeded: {e}")
+    except BrregAPIError as e:
+        print(f"API error: {e} (Status code: {e.status_code})")
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+    finally:
+        # Always close the client to clean up resources
+        await client.close()
+        print("\nClient closed successfully")
+
+
+if __name__ == "__main__":
+    print("Brreg API Wrapper Demo")
+    print("======================\n")
+    asyncio.run(main())

{brreg_wrapper-0.2.3 → brreg_wrapper-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brreg-wrapper"
-version = "0.2.3"
+version = "0.3.0"
 description = "A Python wrapper for the Brønnøysund Register Centre (Brreg) API."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -43,6 +43,10 @@ all = [
     "h2>=4.0,<5.0", # HTTP/2 support
 ]
 
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
 [tool.pytest.ini_options]
 asyncio_mode = "strict" # Or "auto" if preferred
 # Explicitly set the default loop scope to 'function' to silence the warning
@@ -86,9 +90,14 @@ target-version = "py313"
 # Enable flake8-warning `W` codes by default.
 # Enable isort `I` codes by default.
 # See https://docs.astral.sh/ruff/rules/ for all rules.
-select = ["E", "F", "W", "I"]
+# B = flake8-bugbear, UP = pyupgrade.
+select = ["E", "F", "W", "I", "B", "UP"]
 ignore = []
 
+[tool.ruff.lint.per-file-ignores]
+# Generated by datamodel-code-generator; keep diffs against regenerations small.
+"src/brreg_wrapper/models/*" = ["UP"]
+
 # Allow autofix for all enabled rules (when `--fix`) is used.
 fixable = ["ALL"]
 unfixable = []

brreg_wrapper-0.3.0/scripts/README.md

@@ -0,0 +1,50 @@
+# Brreg Wrapper Development Scripts
+
+This directory contains utility scripts for developing and testing the `brreg-wrapper` package.
+
+## Available Scripts
+
+- `test_install.sh`: Shell script for testing the package installation on Unix-like systems (Linux, macOS)
+- `test_install.bat`: Batch script for testing the package installation on Windows
+
+## Using the Scripts
+
+These scripts help verify that the package installs correctly before publishing to PyPI. They:
+
+1. Create a test virtual environment
+2. Install the package in development mode
+3. Run a sample script to verify functionality
+4. Build a wheel package
+5. Install the wheel
+6. Run the sample script again with the installed package
+7. Clean up
+
+### On Unix-like Systems (Linux, macOS)
+
+```bash
+# Make the script executable
+chmod +x scripts/test_install.sh
+
+# Run the script
+./scripts/test_install.sh
+```
+
+### On Windows
+
+```cmd
+scripts\test_install.bat
+```
+
+## Requirements
+
+- Python 3.13 or later
+- UV package manager (recommended) or pip
+- bash shell (for Unix-like systems)
+- Windows command prompt or PowerShell (for Windows)
+
+## Notes
+
+- The scripts use the sample script in the `examples` directory to verify functionality
+- UV is used by default for faster installation and better dependency resolution
+- If UV is not available, it will be installed automatically on Unix systems
+- On Windows, you'll be given installation instructions if UV is not found 

brreg_wrapper-0.3.0/scripts/test_install.bat

@@ -0,0 +1,69 @@
+@echo off
+REM This script demonstrates how to test the brreg-wrapper package installation locally on Windows using UV
+
+echo Brreg Wrapper Local Testing with UV
+echo ==================================
+echo.
+
+REM Check if UV is installed
+where uv > nul 2>&1
+if %ERRORLEVEL% NEQ 0 (
+    echo UV not found. Please install UV first using:
+    echo curl -LsSf https://astral.sh/uv/install.ps1 ^| powershell -c -
+    exit /b 1
+)
+
+REM Check if a virtual environment exists
+if not exist test_venv (
+    echo Creating a test virtual environment with UV...
+    uv venv test_venv
+)
+
+REM Activate the virtual environment
+echo Activating virtual environment...
+call test_venv\Scripts\activate.bat
+
+REM Clean existing installations
+echo Cleaning any existing installations...
+uv pip uninstall -y brreg-wrapper
+
+REM Option 1: Install in development mode (editable)
+echo Installing package in development mode with UV...
+uv pip install -e .
+echo Package installed in development mode
+
+REM Run the sample script
+echo Running sample script...
+python examples\sample.py
+
+REM Option 2: Build and install the package from the wheel
+echo.
+echo.
+echo Building the package...
+uv pip install build
+python -m build
+
+REM Install the wheel
+echo Installing the built package from wheel with UV...
+uv pip uninstall -y brreg-wrapper
+uv pip install --find-links=dist\ brreg-wrapper
+echo Package installed from wheel
+
+REM Verify installation
+echo Verifying installation:
+uv pip show brreg-wrapper
+
+REM Run same sample script with the installed package
+echo Running sample script again...
+python examples\sample.py
+
+REM Deactivate virtual environment
+echo Cleaning up...
+call deactivate
+
+echo.
+echo All tests completed successfully!
+echo You can now upload the package to PyPI if all tests passed.
+echo Command to upload: python -m twine upload dist/*
+
+pause