csf-scraper-python 0.1.1__py3-none-any.whl

csf_scraper/persona_fisica.py

@@ -0,0 +1,25 @@
+"""Modelo de persona física."""
+
+from typing import ClassVar
+
+from csf_scraper.date_parser import DateField
+from csf_scraper.persona import Persona
+
+
+class PersonaFisica(Persona):
+    """Datos fiscales de una persona física."""
+
+    curp: str = ""
+    nombre: str = ""
+    apellido_paterno: str = ""
+    apellido_materno: str = ""
+    fecha_nacimiento: DateField = None
+
+    field_titles: ClassVar[dict[str, str]] = {
+        "curp": "CURP:",
+        "nombre": "Nombre:",
+        "apellido_paterno": "Apellido Paterno:",
+        "apellido_materno": "Apellido Materno:",
+        "fecha_nacimiento": "Fecha Nacimiento:",
+        **Persona.field_titles,
+    }

csf_scraper/persona_moral.py

@@ -0,0 +1,21 @@
+"""Modelo de persona moral."""
+
+from typing import ClassVar
+
+from csf_scraper.date_parser import DateField
+from csf_scraper.persona import Persona
+
+
+class PersonaMoral(Persona):
+    """Datos fiscales de una persona moral."""
+
+    razon_social: str = ""
+    regimen_de_capital: str = ""
+    fecha_constitucion: DateField = None
+
+    field_titles: ClassVar[dict[str, str]] = {
+        "razon_social": "Denominación o Razón Social:",
+        "regimen_de_capital": "Régimen de capital:",
+        "fecha_constitucion": "Fecha de constitución:",
+        **Persona.field_titles,
+    }

csf_scraper/ports/__init__.py

@@ -0,0 +1,5 @@
+"""Puertos (interfaces) de la librería."""
+
+from csf_scraper.ports.rfc_cif_extractor_port import RfcCifExtractorPort
+
+__all__ = ["RfcCifExtractorPort"]

csf_scraper/ports/rfc_cif_extractor_port.py

@@ -0,0 +1,40 @@
+"""Puerto que unifica la extracción de RFC e idCIF de una CSF desde una ruta."""
+
+from abc import ABC, abstractmethod
+
+from csf_scraper.rfc_cif_data import RfcCifData
+
+
+class RfcCifExtractorPort(ABC):
+    """Extrae el :class:`RfcCifData` de una Constancia de Situación Fiscal.
+
+    Contrato público de los adaptadores que leen una CSF *desde una ruta*
+    (PDF, imagen o cualquier formato futuro). ``Scraper`` solo depende de este
+    puerto, así que todos los adaptadores son intercambiables entre sí.
+
+    Reglas del contrato:
+
+    - La ruta se recibe en :meth:`extract`, **no** en el constructor: los
+      adaptadores son sin estado y reutilizables entre archivos.
+    - El constructor se reserva a la configuración del motor (credenciales,
+      modelo, binarios o dependencias inyectadas).
+    - El adaptador valida y devuelve :class:`RfcCifData` con los value objects
+      ya construidos (``rfc: Rfc``, ``id_cif: IdCif``); nunca cadenas crudas.
+    - Los adaptadores de la librería reportan sus fallos con subclases de
+      :class:`~csf_scraper.exceptions.CsfScraperException`. Las dependencias
+      inyectadas (por ejemplo, un ``ImageReaderPort`` externo) pueden propagar
+      sus propias excepciones.
+
+    Implementaciones: :class:`~csf_scraper.pdf_reader.CsfPdfExtractor` (texto
+    del PDF) y :class:`~csf_scraper.image_readers.CsfImageExtractor` (cualquier
+    :class:`~csf_scraper.image_readers.ports.ImageReaderPort`).
+
+    El contrato es **asíncrono**: ``extract`` es una corrutina para que las
+    implementaciones puedan delegar E/S (procesos, disco, red) sin bloquear el
+    bucle de eventos. ``Scraper`` la consume con ``await``.
+    """
+
+    @abstractmethod
+    async def extract(self, path: str) -> RfcCifData:
+        """Devuelve el RFC y el idCIF leídos del archivo en ``path``."""
+        ...

csf_scraper/regimen.py

