Proyecto: gestor de gastos

gastos añadir 12,50 comida "Menú del día"
gastos listar --mes 2026-09 --categoria comida
gastos resumen --mes 2026-09
gastos borrar 6
gastos exportar gastos-septiembre.json --mes 2026-09

from decimal import Decimal

gastos_float = [12.50, 8.20, 27.15, 54.30, 0.1, 0.2]
gastos_decimal = [Decimal("12.50"), Decimal("8.20"), Decimal("27.15"),
                  Decimal("54.30"), Decimal("0.1"), Decimal("0.2")]

print(sum(gastos_float))
print(sum(gastos_decimal))
print(sum(gastos_float) == 102.45)
print(sum(gastos_decimal) == Decimal("102.45"))
print(Decimal("0.1") + Decimal("0.2"))
print(Decimal(0.1))

gastos/
    pyproject.toml        Metadatos y el comando gastos
    src/
        gastos/
            __init__.py
            modelo.py         La dataclass Gasto y las conversiones desde texto
            almacen.py        Leer y escribir el CSV
            configuracion.py  Moneda y ruta de los datos
            informes.py       Totales por categoría y barras
            presentacion.py   Colores y tablas
            cli.py            Argumentos, subcomandos y códigos de salida
            __main__.py       Permite python3 -m gastos

"""El dato central del programa: un gasto, y cómo se convierte desde texto."""

from dataclasses import dataclass
from datetime import date
from decimal import Decimal, InvalidOperation

CENTIMOS = Decimal("0.01")


@dataclass
class Gasto:
        """Un gasto apuntado: cuándo, en qué, cuánto."""

    identificador: int
    fecha: date
    categoria: str
    concepto: str
    importe: Decimal

    @property
    def mes(self) -> str:
                """El mes del gasto en formato aaaa-mm, que es como se filtra."""
        return self.fecha.strftime("%Y-%m")

    def __str__(self) -> str:
                return f"[{self.identificador}] {self.fecha} {self.categoria}: {self.concepto} ({self.importe})"


def a_importe(texto: str) -> Decimal:
        """Convierte texto en un importe exacto de dos decimales.

    Acepta la coma decimal española y el símbolo del euro.
    """
    limpio = texto.strip().replace("€", "").replace(" ", "").replace(",", ".")
    try:
                importe = Decimal(limpio)
    except InvalidOperation:
                raise ValueError(f"'{texto}' no es un importe") from None
    if importe <= 0:
                raise ValueError("el importe tiene que ser mayor que cero")
    if importe.as_tuple().exponent < -2:
                raise ValueError("el importe no puede tener más de dos decimales")
    return importe.quantize(CENTIMOS)


def a_fecha(texto: str) -> date:
        """Convierte texto en fecha. Solo admite el formato aaaa-mm-dd."""
    try:
                return date.fromisoformat(texto)
    except ValueError:
                raise ValueError(f"'{texto}' no es una fecha aaaa-mm-dd") from None


def a_mes(texto: str) -> str:
        """Valida un mes en formato aaaa-mm y lo devuelve tal cual."""
    try:
                date.fromisoformat(f"{texto}-01")
    except ValueError:
                raise ValueError(f"'{texto}' no es un mes aaaa-mm") from None
    return texto


def a_categoria(texto: str) -> str:
        """Normaliza la categoría: sin espacios sobrantes y en minúsculas."""
    categoria = texto.strip().lower()
    if not categoria:
                raise ValueError("la categoría no puede estar vacía")
    return categoria

"""Guardar y recuperar los gastos en un CSV. No sabe nada de la pantalla."""

import csv
from decimal import Decimal
from pathlib import Path

from .modelo import CENTIMOS, Gasto, a_fecha, a_importe

CAMPOS = ["identificador", "fecha", "categoria", "concepto", "importe"]


class ErrorDeAlmacen(Exception):
        """El fichero de datos existe pero no se puede usar."""


