shab-parser 0.1.0__tar.gz

shab_parser-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: shab-parser
+Version: 0.1.0
+Summary: Parse publications from the Swiss Official Gazette of Commerce (SHAB/SOGC/FUSC)
+Keywords: shab,sogc,fusc,swiss,commercial-register,handelsregister
+Author: Prospex
+Author-email: Prospex <hello@prospex.ch>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Typing :: Typed
+Requires-Dist: pytest>=8 ; extra == 'dev'
+Requires-Dist: httpx>=0.27 ; extra == 'dev'
+Requires-Dist: httpx>=0.27 ; extra == 'http'
+Requires-Python: >=3.14
+Project-URL: Homepage, https://prospex.ch
+Project-URL: Repository, https://github.com/ssidorenko/python-shab-parser
+Project-URL: Documentation, https://shab-parser.readthedocs.io
+Provides-Extra: dev
+Provides-Extra: http
+Description-Content-Type: text/markdown
+
+# shab-parser
+
+[![Documentation](https://readthedocs.org/projects/shab-parser/badge/?version=latest)](https://shab-parser.readthedocs.io/en/latest/)
+
+Typed Python client for the Swiss Official Gazette of Commerce (SHAB/SOGC/FUSC).
+
+Fetches publications from the [Amtsblattportal](https://amtsblattportal.ch) public API,
+parses the XML into dataclasses, and classifies each publication into structured events
+(incorporation, seat move, capital increase, deletion, and others).
+
+Built and maintained by [Prospex](https://prospex.ch), a Swiss B2B sales intelligence platform.
+
+## Install
+
+```bash
+pip install shab-parser
+```
+
+To use the HTTP client (for fetching from the live API):
+
+```bash
+pip install shab-parser[http]
+```
+
+## Quick start
+
+### Parse XML you already have
+
+```python
+from shab_parser import parse_xml
+
+with open("publication.xml", "rb") as f:
+    pub = parse_xml(f.read())
+
+print(pub.company_name)  # "Alpenblick Handel AG"
+print(pub.uid)           # "CHE-123.456.789"
+print(pub.canton)        # "ZH"
+
+for event in pub.events:
+    print(event.event_type, event.effective_date, event.payload)
+```
+
+### Fetch and parse from the API
+
+```python
+from datetime import date
+from shab_parser.client import ShabClient
+from shab_parser import parse
+
+with ShabClient() as client:
+    refs = client.discover(date(2026, 6, 15), date(2026, 6, 15))
+
+    for ref in refs[:5]:
+        raw = client.fetch(ref)
+        pub = parse(raw)
+        print(f"{pub.company_name}: {[e.event_type.value for e in pub.events]}")
+```
+
+The client rate-limits itself to one request per second and retries transient failures
+with exponential backoff.
+
+## Event types
+
+The parser classifies each publication into one or more of these events,
+based on the machine-readable XML fields (not free text):
+
+| Event | Sub-rubric | Trigger |
+|---|---|---|
+| `INCORPORATION` | HR01 | `<registration>true</registration>` |
+| `SEAT_MOVED` | HR02 | Different seat in commonsNew vs. commonsActual |
+| `ADDRESS_CHANGED` | HR02 | `<addressChanged>true</addressChanged>` |
+| `NAME_CHANGED` | HR02 | Different company name in commonsNew vs. commonsActual |
+| `CAPITAL_INCREASED` | HR02 | Structured nominal comparison, phrase fallback |
+| `LIQUIDATION` | any | Dissolution flags or "in Liquidation" added to name |
+| `DELETED` | HR03 | `<delete>` block with deletion date |
+
+## Data model
+
+`parse()` and `parse_xml()` return a `Publication` dataclass:
+
+```python
+@dataclass(frozen=True)
+class Publication:
+    external_id: str
+    publication_date: date
+    language: str          # "de", "fr", or "it"
+    source_url: str
+    company_name: str
+    raw_text: str
+    sub_rubric: str        # "HR01", "HR02", or "HR03"
+    effective_date: date | None
+    canton: str | None
+    uid: str | None        # CHE-xxx.xxx.xxx
+    legal_form_code: str | None
+    publication_state: str # "PUBLISHED" or "CANCELLED"
+    events: list[Event]
+    company_new: Company | None
+    company_actual: Company | None
+    capital_new: float | None
+    capital_actual: float | None
+```
+
+## API reference
+
+### `shab_parser.parse(raw: RawResponse) -> Publication`
+
+Parse a `RawResponse` (as returned by `ShabClient.fetch()`) into a `Publication`.
+
+### `shab_parser.parse_xml(xml_bytes, *, source_url="", ref_state=None) -> Publication`
+
+Parse raw XML bytes directly. Use this when you already have the XML
+and don't need the HTTP client.
+
+### `shab_parser.client.ShabClient`
+
+HTTP client for the Amtsblattportal API. Requires the `http` extra.
+
+- `discover(start, end)` lists all HR publications in a date range.
+  Queries both `PUBLISHED` and `CANCELLED` states, deduplicating by external ID.
+- `fetch(ref)` downloads one publication's full XML.
+
+### `shab_parser.client.parse_bulk_export(xml_bytes) -> (list[PublicationRef], int)`
+
+Parse a bulk-export list page into publication references and a total count.
+Useful if you handle pagination yourself.
+
+## Background
+
+SHAB (Schweizerisches Handelsamtsblatt) is the official gazette where Swiss commercial
+register entries are published. Every new company, every seat change, every capital
+increase, every deletion passes through it. The same publication appears in German, French,
+and Italian, each under a different namespace (`HR01:`, `HR02:`, `HR03:`), but with
+identical XML structure.
+
+This library handles the namespace differences transparently using ElementPath's `{*}`
+wildcard, so you get the same parsed output regardless of language.
+
+## License
+
+MIT

shab_parser-0.1.0/README.md

@@ -0,0 +1,140 @@
+# shab-parser
+
+[![Documentation](https://readthedocs.org/projects/shab-parser/badge/?version=latest)](https://shab-parser.readthedocs.io/en/latest/)
+
+Typed Python client for the Swiss Official Gazette of Commerce (SHAB/SOGC/FUSC).
+
+Fetches publications from the [Amtsblattportal](https://amtsblattportal.ch) public API,
+parses the XML into dataclasses, and classifies each publication into structured events
+(incorporation, seat move, capital increase, deletion, and others).
+
+Built and maintained by [Prospex](https://prospex.ch), a Swiss B2B sales intelligence platform.
+
+## Install
+
+```bash
+pip install shab-parser
+```
+
+To use the HTTP client (for fetching from the live API):
+
+```bash
+pip install shab-parser[http]
+```
+
+## Quick start
+
+### Parse XML you already have
+
+```python
+from shab_parser import parse_xml
+
+with open("publication.xml", "rb") as f:
+    pub = parse_xml(f.read())
+
+print(pub.company_name)  # "Alpenblick Handel AG"
+print(pub.uid)           # "CHE-123.456.789"
+print(pub.canton)        # "ZH"
+
+for event in pub.events:
+    print(event.event_type, event.effective_date, event.payload)
+```
+
+### Fetch and parse from the API
+
+```python
+from datetime import date
+from shab_parser.client import ShabClient
+from shab_parser import parse
+
+with ShabClient() as client:
+    refs = client.discover(date(2026, 6, 15), date(2026, 6, 15))
+
+    for ref in refs[:5]:
+        raw = client.fetch(ref)
+        pub = parse(raw)
+        print(f"{pub.company_name}: {[e.event_type.value for e in pub.events]}")
+```
+
+The client rate-limits itself to one request per second and retries transient failures
+with exponential backoff.
+
+## Event types
+
+The parser classifies each publication into one or more of these events,
+based on the machine-readable XML fields (not free text):
+
+| Event | Sub-rubric | Trigger |
+|---|---|---|
+| `INCORPORATION` | HR01 | `<registration>true</registration>` |
+| `SEAT_MOVED` | HR02 | Different seat in commonsNew vs. commonsActual |
+| `ADDRESS_CHANGED` | HR02 | `<addressChanged>true</addressChanged>` |
+| `NAME_CHANGED` | HR02 | Different company name in commonsNew vs. commonsActual |
+| `CAPITAL_INCREASED` | HR02 | Structured nominal comparison, phrase fallback |
+| `LIQUIDATION` | any | Dissolution flags or "in Liquidation" added to name |
+| `DELETED` | HR03 | `<delete>` block with deletion date |
+
+## Data model
+
+`parse()` and `parse_xml()` return a `Publication` dataclass:
+
+```python
+@dataclass(frozen=True)
+class Publication:
+    external_id: str
+    publication_date: date
+    language: str          # "de", "fr", or "it"
+    source_url: str
+    company_name: str
+    raw_text: str
+    sub_rubric: str        # "HR01", "HR02", or "HR03"
+    effective_date: date | None
+    canton: str | None
+    uid: str | None        # CHE-xxx.xxx.xxx
+    legal_form_code: str | None
+    publication_state: str # "PUBLISHED" or "CANCELLED"
+    events: list[Event]
+    company_new: Company | None
+    company_actual: Company | None
+    capital_new: float | None
+    capital_actual: float | None
+```
+
+## API reference
+
+### `shab_parser.parse(raw: RawResponse) -> Publication`
+
+Parse a `RawResponse` (as returned by `ShabClient.fetch()`) into a `Publication`.
+
+### `shab_parser.parse_xml(xml_bytes, *, source_url="", ref_state=None) -> Publication`
+
+Parse raw XML bytes directly. Use this when you already have the XML
+and don't need the HTTP client.
+
+### `shab_parser.client.ShabClient`
+
+HTTP client for the Amtsblattportal API. Requires the `http` extra.
+
+- `discover(start, end)` lists all HR publications in a date range.
+  Queries both `PUBLISHED` and `CANCELLED` states, deduplicating by external ID.
+- `fetch(ref)` downloads one publication's full XML.
+
+### `shab_parser.client.parse_bulk_export(xml_bytes) -> (list[PublicationRef], int)`
+
+Parse a bulk-export list page into publication references and a total count.
+Useful if you handle pagination yourself.
+
+## Background
+
+SHAB (Schweizerisches Handelsamtsblatt) is the official gazette where Swiss commercial
+register entries are published. Every new company, every seat change, every capital
+increase, every deletion passes through it. The same publication appears in German, French,
+and Italian, each under a different namespace (`HR01:`, `HR02:`, `HR03:`), but with
+identical XML structure.
+
+This library handles the namespace differences transparently using ElementPath's `{*}`
+wildcard, so you get the same parsed output regardless of language.
+
+## License
+
+MIT

shab_parser-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "shab-parser"
+version = "0.1.0"
+description = "Parse publications from the Swiss Official Gazette of Commerce (SHAB/SOGC/FUSC)"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Prospex", email = "hello@prospex.ch" },
+]
+requires-python = ">=3.14"
+keywords = ["shab", "sogc", "fusc", "swiss", "commercial-register", "handelsregister"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Text Processing :: Markup :: XML",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+http = ["httpx>=0.27"]
+dev = ["pytest>=8", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://prospex.ch"
+Repository = "https://github.com/ssidorenko/python-shab-parser"
+Documentation = "https://shab-parser.readthedocs.io"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

shab_parser-0.1.0/src/shab_parser/__init__.py

@@ -0,0 +1,39 @@
+"""Parse publications from the Swiss Official Gazette of Commerce (SHAB/SOGC/FUSC)."""
+
+from .schemas import (
+    Company,
+    DateRange,
+    Event,
+    EventType,
+    Language,
+    ParserError,
+    Publication,
+    PublicationRef,
+    PublicationState,
+    RawResponse,
+    RetryableError,
+    ShabError,
+    SubRubric,
+    TransportError,
+)
+from .parser import parse, parse_xml, PARSER_VERSION
+
+__all__ = [
+    "Company",
+    "DateRange",
+    "Event",
+    "EventType",
+    "Language",
+    "PARSER_VERSION",
+    "ParserError",
+    "Publication",
+    "PublicationRef",
+    "PublicationState",
+    "RawResponse",
+    "RetryableError",
+    "ShabError",
+    "SubRubric",
+    "TransportError",
+    "parse",
+    "parse_xml",
+]

shab_parser-0.1.0/src/shab_parser/_xml_utils.py

@@ -0,0 +1,26 @@
+"""Namespace-agnostic helpers for SHAB XML feeds.
+
+SHAB publications use a different namespace per sub-rubric (HR01/HR02/HR03) and
+the bulk export uses its own. The ``{*}`` wildcard in ElementPath matches any
+namespace, so a single path works across all of them.
+"""
+
+from __future__ import annotations
+
+from xml.etree import ElementTree as ET
+
+
+def child_text(elem: ET.Element | None, path: str) -> str | None:
+    """Stripped text of the first element matching *path*, or ``None``."""
+    if elem is None:
+        return None
+    found = elem.find(path)
+    if found is None or found.text is None:
+        return None
+    text = found.text.strip()
+    return text or None
+
+
+def is_true(elem: ET.Element | None, path: str) -> bool:
+    """True iff *path* resolves to an element whose text is ``"true"``."""
+    return child_text(elem, path) == "true"

shab_parser-0.1.0/src/shab_parser/client.py

@@ -0,0 +1,210 @@
+"""HTTP client for the Amtsblattportal public API.
+
+Requires the ``http`` extra (``pip install shab-parser[http]``), which pulls in
+`httpx <https://www.python-httpx.org/>`_.
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import date, datetime, timezone
+from xml.etree import ElementTree as ET
+
+from .schemas import (
+    DateRange,
+    PublicationRef,
+    PublicationState,
+    RawResponse,
+    RetryableError,
+    TransportError,
+)
+from ._xml_utils import child_text
+
+DEFAULT_BASE_URL = "https://amtsblattportal.ch/api/v1"
+
+MAX_PAGE_SIZE = 2000
+
+
+def parse_bulk_export(xml_bytes: bytes) -> tuple[list[PublicationRef], int]:
+    """Parse a bulk-export list page into refs and the total count."""
+    try:
+        root = ET.fromstring(xml_bytes)
+    except ET.ParseError as exc:
+        raise TransportError(f"invalid bulk-export XML: {exc}") from exc
+
+    total = int(child_text(root, "{*}total") or "0")
+    refs: list[PublicationRef] = []
+    for pub in root.findall("{*}publication"):
+        url = pub.get("ref")
+        meta = pub.find("{*}meta")
+        external_id = child_text(meta, "{*}id")
+        pub_date = child_text(meta, "{*}publicationDate")
+        if not (url and external_id and pub_date):
+            continue
+        refs.append(
+            PublicationRef(
+                external_id=external_id,
+                publication_date=date.fromisoformat(pub_date),
+                language=(child_text(meta, "{*}language") or "").lower(),
+                url=url,
+                publication_state=(
+                    child_text(meta, "{*}publicationState")
+                    or PublicationState.PUBLISHED
+                ).upper(),
+            )
+        )
+    return refs, total
+
+
+class ShabClient:
+    """Polite HTTP client for the SHAB publication API.
+
+    Rate-limits requests to at most one per *min_interval* seconds and retries
+    transient failures with exponential backoff.
+
+    Args:
+        base_url: Root of the Amtsblattportal API.
+        min_interval: Minimum seconds between requests (rate limit).
+        timeout: HTTP timeout in seconds.
+        page_size: Publications per page when listing (max 2000).
+        max_retries: How many times to retry a transient failure.
+        user_agent: User-Agent header sent with every request.
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        min_interval: float = 1.0,
+        timeout: float = 30.0,
+        page_size: int = 500,
+        max_retries: int = 4,
+        user_agent: str = "python-shab-parser/0.1",
+    ) -> None:
+        try:
+            import httpx
+        except ImportError:
+            raise ImportError(
+                "httpx is required for ShabClient. "
+                "Install it with: pip install shab-parser[http]"
+            ) from None
+
+        if not 1 <= page_size <= MAX_PAGE_SIZE:
+            raise ValueError(f"page_size must be in 1..{MAX_PAGE_SIZE}, got {page_size!r}")
+
+        self.base_url = base_url.rstrip("/")
+        self.min_interval = min_interval
+        self.page_size = page_size
+        self.max_retries = max_retries
+        self._last_request_at = 0.0
+        self._client = httpx.Client(
+            timeout=timeout, headers={"User-Agent": user_agent}
+        )
+
+    def _throttle(self) -> None:
+        elapsed = time.monotonic() - self._last_request_at
+        if elapsed < self.min_interval:
+            time.sleep(self.min_interval - elapsed)
+        self._last_request_at = time.monotonic()
+
+    def _get(self, url: str, params: dict | None = None):
+        import httpx
+
+        self._throttle()
+        try:
+            response = self._client.get(url, params=params)
+        except httpx.TransportError as exc:
+            raise RetryableError(str(exc)) from exc
+
+        if response.status_code == 429 or 500 <= response.status_code < 600:
+            raise RetryableError(f"HTTP {response.status_code} for {url}")
+        if response.status_code >= 400:
+            raise TransportError(f"HTTP {response.status_code} for {url}")
+        return response
+
+    def _get_with_retry(self, url: str, params: dict | None = None):
+        last_exc: Exception | None = None
+        backoff = 0.5
+        for attempt in range(self.max_retries + 1):
+            try:
+                return self._get(url, params)
+            except RetryableError as exc:
+                last_exc = exc
+                if attempt < self.max_retries:
+                    time.sleep(min(backoff, 30.0))
+                    backoff *= 2
+        raise last_exc  # type: ignore[misc]
+
+    def discover(
+        self,
+        start: date,
+        end: date,
+    ) -> list[PublicationRef]:
+        """List all HR publications in a date window.
+
+        Both ``PUBLISHED`` and ``CANCELLED`` states are queried. When the same
+        publication appears in both, ``CANCELLED`` wins.
+        """
+        refs: list[PublicationRef] = []
+        for state in (PublicationState.PUBLISHED, PublicationState.CANCELLED):
+            refs.extend(self._discover_state(DateRange(start, end), state))
+        return _dedupe(refs)
+
+    def _discover_state(
+        self, date_range: DateRange, state: str
+    ) -> list[PublicationRef]:
+        refs: list[PublicationRef] = []
+        page = 0
+        while True:
+            params = {
+                "tenant": "shab",
+                "rubrics": "HR",
+                "publicationStates": state,
+                "publicationDate.start": date_range.start.isoformat(),
+                "publicationDate.end": date_range.end.isoformat(),
+                "pageRequest.page": page,
+                "pageRequest.size": self.page_size,
+            }
+            response = self._get_with_retry(
+                f"{self.base_url}/publications/xml", params=params
+            )
+            page_refs, total = parse_bulk_export(response.content)
+            refs.extend(page_refs)
+            if not page_refs or len(refs) >= total:
+                break
+            page += 1
+        return refs
+
+    def fetch(self, ref: PublicationRef) -> RawResponse:
+        """Fetch the full XML body of one publication."""
+        response = self._get_with_retry(ref.url)
+        return RawResponse(
+            ref=ref,
+            content=response.content,
+            content_type=response.headers.get("content-type", "application/xml"),
+            fetched_at=datetime.now(timezone.utc),
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+def _dedupe(refs: list[PublicationRef]) -> list[PublicationRef]:
+    """Collapse by external_id, preferring CANCELLED over PUBLISHED."""
+    seen: dict[str, PublicationRef] = {}
+    for ref in refs:
+        existing = seen.get(ref.external_id)
+        if existing is None or (
+            ref.publication_state == PublicationState.CANCELLED
+            and existing.publication_state != PublicationState.CANCELLED
+        ):
+            seen[ref.external_id] = ref
+    result = list(seen.values())
+    result.sort(key=lambda r: (r.publication_date, r.external_id))
+    return result

shab_parser-0.1.0/src/shab_parser/parser.py

@@ -0,0 +1,332 @@
+"""Parse SHAB publication XML into structured :class:`Publication` objects.
+
+Event classification is driven by the machine-readable ``subRubric`` and
+``<transaction>`` block (registration / changements flags / delete), so German,
+French and Italian publications of the same act produce the same event types.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date
+from xml.etree import ElementTree as ET
+
+from .schemas import (
+    Company,
+    Event,
+    EventType,
+    ParserError,
+    Publication,
+    PublicationState,
+    RawResponse,
+)
+from ._xml_utils import child_text, is_true
+
+PARSER_VERSION = "shab-parser/0.1.0"
+
+LIQUIDATION_RE = re.compile(
+    r"\s*(?:in\s+Liquidation|en\s+liquidation|in\s+liquidazione)\s*",
+    re.IGNORECASE,
+)
+
+LIQUIDATION_DISSOLUTION_PATHS = (
+    "{*}statusChanged/{*}liquidation/{*}dissolution/{*}nonExceptional",
+    "{*}statusChanged/{*}liquidation/{*}dissolution/{*}or731b",
+    "{*}statusChanged/{*}liquidation/{*}dissolution/{*}hregv153b",
+    "{*}statusChanged/{*}bankruptcy/{*}dissolution",
+)
+
+CAPITAL_INCREASE_PHRASES: dict[str, list[str]] = {
+    "de": [
+        "kapitalerhöhung",
+        "erhöhung des aktienkapitals",
+        "erhöhung des stammkapitals",
+        "erhöhung des kapitals",
+    ],
+    "fr": ["augmentation du capital", "augmentation de capital"],
+    "it": ["aumento del capitale", "aumento di capitale"],
+}
+
+TAXONOMY_ORDER = [e.value for e in EventType]
+
+_SUPPORTED_LANGUAGES = ("de", "fr", "it")
+
+
+def parse(raw: RawResponse) -> Publication:
+    """Parse one raw response into a :class:`Publication`.
+
+    Raises :class:`ParserError` for permanently unparseable input.
+    """
+    return parse_xml(raw.content, source_url=raw.ref.url, ref_state=raw.ref.publication_state)
+
+
+def parse_xml(
+    xml_bytes: bytes,
+    *,
+    source_url: str = "",
+    ref_state: str | None = None,
+) -> Publication:
+    """Parse raw XML bytes into a :class:`Publication`.
+
+    This is the lower-level entry point when you already have the XML
+    and don't need the client's :class:`RawResponse` wrapper.
+    """
+    try:
+        root = ET.fromstring(xml_bytes)
+    except ET.ParseError as exc:
+        raise ParserError(f"invalid XML body: {exc}") from exc
+
+    meta = root.find("{*}meta")
+    if meta is None:
+        raise ParserError("missing <meta> element")
+
+    external_id = child_text(meta, "{*}id")
+    if not external_id:
+        raise ParserError("missing meta/id")
+
+    language = (child_text(meta, "{*}language") or "").lower()
+    if language not in _SUPPORTED_LANGUAGES:
+        raise ParserError(f"unsupported language: {language!r}")
+
+    publication_date = _parse_date(child_text(meta, "{*}publicationDate"))
+    if publication_date is None:
+        raise ParserError("missing publicationDate")
+
+    sub_rubric = child_text(meta, "{*}subRubric") or ""
+    canton = child_text(meta, "{*}cantons")
+    publication_state = _resolve_publication_state(
+        child_text(meta, "{*}publicationState"), ref_state
+    )
+    content_el = root.find("{*}content")
+
+    company_el = None
+    if content_el is not None:
+        for path in ("{*}commonsNew/{*}company", "{*}commonsActual/{*}company"):
+            company_el = content_el.find(path)
+            if company_el is not None:
+                break
+    company_name = child_text(company_el, "{*}name")
+    uid = child_text(company_el, "{*}uid")
+    legal_form_code = child_text(company_el, "{*}legalForm")
+
+    prior_name = child_text(
+        content_el, "{*}commonsActual/{*}company/{*}name"
+    ) if content_el is not None else ""
+    new_name = child_text(
+        content_el, "{*}commonsNew/{*}company/{*}name"
+    ) if content_el is not None else ""
+
+    prior_seat = child_text(
+        content_el, "{*}commonsActual/{*}company/{*}seat"
+    ) if content_el is not None else ""
+    new_seat = child_text(
+        content_el, "{*}commonsNew/{*}company/{*}seat"
+    ) if content_el is not None else ""
+
+    title = child_text(meta, f"{{*}}title/{{*}}{language}")
+    if not company_name:
+        company_name = title
+    if not company_name:
+        raise ParserError("missing company name")
+
+    raw_text = child_text(content_el, "{*}publicationText") or title or ""
+
+    transaction = content_el.find("{*}transaction") if content_el is not None else None
+    journal_date = _parse_date(child_text(content_el, "{*}journalDate"))
+    deletion_date = _parse_date(child_text(transaction, "{*}delete/{*}deletionDate"))
+
+    effective_date = deletion_date if sub_rubric == "HR03" else journal_date
+
+    company_new = _extract_company(content_el, "{*}commonsNew/{*}company")
+    company_actual = _extract_company(content_el, "{*}commonsActual/{*}company")
+    capital_new = _to_float(child_text(content_el, "{*}commonsNew/{*}capital/{*}nominal"))
+    capital_actual = _to_float(child_text(content_el, "{*}commonsActual/{*}capital/{*}nominal"))
+
+    events = _classify(
+        sub_rubric, transaction, content_el, prior_name, new_name,
+        prior_seat, new_seat, raw_text, language, journal_date, deletion_date,
+    )
+
+    return Publication(
+        external_id=external_id,
+        publication_date=publication_date,
+        language=language,
+        source_url=source_url,
+        company_name=company_name,
+        raw_text=raw_text,
+        sub_rubric=sub_rubric,
+        effective_date=effective_date,
+        canton=canton or None,
+        uid=uid or None,
+        legal_form_code=legal_form_code or None,
+        publication_state=publication_state,
+        events=events,
+        company_new=company_new,
+        company_actual=company_actual,
+        capital_new=capital_new,
+        capital_actual=capital_actual,
+    )
+
+
+def _extract_company(content_el: ET.Element | None, path: str) -> Company | None:
+    if content_el is None:
+        return None
+    el = content_el.find(path)
+    if el is None:
+        return None
+    name = child_text(el, "{*}name")
+    if not name:
+        return None
+    return Company(
+        name=name,
+        uid=child_text(el, "{*}uid"),
+        seat=child_text(el, "{*}seat"),
+        legal_form_code=child_text(el, "{*}legalForm"),
+    )
+
+
+def _resolve_publication_state(body_state: str | None, ref_state: str | None) -> str:
+    body = (body_state or "").upper()
+    ref = (ref_state or "").upper()
+    if body and ref and body != ref and PublicationState.CANCELLED in (body, ref):
+        return PublicationState.CANCELLED
+    return body or ref or PublicationState.PUBLISHED
+
+
+def _renamed_beyond_liquidation(prior_name: str, new_name: str) -> bool:
+    prior = LIQUIDATION_RE.sub("", prior_name).strip()
+    new = LIQUIDATION_RE.sub("", new_name).strip()
+    return prior != new
+
+
+def _classify(
+    sub_rubric: str,
+    transaction: ET.Element | None,
+    content_el: ET.Element | None,
+    prior_name: str,
+    new_name: str,
+    prior_seat: str,
+    new_seat: str,
+    text: str,
+    language: str,
+    journal_date: date | None,
+    deletion_date: date | None,
+) -> list[Event]:
+    found: dict[str, Event] = {}
+    haystack = text.lower()
+    changements = transaction.find("{*}update/{*}changements") if transaction is not None else None
+
+    def add(event_type: EventType, effective_date: date | None, payload: dict) -> None:
+        found[event_type.value] = Event(
+            event_type=event_type, effective_date=effective_date, payload=payload
+        )
+
+    if sub_rubric == "HR01":
+        if is_true(transaction, "{*}registration"):
+            payload: dict = {"sub_rubric": sub_rubric, "trigger": "registration"}
+            nominal = _to_float(child_text(content_el, "{*}commonsNew/{*}capital/{*}nominal"))
+            if nominal is not None:
+                payload["capital_nominal"] = nominal
+            add(EventType.INCORPORATION, journal_date, payload)
+
+    elif sub_rubric == "HR02":
+        if prior_seat and new_seat and prior_seat.strip() != new_seat.strip():
+            add(EventType.SEAT_MOVED, journal_date, {
+                "sub_rubric": sub_rubric,
+                "from": prior_seat.strip(),
+                "to": new_seat.strip(),
+            })
+        if is_true(changements, "{*}addressChanged"):
+            add(EventType.ADDRESS_CHANGED, journal_date, {"sub_rubric": sub_rubric})
+        if (
+            prior_name
+            and new_name
+            and prior_name.strip() != new_name.strip()
+            and _renamed_beyond_liquidation(prior_name, new_name)
+        ):
+            add(EventType.NAME_CHANGED, journal_date, {
+                "sub_rubric": sub_rubric,
+                "from": prior_name.strip(),
+                "to": new_name.strip(),
+            })
+        capital = _capital_change(changements, content_el, haystack, language)
+        if capital is not None:
+            add(EventType.CAPITAL_INCREASED, journal_date, {"sub_rubric": sub_rubric, **capital})
+
+    elif sub_rubric == "HR03":
+        if transaction is not None and transaction.find("{*}delete") is not None:
+            add(EventType.DELETED, deletion_date or journal_date, {"sub_rubric": sub_rubric})
+
+    dissolved = any(
+        is_true(changements, path) for path in LIQUIDATION_DISSOLUTION_PATHS
+    )
+    entered = bool(
+        prior_name
+        and new_name
+        and not LIQUIDATION_RE.search(prior_name)
+        and LIQUIDATION_RE.search(new_name)
+    )
+    if dissolved or entered:
+        add(EventType.LIQUIDATION, journal_date, {
+            "sub_rubric": sub_rubric,
+            "trigger": "statusChanged" if dissolved else "name_entered_liquidation",
+            "from": (prior_name or "").strip(),
+            "to": (new_name or "").strip(),
+        })
+
+    return [found[et] for et in TAXONOMY_ORDER if et in found]
+
+
+def _capital_change(
+    changements: ET.Element | None,
+    content_el: ET.Element | None,
+    haystack: str,
+    language: str,
+) -> dict | None:
+    capital = changements.find("{*}capitalChanged") if changements is not None else None
+    if capital is None:
+        return None
+    if not (is_true(capital, "{*}nominal") or is_true(capital, "{*}paid")):
+        return None
+
+    new_nominal = _to_float(child_text(content_el, "{*}commonsNew/{*}capital/{*}nominal"))
+    old_nominal = _to_float(child_text(content_el, "{*}commonsActual/{*}capital/{*}nominal"))
+    if new_nominal is not None and old_nominal is not None:
+        if new_nominal > old_nominal:
+            return {"from": old_nominal, "to": new_nominal, "direction": "structured"}
+        return None
+
+    phrase = _capital_increase_phrase(language, haystack)
+    if phrase:
+        return {
+            "from": old_nominal,
+            "to": new_nominal,
+            "direction": "phrase",
+            "matched_phrase": phrase,
+        }
+    return None
+
+
+def _capital_increase_phrase(language: str, haystack: str) -> str | None:
+    for phrase in CAPITAL_INCREASE_PHRASES.get(language, []):
+        if phrase in haystack:
+            return phrase
+    return None
+
+
+def _to_float(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return float(value.replace("'", "").replace(" ", ""))
+    except ValueError:
+        return None
+
+
+def _parse_date(value: str | None) -> date | None:
+    if not value:
+        return None
+    try:
+        return date.fromisoformat(value)
+    except ValueError as exc:
+        raise ParserError(f"invalid date {value!r}: {exc}") from exc

shab_parser-0.1.0/src/shab_parser/schemas.py

@@ -0,0 +1,127 @@
+"""Data contracts for parsed SHAB publications.
+
+Plain dataclasses with no external dependencies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from enum import Enum
+
+
+class PublicationState(str, Enum):
+    PUBLISHED = "PUBLISHED"
+    CANCELLED = "CANCELLED"
+
+
+class SubRubric(str, Enum):
+    """The three commercial-register sub-rubrics."""
+
+    HR01 = "HR01"  # new registrations
+    HR02 = "HR02"  # mutations
+    HR03 = "HR03"  # deletions
+
+
+class EventType(str, Enum):
+    INCORPORATION = "INCORPORATION"
+    SEAT_MOVED = "SEAT_MOVED"
+    ADDRESS_CHANGED = "ADDRESS_CHANGED"
+    NAME_CHANGED = "NAME_CHANGED"
+    CAPITAL_INCREASED = "CAPITAL_INCREASED"
+    LIQUIDATION = "LIQUIDATION"
+    DELETED = "DELETED"
+
+
+class Language(str, Enum):
+    DE = "de"
+    FR = "fr"
+    IT = "it"
+
+
+@dataclass(frozen=True)
+class DateRange:
+    start: date
+    end: date
+
+    def contains(self, day: date) -> bool:
+        return self.start <= day <= self.end
+
+
+@dataclass(frozen=True)
+class PublicationRef:
+    """A discovered publication, before its body is fetched."""
+
+    external_id: str
+    publication_date: date
+    language: str
+    url: str
+    publication_state: str = PublicationState.PUBLISHED
+
+
+@dataclass(frozen=True)
+class RawResponse:
+    """The bytes returned for one publication."""
+
+    ref: PublicationRef
+    content: bytes
+    content_type: str
+    fetched_at: datetime
+
+
+@dataclass(frozen=True)
+class Event:
+    """One classified event from a publication."""
+
+    event_type: EventType
+    effective_date: date | None = None
+    payload: dict = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Company:
+    """Structured company data from the XML."""
+
+    name: str
+    uid: str | None = None
+    seat: str | None = None
+    legal_form_code: str | None = None
+
+
+@dataclass(frozen=True)
+class Publication:
+    """A fully parsed SHAB publication."""
+
+    external_id: str
+    publication_date: date
+    language: str
+    source_url: str
+    company_name: str
+    raw_text: str
+    sub_rubric: str
+    effective_date: date | None = None
+    canton: str | None = None
+    uid: str | None = None
+    legal_form_code: str | None = None
+    publication_state: str = PublicationState.PUBLISHED
+    events: list[Event] = field(default_factory=list)
+    company_new: Company | None = None
+    company_actual: Company | None = None
+    capital_new: float | None = None
+    capital_actual: float | None = None
+
+
+class ShabError(Exception):
+    """Base exception for shab-parser."""
+
+
+class ParserError(ShabError):
+    """Input that cannot be parsed."""
+
+
+class TransportError(ShabError):
+    """A request to the SHAB API failed."""
+
+
+class RetryableError(TransportError):
+    """A transient failure (rate limit, server error) worth retrying."""