csf-scraper-python 0.1.1__tar.gz → 0.2.0__tar.gz

csf_scraper_python-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,103 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14.8"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install poppler-utils
+        run: sudo apt-get update && sudo apt-get install -y poppler-utils
+      - name: Install development dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev,opencv,llm-gemini]"
+      - name: Ruff
+        run: ruff check src tests
+      - name: Mypy
+        run: mypy
+      - name: Pytest
+        run: pytest
+      - name: Verify OpenCV extra
+        run: |
+          python -c "import cv2, numpy; print('OpenCV', cv2.__version__, 'NumPy', numpy.__version__)"
+          python -c "from csf_scraper import OpenCvImageReader; print(OpenCvImageReader.__name__)"
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14.8"
+      - name: Install build tools
+        run: python -m pip install --upgrade build twine
+      - name: Verify version matches tag
+        run: |
+          set -euo pipefail
+          VERSION=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          echo "pyproject.toml version: v${VERSION}"
+          echo "Received tag: ${GITHUB_REF_NAME}"
+          test "v${VERSION}" = "${GITHUB_REF_NAME}"
+      - name: Build distributions
+        run: python -m build
+      - name: Check distributions
+        run: python -m twine check dist/*
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1 || \
+            gh release create "$GITHUB_REF_NAME" dist/* \
+              --title "$GITHUB_REF_NAME" \
+              --generate-notes

{csf_scraper_python-0.1.1 → csf_scraper_python-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: csf-scraper-python
-Version: 0.1.1
+Version: 0.2.0
 Summary: Obtiene los datos fiscales actuales de una persona moral o física dado su RFC y su idCIF (port de phpcfdi/csf-scraper)
 Project-URL: Homepage, https://github.com/PJMP4826/csf-scraper-python
 Project-URL: Issues, https://github.com/PJMP4826/csf-scraper-python/issues
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: beautifulsoup4>=4.12
@@ -35,9 +36,12 @@ Requires-Dist: ruff>=0.6; extra == 'dev'
 Provides-Extra: llm-gemini
 Requires-Dist: google-genai>=1.0; extra == 'llm-gemini'
 Requires-Dist: llama-index-llms-google-genai<0.12,>=0.11; extra == 'llm-gemini'
+Provides-Extra: opencv
+Requires-Dist: numpy>=2; extra == 'opencv'
+Requires-Dist: opencv-python-headless>=5.0; extra == 'opencv'
 Description-Content-Type: text/markdown
 
-# csf-scraper
+# csf-scraper-python
 
 Port a Python de [phpcfdi/csf-scraper](https://github.com/phpcfdi/csf-scraper):
 obtiene los datos fiscales actuales de una persona moral o física dado su RFC y
@@ -50,7 +54,8 @@ su idCIF (SAT, Constancia de Situación Fiscal).
   `poppler-utils`), necesario **solo** para leer la CSF desde un archivo PDF
   (`obtain_from_pdf_path`).
 - Dependencias: `httpx`, `beautifulsoup4`, `lxml`, `pydantic`, `llama-index-core`.
-  Los clientes de cada proveedor LLM son extras opcionales (`llm-gemini`).
+  Los clientes de cada proveedor LLM son extras opcionales (`llm-gemini`). El
+  lector de imágenes basado en OpenCV requiere el extra `opencv`.
 
 ## Instalación
 
@@ -66,6 +71,12 @@ Para leer CSF escaneadas (JPEG/PNG) con Gemini, agrega el extra:
 pip install "csf-scraper-python[llm-gemini]"
 ```
 
+Para leerlas usando el lector basado en OpenCV:
+
+```bash
+pip install "csf-scraper-python[opencv]"
+```
+
 Desde el código fuente:
 
 ```bash
@@ -77,6 +88,10 @@ pip install .
 Todo el flujo es asíncrono: `Scraper` envuelve un `httpx.AsyncClient` y todos
 los métodos de lectura son corrutinas, así que se consumen con `await`.
 
+`Scraper.create()` crea y devuelve la instancia directamente; **no** es
+obligatorio usarla con `async with`. Basta con cerrar el cliente al terminar,
+ya sea llamando a `aclose()` o usando el scraper como _async context manager_:
+
 ```python
 import asyncio
 
@@ -84,14 +99,17 @@ from csf_scraper import Scraper
 
 
 async def main() -> None:
-    # El scraper es un context manager asíncrono: cierra el AsyncClient al salir
-    async with Scraper.create() as scraper:
+    scraper = Scraper.create()
+
+    try:
         # RFC + idCIF directamente (se validan con los value objects Rfc e IdCif)
         person = await scraper.obtain_from_rfc_and_cif("DIM8701081LA", "1904014102123")
 
         # También puedes obtener los datos directamente de un archivo local PDF
         # (requiere pdftotext / poppler-utils instalado)
         person = await scraper.obtain_from_pdf_path("ruta/al/csf.pdf")
+    finally:
+        await scraper.aclose()
 
     # Acceso a los datos de la persona (moral o física) por atributos
     if person.is_fisica():
@@ -115,6 +133,16 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+Si prefieres no gestionar el cierre manualmente, el scraper también funciona
+como _async context manager_ (cierra el `AsyncClient` al salir del bloque):
+
+```python
+async def main() -> None:
+    async with Scraper.create() as scraper:
+        person = await scraper.obtain_from_rfc_and_cif("DIM8701081LA", "1904014102123")
+    print(person.to_dict())
+```
+
 Para leer una CSF escaneada (JPEG/PNG) se inyecta el motor de lectura de imágenes.
 Requiere el extra `llm-gemini`:
 
@@ -126,8 +154,33 @@ from csf_scraper import CsfImageExtractor, GeminiImageReader, Scraper
 
 async def main() -> None:
     reader = GeminiImageReader(api_key="…", model_name="…")
-    async with Scraper.create(image_extractor=CsfImageExtractor(reader)) as scraper:
+    scraper = Scraper.create(image_extractor=CsfImageExtractor(reader))
+    try:
+        person = await scraper.obtain_from_image_path("ruta/al/csf.png")
+    finally:
+        await scraper.aclose()
+    print(person.to_dict())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Para usar el lector basado en OpenCV no se necesita un proveedor LLM. Requiere
+el extra `opencv`:
+
+```python
+import asyncio
+
+from csf_scraper import CsfImageExtractor, OpenCvImageReader, Scraper
+
+
+async def main() -> None:
+    scraper = Scraper.create(image_extractor=CsfImageExtractor(OpenCvImageReader()))
+    try:
         person = await scraper.obtain_from_image_path("ruta/al/csf.png")
+    finally:
+        await scraper.aclose()
     print(person.to_dict())
 
 
@@ -135,14 +188,31 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-Salida de `person.to_dict()` para una persona moral (fechas como `datetime`):
+`to_dict()` devuelve el conjunto completo de propiedades del modelo que se haya
+obtenido: los campos comunes de `Persona` más los propios de `PersonaMoral` o de
+`PersonaFisica`. Las fechas se devuelven como `datetime` (o `None`) y los value
+objects `Rfc`/`IdCif` como cadenas.
+
+Salida de `person.to_dict()` para una **persona moral**:
 
 ```python
 {
+    # Compartidos con PersonaFisica
     "rfc": "DIM8701081LA",
     "id_cif": "12345678",
     "fecha_inicio_operaciones": datetime(2019, 2, 21),
-    # …
+    "situacion_contribuyente": "ACTIVO",
+    "fecha_ultimo_cambio_situacion": datetime(2019, 2, 21),
+    "entidad_federativa": "CIUDAD DE MEXICO",
+    "municipio_delegacion": "CUAUHTEMOC",
+    "colonia": "CENTRO",
+    "tipo_vialidad": "CALLE",
+    "nombre_vialidad": "AVENIDA REFORMA",
+    "numero_exterior": "123",
+    "numero_interior": "A",
+    "codigo_postal": "06000",
+    "correo_electronico": "contacto@ejemplo.mx",
+    "al": "CIUDAD DE MEXICO",
     "regimenes": [
         {
             "regimen": "Régimen General de Ley Personas Morales",
@@ -151,12 +221,53 @@ Salida de `person.to_dict()` para una persona moral (fechas como `datetime`):
         },
     ],
     "extra_data": {"localidad": ""},
+    # Propios de PersonaMoral
     "razon_social": "Mi razón social",
     "regimen_de_capital": "SA DE CV",
     "fecha_constitucion": datetime(2019, 2, 21),
 }
 ```
 
+Salida de `person.to_dict()` para una **persona física**:
+
+```python
+{
+    # Compartidos con PersonaMoral
+    "rfc": "GODE561231GR8",
+    "id_cif": "12345678",
+    "fecha_inicio_operaciones": datetime(2019, 2, 21),
+    "situacion_contribuyente": "ACTIVO",
+    "fecha_ultimo_cambio_situacion": datetime(2019, 2, 21),
+    "entidad_federativa": "CIUDAD DE MEXICO",
+    "municipio_delegacion": "CUAUHTEMOC",
+    "colonia": "CENTRO",
+    "tipo_vialidad": "CALLE",
+    "nombre_vialidad": "AVENIDA REFORMA",
+    "numero_exterior": "123",
+    "numero_interior": "A",
+    "codigo_postal": "06000",
+    "correo_electronico": "contacto@ejemplo.mx",
+    "al": "CIUDAD DE MEXICO",
+    "regimenes": [
+        {
+            "regimen": "Régimen de Sueldos y Salarios e Ingresos Asimilados a Salarios",
+            "fecha_alta": datetime(2019, 2, 21),
+            "regimen_id": "605",
+        },
+    ],
+    "extra_data": {"localidad": ""},
+    # Propios de PersonaFisica
+    "curp": "GODE561231HDFRRN09",
+    "nombre": "MI NOMBRE",
+    "apellido_paterno": "MI APELLIDO PATERNO",
+    "apellido_materno": "MI APELLIDO MATERNO",
+    "fecha_nacimiento": datetime(1956, 12, 31),
+}
+```
+
+Si necesitas las fechas en ISO-8601, usa `person.model_dump_json()`, que
+serializa exactamente las mismas propiedades.
+
 ## Modelos
 
 - `Persona` es la base de `PersonaFisica` y `PersonaMoral`; sus campos se

{csf_scraper_python-0.1.1 → csf_scraper_python-0.2.0}/README.md

@@ -1,4 +1,4 @@
-# csf-scraper
+# csf-scraper-python
 
 Port a Python de [phpcfdi/csf-scraper](https://github.com/phpcfdi/csf-scraper):
 obtiene los datos fiscales actuales de una persona moral o física dado su RFC y
@@ -11,7 +11,8 @@ su idCIF (SAT, Constancia de Situación Fiscal).
   `poppler-utils`), necesario **solo** para leer la CSF desde un archivo PDF
   (`obtain_from_pdf_path`).
 - Dependencias: `httpx`, `beautifulsoup4`, `lxml`, `pydantic`, `llama-index-core`.
-  Los clientes de cada proveedor LLM son extras opcionales (`llm-gemini`).
+  Los clientes de cada proveedor LLM son extras opcionales (`llm-gemini`). El
+  lector de imágenes basado en OpenCV requiere el extra `opencv`.
 
 ## Instalación
 
@@ -27,6 +28,12 @@ Para leer CSF escaneadas (JPEG/PNG) con Gemini, agrega el extra:
 pip install "csf-scraper-python[llm-gemini]"
 ```
 
+Para leerlas usando el lector basado en OpenCV:
+
+```bash
+pip install "csf-scraper-python[opencv]"
+```
+
 Desde el código fuente:
 
 ```bash
@@ -38,6 +45,10 @@ pip install .
 Todo el flujo es asíncrono: `Scraper` envuelve un `httpx.AsyncClient` y todos
 los métodos de lectura son corrutinas, así que se consumen con `await`.
 
+`Scraper.create()` crea y devuelve la instancia directamente; **no** es
+obligatorio usarla con `async with`. Basta con cerrar el cliente al terminar,
+ya sea llamando a `aclose()` o usando el scraper como _async context manager_:
+
 ```python
 import asyncio
 
@@ -45,14 +56,17 @@ from csf_scraper import Scraper
 
 
 async def main() -> None:
-    # El scraper es un context manager asíncrono: cierra el AsyncClient al salir
-    async with Scraper.create() as scraper:
+    scraper = Scraper.create()
+
+    try:
         # RFC + idCIF directamente (se validan con los value objects Rfc e IdCif)
         person = await scraper.obtain_from_rfc_and_cif("DIM8701081LA", "1904014102123")
 
         # También puedes obtener los datos directamente de un archivo local PDF
         # (requiere pdftotext / poppler-utils instalado)
         person = await scraper.obtain_from_pdf_path("ruta/al/csf.pdf")
+    finally:
+        await scraper.aclose()
 
     # Acceso a los datos de la persona (moral o física) por atributos
     if person.is_fisica():
@@ -76,6 +90,16 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+Si prefieres no gestionar el cierre manualmente, el scraper también funciona
+como _async context manager_ (cierra el `AsyncClient` al salir del bloque):
+
+```python
+async def main() -> None:
+    async with Scraper.create() as scraper:
+        person = await scraper.obtain_from_rfc_and_cif("DIM8701081LA", "1904014102123")
+    print(person.to_dict())
+```
+
 Para leer una CSF escaneada (JPEG/PNG) se inyecta el motor de lectura de imágenes.
 Requiere el extra `llm-gemini`:
 
@@ -87,8 +111,33 @@ from csf_scraper import CsfImageExtractor, GeminiImageReader, Scraper
 
 async def main() -> None:
     reader = GeminiImageReader(api_key="…", model_name="…")
-    async with Scraper.create(image_extractor=CsfImageExtractor(reader)) as scraper:
+    scraper = Scraper.create(image_extractor=CsfImageExtractor(reader))
+    try:
+        person = await scraper.obtain_from_image_path("ruta/al/csf.png")
+    finally:
+        await scraper.aclose()
+    print(person.to_dict())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Para usar el lector basado en OpenCV no se necesita un proveedor LLM. Requiere
+el extra `opencv`:
+
+```python
+import asyncio
+
+from csf_scraper import CsfImageExtractor, OpenCvImageReader, Scraper
+
+
+async def main() -> None:
+    scraper = Scraper.create(image_extractor=CsfImageExtractor(OpenCvImageReader()))
+    try:
         person = await scraper.obtain_from_image_path("ruta/al/csf.png")
+    finally:
+        await scraper.aclose()
     print(person.to_dict())
 
 
@@ -96,14 +145,31 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-Salida de `person.to_dict()` para una persona moral (fechas como `datetime`):
+`to_dict()` devuelve el conjunto completo de propiedades del modelo que se haya
+obtenido: los campos comunes de `Persona` más los propios de `PersonaMoral` o de
+`PersonaFisica`. Las fechas se devuelven como `datetime` (o `None`) y los value
+objects `Rfc`/`IdCif` como cadenas.
+
+Salida de `person.to_dict()` para una **persona moral**:
 
 ```python
 {
+    # Compartidos con PersonaFisica
     "rfc": "DIM8701081LA",
     "id_cif": "12345678",
     "fecha_inicio_operaciones": datetime(2019, 2, 21),
-    # …
+    "situacion_contribuyente": "ACTIVO",
+    "fecha_ultimo_cambio_situacion": datetime(2019, 2, 21),
+    "entidad_federativa": "CIUDAD DE MEXICO",
+    "municipio_delegacion": "CUAUHTEMOC",
+    "colonia": "CENTRO",
+    "tipo_vialidad": "CALLE",
+    "nombre_vialidad": "AVENIDA REFORMA",
+    "numero_exterior": "123",
+    "numero_interior": "A",
+    "codigo_postal": "06000",
+    "correo_electronico": "contacto@ejemplo.mx",
+    "al": "CIUDAD DE MEXICO",
     "regimenes": [
         {
             "regimen": "Régimen General de Ley Personas Morales",
@@ -112,12 +178,53 @@ Salida de `person.to_dict()` para una persona moral (fechas como `datetime`):
         },
     ],
     "extra_data": {"localidad": ""},
+    # Propios de PersonaMoral
     "razon_social": "Mi razón social",
     "regimen_de_capital": "SA DE CV",
     "fecha_constitucion": datetime(2019, 2, 21),
 }
 ```
 
+Salida de `person.to_dict()` para una **persona física**:
+
+```python
+{
+    # Compartidos con PersonaMoral
+    "rfc": "GODE561231GR8",
+    "id_cif": "12345678",
+    "fecha_inicio_operaciones": datetime(2019, 2, 21),
+    "situacion_contribuyente": "ACTIVO",
+    "fecha_ultimo_cambio_situacion": datetime(2019, 2, 21),
+    "entidad_federativa": "CIUDAD DE MEXICO",
+    "municipio_delegacion": "CUAUHTEMOC",
+    "colonia": "CENTRO",
+    "tipo_vialidad": "CALLE",
+    "nombre_vialidad": "AVENIDA REFORMA",
+    "numero_exterior": "123",
+    "numero_interior": "A",
+    "codigo_postal": "06000",
+    "correo_electronico": "contacto@ejemplo.mx",
+    "al": "CIUDAD DE MEXICO",
+    "regimenes": [
+        {
+            "regimen": "Régimen de Sueldos y Salarios e Ingresos Asimilados a Salarios",
+            "fecha_alta": datetime(2019, 2, 21),
+            "regimen_id": "605",
+        },
+    ],
+    "extra_data": {"localidad": ""},
+    # Propios de PersonaFisica
+    "curp": "GODE561231HDFRRN09",
+    "nombre": "MI NOMBRE",
+    "apellido_paterno": "MI APELLIDO PATERNO",
+    "apellido_materno": "MI APELLIDO MATERNO",
+    "fecha_nacimiento": datetime(1956, 12, 31),
+}
+```
+
+Si necesitas las fechas en ISO-8601, usa `person.model_dump_json()`, que
+serializa exactamente las mismas propiedades.
+
 ## Modelos
 
 - `Persona` es la base de `PersonaFisica` y `PersonaMoral`; sus campos se