class Almacen:
        """La lista de gastos en memoria y su fichero CSV en disco."""

    def __init__(self, ruta: Path):
                self.ruta = Path(ruta)
        self.gastos: list[Gasto] = []

    def __len__(self) -> int:
                return len(self.gastos)

    def cargar(self) -> None:
                """Lee el CSV. Si no existe, se empieza con la lista vacía."""
        if not self.ruta.exists():
                        self.gastos = []
            return
        gastos = []
        with open(self.ruta, encoding="utf-8", newline="") as fichero:
                        for numero, fila in enumerate(csv.DictReader(fichero), start=2):
                                try:
                                        gastos.append(Gasto(
                        identificador=int(fila["identificador"]),
                        fecha=a_fecha(fila["fecha"]),
                        categoria=fila["categoria"],
                        concepto=fila["concepto"],
                        importe=a_importe(fila["importe"]),
                    ))
                except (KeyError, TypeError, ValueError) as error:
                                        raise ErrorDeAlmacen(
                        f"{self.ruta}, línea {numero}: {error}"
                    ) from error
        self.gastos = gastos

    def guardar(self) -> None:
                """Escribe el CSV entero, primero en un temporal y luego encima."""
        self.ruta.parent.mkdir(parents=True, exist_ok=True)
        temporal = self.ruta.with_suffix(".csv.tmp")
        with open(temporal, "w", encoding="utf-8", newline="") as fichero:
                        escritor = csv.DictWriter(fichero, fieldnames=CAMPOS)
            escritor.writeheader()
            for gasto in sorted(self.gastos, key=lambda gasto: (gasto.fecha, gasto.identificador)):
                                escritor.writerow({
                    "identificador": gasto.identificador,
                    "fecha": gasto.fecha.isoformat(),
                    "categoria": gasto.categoria,
                    "concepto": gasto.concepto,
                    "importe": f"{gasto.importe:.2f}",
                })
        temporal.replace(self.ruta)

        def siguiente_identificador(self) -> int:
                if not self.gastos:
                        return 1
        return max(gasto.identificador for gasto in self.gastos) + 1

    def anadir(self, fecha, categoria: str, concepto: str, importe: Decimal) -> Gasto:
                concepto = concepto.strip()
        if not concepto:
                        raise ValueError("el concepto no puede estar vacío")
        gasto = Gasto(self.siguiente_identificador(), fecha, categoria, concepto, importe)
        self.gastos.append(gasto)
        return gasto

    def buscar(self, identificador: int) -> Gasto | None:
                for gasto in self.gastos:
                        if gasto.identificador == identificador:
                                return gasto
        return None

    def borrar(self, identificador: int) -> Gasto | None:
                gasto = self.buscar(identificador)
        if gasto is not None:
                        self.gastos.remove(gasto)
        return gasto

    def filtrar(self, mes: str | None = None, categoria: str | None = None) -> list[Gasto]:
                """Devuelve los gastos que cumplen los filtros, ordenados por fecha."""
        seleccion = self.gastos
        if mes is not None:
                        seleccion = [gasto for gasto in seleccion if gasto.mes == mes]
        if categoria is not None:
                        seleccion = [gasto for gasto in seleccion if gasto.categoria == categoria]
        return sorted(seleccion, key=lambda gasto: (gasto.fecha, gasto.identificador))

    def meses(self) -> list[str]:
                return sorted({gasto.mes for gasto in self.gastos})


def total(gastos: list[Gasto]) -> Decimal:
        """Suma exacta de una lista de gastos."""
    return sum((gasto.importe for gasto in gastos), Decimal("0")).quantize(CENTIMOS)

from datetime import date
from pathlib import Path

from gastos.almacen import Almacen, total
from gastos.modelo import a_importe

almacen = Almacen(Path("prueba/demo.csv"))
almacen.cargar()

almacen.anadir(date(2026, 9, 1), "comida", "Menú del día", a_importe("12,50"))
almacen.anadir(date(2026, 9, 3), "comida", "Café y tostada", a_importe("8.20"))
almacen.anadir(date(2026, 8, 28), "ocio", "Cine", a_importe("9"))
almacen.guardar()

print(len(almacen))
print(total(almacen.gastos))
print([gasto.identificador for gasto in almacen.filtrar(mes="2026-09")])
print(almacen.meses())

otro = Almacen(Path("prueba/demo.csv"))
otro.cargar()
print(otro.filtrar() == almacen.filtrar())
print(Path("prueba/demo.csv").read_text(encoding="utf-8"))

"""De dónde salen la moneda y la ruta de los datos."""

import json
import os
from dataclasses import dataclass
from pathlib import Path

