catalejo 0.1.0__py3-none-any.whl

catalejo/__init__.py

@@ -0,0 +1,10 @@
+"""catalejo: Spanish CNMV public data, made usable."""
+
+__version__ = "0.1.0"
+
+from catalejo.documents import document_text
+from catalejo.filings import filings
+from catalejo.models import Filing, Security
+from catalejo.securities import securities
+
+__all__ = ["Filing", "Security", "document_text", "filings", "securities"]

catalejo/_http.py

@@ -0,0 +1,203 @@
+"""Polite HTTP client for cnmv.es.
+
+Everything catalejo downloads goes through here, so the rules for being a
+good citizen live in one place:
+
+* identifiable User-Agent,
+* at most one request per ``min_interval`` seconds,
+* on-disk cache so repeated calls don't hit the CNMV again,
+* a few retries with backoff on 429/5xx and network errors,
+* only *.cnmv.es hosts are allowed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import httpx
+
+from catalejo import __version__
+
+USER_AGENT = f"catalejo/{__version__} (+https://github.com/polfananas/catalejo)"
+ALLOWED_HOST_SUFFIX = "cnmv.es"
+RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+
+class CNMVRequestError(RuntimeError):
+    """Raised when the CNMV can't be reached or keeps answering with errors."""
+
+
+@dataclass(frozen=True)
+class Response:
+    url: str
+    status_code: int
+    content: bytes
+    content_type: str
+    from_cache: bool = False
+
+    @property
+    def text(self) -> str:
+        return self.content.decode("utf-8", errors="replace")
+
+
+def default_cache_dir() -> Path:
+    env = os.environ.get("CATALEJO_CACHE_DIR")
+    if env:
+        return Path(env)
+    base = os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    return Path(base) / "catalejo"
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        cache_dir: Path | None = None,
+        cache_ttl: float = 3600.0,
+        min_interval: float = 1.0,
+        max_retries: int = 3,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.cache_dir = cache_dir if cache_dir is not None else default_cache_dir()
+        self.cache_ttl = cache_ttl
+        self.min_interval = min_interval
+        self.max_retries = max_retries
+        self._sleep = sleep
+        self._clock = clock
+        self._last_request: float | None = None
+        self._client = httpx.Client(
+            headers={"User-Agent": USER_AGENT},
+            timeout=timeout,
+            follow_redirects=True,
+            transport=transport,
+        )
+
+    # -- public -----------------------------------------------------------
+
+    def get(
+        self,
+        url: str,
+        params: Mapping[str, str | int] | None = None,
+        *,
+        use_cache: bool = True,
+        ttl: float | None = None,
+    ) -> Response:
+        """GET a cnmv.es URL. `ttl` overrides the client's cache_ttl for this call
+        (use `math.inf` for things that never change, like filed documents)."""
+        _check_host(url)
+        key = _cache_key(url, params)
+        ttl = self.cache_ttl if ttl is None else ttl
+
+        if use_cache and ttl > 0:
+            cached = self._read_cache(key, ttl)
+            if cached is not None:
+                return cached
+
+        response = self._fetch(url, params)
+        if use_cache and ttl > 0:
+            self._write_cache(key, response)
+        return response
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- internals --------------------------------------------------------
+
+    def _throttle(self) -> None:
+        if self._last_request is not None:
+            wait = self.min_interval - (self._clock() - self._last_request)
+            if wait > 0:
+                self._sleep(wait)
+        self._last_request = self._clock()
+
+    def _fetch(self, url: str, params: Mapping[str, str | int] | None) -> Response:
+        last_error: str = ""
+        for attempt in range(self.max_retries + 1):
+            if attempt:
+                self._sleep(min(2**attempt, 30))
+            self._throttle()
+            try:
+                r = self._client.get(url, params=dict(params) if params else None)
+            except httpx.TransportError as e:
+                last_error = f"{type(e).__name__}: {e}"
+                continue
+
+            if r.status_code in RETRY_STATUSES:
+                last_error = f"HTTP {r.status_code}"
+                retry_after = r.headers.get("Retry-After", "")
+                if retry_after.isdigit():
+                    self._sleep(min(int(retry_after), 60))
+                continue
+            if r.status_code >= 400:
+                raise CNMVRequestError(f"HTTP {r.status_code} for {r.url}")
+
+            return Response(
+                url=str(r.url),
+                status_code=r.status_code,
+                content=r.content,
+                content_type=r.headers.get("Content-Type", ""),
+            )
+
+        raise CNMVRequestError(
+            f"giving up on {url} after {self.max_retries + 1} attempts ({last_error})"
+        )
+
+    def _read_cache(self, key: str, ttl: float) -> Response | None:
+        meta_path = self.cache_dir / f"{key}.json"
+        body_path = self.cache_dir / f"{key}.bin"
+        try:
+            meta = json.loads(meta_path.read_text())
+            if time.time() - meta["fetched_at"] > ttl:
+                return None
+            content = body_path.read_bytes()
+        except (OSError, ValueError, KeyError):
+            return None
+        return Response(
+            url=meta["url"],
+            status_code=meta["status_code"],
+            content=content,
+            content_type=meta["content_type"],
+            from_cache=True,
+        )
+
+    def _write_cache(self, key: str, response: Response) -> None:
+        try:
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+            (self.cache_dir / f"{key}.bin").write_bytes(response.content)
+            meta = {
+                "url": response.url,
+                "status_code": response.status_code,
+                "content_type": response.content_type,
+                "fetched_at": time.time(),
+            }
+            (self.cache_dir / f"{key}.json").write_text(json.dumps(meta))
+        except OSError:
+            pass  # a broken cache shouldn't break the request
+
+
+def _check_host(url: str) -> None:
+    host = (urlsplit(url).hostname or "").lower()
+    if host != ALLOWED_HOST_SUFFIX and not host.endswith("." + ALLOWED_HOST_SUFFIX):
+        raise ValueError(f"catalejo only talks to cnmv.es, got {host!r}")
+
+
+def _cache_key(url: str, params: Mapping[str, str | int] | None) -> str:
+    items = sorted((k, str(v)) for k, v in (params or {}).items())
+    raw = url + "?" + "&".join(f"{k}={v}" for k, v in items)
+    return hashlib.sha256(raw.encode()).hexdigest()[:32]

