py-invoices

Framework-agnostic invoice management with pluggable storage backends.

Features

• Pluggable Storage Backends: Swap between SQLite, PostgreSQL, MySQL or in-memory storage
• E-Invoicing Ready: Built-in support for Factur-X (ZUGFeRD) and UBL standards
• Audit Logging: Integrated audit trail for tracking all invoice lifecycles
• Framework-Agnostic: Designed for integration into any Python application
• Type-Safe: Built on pydantic-invoices schemas with full type hints
• Flexible: Optional dependencies - install only what you need
• In-Memory Operations: HTML generation and byte-stream output supported out-of-the-box

Installation

Requires Python 3.14 or later.

# Basic installation (includes HTML generation)
pip install py-invoices

# With CLI support (recommended for interactive use)
pip install "py-invoices[cli]"

# With SQLite support
pip install py-invoices[sqlite]

# With PostgreSQL support
pip install py-invoices[postgres]

# With MySQL support
pip install py-invoices[mysql]

# With PDF generation
pip install py-invoices[pdf]

# With .env file support (for setup command)
pip install py-invoices[dotenv]

# Everything
pip install py-invoices[all]

PDF Generation Requirements

PDF generation uses WeasyPrint, which requires system-level libraries for rendering (Pango, GObject, Cairo).

macOS:

brew install pango libffi
# You may also need to set the library path:
export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_FALLBACK_LIBRARY_PATH

Linux/Ubuntu:

sudo apt-get install python3-pip python3-cffi python3-brotli libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0

For more details, see the WeasyPrint installation guide.

CLI Usage

The package includes a configured CLI tool py-invoices.

Quick Start:

# 1. Setup configuration (interactive wizard)
py-invoices setup

# 2. Initialize the backend
py-invoices init

# 3. Create an invoice (and auto-create client)
py-invoices invoices create --client-name "Acme Corp" --amount 1500.00 --description "Consulting"

For full documentation on available commands (listing, generating PDFs, backend configuration), see the CLI Documentation.

Quick Start

from datetime import datetime
from py_invoices import RepositoryFactory
from pydantic_invoices.schemas import ClientCreate, InvoiceCreate, InvoiceLineCreate, InvoiceStatus

# Initialize with memory backend
factory = RepositoryFactory(backend="memory")

# Get repositories
client_repo = factory.create_client_repository()
invoice_repo = factory.create_invoice_repository()

# Create a client
client = client_repo.create(ClientCreate(
    name="Acme Corp",
    address="123 Business St",
    tax_id="12-3456789"
))

# Create an invoice
invoice = invoice_repo.create(InvoiceCreate(
    number="INV-2025-0001",
    issue_date=datetime.now(),
    status=InvoiceStatus.UNPAID,
    client_id=client.id,
    client_name_snapshot=client.name,
    client_address_snapshot=client.address,
    client_tax_id_snapshot=client.tax_id,
    lines=[
        InvoiceLineCreate(
            description="Professional Services",
            quantity=40,
            unit_price=150.0
        )
    ]
))

print(f"Created invoice {invoice.number} for ${invoice.total_amount}")

Configuration

Environment Variables

Configure backends using environment variables or .env files:

# Set environment variables
export INVOICES_BACKEND=sqlite
export INVOICES_DATABASE_URL=sqlite:///invoices.db
export INVOICES_DATABASE_ECHO=false

from py_invoices import RepositoryFactory

# Automatically loads from environment variables and .env file
factory = RepositoryFactory.from_settings()

Using .env File

Create a .env file in your project root:

INVOICES_BACKEND=sqlite
INVOICES_DATABASE_URL=sqlite:///invoices.db
INVOICES_DATABASE_ECHO=false
# INVOICES_TEMPLATE_DIR=templates
INVOICES_OUTPUT_DIR=output

from py_invoices import RepositoryFactory

# Loads configuration from .env file automatically
factory = RepositoryFactory.from_settings()

Programmatic Configuration

from py_invoices import InvoiceSettings, RepositoryFactory

settings = InvoiceSettings(
    backend="sqlite",
    database_url="sqlite:///invoices.db",
    database_echo=False
)

factory = RepositoryFactory.from_settings(settings)

Available Settings

Core Services

PDF Generation

Generate professional PDF/HTML invoices using Jinja2 templates:

from py_invoices.core import PDFService

# Company details for the invoice header
company = {
    "name": "My Company",
    "address": "123 HQ Blvd, Tech City",
    "tax_id": "US-99999"
}

pdf_service = PDFService(output_dir="output")