RUTA_CONFIGURACION_POR_DEFECTO = Path.home() / ".config" / "gastos" / "configuracion.json"
RUTA_DATOS_POR_DEFECTO = Path.home() / ".local" / "share" / "gastos" / "gastos.csv"


@dataclass
class Configuracion:
        """Los ajustes del programa, ya resueltos."""

    moneda: str = "€"
    datos: Path = RUTA_DATOS_POR_DEFECTO
    ancho_barra: int = 32


def ruta_configuracion() -> Path:
        """La ruta del fichero de ajustes, que GASTOS_CONFIG puede cambiar."""
    variable = os.environ.get("GASTOS_CONFIG")
    if variable:
                return Path(variable).expanduser()
    return RUTA_CONFIGURACION_POR_DEFECTO


def cargar_configuracion() -> Configuracion:
        """Lee el fichero de ajustes si existe y rellena lo que falte por defecto."""
    ruta = ruta_configuracion()
    if not ruta.exists():
                return Configuracion()

    try:
                datos = json.loads(ruta.read_text(encoding="utf-8"))
    except json.JSONDecodeError as error:
                raise ValueError(f"{ruta} no es un JSON válido: {error}") from error
    if not isinstance(datos, dict):
                raise ValueError(f"{ruta} debería contener un objeto JSON")

    configuracion = Configuracion()
    if "moneda" in datos:
                configuracion.moneda = str(datos["moneda"])
    if "datos" in datos:
                configuracion.datos = Path(str(datos["datos"])).expanduser()
    if "ancho_barra" in datos:
                configuracion.ancho_barra = int(datos["ancho_barra"])
    return configuracion

{
  "moneda": "€",
  "datos": "~/Documentos/gastos.csv",
  "ancho_barra": 28
}

"""Los cálculos del resumen: totales por categoría y barras de texto."""

from decimal import Decimal

from .modelo import CENTIMOS, Gasto

# El bloque lleno y los ocho anchos parciales, del más estrecho al lleno.
OCTAVOS = " ▏▎▍▌▋▊▉█"


def totales_por_categoria(gastos: list[Gasto]) -> list[tuple[str, Decimal]]:
        """Suma por categoría, de mayor a menor gasto."""
    acumulado: dict[str, Decimal] = {}
    for gasto in gastos:
                acumulado[gasto.categoria] = acumulado.get(gasto.categoria, Decimal("0")) + gasto.importe
    parejas = [(categoria, suma.quantize(CENTIMOS)) for categoria, suma in acumulado.items()]
    return sorted(parejas, key=lambda par: (-par[1], par[0]))


def barra(valor: Decimal, maximo: Decimal, ancho: int) -> str:
        """Dibuja una barra proporcional con bloques, con resolución de un octavo."""
    if maximo <= 0 or valor <= 0:
                return ""
    octavos = int(valor / maximo * ancho * 8)
    octavos = max(octavos, 1)
    enteros, resto = divmod(octavos, 8)
    return OCTAVOS[8] * enteros + (OCTAVOS[resto] if resto else "")


def porcentaje(valor: Decimal, total: Decimal) -> Decimal:
        """El peso de un importe sobre el total, con un decimal."""
    if total <= 0:
                return Decimal("0.0")
    return (valor / total * 100).quantize(Decimal("0.1"))

from decimal import Decimal

from gastos.informes import barra

maximo = Decimal("62.00")
for valor in ["62.00", "45.90", "20.70", "3.00", "0.40"]:
        print(f"{valor:>6} |{barra(Decimal(valor), maximo, 20)}|")

"""Todo lo que se ve: colores, tablas y gráficos. Aquí sí se imprime."""

import os
import sys
from decimal import Decimal

from .informes import barra, porcentaje, totales_por_categoria
from .modelo import Gasto

NORMAL = "\033[0m"
NEGRITA = "\033[1m"
APAGADO = "\033[2m"
ROJO = "\033[31m"

# Colores que se reparten entre las categorías: cian, verde, amarillo, magenta, azul.
PALETA = ["\033[36m", "\033[32m", "\033[33m", "\033[35m", "\033[34m"]

ANCHO_CONCEPTO = 28
ANCHO_CATEGORIA = 12