catalejo/_parse.py

@@ -0,0 +1,162 @@
+"""HTML parsing for CNMV result listings (IP and OIR share the same markup)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import date, datetime
+from urllib.parse import unquote
+from zoneinfo import ZoneInfo
+
+from selectolax.lexbor import LexborHTMLParser as HTMLParser
+from selectolax.lexbor import LexborNode as Node
+
+from catalejo.models import Filing, FilingKind, Security
+
+MADRID = ZoneInfo("Europe/Madrid")
+
+_PAGE_INFO = re.compile(r"(\d+)\D+(\d+)")  # "Página 1 de 8" / "Page 1 out of 8"
+_REGISTRY = re.compile(r"(\d+)\s*$")
+
+
+class CNMVParseError(ValueError):
+    """The page didn't look like we expected. Probably the CNMV changed its HTML."""
+
+
+@dataclass(frozen=True, slots=True)
+class ResultsPage:
+    filings: list[Filing]
+    page: int
+    """1-based number of this page."""
+    total_pages: int
+
+    @property
+    def is_last(self) -> bool:
+        return self.page >= self.total_pages
+
+
+def parse_results_page(html: str, kind: FilingKind) -> ResultsPage:
+    tree = HTMLParser(html)
+    filings = [_parse_entry(node, kind) for node in tree.css("#listaElementosPrimernivel > li")]
+    page, total = _parse_page_info(tree)
+    return ResultsPage(filings=filings, page=page, total_pages=total)
+
+
+def normalize_nif(raw: str) -> str:
+    return re.sub(r"[\s\-.]", "", raw).upper()
+
+
+def _parse_entry(node: Node, kind: FilingKind) -> Filing:
+    date = _text(node, "li.fecha-con-hora")
+    time = _text(node, "li.time")
+    issuer_link = _required(node, "a[id$=hlTituloCabecera]")
+    doc_link = _required(node, "a[id$=subtituloRegistroEnlace]")
+
+    registry_text = next(
+        (li.text(strip=True) for li in node.css("li.resumen") if "registro" in li.text().lower()),
+        "",
+    )
+    registry = _REGISTRY.search(registry_text)
+    if registry is None:
+        raise CNMVParseError(f"no registry number in entry: {node.text(strip=True)[:120]!r}")
+
+    try:
+        registered_at = datetime.strptime(f"{date} {time}", "%d/%m/%Y %H:%M").replace(tzinfo=MADRID)
+    except ValueError as e:
+        raise CNMVParseError(f"bad date/time {date!r} {time!r}") from e
+
+    raw_nif = _nif_from_href(issuer_link.attributes.get("href") or "")
+    return Filing(
+        kind=kind,
+        registered_at=registered_at,
+        issuer=issuer_link.text(strip=True),
+        issuer_nif=normalize_nif(raw_nif) if raw_nif else None,
+        category=_text(node, "span[id$=descripcionSubtituloCabecera]"),
+        title=doc_link.text(strip=True),
+        registry_number=int(registry.group(1)),
+        document_url=(doc_link.attributes.get("href") or "").strip(),
+        issuer_nif_raw=raw_nif,
+    )
+
+
+def _parse_page_info(tree: HTMLParser) -> tuple[int, int]:
+    info = tree.css_first(".PagActivaTXT")
+    if info is None:
+        return 1, 1  # single page of results: the CNMV shows no paginator
+    match = _PAGE_INFO.search(info.text())
+    if match is None:
+        raise CNMVParseError(f"can't read pagination from {info.text()!r}")
+    return int(match.group(1)), int(match.group(2))
+
+
+def _nif_from_href(href: str) -> str | None:
+    match = re.search(r"[?&]nif=([^&]+)", href, flags=re.IGNORECASE)
+    return unquote(match.group(1)).strip() if match else None
+
+
+def _required(node: Node, selector: str) -> Node:
+    found = node.css_first(selector)
+    if found is None:
+        raise CNMVParseError(f"missing {selector!r} in entry: {node.text(strip=True)[:120]!r}")
+    return found
+
+
+def _text(node: Node, selector: str) -> str:
+    return _required(node, selector).text(strip=True)
+
+
+@dataclass(frozen=True, slots=True)
+class SecuritiesPage:
+    securities: list[Security]
+    page: int
+    total_pages: int
+
+    @property
+    def is_last(self) -> bool:
+        return self.page >= self.total_pages
+
+
+def parse_securities_page(html: str) -> SecuritiesPage:
+    tree = HTMLParser(html)
+    securities = []
+    for row in tree.css("table#ctl00_ContentPrincipal_grdDatos tbody tr"):
+        cells = {
+            (td.attributes.get("data-th") or ""): td.text().strip() or None for td in row.css("td")
+        }
+        isin = cells.get("ISIN")
+        if not isin:
+            raise CNMVParseError(f"ISIN row without ISIN: {row.text(strip=True)[:120]!r}")
+        securities.append(
+            Security(
+                isin=isin,
+                fisn=cells.get("FISN"),
+                cfi=cells.get("CFI 2015"),
+                currency=cells.get("Moneda"),
+                issue_date=_es_date(cells.get("Fecha emisión")),
+                maturity_date=_es_date(cells.get("Fecha vencimiento")),
+                outstanding=_es_number(cells.get("Nº valores / Saldo emitido")),
+                nominal=_es_number(cells.get("Nominal / VMN / Precio")),
+                interest_rate=_es_number(cells.get("Interés")),
+            )
+        )
+    page, total = _parse_page_info(tree)
+    return SecuritiesPage(securities=securities, page=page, total_pages=total)
+
+
+def _es_number(text: str | None) -> float | None:
+    """ "4.768.462.486,00" -> 4768462486.0"""
+    if not text:
+        return None
+    try:
+        return float(text.replace(".", "").replace(",", "."))
+    except ValueError as e:
+        raise CNMVParseError(f"bad number {text!r}") from e
+
+
+def _es_date(text: str | None) -> date | None:
+    if not text:
+        return None
+    try:
+        return datetime.strptime(text, "%d/%m/%Y").date()
+    except ValueError as e:
+        raise CNMVParseError(f"bad date {text!r}") from e

