How sat-cfdi/python-satcfdi works
Project Type and Purpose
• This is an open-source Python library (not a web app) called “satcfdi” for generating, processing, signing and rendering Mexican electronic invoices (CFDI, DIOT, PLD, Contabilidad Electrónica, Retenciones) and integrating with PAC/SAT services.
• It supplies both a CLI (satcfdi/cli/main.py) and a programmatic API for Python applications.
Top-Level Architectural Components
A. Entry Points
• CLI: satcfdi/cli/main.py — parses user commands for create, process, download, validate, export
• Python API: importable module “satcfdi” for embedding in other apps
B. Core Library Layers
1. Domain Models (satcfdi/models, satcfdi/cfdi.py, satcfdi/xelement.py)
– Python classes that represent CFDI, DIOT, PLD, Contabilidad, Retenciones, Certificates, Signer, etc.
2. Creation Layer (satcfdi/create/…)
– Subpackages for each document type (cfd, cancelación, contabilidad, pld, retención, w3 signatures)
– Factories that populate Domain Model objects
3. Processing & Transformation Layer
– XMLify & XSLT (satcfdi/transform/*.py, schemas/XSD & XSLT under transform/schemas)
– Signing & Certificates (satcfdi/certifica/pkcs7.py, satcfdi/models/certificate_*)
– Validation utilities (XML schema validation, listing SAT catalogs)
4. External Services & API Connectors (satcfdi/apis, satcfdi/pacs)
– HTTP wrappers for Banxico, Diverza, Finkok, Prodigia, SW Sapien, SAT (authentication, stamping, consulta, descarga)
5. Rendering Layer (satcfdi/render)
– Jinja2 templates for HTML/JSON (render/templates)
– PDF generation (via external library calls)
6. Utilities & I/O
– File I/O (read/write XML, JSON, ZIP)
– ZIP handling (satcfdi/zip.py)
– Common helpers (satcfdi/utils.py, satcfdi/sat_requests_utils.py)
C. Output Targets and Side-Effects
• Local File System (XML, JSON, HTML, PDF, Excel)
• PAC/SAT endpoints (send/receive web service calls)
• Read-the-Docs & GitHub Actions (documentation, tests, publishing pipelines)
Relationships & Data Flow
• CLI/API → Creation Layer: user specifies “create CFDI” → Python factory constructs Domain Model.
• Domain Model → Processing: transform to XML, sign certificate, validate against XSD.
• Processing → External Services: optional stamping/consulta/descarga via PAC connectors.
• Processed object → Rendering: render to JSON, HTML (single/multiple), PDF.
• Rendered output →File System.
• Loading existing XML: inverse path via Transform.Objectify → Domain Model.
Architectural Patterns & Principles
• Layered architecture: clear separation of concerns (model, creation, transform, render, API connectors).
• Plugin-style extensibility:
• “satcfdi/create” modules for each document type
• “satcfdi/pacs” connectors for each PAC provider
• Jinja2 templates for renderers
• Schema-driven transformation: uses XSD and XSLT under transform/schemas for strict validation and canonicalization.
• Domain-Driven Design: core Domain Models encapsulate invoice structure & behavior (sign, process).
• CLI facade over library with argparse (or click) to offer command-line usability.
Technologies & Frameworks
• Python 3.x
• Jinja2 for HTML/JSON templates
• requests (or urllib) for HTTP to external services
• lxml or xml.etree for XML handling
• cryptography / pkcs7 for digital signatures
• ZIP, base64, decimal, datetime from stdlib
• setuptools for packaging (setup.py)
• CI/CD via GitHub Actions (tests.yml, codeql.yml, publish.yml)
• ReadTheDocs for documentation, Sphinx under docs/
Detail Balance
• Essential high-level components; avoid listing every single file.