def quiere_color(modo: str, flujo=sys.stdout) -> bool:
        """Decide si se pinta en color: por opción, por entorno o por destino."""
    if modo == "nunca":
                return False
    if modo == "siempre":
                return True
    if os.environ.get("NO_COLOR"):
                return False
    return flujo.isatty()


class Pintor:
        """Envuelve texto en códigos ANSI, o no hace nada si el color está apagado."""

    def __init__(self, activo: bool):
                self.activo = activo

    def pinta(self, texto: str, *codigos: str) -> str:
                if not self.activo or not codigos:
                        return texto
        return "".join(codigos) + texto + NORMAL

    def color_de(self, categoria: str) -> str:
                """Un color estable para cada categoría, el mismo en todas las ejecuciones."""
        return PALETA[sum(ord(letra) for letra in categoria) % len(PALETA)]

gastos listar > gastos.txt

def importe_con_moneda(importe: Decimal, moneda: str) -> str:
        return f"{importe:,.2f} {moneda}".replace(",", " ")


def tabla_gastos(gastos: list[Gasto], moneda: str, pintor: Pintor) -> None:
        """Pinta la lista de gastos en columnas alineadas."""
    cabecera = (
        f"{'ID':>4}  {'FECHA':<10}  {'CATEGORÍA':<{ANCHO_CATEGORIA}}  "
        f"{'CONCEPTO':<{ANCHO_CONCEPTO}}  {'IMPORTE':>12}"
    )
    print(pintor.pinta(cabecera, NEGRITA))
    print(pintor.pinta("-" * len(cabecera), APAGADO))

    for gasto in gastos:
                categoria = f"{gasto.categoria[:ANCHO_CATEGORIA]:<{ANCHO_CATEGORIA}}"
        concepto = f"{gasto.concepto[:ANCHO_CONCEPTO]:<{ANCHO_CONCEPTO}}"
        importe = f"{importe_con_moneda(gasto.importe, moneda):>12}"
        print(
            f"{gasto.identificador:>4}  "
            f"{pintor.pinta(gasto.fecha.isoformat(), APAGADO)}  "
            f"{pintor.pinta(categoria, pintor.color_de(gasto.categoria))}  "
            f"{concepto}  "
            f"{pintor.pinta(importe, NEGRITA)}"
        )


def tabla_resumen(gastos: list[Gasto], moneda: str, ancho_barra: int, pintor: Pintor) -> None:
        """Pinta los totales por categoría con su gráfico de barras."""
    totales = totales_por_categoria(gastos)
    suma = sum((importe for _, importe in totales), Decimal("0"))
    mayor = totales[0][1]

    cabecera = f"{'CATEGORÍA':<{ANCHO_CATEGORIA}}  {'IMPORTE':>12}  {'%':>6}  GRÁFICO"
    print(pintor.pinta(cabecera, NEGRITA))
    print(pintor.pinta("-" * (len(cabecera) + ancho_barra - 7), APAGADO))

    for categoria, importe in totales:
                nombre = f"{categoria[:ANCHO_CATEGORIA]:<{ANCHO_CATEGORIA}}"
        peso = f"{porcentaje(importe, suma):>5.1f}%"
        dibujo = barra(importe, mayor, ancho_barra)
        print(
            f"{pintor.pinta(nombre, pintor.color_de(categoria))}  "
            f"{importe_con_moneda(importe, moneda):>12}  {peso}  "
            f"{pintor.pinta(dibujo, pintor.color_de(categoria))}"
        )

    print(pintor.pinta("-" * (len(cabecera) + ancho_barra - 7), APAGADO))
    total = f"{'TOTAL':<{ANCHO_CATEGORIA}}  {importe_con_moneda(suma, moneda):>12}"
    print(pintor.pinta(total, NEGRITA))


def aviso(mensaje: str, pintor: Pintor) -> None:
        """Un mensaje de error por stderr, en rojo si hay color."""
    print(pintor.pinta(f"gastos: {mensaje}", ROJO), file=sys.stderr)