@@ -0,0 +1,62 @@
+"""Modelo de un régimen fiscal."""
+
+import re
+
+from pydantic import BaseModel, ConfigDict, computed_field
+
+from csf_scraper.date_parser import DateField
+
+_REGIMEN_CATALOG: dict[str, str] = {
+    "601": "General de Ley Personas Morales",
+    "603": "Personas Morales con Fines no Lucrativos",
+    "605": "Sueldos y Salarios e Ingresos Asimilados a Salarios",
+    "606": "Arrendamiento",
+    "607": "Enajenación o Adquisición de Bienes",
+    "608": "Demás ingresos",
+    "610": "Residentes en el Extranjero sin Establecimiento Permanente en México",
+    "611": "Ingresos por Dividendos (socios y accionistas)",
+    "612": "Personas Físicas con Actividades Empresariales y Profesionales",
+    "614": "Ingresos por intereses",
+    "615": "ingresos por obtención de premios",
+    "616": "Sin obligaciones fiscales",
+    "620": "Sociedades Cooperativas de Producción que optan por diferir sus ingresos",
+    "621": "Incorporación Fiscal",
+    "622": "Actividades Agrícolas, Ganaderas, Silvícolas y Pesqueras",
+    "623": "Opcional para Grupos de Sociedades",
+    "624": "Coordinados",
+    "625": "Actividades Empresariales con ingresos a través de Plataformas Tecnológicas",
+    "626": "Simplificado de Confianza",
+}
+
+_REGIMEN_BY_TEXT: dict[str, str] = {
+    text.upper(): regimen_id for regimen_id, text in _REGIMEN_CATALOG.items()
+}
+
+_PREFIX = re.compile(r"^Régimen (?:de (?:las |los )?)?")
+_SUFFIX_PM = re.compile(r" PM$")
+_SUFFIX_DOT = re.compile(r"\.$")
+
+
+def _normalize_text(regimen: str) -> str:
+    text = _PREFIX.sub("", regimen)
+    text = _SUFFIX_PM.sub("", text)
+    return _SUFFIX_DOT.sub("", text)
+
+
+def _search_regimen_id(regimen: str) -> str:
+    return _REGIMEN_BY_TEXT.get(_normalize_text(regimen).upper(), "")
+
+
+class Regimen(BaseModel):
+    """Un régimen fiscal con su id derivado del texto y su fecha de alta."""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    regimen: str = ""
+    fecha_alta: DateField = None
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def regimen_id(self) -> str:
+        """Id del catálogo que corresponde al texto de :attr:`regimen`."""
+        return _search_regimen_id(self.regimen)

csf_scraper/rfc_cif_data.py

@@ -0,0 +1,15 @@
+"""DTO con el RFC y el idCIF extraídos de una CSF (PDF o imagen)."""
+
+from pydantic import BaseModel, ConfigDict
+
+from csf_scraper.value_objects.id_cif import IdCif
+from csf_scraper.value_objects.rfc import Rfc
+
+
+class RfcCifData(BaseModel):
+    """Par validado de RFC e idCIF obtenido por cualquier extractor."""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    rfc: Rfc
+    id_cif: IdCif

csf_scraper/scraper.py