catalejo/documents.py

@@ -0,0 +1,31 @@
+"""Text of the documents attached to filings (PDFs)."""
+
+from __future__ import annotations
+
+import io
+import math
+
+from catalejo._http import HttpClient
+from catalejo.filings import _default_client
+from catalejo.models import Filing
+
+
+def document_text(filing: Filing | str, *, client: HttpClient | None = None) -> str:
+    """Plain text of a filing's PDF (or of a document URL).
+
+    Needs the optional dependency: ``pip install "catalejo[pdf]"``.
+    Documents never change, so they're cached forever after the first download.
+    Scanned PDFs have no text layer and return "".
+    """
+    try:
+        from pypdf import PdfReader
+    except ImportError:
+        raise ImportError('document_text() needs pypdf: pip install "catalejo[pdf]"') from None
+
+    url = filing.document_url if isinstance(filing, Filing) else filing
+    response = (client or _default_client()).get(url, ttl=math.inf)
+    if not response.content.startswith(b"%PDF"):
+        raise ValueError(f"not a PDF ({response.content_type or 'unknown type'}): {url}")
+
+    reader = PdfReader(io.BytesIO(response.content))
+    return "\n".join(page.extract_text() or "" for page in reader.pages).strip()

catalejo/filings.py

@@ -0,0 +1,138 @@
+"""Price-sensitive (IP) and other regulatory (OIR) announcements published by issuers."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+import warnings
+from datetime import date, datetime, timedelta
+from typing import Literal
+
+from catalejo._http import HttpClient
+from catalejo._parse import MADRID, normalize_nif, parse_results_page
+from catalejo.models import Filing, FilingKind
+
+BASE = "https://www.cnmv.es/portal"
+RESULT_URLS: dict[FilingKind, str] = {
+    "IP": f"{BASE}/Informacion-Privilegiada/Resultado-IP",
+    "OIR": f"{BASE}/Otra-Informacion-Relevante/Resultado-OIR",
+}
+
+# Spanish NIF/CIF shapes: B12345678, A1234567B, 12345678Z (foreign issuers: N1234567X)
+MAX_DAYS = 90  # the CNMV answers HTTP 400 above ~91; longer windows go as a date range
+
+_NIF = re.compile(r"^(?:[A-Z]\d{7}[A-Z0-9]|\d{8}[A-Z])$")
+
+_client: HttpClient | None = None
+
+
+def _default_client() -> HttpClient:
+    global _client
+    if _client is None:
+        _client = HttpClient()
+    return _client
+
+
+def filings(
+    days: int = 7,
+    kind: FilingKind | Literal["all"] = "all",
+    issuer: str | None = None,
+    *,
+    since: date | None = None,
+    until: date | None = None,
+    max_pages: int = 50,
+    client: HttpClient | None = None,
+) -> list[Filing]:
+    """Filings registered at the CNMV, newest first.
+
+    By default the last `days` days. Pass `since` (and optionally `until`) for a
+    fixed date range instead, e.g. to pull history.
+
+    >>> import catalejo
+    >>> catalejo.filings(days=3, kind="IP")  # doctest: +SKIP
+    >>> catalejo.filings(since=date(2024, 1, 1), issuer="A64907306")  # doctest: +SKIP
+    """
+    if days < 1:
+        raise ValueError("days must be >= 1")
+    window = _window(days, since, until)
+    client = client or _default_client()
+    kinds: list[FilingKind] = ["IP", "OIR"] if kind == "all" else [kind]
+
+    nif = _as_nif(issuer) if issuer is not None else None
+
+    result: list[Filing] = []
+    for k in kinds:
+        if nif:
+            # Ask the CNMV for just this issuer. It only matches the NIF in the exact
+            # form it stores it, and that can have a dash or not, so try both.
+            seen = set()
+            for variant in (nif, f"{nif[0]}-{nif[1:]}"):
+                for f in _fetch_all_pages(client, k, {**window, "nif": variant}, max_pages):
+                    if f.registry_number not in seen:
+                        seen.add(f.registry_number)
+                        result.append(f)
+        else:
+            result.extend(_fetch_all_pages(client, k, window, max_pages))
+
+    if issuer is not None:
+        result = [f for f in result if matches_issuer(f, issuer)]
+
+    result.sort(key=lambda f: f.registered_at, reverse=True)
+    return result
+
+
+def _fetch_all_pages(
+    client: HttpClient, kind: FilingKind, params: dict[str, str | int], max_pages: int
+) -> list[Filing]:
+    out: list[Filing] = []
+    for page_index in range(max_pages):  # the CNMV's `page` param is zero-based
+        response = client.get(RESULT_URLS[kind], {**params, "page": page_index})
+        page = parse_results_page(response.text, kind)
+        out.extend(page.filings)
+        if page.is_last or not page.filings:
+            break
+    else:
+        warnings.warn(
+            f"stopped after max_pages={max_pages}; results are incomplete. "
+            "Narrow the date range or raise max_pages.",
+            stacklevel=3,
+        )
+    return out
+
+
+def _window(days: int, since: date | None, until: date | None) -> dict[str, str | int]:
+    """Query params for the time window: `dias=N` when possible, a date range otherwise."""
+    if since is None and until is None and days <= MAX_DAYS:
+        return {"dias": days}
+    today = datetime.now(MADRID).date()
+    until = until or today
+    since = since or until - timedelta(days=days)
+    if since > until:
+        raise ValueError(f"since ({since}) is after until ({until})")
+    return {"fechaDesde": f"{since:%d/%m/%Y}", "fechaHasta": f"{until:%d/%m/%Y}"}
+
+
+def _as_nif(query: str) -> str | None:
+    """The query normalized as a NIF, or None if it doesn't look like one."""
+    candidate = normalize_nif(query)
+    return candidate if _NIF.match(candidate) else None
+
+
+def matches_issuer(filing: Filing, query: str) -> bool:
+    """True if `query` identifies the filing's issuer.
+
+    `query` can be a NIF ("A28004885", "A-28004885") or part of the name
+    ("cellnex", "Telefónica" == "telefonica").
+    """
+    q = query.strip()
+    if not q:
+        raise ValueError("issuer can't be empty")
+    if filing.issuer_nif and normalize_nif(q) == filing.issuer_nif:
+        return True
+    return _fold(q) in _fold(filing.issuer)
+
+
+def _fold(text: str) -> str:
+    """Lowercase and strip accents, so "Telefónica" == "telefonica"."""
+    decomposed = unicodedata.normalize("NFKD", text)
+    return "".join(c for c in decomposed if not unicodedata.combining(c)).casefold()