def validador(conversor):
        """Convierte una función de modelo.py en un type= de argparse."""
    def convertir(texto: str):
                try:
                        return conversor(texto)
        except ValueError as error:
                        raise argparse.ArgumentTypeError(str(error)) from None
    convertir.__name__ = conversor.__name__
    return convertir

        subcomandos = analizador.add_subparsers(dest="subcomando", metavar="SUBCOMANDO")
    subcomandos.required = True

    anadir = subcomandos.add_parser(
        "añadir", aliases=["anadir"], help="apunta un gasto nuevo",
        description="Apunta un gasto nuevo.",
    )
    anadir.add_argument("importe", type=validador(a_importe), help="cuánto, por ejemplo 12,50")
    anadir.add_argument("categoria", type=validador(a_categoria), help="comida, transporte, ocio...")
    anadir.add_argument("concepto", help="descripción corta, entre comillas si lleva espacios")
    anadir.add_argument(
        "-f", "--fecha",
        type=validador(a_fecha),
        default=date.today(),
        help="fecha aaaa-mm-dd (por defecto: hoy)",
    )
    anadir.set_defaults(funcion=accion_anadir)

python3 -m gastos --help

@dataclass
class Contexto:
        """Lo que necesita cualquier acción para hacer su trabajo."""

    almacen: Almacen
    configuracion: Configuracion
    pintor: Pintor
    pintor_error: Pintor


def accion_anadir(opciones, contexto: Contexto) -> int:
        try:
                gasto = contexto.almacen.anadir(
            opciones.fecha, opciones.categoria, opciones.concepto, opciones.importe
        )
    except ValueError as error:
                aviso(str(error), contexto.pintor_error)
        return 1
    contexto.almacen.guardar()
    moneda = contexto.configuracion.moneda
    print(
        f"Apuntado [{gasto.identificador}] "
        f"{importe_con_moneda(gasto.importe, moneda)} en {gasto.categoria} el {gasto.fecha}."
    )
    return 0


def accion_borrar(opciones, contexto: Contexto) -> int:
        gasto = contexto.almacen.buscar(opciones.identificador)
    if gasto is None:
                aviso(f"no hay ningún gasto con el identificador {opciones.identificador}.", contexto.pintor_error)
        return 1

    if not opciones.si:
                if not sys.stdin.isatty():
                        aviso("no puedo preguntar sin terminal; repite con --si.", contexto.pintor_error)
            return 1
        moneda = contexto.configuracion.moneda
        print(f"Vas a borrar [{gasto.identificador}] {gasto.concepto}, "
              f"{importe_con_moneda(gasto.importe, moneda)} del {gasto.fecha}.")
        try:
                        respuesta = input("¿Seguro? [s/N]: ").strip().lower()
        except EOFError:
                        respuesta = ""
            print()
        if respuesta not in {"s", "si", "sí"}:
                        print("Cancelado. No se ha borrado nada.")
            return 1

    contexto.almacen.borrar(opciones.identificador)
    contexto.almacen.guardar()
    print(f"Borrado el gasto {opciones.identificador}.")
    return 0

def accion_listar(opciones, contexto: Contexto) -> int:
        gastos = contexto.almacen.filtrar(opciones.mes, opciones.categoria)
    if not gastos:
                print("No hay gastos que cumplan esos filtros.")
        return 0
    tabla_gastos(gastos, contexto.configuracion.moneda, contexto.pintor)
    suma = importe_con_moneda(total(gastos), contexto.configuracion.moneda)
    etiqueta = "gasto" if len(gastos) == 1 else "gastos"
    print(f"\n{len(gastos)} {etiqueta}, {suma} en total.")
    return 0


def accion_resumen(opciones, contexto: Contexto) -> int:
        gastos = contexto.almacen.filtrar(opciones.mes)
    if not gastos:
                print("No hay gastos que resumir.")
        return 0
    titulo = f"Resumen de {opciones.mes}" if opciones.mes else "Resumen de todo"
    print(f"{titulo}\n")
    tabla_resumen(
        gastos,
        contexto.configuracion.moneda,
        contexto.configuracion.ancho_barra,
        contexto.pintor,
    )
    return 0


def accion_exportar(opciones, contexto: Contexto) -> int:
        gastos = contexto.almacen.filtrar(opciones.mes)
    datos = [
        {
            "identificador": gasto.identificador,
            "fecha": gasto.fecha.isoformat(),
            "categoria": gasto.categoria,
            "concepto": gasto.concepto,
            "importe": f"{gasto.importe:.2f}",
        }
        for gasto in gastos
    ]
    texto = json.dumps(datos, indent=2, ensure_ascii=False)

    if str(opciones.fichero) == "-":
                print(texto)
        return 0
    try:
                opciones.fichero.write_text(texto + "\n", encoding="utf-8")
    except OSError as error:
                aviso(f"no he podido escribir en {opciones.fichero}: {error}", contexto.pintor_error)
        return 1
    print(f"Exportados {len(datos)} gastos a {opciones.fichero}.")
    return 0