# Generate to file
pdf_path = pdf_service.generate_pdf(invoice=invoice, company=company)

# Generate to memory (bytes)
pdf_bytes = pdf_service.generate_pdf_bytes(invoice=invoice, company=company)

HTML Generation

For scenarios where you only need HTML (e.g. emails) or don't want the heavy WeasyPrint dependency:

from py_invoices.core import HTMLService

# Uses only Jinja2 (no WeasyPrint)
html_service = HTMLService(output_dir="output")

# Generate HTML string
html_content = html_service.generate_html(invoice=invoice, company=company)

# Save to HTML file
html_path = html_service.save_html(invoice=invoice, company=company)

Industry Standard (Factur-X / UBL)

Generate enterprise-ready invoices compliant with European standards:

Factur-X (PDF/A-3 + XML): A PDF/A-3b document embedding the invoice as UN/CEFACT CII XML (factur-x.xml), Factur-X 1.0 profile EN 16931 (compatible with ZUGFeRD 2 COMFORT). Credit notes use document type 381.

# Requires py-invoices[pdf]
facturx_path = pdf_service.generate_facturx(invoice=invoice, company=company)

EN 16931 requires data that plain PDFs do not:

• company: name, country_code (or country) as an ISO 3166-1 alpha-2 code, and tax_id; when tax_id is not a VAT number (e.g. DE123456789), also registration_number
• the invoice: client_name_snapshot and client_country_snapshot, filled from the client's country when the invoice is created (clients create --country DE, invoices create --client-country DE)

Missing data raises FacturXDataError listing every problem. The delivery date defaults to the issue date (delivery_date= overrides it); pass original_invoice_number= for a credit note. The CII XML alone is available from CIIService().generate_cii(invoice, company).

UBL (XML Only): Universal Business Language Version 2.1 XML invoices.

from py_invoices.core import UBLService

ubl_service = UBLService(output_dir="output")
ubl_path = ubl_service.save_ubl(invoice, company)

In-Memory Generation (Bytes)

Generate files directly to memory without saving to disk:

# Generate Factur-X bytes
pdf_bytes = pdf_service.generate_facturx_bytes(invoice, company)

# Generate UBL XML bytes
xml_bytes = ubl_service.generate_ubl_bytes(invoice, company)

Audit Logging

Track every change in the invoice lifecycle:

from py_invoices.core import AuditService

audit_service = AuditService(audit_repo=factory.create_audit_repository())

# Log event
audit_service.log_invoice_created(invoice, user_id="system_admin")
audit_service.log_payment_added(invoice, payment, user_id="cashier_01")

# Retrieve logs
logs = audit_service.get_logs(invoice_id=invoice.id)

Invoice Numbering

Generate sequential, formatted invoice numbers:

from py_invoices.core import NumberingService

# Default format: INV-{year}-{sequence:04d}
numbering = NumberingService(invoice_repo=invoice_repo)
next_number = numbering.generate_number()

Storage Backends

Memory (Testing)

Perfect for development and testing:

factory = RepositoryFactory(backend="memory")

SQLite (Production-Ready)

For single-file database storage:

factory = RepositoryFactory(
    backend="sqlite",
    database_url="sqlite:///invoices.db"
)

PostgreSQL (Enterprise)

For production deployments:

factory = RepositoryFactory(
    backend="postgres",
    database_url="postgresql://user:pass@localhost/invoices"
)

MySQL

For common web server setups:

factory = RepositoryFactory(
    backend="mysql",
    database_url="mysql+pymysql://user:pass@localhost/invoices"
)

Files (Local Storage)

Stores data as individual files (JSON, YAML, XML, or Markdown) in a local directory. Markdown format is recommended for human readability and direct editing.

factory = RepositoryFactory(
    backend="files",
    root_dir="./data",
    file_format="yaml"  # Defaults to "md" for *writing* new files
)

Note: The backend automatically detects and reads files in any supported format (json, yaml, xml, md) regardless of the file_format setting. This allows you to mix formats or manually edit files in your preferred format. It also supports friendly filenames for better organization (e.g., 1.Customer Name.json instead of just 1.json).

Architecture

py-invoices (business logic)
    ↓ depends on
pydantic-invoices (schemas)

Development

# Clone repository
git clone https://github.com/Romamo/py-invoices
cd py-invoices

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy py_invoices

# Linting
ruff check py_invoices

License

MIT License - see LICENSE file for details.

Related Packages

• pydantic-invoices - Pydantic schemas and interfaces
• pydantic - Data validation using Python type hints