@@ -0,0 +1,117 @@
+"""Cliente para consultar los datos fiscales en el validador del SAT."""
+
+import ssl
+from types import TracebackType
+from typing import ClassVar, Self
+
+import httpx
+
+from csf_scraper.data_extractor import DataExtractor
+from csf_scraper.exceptions import CifDownloadException
+from csf_scraper.exceptions.image_reader import ImageExtractorNotConfiguredException
+from csf_scraper.pdf_reader import CsfPdfExtractor
+from csf_scraper.persona_fisica import PersonaFisica
+from csf_scraper.persona_moral import PersonaMoral
+from csf_scraper.ports import RfcCifExtractorPort
+from csf_scraper.value_objects.id_cif import IdCif
+from csf_scraper.value_objects.rfc import Rfc
+
+
+def _create_ssl_context() -> ssl.SSLContext:
+    context = ssl.create_default_context()
+    context.set_ciphers("DEFAULT@SECLEVEL=1")
+    return context
+
+
+class Scraper:
+    """Obtiene una :class:`PersonaMoral` o :class:`PersonaFisica` desde el sitio del SAT.
+
+    Todo el flujo es asíncrono: la descarga usa un
+    :class:`httpx.AsyncClient` y la extracción de datos se espera con
+    ``await``. El cliente se puede cerrar con :meth:`aclose` o usando el
+    scraper como *async context manager*::
+
+        async with Scraper.create() as scraper:
+            person = await scraper.obtain_from_rfc_and_cif(rfc, id_cif)
+    """
+
+    url: ClassVar[str] = (
+        "https://siat.sat.gob.mx/app/qr/faces/pages/mobile/validadorqr.jsf?D1=10&D2=1&D3=%s_%s"
+    )
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient,
+        *,
+        pdf_extractor: RfcCifExtractorPort | None = None,
+        image_extractor: RfcCifExtractorPort | None = None,
+    ) -> None:
+        self.client = client
+        #: Extractor de CSF en PDF; por omisión usa ``pdftotext``.
+        self.pdf_extractor: RfcCifExtractorPort = pdf_extractor or CsfPdfExtractor()
+        #: Extractor de CSF escaneada (LLM/OCR); opcional.
+        self.image_extractor = image_extractor
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        pdf_extractor: RfcCifExtractorPort | None = None,
+        image_extractor: RfcCifExtractorPort | None = None,
+    ) -> Self:
+        """Crea un cliente HTTP asíncrono listo para usar contra el SAT."""
+        return cls(
+            httpx.AsyncClient(follow_redirects=True, timeout=None, verify=_create_ssl_context()),
+            pdf_extractor=pdf_extractor,
+            image_extractor=image_extractor,
+        )
+
+    async def __aenter__(self) -> Self:
+        """Permite usar el scraper en un bloque ``async with``."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Cierra el cliente HTTP al salir del bloque ``async with``."""
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Cierra el cliente HTTP subyacente."""
+        await self.client.aclose()
+
+    async def obtain_from_rfc_and_cif(self, rfc: str, id_cif: str) -> PersonaMoral | PersonaFisica:
+        """Obtiene la persona a partir de su RFC y su idCIF."""
+        parsed_rfc = Rfc(rfc)
+        parsed_cif = IdCif(id_cif)
+
+        uri = type(self).url % (parsed_cif, parsed_rfc)
+        html = await self._obtain_html(uri)
+        person = DataExtractor(html).extract(is_fisica=parsed_rfc.is_fisica())
+
+        person.rfc = parsed_rfc
+        person.id_cif = parsed_cif
+        return person
+
+    async def obtain_from_pdf_path(self, path: str) -> PersonaMoral | PersonaFisica:
+        """Obtiene la persona leyendo su RFC e idCIF de una CSF en PDF."""
+        data = await self.pdf_extractor.extract(path)
+        return await self.obtain_from_rfc_and_cif(data.rfc, data.id_cif)
+
+    async def obtain_from_image_path(self, path: str) -> PersonaMoral | PersonaFisica:
+        """Obtiene la persona leyendo su RFC e idCIF de una CSF escaneada (JPEG/PNG)."""
+        if self.image_extractor is None:
+            raise ImageExtractorNotConfiguredException()
+        data = await self.image_extractor.extract(path)
+        return await self.obtain_from_rfc_and_cif(data.rfc, data.id_cif)
+
+    async def _obtain_html(self, uri: str) -> str:
+        try:
+            response = await self.client.get(uri)
+            response.raise_for_status()
+        except httpx.HTTPError as exception:
+            raise CifDownloadException(uri) from exception
+        return response.text

csf_scraper/value_objects/__init__.py

@@ -0,0 +1,7 @@
+"""Value objects del dominio de la CSF."""
+
+from csf_scraper.value_objects.csf_image import CsfImage
+from csf_scraper.value_objects.id_cif import IdCif
+from csf_scraper.value_objects.rfc import Rfc
+
+__all__ = ["CsfImage", "IdCif", "Rfc"]

csf_scraper/value_objects/csf_image.py

@@ -0,0 +1,68 @@
+"""Value object de una CSF escaneada como imagen (JPEG o PNG)."""
+
+import base64
+from pathlib import Path
+from typing import Self
+
+from csf_scraper.exceptions.image_reader import (
+    InvalidImageException,
+    InvalidImageFormatException,
+)
+
+#: Firmas (magic bytes) de los formatos de imagen soportados.
+_MIME_TYPES: dict[bytes, str] = {
+    b"\xff\xd8\xff": "image/jpeg",
+    b"\x89PNG\r\n\x1a\n": "image/png",
+}
+
+
+class CsfImage:
+    """Imagen de una Constancia de Situación Fiscal en formato JPEG o PNG.
+
+    Se construye desde una ruta (:meth:`new_from_path`) o desde bytes
+    (:meth:`new_from_contents`); en ambos casos se valida el formato por sus
+    *magic bytes* y se determina su tipo MIME.
+    """
+
+    __slots__ = ("_contents", "_mime_type")
+
+    def __init__(self, contents: bytes, mime_type: str) -> None:
+        self._contents = contents
+        self._mime_type = mime_type
+
+    @classmethod
+    def new_from_path(cls, path: str) -> Self:
+        """Lee y valida la imagen en ``path``; lanza :class:`InvalidImageException`."""
+        try:
+            contents = Path(path).read_bytes()
+        except OSError as exception:
+            raise InvalidImageException(f"Cannot read image from path: {path}") from exception
+        return cls.new_from_contents(contents)
+
+    @classmethod
+    def new_from_contents(cls, contents: bytes) -> Self:
+        """Valida ``contents`` como imagen soportada y detecta su tipo MIME."""
+        if not contents:
+            raise InvalidImageException("The image is empty.")
+        return cls(contents, cls._detect_mime_type(contents))
+
+    @staticmethod
+    def _detect_mime_type(contents: bytes) -> str:
+        for signature, mime_type in _MIME_TYPES.items():
+            if contents.startswith(signature):
+                return mime_type
+        raise InvalidImageFormatException(
+            "The given file is not a supported image (expected JPEG or PNG).",
+        )
+
+    def as_bytes(self) -> bytes:
+        """Contenido binario de la imagen."""
+        return self._contents
+
+    def as_base64(self) -> str:
+        """Contenido de la imagen codificado en base64."""
+        return base64.b64encode(self._contents).decode("ascii")
+
+    def get_mime_type(self) -> str:
+        """Tipo MIME detectado (``image/jpeg`` o ``image/png``)."""
+        return self._mime_type

csf_scraper/value_objects/id_cif.py

@@ -0,0 +1,48 @@
+"""Value object del idCIF (identificador del CIF del SAT)."""
+
+import re
+from typing import Any, Self
+
+from pydantic_core import CoreSchema, core_schema
+
+from csf_scraper.exceptions.value_objects import InvalidIdCifFormatException
+
+#: Entre 8 y 13 dígitos (los idCIF observados van de 8 a 13 posiciones).
+_PATTERN = re.compile(r"\d{8,13}\Z")
+
+
+class IdCif(str):
+    """idCIF validado (de 8 a 13 dígitos).
+
+    Se construye con ``IdCif("1904014102123")``; lanza
+    :class:`~csf_scraper.exceptions.value_objects.InvalidIdCifFormatException` si el
+    valor no cumple el formato.
+    """
+
+    __slots__ = ()
+
+    def __new__(cls, value: Any) -> Self:
+        if isinstance(value, cls):
+            return value
+        text = value.strip() if isinstance(value, str) else value
+        if not isinstance(text, str) or _PATTERN.fullmatch(text) is None:
+            raise InvalidIdCifFormatException(f"Invalid idCIF format: {value!r}")
+        return super().__new__(cls, text)
+
+    @classmethod
+    def ensure(cls, value: Any) -> Self:
+        """Convierte ``value`` a :class:`IdCif` validando su formato."""
+        return cls(value)
+
+    @property
+    def value(self) -> str:
+        """idCIF como ``str`` plano (sin la subclase :class:`IdCif`)."""
+        return str(self)
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source: Any, handler: Any) -> CoreSchema:
+        return core_schema.no_info_after_validator_function(
+            cls,
+            core_schema.str_schema(),
+            serialization=core_schema.to_string_ser_schema(),
+        )

csf_scraper/value_objects/rfc.py

@@ -0,0 +1,56 @@
+"""Value object del RFC (Registro Federal de Contribuyentes)."""
+
+import re
+from typing import Any, Self
+
+from pydantic_core import CoreSchema, core_schema
+
+from csf_scraper.exceptions.value_objects import InvalidRfcFormatException
+
+#: Alfanumérico: de 3 a 4 letras (incluye ``Ñ`` y ``&``), 6 dígitos de fecha y 3 de homoclave.
+_PATTERN = re.compile(r"[A-ZÑ&]{3,4}\d{6}[A-Z\d]{3}\Z")
+
+
+class Rfc(str):
+    """RFC validado de una persona física (13 caracteres) o moral (12 caracteres).
+
+    Se construye con ``Rfc("DIM8701081LA")``; lanza
+    :class:`~csf_scraper.exceptions.value_objects.InvalidRfcFormatException` si el
+    valor no cumple el formato. Normaliza espacios y mayúsculas.
+    """
+
+    __slots__ = ()
+
+    def __new__(cls, value: Any) -> Self:
+        if isinstance(value, cls):
+            return value
+        text = value.strip().upper() if isinstance(value, str) else value
+        if not isinstance(text, str) or _PATTERN.fullmatch(text) is None:
+            raise InvalidRfcFormatException(f"Invalid RFC format: {value!r}")
+        return super().__new__(cls, text)
+
+    @classmethod
+    def ensure(cls, value: Any) -> Self:
+        """Convierte ``value`` a :class:`Rfc` validando (y normalizando) su formato."""
+        return cls(value)
+
+    @property
+    def value(self) -> str:
+        """RFC como ``str`` plano (sin la subclase :class:`Rfc`)."""
+        return str(self)
+
+    def is_fisica(self) -> bool:
+        """Indica si el RFC corresponde a una persona física (13 caracteres)."""
+        return len(self) == 13
+
+    def is_moral(self) -> bool:
+        """Indica si el RFC corresponde a una persona moral (12 caracteres)."""
+        return not self.is_fisica()
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source: Any, handler: Any) -> CoreSchema:
+        return core_schema.no_info_after_validator_function(
+            cls,
+            core_schema.str_schema(),
+            serialization=core_schema.to_string_ser_schema(),
+        )