gastos exportar - --mes 2026-09 | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d), 'gastos')"

def main(argumentos: list[str] | None = None) -> int:
        opciones = construir_analizador().parse_args(argumentos)

    pintor = Pintor(quiere_color(opciones.color, sys.stdout))
    pintor_error = Pintor(quiere_color(opciones.color, sys.stderr))

    try:
                configuracion = cargar_configuracion()
    except ValueError as error:
                aviso(str(error), pintor_error)
        return 1
    if opciones.datos is not None:
                configuracion.datos = opciones.datos

    almacen = Almacen(configuracion.datos)
    try:
                almacen.cargar()
    except (ErrorDeAlmacen, OSError) as error:
                aviso(str(error), pintor_error)
        return 1

    contexto = Contexto(almacen, configuracion, pintor, pintor_error)
    return opciones.funcion(opciones, contexto)


def ejecutar() -> int:
        """Punto de entrada del comando instalado. Aquí muere el Ctrl+C."""
    try:
                return main()
    except KeyboardInterrupt:
                print("\nCancelado.", file=sys.stderr)
        return 130

"""La interfaz de terminal: argumentos, subcomandos y códigos de salida."""

import argparse
import json
import sys
from dataclasses import dataclass
from datetime import date
from pathlib import Path

from .almacen import Almacen, ErrorDeAlmacen, total
from .configuracion import Configuracion, cargar_configuracion
from .modelo import a_categoria, a_fecha, a_importe, a_mes
from .presentacion import (
    Pintor,
    aviso,
    importe_con_moneda,
    quiere_color,
    tabla_gastos,
    tabla_resumen,
)


@dataclass
class Contexto:
        """Lo que necesita cualquier acción para hacer su trabajo."""

    almacen: Almacen
    configuracion: Configuracion
    pintor: Pintor
    pintor_error: Pintor


def validador(conversor):
        """Convierte una función de modelo.py en un type= de argparse."""
    def convertir(texto: str):
                try:
                        return conversor(texto)
        except ValueError as error:
                        raise argparse.ArgumentTypeError(str(error)) from None
    convertir.__name__ = conversor.__name__
    return convertir


def construir_analizador() -> argparse.ArgumentParser:
        analizador = argparse.ArgumentParser(
        prog="gastos",
        description="Lleva la cuenta de tus gastos desde la terminal.",
    )
    analizador.add_argument(
        "--datos",
        type=Path,
        metavar="FICHERO",
        help="usa este CSV en vez del de la configuración",
    )
    analizador.add_argument(
        "--color",
        choices=["auto", "siempre", "nunca"],
        default="auto",
        help="cuándo usar color (por defecto: auto)",
    )

    subcomandos = analizador.add_subparsers(dest="subcomando", metavar="SUBCOMANDO")
    subcomandos.required = True

    anadir = subcomandos.add_parser(
        "añadir", aliases=["anadir"], help="apunta un gasto nuevo",
        description="Apunta un gasto nuevo.",
    )
    anadir.add_argument("importe", type=validador(a_importe), help="cuánto, por ejemplo 12,50")
    anadir.add_argument("categoria", type=validador(a_categoria), help="comida, transporte, ocio...")
    anadir.add_argument("concepto", help="descripción corta, entre comillas si lleva espacios")
    anadir.add_argument(
        "-f", "--fecha",
        type=validador(a_fecha),
        default=date.today(),
        help="fecha aaaa-mm-dd (por defecto: hoy)",
    )
    anadir.set_defaults(funcion=accion_anadir)

    listar = subcomandos.add_parser(
        "listar", help="enseña los gastos apuntados",
        description="Enseña los gastos, con filtros opcionales.",
    )
    listar.add_argument("-m", "--mes", type=validador(a_mes), help="solo los de este mes, aaaa-mm")
    listar.add_argument("-c", "--categoria", type=validador(a_categoria), help="solo los de esta categoría")
    listar.set_defaults(funcion=accion_listar)

    resumen = subcomandos.add_parser(
        "resumen", help="totales por categoría con gráfico de barras",
        description="Totales por categoría con gráfico de barras.",
    )
    resumen.add_argument("-m", "--mes", type=validador(a_mes), help="solo los de este mes, aaaa-mm")
    resumen.set_defaults(funcion=accion_resumen)

    borrar = subcomandos.add_parser(
        "borrar", help="elimina un gasto por su identificador",
        description="Elimina un gasto por su identificador.",
    )
    borrar.add_argument("identificador", type=int, help="el número que sale en la columna ID")
    borrar.add_argument("-s", "--si", action="store_true", help="no preguntar antes de borrar")
    borrar.set_defaults(funcion=accion_borrar)

    exportar = subcomandos.add_parser(
        "exportar", help="vuelca los gastos a JSON",
        description="Vuelca los gastos a un fichero JSON, o a la salida estándar con -.",
    )
    exportar.add_argument("fichero", type=Path, help="fichero de destino, o - para la salida estándar")
    exportar.add_argument("-m", "--mes", type=validador(a_mes), help="solo los de este mes, aaaa-mm")
    exportar.set_defaults(funcion=accion_exportar)

    return analizador