catalejo/mcp_server.py

@@ -0,0 +1,63 @@
+"""MCP server exposing CNMV filings to AI agents."""
+
+from __future__ import annotations
+
+import dataclasses
+import logging
+from datetime import date
+from typing import Any, Literal
+
+from mcp.server.fastmcp import FastMCP
+
+import catalejo
+
+mcp = FastMCP("catalejo")
+
+
+def _as_dict(f: catalejo.Filing) -> dict[str, Any]:
+    d = dataclasses.asdict(f)
+    d["registered_at"] = f.registered_at.isoformat()  # datetime isn't JSON
+    return d
+
+
+@mcp.tool()
+def latest_filings(
+    days: int = 3, kind: Literal["IP", "OIR", "all"] = "all"
+) -> list[dict[str, Any]]:
+    """Latest filings published at the Spanish CNMV, newest first.
+
+    kind: "IP" = price-sensitive announcements, "OIR" = other regulatory announcements.
+    """
+    return [_as_dict(f) for f in catalejo.filings(days=days, kind=kind)]
+
+
+@mcp.tool()
+def issuer_filings(
+    issuer: str,
+    days: int = 7,
+    kind: Literal["IP", "OIR", "all"] = "all",
+    since: date | None = None,
+    until: date | None = None,
+    limit: int = 50,
+) -> list[dict[str, Any]]:
+    """Filings from one specific company at the Spanish CNMV, newest first.
+
+    issuer: its Spanish tax id / NIF ("A64907306") is best: the CNMV filters by it
+    directly, so even years of history come back in seconds. A company name or part
+    of it ("Cellnex", "telefonica") also works but scans every filing, so keep
+    `days` small (7-14) when searching by name.
+    since / until: optional date range (YYYY-MM-DD) for history; overrides `days`.
+    Price-sensitive announcements (IP) exist from Feb 2020 onwards.
+    limit: max filings returned (the newest ones).
+    """
+    found = catalejo.filings(days=days, kind=kind, issuer=issuer, since=since, until=until)
+    return [_as_dict(f) for f in found[:limit]]
+
+
+def main() -> None:
+    logging.getLogger("httpx").setLevel(logging.WARNING)  # one INFO line per request is noise
+    mcp.run()  # stdio by default
+
+
+if __name__ == "__main__":
+    main()

