formula-engine
Simple to configure. Explicit to execute. Powerful to extend.
Motor universal declarativo de fórmulas, expresiones y reglas para Python ≥ 3.12. Configurable mediante YAML, JSON o dict, agnóstico al dominio: precios, impuestos, comisiones, scoring, tarifas, nóminas o cualquier cálculo reglamentario.
Tú defines qué calcular; el motor se encarga de parsear, validar, resolver dependencias, evaluar, explicar y proteger contra ejecución arbitraria.
¿Para quién es?
- Equipos que necesitan cambiar reglas de negocio sin desplegar código:
la lógica vive en un archivo YAML versionable, no en
if/elsedispersos. - Aplicaciones financieras o reglamentarias que exigen
Decimalexacto (nada de0.1 + 0.2 != 0.3), tipos estrictos y determinismo total. - Quienes quieren auditabilidad:
explain()devuelve qué se calculó, cómo y en qué orden.
¿Qué NO es?
- No es un sistema no-code: no tiene UI, editor visual ni ejecución remota de reglas.
- No es un ORM ni una capa de acceso a datos: no toca bases de datos.
- No trae HTTP, logging externo ni cache: el núcleo es solo el motor de cálculo (spec §3, §39, §44, §45). Si necesitas esas capas, van en tu aplicación, no en la librería.
Características clave
- Seguro por diseño: sin
eval()/exec(). Pipeline obligatorioLexer → Parser → AST → Validator → Evaluator; nombres prohibidos y límites de complejidad → error controlado. Decimalfinanciero: aritmética exacta, sin errores de coma flotante.- Tipos estrictos: 10 tipos con coerción explícita y validación fail-fast en carga y en cada cálculo.
- Reglas con semántica inequívoca:
when/set/priority, orden por prioridad asc + declaración, last-write-wins. Sin ambigüedad de conflictos. - Dependencias automáticas: el motor ordena fórmulas en topológico y detecta ciclos con el error correspondiente.
explain()estructurado: cada cálculo devuelve el detalle de inputs, variables, fórmulas, reglas, outputs y orden de evaluación.- CLI incluida:
validate,calculate,explain,dependencies,test. - Extensible:
register_function()para incorporar funciones personalizadas sin tocar el motor. - Determinista e inmutable: mismo input → mismo resultado; los datos de entrada nunca se mutan.
Tabla de contenidos
- Instalación
- Primer cálculo en menos de 5 minutos
- Uso en 4 pasos
- API pública
- Ejemplos multi-dominio
- Seguridad
- CLI
- Documentación
- Calidad y testing
- Estado y roadmap
- Contribución
- Licencia
Instalación
Requisito: Python >= 3.12.
# desde la raíz del proyecto (usa tu venv si lo tienes)
pip install .
# en editable, con dependencias de desarrollo
pip install -e ".[dev]"
Única dependencia de runtime: PyYAML (para from_yaml). Todo lo demás es
stdlib (decimal, datetime, json, argparse). Ver pyproject.toml.
Primer cálculo en menos de 5 minutos
Crea pricing.yaml:
name: pricing
variables:
costo:
type: decimal
required: true
margen:
type: decimal
required: true
cantidad:
type: integer
required: true
formulas:
precio_base:
expression: "costo * (1 + margen)"
descuento:
expression: "0"
rules:
- name: volumen
when: "cantidad >= 100"
set:
descuento: "precio_base * 0.10"
outputs:
precio_final: "precio_base - descuento"
Calcúlalo:
from formula_engine import FormulaEngine
engine = FormulaEngine.from_yaml("pricing.yaml")
resultado = engine.calculate({
"costo": 100,
"margen": 0.30,
"cantidad": 150,
})
print(resultado)
Resultado real (los valores son decimal.Decimal):
{'precio_final': Decimal('117.000')}
Qué ha pasado: la regla volumen aplica porque cantidad >= 100 (150),
sobrescribe descuento con el 10 % de precio_base, y el output
precio_final se evalúa al final:
precio_base = 100 * (1 + 0.30) = 130.0descuento = 130.0 * 0.10 = 13.000precio_final = 130.0 - 13.000 = 117.000
Nota:
calculate(data)devuelve por defecto solo los outputs declarados (precio_final). Para obtener también las fórmulas y los valores escritos por reglas usaoutputs="*":engine.calculate(data, outputs="*") # -> {'precio_base': Decimal('130.0'), # 'descuento': Decimal('13.000'), # 'precio_final': Decimal('117.000')}
Uso en 4 pasos
1. Definir (YAML / JSON / dict)
La definición declara variables, fórmulas, reglas y outputs (el YAML del quickstart). Los tres formatos son equivalentes y semánticamente idénticos (spec §42):
engine = FormulaEngine.from_yaml("pricing.yaml") # archivo YAML
engine = FormulaEngine.from_json("pricing.json") # archivo JSON (mismo schema)
engine = FormulaEngine.from_dict({...}) # dict en Python
2. Cargar
from_yaml / from_json / from_dict validan fail-fast: parsean,
normalizan, validan schema, nombres, expresiones y detectan ciclos. Un error
aquí lanza una excepción de formula_engine.errors inmediatamente.
engine = FormulaEngine.from_yaml("pricing.yaml") # valida y construye
engine.validate() # revalida (idempotente)
3. Calcular
resultado = engine.calculate({"costo": 100, "margen": 0.30, "cantidad": 150})
# {'precio_final': Decimal('117.000')}
El pipeline es inputs → fórmulas → reglas → outputs. Los datos de entrada
no se mutan y las claves extra se ignoran. outputs admite None (solo
outputs declarados), una lista de nombres computados en el orden pedido, o
"*" (fórmulas + targets de reglas + outputs).
4. Explicar
reporte = engine.explain({"costo": 100, "margen": 0.30, "cantidad": 150})
explain() reutiliza el mismo pipeline (no recalcula: captura los valores
intermedios reales) y devuelve un dict estructurado:
{
"definition": {"name": "pricing", "version": None},
"inputs": {"costo": 100, "margen": 0.3, "cantidad": 150},
"variables": {"costo": {"value": "100", "source": "input"}},
"formulas": {
"precio_base": {"expression": "costo * (1 + margen)",
"value": "130.0", "dependencies": ["costo", "margen"]},
},
"rules": [{"name": "volumen",
"when": {"expression": "cantidad >= 100", "result": True},
"set": {"descuento": {"expression": "precio_base * 0.10",
"value": "13.000"}},
"applied": True}],
"outputs": {"precio_final": {"expression": "precio_base - descuento",
"value": "117.000"}},
"order": ["cantidad", "margen", "costo", "precio_base",
"descuento", "volumen", "precio_final"],
}
API pública
Public API estable (spec §5, §41), expuesta desde formula_engine:
from formula_engine import FormulaEngine
engine = FormulaEngine.from_yaml("formula.yaml") # o from_json / from_dict
engine.validate() # revalida (idempotente)
engine.calculate(data, outputs=None) # resultado: dict con Decimal
engine.explain(data) # dict estructurado del cálculo
engine.dependencies() # grafo de dependencias
engine.register_function("mi_fn", fn) # extiende el registry
from_yaml(path)/from_json(path)/from_dict(data)— cargan y validan la definición fail-fast. El chequeo de funciones aún no registradas se difiere avalidate()/calculate()(ver funciones).validate()— re-ejecuta la validación completa contra el registry actual.calculate(data, outputs=None)— evalúa el pipelineinputs → fórmulas → reglas → outputs.outputs=Nonedevuelve solo los outputs declarados; una lista devuelve cualquier nombre computado (fórmulas u outputs) en el orden pedido;"*"devuelve fórmulas + targets de reglas + outputs.datanunca se muta y las claves extra se ignoran.explain(data)— devuelve el dict anidado del paso 4 (entradas, variables con su origen, fórmulas, reglas, outputs y orden de evaluación).dependencies()—{"variables": [...], "formulas": {...}, "rules": {...}, "outputs": {...}, "order": [...]}.register_function(name, fn)— registra una función personalizada; los nombres prohibidos (eval,exec, dunders, …), los ya registrados y los que colisionan con definiciones existentes se rechazan conDefinitionError.
Errores: las 10 excepciones públicas heredan de FormulaEngineError y
llevan contexto estructurado (expresión, variable, fórmula, regla, causa).
Ver errors.
from formula_engine import (
FormulaEngineError, DefinitionError, ParseError, ValidationError,
TypeValidationError, UnknownVariableError, UnknownFunctionError,
CircularDependencyError, EvaluationError, UnsafeExpressionError,
)
Ejemplos multi-dominio
Todos los ejemplos están en examples/, organizados por dominio (una carpeta
autocontenida por ejemplo) y verificados con casos de prueba integrados.
Ejecútalos todos con python examples/demo.py o uno a uno con
formula-engine test examples/<dominio>/<dominio>.yaml:
| Ejemplo | Dominio | Demuestra |
|---|---|---|
examples/pricing/pricing.yaml |
Precios | fórmula + regla de volumen + output |
examples/taxes/taxes.yaml |
Impuestos (IVA + retención) | reglas con priority sobre el mismo target, string |
examples/commissions/commissions.yaml |
Comisiones por tramos | when compuesto con and, regla sin condición, min/max |
examples/credit_scoring/credit_scoring.yaml |
Scoring de crédito | or/!=, reglas que escriben strings, min(puntos, 100) |
examples/payroll/payroll.yaml |
Nómina | Decimal, round, defaults, regla que suma al output |
examples/shipping/shipping.yaml |
Envíos y tarifas | 5 reglas → 3 targets, booleano urgente |
examples/savings/savings.yaml |
Interés compuesto | pow() Decimal, múltiples outputs |
python examples/demo.py # ejecuta los 7 ejemplos
formula-engine test examples/taxes/taxes.yaml # 3/3 passed
formula-engine calculate examples/payroll/payroll.yaml examples/payroll/payroll_input.json
Nota: las definiciones de
examples/incluyen una seccióntestsde nivel CLI (spec §32) que el schema del motor rechaza conDefinitionError— es la CLI (yexamples/demo.py) quien la separa antes de construir el motor. El quickstart de este README usa la definición mínima sin esa sección.
Seguridad
Sin eval() ni exec(). Toda expresión pasa por el pipeline obligatorio
Lexer → Parser → AST → Validator → Evaluator
El AST solo contiene las operaciones de la gramática; el evaluador resuelve
llamadas únicamente contra el registry de funciones registradas, nunca contra
globals()/getattr. Límites aplicados en validación:
| Límite | Valor | Error |
|---|---|---|
| Longitud de expresión | 10 000 caracteres | UnsafeExpressionError |
| Profundidad de AST | 300 | UnsafeExpressionError |
| Nombres prohibidos | eval, exec, open, os, __import__, dunders (__class__…) |
UnsafeExpressionError |
FormulaEngine.from_dict({
"name": "x",
"variables": {},
"formulas": {"f": {"expression": "eval(\"1\")"}},
"outputs": {"o": "f"},
})
# UnsafeExpressionError: forbidden name 'eval'
Ver security para la lista completa de vectores probados y extending para cómo registrar funciones seguras.
CLI
formula-engine se instala como comando del paquete con 5 subcomandos
(spec §32):
formula-engine validate examples/pricing/pricing.yaml
formula-engine calculate examples/pricing/pricing.yaml examples/pricing/input.json
formula-engine explain examples/pricing/pricing.yaml examples/pricing/input.json
formula-engine dependencies examples/pricing/pricing.yaml
formula-engine test examples/pricing/pricing.yaml
validate— valida la definición y construye el motor; imprimeOK: pricing v1.0.0 valid(exit 0) o un error claro en stderr (exit 1).calculate/explain— necesitan un JSON con los datos de entrada (objeto plano); la salida es JSON. LosDecimalse serializan como número; las fechas como ISO-8601; unDecimalfuera de rango defloatse serializa como string para que la serialización nunca falle.dependencies— imprime el grafo de dependencias como JSON.test— ejecuta la seccióntestsde la definición ([{name?, input, expect}], comparación Decimal-aware); FAIL → exit 1.
Ejemplo real:
$ formula-engine validate examples/pricing/pricing.yaml
OK: pricing v1.0.0 valid
$ formula-engine test examples/taxes/taxes.yaml
OK gran empresa retiene 20 %
OK pyme retiene 10 %
OK cliente sin convenio usa el default 15 %
3/3 passed
$ formula-engine calculate examples/payroll/payroll.yaml examples/payroll/payroll_input.json
{
"bruto": 2625.0,
"deduccion_irpf": 393.75,
"deduccion_ss": 157.5,
"neto": 2073.75
}
Exit codes: 0 éxito; 1 error de definición, de entrada, de archivo o del
motor; 2 error de uso de argparse.
Documentación
Guías completas en docs/:
- getting-started — instalación, primer cálculo, CLI
- definitions — formato de definición y schema
- expressions — lenguaje de expresiones
- variables — variables y tipos
- formulas — fórmulas y dependencias
- rules — reglas y conflictos
- functions — funciones built-in y personalizadas
- types — sistema de tipos y
Decimal - errors — excepciones y contexto
- security — seguridad y vectores de ataque
- testing — suite de tests y cobertura
- architecture — arquitectura interna
- extending — cómo extender el motor
- performance — benchmarks
- mutation — mutation testing
Calidad y testing
Estado real del repositorio (verificado en la entrega de la versión 0.1.0):
| Métrica | Valor |
|---|---|
| Tests | 1125 passed (pytest -q) |
| Cobertura de línea | 99 % (1441 líneas, 4 sin cubrir) |
| Cobertura de branch | 99 % (588 branches, 12 partial) |
| Mutation score | 84.0 % (2260/2689 mutantes matados) |
| Lint | ruff check . — limpio |
| Tipos | mypy . — estricto, limpio (51 archivos) |
Comandos para reproducir:
pytest -q # 1125 passed
pytest --cov=formula_engine --cov-branch --cov-report=term # cobertura
ruff check . # limpio
mypy . # estricto, limpio
mutmut run --use-coverage # mutation score (lento)
Estado y roadmap
- Versión:
0.1.0(formula_engine.__version__), versionado semántico. La Public API documentada arriba es estable; los módulos internos (parser/,ast/,evaluator/, …) son Internal API y pueden cambiar sin aviso (spec §41). - Estado: Beta — núcleo completo y verificado: parser, AST, evaluador, tipos, variables, fórmulas, dependency resolver, reglas, funciones, explain, seguridad, CLI y packaging.
Ideas futuras (roadmap honesto, sin fecha):
- Cache de AST por definición (reutilizar árbol parseado entre cálculos).
- Más built-ins (potencias modulares, funciones trigonométricas, agregados).
- Tipos dedicados
moneyypercentagecon reglas de redondeo configurables. - Plugins de funciones cargados desde YAML.
Nada de esto existe aún; si lo necesitas, register_function() cubre los
casos de funciones hoy.
Contribución
- Clona el repositorio y crea un venv con Python >= 3.12:
git clone <url-del-repo> && cd formula-engine python -m venv .venv .venv/bin/pip install -e ".[dev]"
- Antes de enviar un PR, todo debe pasar:
pytest ruff check . mypy .
- Política de PRs:
- Tests obligatorios: cada bug corregido lleva su test de regresión (spec §29); cada feature nueva lleva tests de comportamiento real.
- No romper cobertura ≥ 90 %; los módulos críticos deben mantenerla aún más alta.
- Prohibido
eval()/exec()en el código del motor (spec §8). - La lógica de dominio no se mezcla con serialización; la CLI no contiene lógica de motor (spec §35).
- Documentación: si cambia la API pública o el schema, actualiza
docs/y el README en el mismo PR.
Guías de referencia: architecture, extending y testing.
Publicación (PyPI)
El paquete se construye con python -m build y se verifica con twine check
(ambos en .[dev]). El CI (.github/workflows/ci.yml) valida calidad en cada
push/PR; .github/workflows/publish.yml publica automáticamente en
PyPI/TestPyPI al crear un tag v* o vía workflow_dispatch (Trusted
Publishing, sin tokens). Procedimiento completo: RELEASE.md.
pip install -e ".[dev]"
python -m build # genera dist/*.whl + dist/*.tar.gz
twine check dist/* # valida metadatos
Licencia
MIT — declarada en pyproject.toml y LICENSE. Uso libre, incluido uso
comercial, con atribución y sin garantía.
Metadata
Release files for formula-engine 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| formula_engine-0.1.0.tar.gz | 59.1 kB | With provenance | Details for formula_engine-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| formula_engine-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for formula_engine-0.1.0-py3-none-any.whl |
Total release size: 118.5 kB
Release files / formula_engine-0.1.0.tar.gz
| Download URL | formula_engine-0.1.0.tar.gz |
|---|---|
| Size | 59.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0cc014c0c6ca653974c546fe606f8b01418c46d2609911031dab6ba965d3c9c2
|
|
BLAKE2b-256 checksum How to use checksums |
bb43dec101b7659a0a4367515f029ba13b71151feb9986f00902e9bd81df2acb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 10, 2026.
Transparency logRelease files / formula_engine-0.1.0-py3-none-any.whl
| Download URL | formula_engine-0.1.0-py3-none-any.whl |
|---|---|
| Size | 59.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3c9fbd8cbf08459ab786d333c55a65ca59abd4cce4aa8df054d9f8851a096758
|
|
BLAKE2b-256 checksum How to use checksums |
9b0f987c937dee7c287a3e4b36dfe18a18a7654d072980e6b3b3d99aa65dfeaa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 10, 2026.
Transparency logSecurity for formula-engine 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for formula_engine-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.