def accion_anadir(opciones, contexto: Contexto) -> int:
        try:
                gasto = contexto.almacen.anadir(
            opciones.fecha, opciones.categoria, opciones.concepto, opciones.importe
        )
    except ValueError as error:
                aviso(str(error), contexto.pintor_error)
        return 1
    contexto.almacen.guardar()
    moneda = contexto.configuracion.moneda
    print(
        f"Apuntado [{gasto.identificador}] "
        f"{importe_con_moneda(gasto.importe, moneda)} en {gasto.categoria} el {gasto.fecha}."
    )
    return 0


def accion_listar(opciones, contexto: Contexto) -> int:
        gastos = contexto.almacen.filtrar(opciones.mes, opciones.categoria)
    if not gastos:
                print("No hay gastos que cumplan esos filtros.")
        return 0
    tabla_gastos(gastos, contexto.configuracion.moneda, contexto.pintor)
    suma = importe_con_moneda(total(gastos), contexto.configuracion.moneda)
    etiqueta = "gasto" if len(gastos) == 1 else "gastos"
    print(f"\n{len(gastos)} {etiqueta}, {suma} en total.")
    return 0


def accion_resumen(opciones, contexto: Contexto) -> int:
        gastos = contexto.almacen.filtrar(opciones.mes)
    if not gastos:
                print("No hay gastos que resumir.")
        return 0
    titulo = f"Resumen de {opciones.mes}" if opciones.mes else "Resumen de todo"
    print(f"{titulo}\n")
    tabla_resumen(
        gastos,
        contexto.configuracion.moneda,
        contexto.configuracion.ancho_barra,
        contexto.pintor,
    )
    return 0


def accion_borrar(opciones, contexto: Contexto) -> int:
        gasto = contexto.almacen.buscar(opciones.identificador)
    if gasto is None:
                aviso(f"no hay ningún gasto con el identificador {opciones.identificador}.", contexto.pintor_error)
        return 1

    if not opciones.si:
                if not sys.stdin.isatty():
                        aviso("no puedo preguntar sin terminal; repite con --si.", contexto.pintor_error)
            return 1
        moneda = contexto.configuracion.moneda
        print(f"Vas a borrar [{gasto.identificador}] {gasto.concepto}, "
              f"{importe_con_moneda(gasto.importe, moneda)} del {gasto.fecha}.")
        try:
                        respuesta = input("¿Seguro? [s/N]: ").strip().lower()
        except EOFError:
                        respuesta = ""
            print()
        if respuesta not in {"s", "si", "sí"}:
                        print("Cancelado. No se ha borrado nada.")
            return 1

    contexto.almacen.borrar(opciones.identificador)
    contexto.almacen.guardar()
    print(f"Borrado el gasto {opciones.identificador}.")
    return 0