catalejo/models.py

@@ -0,0 +1,61 @@
+"""Data models returned by catalejo."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime
+from typing import Literal
+from urllib.parse import parse_qs, urlsplit
+
+FilingKind = Literal["IP", "OIR"]
+"""``IP`` = información privilegiada (inside information, art. 17 MAR).
+``OIR`` = otra información relevante (other relevant information)."""
+
+
+@dataclass(frozen=True, slots=True)
+class Filing:
+    """One disclosure published by an issuer through the CNMV."""
+
+    kind: FilingKind
+    registered_at: datetime
+    """When the CNMV registered it (timezone-aware, Europe/Madrid)."""
+    issuer: str
+    issuer_nif: str | None
+    """Spanish tax id of the issuer, without dashes. Foreign issuers get an N-prefixed NIF."""
+    category: str
+    """Category as shown by the CNMV, in Spanish (e.g. "Sobre gobierno corporativo")."""
+    title: str
+    registry_number: int
+    """Official registry number. IP and OIR are numbered separately."""
+    document_url: str
+    """Link to the filed document (usually a PDF)."""
+    issuer_nif_raw: str | None = None
+    """NIF exactly as the CNMV writes it (sometimes "A-28004885"). Needed to query by issuer."""
+
+    @property
+    def document_id(self) -> str | None:
+        """The GUID the CNMV uses to identify the document, if present in the URL."""
+        values = parse_qs(urlsplit(self.document_url).query).get("t")
+        return values[0].strip("{}") if values else None
+
+
+@dataclass(frozen=True, slots=True)
+class Security:
+    """A security registered under an issuer at the CNMV's ISIN agency (ANCV)."""
+
+    isin: str
+    fisn: str | None
+    """Short name, e.g. "CLNX/AC 0.25" (AC = acciones / shares, OB = bonds)."""
+    cfi: str | None
+    """ISO 10962 classification. Shares start with "ES". Empty for most foreign issuers."""
+    currency: str | None = None
+    issue_date: date | None = None
+    maturity_date: date | None = None
+    outstanding: float | None = None
+    """Number of securities (shares) or amount issued (debt)."""
+    nominal: float | None = None
+    interest_rate: float | None = None
+
+    @property
+    def is_share(self) -> bool:
+        return (self.cfi or "").startswith("ES")