def accion_exportar(opciones, contexto: Contexto) -> int:
        gastos = contexto.almacen.filtrar(opciones.mes)
    datos = [
        {
            "identificador": gasto.identificador,
            "fecha": gasto.fecha.isoformat(),
            "categoria": gasto.categoria,
            "concepto": gasto.concepto,
            "importe": f"{gasto.importe:.2f}",
        }
        for gasto in gastos
    ]
    texto = json.dumps(datos, indent=2, ensure_ascii=False)

    if str(opciones.fichero) == "-":
                print(texto)
        return 0
    try:
                opciones.fichero.write_text(texto + "\n", encoding="utf-8")
    except OSError as error:
                aviso(f"no he podido escribir en {opciones.fichero}: {error}", contexto.pintor_error)
        return 1
    print(f"Exportados {len(datos)} gastos a {opciones.fichero}.")
    return 0


def main(argumentos: list[str] | None = None) -> int:
        opciones = construir_analizador().parse_args(argumentos)

    pintor = Pintor(quiere_color(opciones.color, sys.stdout))
    pintor_error = Pintor(quiere_color(opciones.color, sys.stderr))

    try:
                configuracion = cargar_configuracion()
    except ValueError as error:
                aviso(str(error), pintor_error)
        return 1
    if opciones.datos is not None:
                configuracion.datos = opciones.datos

    almacen = Almacen(configuracion.datos)
    try:
                almacen.cargar()
    except (ErrorDeAlmacen, OSError) as error:
                aviso(str(error), pintor_error)
        return 1

    contexto = Contexto(almacen, configuracion, pintor, pintor_error)
    return opciones.funcion(opciones, contexto)


def ejecutar() -> int:
        """Punto de entrada del comando instalado. Aquí muere el Ctrl+C."""
    try:
                return main()
    except KeyboardInterrupt:
                print("\nCancelado.", file=sys.stderr)
        return 130


if __name__ == "__main__":
        sys.exit(ejecutar())

"""Permite ejecutar el paquete con python3 -m gastos."""

import sys

from .cli import ejecutar

sys.exit(ejecutar())

[project]
name = "gastos"
version = "1.0.0"
description = "Control de gastos personales desde la terminal"
requires-python = ">=3.11"

[project.scripts]
gastos = "gastos.cli:ejecutar"

[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
gastos resumen --mes 2026-09

gastos añadir 12,50 comida "Menú del día" --fecha 2026-09-01
gastos añadir 45.90 transporte "Abono mensual" -f 2026-09-01
gastos añadir 8,20 comida "Café y tostada" -f 2026-09-03
gastos añadir 62 ocio "Entradas del teatro" -f 2026-09-05
gastos añadir 129.99 hogar "Lámpara del salón" -f 2026-09-08
gastos añadir 3,40 transporte "Billete de metro" -f 2026-09-09
gastos añadir 27,15 comida "Compra semanal" -f 2026-09-12
gastos añadir 19,99 ocio "Suscripción de música" -f 2026-09-15
gastos añadir 54,30 comida "Cena con Marta" -f 2026-08-28

identificador,fecha,categoria,concepto,importe
9,2026-08-28,comida,Cena con Marta,54.30
1,2026-09-01,comida,Menú del día,12.50
2,2026-09-01,transporte,Abono mensual,45.90
3,2026-09-03,comida,Café y tostada,8.20
4,2026-09-05,ocio,Entradas del teatro,62.00
5,2026-09-08,hogar,Lámpara del salón,129.99
6,2026-09-09,transporte,Billete de metro,3.40
7,2026-09-12,comida,Compra semanal,27.15
8,2026-09-15,ocio,Suscripción de música,19.99

gastos listar

gastos listar --mes 2026-09 --categoria comida

gastos resumen --mes 2026-09

gastos borrar 6

gastos borrar 6
echo $?

gastos exportar gastos-septiembre.json --mes 2026-09

[
  {
    "identificador": 1,
    "fecha": "2026-09-01",
    "categoria": "comida",
    "concepto": "Menú del día",
    "importe": "12.50"
  },
  {
    "identificador": 2,
    "fecha": "2026-09-01",
    "categoria": "transporte",
    "concepto": "Abono mensual",
    "importe": "45.90"
  }
]

gastos --datos viaje.csv añadir 340 transporte "Vuelo a Bilbao" -f 2026-09-10
gastos --datos viaje.csv listar

gastos añadir doce comida "Prueba"
echo $?

gastos añadir 5 comida "Prueba" -f 31-12-2026
echo $?

gastos borrar 99 --si
echo $?