catalejo/securities.py

@@ -0,0 +1,43 @@
+"""Securities (ISINs) registered under an issuer, from the CNMV's ISIN agency."""
+
+from __future__ import annotations
+
+from catalejo._http import HttpClient
+from catalejo._parse import normalize_nif, parse_securities_page
+from catalejo.filings import _default_client
+from catalejo.models import Security
+
+ISIN_URL = "https://www.cnmv.es/portal/ancv/isin.aspx"
+
+
+def securities(
+    nif: str, *, client: HttpClient | None = None, max_pages: int = 50
+) -> list[Security]:
+    """All ISINs the CNMV lists for an issuer: shares, bonds, notes...
+
+    `nif` can be written with or without dash. Use `[s for s in ... if s.is_share]`
+    to keep only shares.
+
+    >>> catalejo.securities("A64907306")  # doctest: +SKIP
+    [Security(isin='ES0105066007', fisn='CLNX/AC 0.25', cfi='ESVUFB', ...)]
+    """
+    client = client or _default_client()
+    base = normalize_nif(nif)
+    if not base:
+        raise ValueError("nif can't be empty")
+    # Like the filings search, the CNMV only matches the NIF in the form it stores it.
+    for variant in (base, f"{base[0]}-{base[1:]}"):
+        found = _fetch(client, variant, max_pages)
+        if found:
+            return found
+    return []
+
+
+def _fetch(client: HttpClient, nif: str, max_pages: int) -> list[Security]:
+    out: list[Security] = []
+    for page_index in range(max_pages):
+        page = parse_securities_page(client.get(ISIN_URL, {"nif": nif, "page": page_index}).text)
+        out.extend(page.securities)
+        if page.is_last or not page.securities:
+            break
+    return out

catalejo-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: catalejo
+Version: 0.1.0
+Summary: Clean, structured access to Spanish securities regulator (CNMV) public data, as a Python library and MCP server.
+Project-URL: Homepage, https://github.com/polfananas/catalejo
+Project-URL: Issues, https://github.com/polfananas/catalejo/issues
+Project-URL: Changelog, https://github.com/polfananas/catalejo/blob/main/CHANGELOG.md
+Author: Pol Fañanás
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cnmv,corporate-disclosures,edgar,finance,financial-data,mcp,securities,spain
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: selectolax>=1.0
+Requires-Dist: tzdata; sys_platform == 'win32'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pypdf>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.20; extra == 'mcp'
+Provides-Extra: pdf
+Requires-Dist: pypdf>=5; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# catalejo
+
+[![tests](https://github.com/polfananas/catalejo/actions/workflows/tests.yml/badge.svg)](https://github.com/polfananas/catalejo/actions/workflows/tests.yml)
+
+> *catalejo* (Spanish): spyglass.
+
+**Spain's securities regulator (CNMV) publishes everything listed companies have to disclose, but only through web forms and PDFs.** catalejo turns that into clean Python objects, and plugs it into AI agents through an MCP server.
+
+Think of it as a small **SEC EDGAR for Spain**.
+
+> *Having had perfect understanding of all things from the very first, to write unto thee in order, that thou mightest know the certainty of those things.* (Luke 1:3-4)
+
+![catalejo in a terminal: the latest price-sensitive announcements, 176 BBVA filings since 2020, the whole BBVA–Sabadell takeover bid in order, and its outcome read from the CNMV's own PDF. All live data.](https://raw.githubusercontent.com/polfananas/catalejo/main/docs/demo.gif)
+
+<!-- TODO: second GIF, Claude Desktop using the MCP server -->
+
+```python
+>>> import catalejo
+>>> for f in catalejo.filings(days=7, kind="IP"):
+...     print(f.registered_at, f.issuer, "|", f.title)
+2026-11-10 16:20:00+01:00 CONSTRUCCIONES Y AUXILIAR DE FERROCARRILES, S.A | El Consejo de Administración de la Sociedad ha aprobado el Plan Estratégico 2027-2030.
+2026-11-09 12:14:00+01:00 ELECNOR, S.A. | Elecnor comunica la propuesta del Consejo de Administración de distribución de un dividendo ...
+```
+
+## Install
+
+```bash
+pip install catalejo            # library
+pip install "catalejo[mcp]"     # + MCP server for Claude and other agents
+pip install "catalejo[pdf]"     # + text extraction from filed PDFs
+```
+
+Python 3.10+.
+
+## What you can get
+
+**Price-sensitive announcements (`IP`) and other regulatory announcements (`OIR`)**, the two channels issuers use to disclose anything that can move the price: results, M&A, takeover bids, guidance, board changes, buybacks...
+
+```python
+from datetime import date
+import catalejo
+
+catalejo.filings(days=3)                          # everything from the last 3 days, IP + OIR
+catalejo.filings(days=30, kind="IP", issuer="cellnex")
+
+# Full history for one company. Filtering by NIF (Spanish tax id) is done
+# by the CNMV itself, so years of data come back in a few seconds.
+catalejo.filings(since=date(2020, 1, 1), kind="IP", issuer="A64907306")
+```
+
+Each `Filing` has `kind`, `registered_at` (timezone-aware, Madrid), `issuer`, `issuer_nif`, `category`, `title`, `registry_number` and `document_url`.
+
+**The text of the filed document:**
+
+```python
+f = catalejo.filings(days=10, kind="IP", issuer="A64907306")[0]
+print(catalejo.document_text(f))     # needs catalejo[pdf]
+```
+
+**The securities (ISINs) of an issuer**, shares and bonds:
+
+```python
+>>> [s for s in catalejo.securities("A64907306") if s.is_share]
+[Security(isin='ES0105066007', fisn='CLNX/AC 0.25', cfi='ESVUFB', ...)]
+```
+
+## Use it from Claude (MCP)
+
+catalejo ships an MCP server with two tools, `latest_filings` and `issuer_filings`, so you can ask things like *"What price-sensitive news has Cellnex published since 2023? Group it by topic."*
+
+**Claude Desktop:** add this to `claude_desktop_config.json` (Settings → Developer → Edit Config) and restart the app:
+
+```json
+{
+  "mcpServers": {
+    "catalejo": { "command": "catalejo-mcp" }
+  }
+}
+```
+
+If Claude can't find the command, use the full path from `which catalejo-mcp`.
+
+**Claude Code:** `claude mcp add catalejo -- catalejo-mcp`
+
+## Why not just ask an AI with web search?
+
+Because the CNMV's search pages are forms that search engines barely index. An agent with web search ends up reading press articles: incomplete, late, and you can't tell what's missing. With catalejo it reads the official register directly: every filing, with its exact time, registry number and a link to the original document. And it can do what web search can't, like going through years of history or across every issuer.
+
+## Being a good citizen
+
+catalejo talks only to `cnmv.es`, sends an identifiable User-Agent, makes **at most one request per second** and caches responses on disk (`~/.cache/catalejo`, or set `CATALEJO_CACHE_DIR`). Filed documents never change, so they are downloaded once. Please keep it that way if you fork it.
+
+## Good to know
+
+- **Price-sensitive announcements (`IP`) have their own channel since 8 February 2020.** Before that, everything was published as *hechos relevantes*, which catalejo doesn't cover yet.
+- Searching by **NIF** is fast (the CNMV filters). Searching by **name** works, but scans every filing in the window, so keep the window short.
+- Times are the CNMV's registration time, to the minute.
+- Filings come in the language the issuer used, which is almost always Spanish.
+- Early days: the API may still change before 1.0.
+
+## Roadmap
+
+- [x] Price-sensitive and other regulatory announcements, with full history
+- [x] ISINs per issuer, text of filed PDFs
+- [x] MCP server
+- [ ] Directors' and managers' share dealings (art. 19 MAR)
+- [ ] Net short positions
+- [ ] Takeover bids (OPAs): status, price, spread
+- [ ] Fund portfolios
+- [ ] CLI
+
+## Data and license
+
+The data comes from the [CNMV](https://www.cnmv.es) public registers and remains subject to the CNMV's [legal notice](https://www.cnmv.es/Portal/utilidades/NotaLegal): reproduce it faithfully, and if you ever sell it, tell your buyers it's free at cnmv.es. catalejo is not affiliated with or endorsed by the CNMV.
+
+Code: MIT. See [LICENSE](https://github.com/polfananas/catalejo/blob/main/LICENSE).

catalejo-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+catalejo/__init__.py,sha256=qsAtDLoXw2Dd7qcbUriAVETKXaZoc1dZ3pr9n-ssZ28,325
+catalejo/_http.py,sha256=fP9bLKfR4SJSv_PEED6c53wQLXJgV_0vBKs_UThzZtg,6692
+catalejo/_parse.py,sha256=pZqOnamHZxGyaefXc6cWlIWAv5qlBcZwWrBpst76mcs,5462
+catalejo/documents.py,sha256=JWP-5GKSi_eh1RZmSG3Eqy5DyawAuTf2kWXVDz7z6sM,1169
+catalejo/filings.py,sha256=jJghACO3bgSLZWM8PPbfIBBph6PCOMZsSELbgW9fD_8,4896
+catalejo/mcp_server.py,sha256=kgBFtL70ZBVI2YjRvQU5COfaNqD2Y0oMhmJYWIvSv7U,1937
+catalejo/models.py,sha256=vGI0nHL-Z7CrXfEObPF3xUH-VnvP39zPRqa78tLgWM4,2212
+catalejo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+catalejo/securities.py,sha256=FuQbs0AvmWlTMYDimxdm5JRg4u5MbdY7M9IqOyueUEw,1539
+catalejo-0.1.0.dist-info/METADATA,sha256=5fC6LjI8JCjdTvODK19g71NdzVJlCoIwEYTSIJvA478,6831
+catalejo-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+catalejo-0.1.0.dist-info/entry_points.txt,sha256=rHRSXqxtYzYpLmRGqyGH_Ac859PpXzgAm5G1a432VbE,58
+catalejo-0.1.0.dist-info/licenses/LICENSE,sha256=3Yga6SazeCMa1lYyNhcvRtg7-q3Nw2AFh-4Xk8RGfy8,1070
+catalejo-0.1.0.dist-info/RECORD,,

catalejo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

catalejo-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+catalejo-mcp = catalejo.mcp_server:main

catalejo-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pol Fañanás
+
+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.