acodo 0.3.0__py3-none-any.whl

acodo/__init__.py

@@ -0,0 +1,11 @@
+"""Acodo Framework: utilidades puras en Python, sin dependencias externas.
+
+Subpaquetes:
+
+- `acodo.utils`: validación, conversión, parseo, formateo y obtención de valores.
+- `acodo.logger`: logger con destino configurable (consola y/o fichero).
+"""
+
+from importlib.metadata import version
+
+__version__ = version("acodo")

acodo/logger/__init__.py

@@ -0,0 +1,13 @@
+"""Logger de Acodo: salida configurable a consola y fichero con rotación diaria.
+
+Uso:
+
+```python
+from acodo.logger import Logger
+
+log = Logger("miapp")
+log.info("Procesando %(n)s ficheros", n=3)
+```
+"""
+
+from .logger import Logger as Logger

acodo/logger/logger.py

@@ -0,0 +1,249 @@
+"""Logger con destino configurable (consola y/o fichero) sobre ``logging``.
+
+Ofrece `Logger`, un wrapper que permite decidir en cada mensaje si se muestra
+por consola, se escribe en el fichero de log o ambos. Se configura una sola vez
+por nombre y no toca el logger raíz.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import pprint
+import sys
+from logging.handlers import TimedRotatingFileHandler
+from typing import TYPE_CHECKING, Any
+
+from acodo.utils.validators import valid_filename
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+
+_RESET = "\u001b[0m"
+
+_LEVEL_COLORS = {
+    logging.DEBUG: "\u001b[30;1m",
+    logging.INFO: "\u001b[34;1m",
+    logging.WARNING: "\u001b[33;1m",
+    logging.ERROR: "\u001b[31;1m",
+}
+
+
+def _prettify(value: Any) -> str:
+    """Convierte un valor en una representación legible de varias líneas.
+
+    Args:
+        value: Valor a formatear.
+
+    Returns:
+        Cadena formateada con ``pprint`` para contenedores o ``str`` para el
+        resto.
+    """
+    if isinstance(value, (dict, list, tuple, set)):
+        return pprint.pformat(value, indent=4, width=120)
+    return str(value)
+
+
+class _DestinationFilter(logging.Filter):
+    """Filtra registros según el destino solicitado (consola o fichero)."""
+
+    def __init__(self, key: str) -> None:
+        super().__init__()
+        self._key = key
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        # Un registro sin la marca (emitido directamente con `logging`) se
+        # deja pasar a todos los destinos.
+        return bool(getattr(record, self._key, True))
+
+
+class _ConsoleFormatter(logging.Formatter):
+    """Antepone `[NIVEL]` al mensaje, con color solo si la salida es un terminal."""
+
+    def __init__(self, *, color: bool) -> None:
+        super().__init__("%(message)s")
+        self._color = color
+
+    def format(self, record: logging.LogRecord) -> str:
+        tag = f"[{record.levelname}]"
+        if self._color and record.levelno in _LEVEL_COLORS:
+            tag = f"{_LEVEL_COLORS[record.levelno]}{tag}{_RESET}"
+        return f"{tag} {super().format(record)}"
+
+
+class Logger:
+    """Wrapper sobre ``logging`` que permite elegir el destino de cada mensaje.
+
+    Los valores con nombre se interpolan con ``%(nombre)s``; un ``%`` literal en
+    ``msg`` debe escribirse ``%%`` cuando se pasan valores.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        file: Path | None = None,
+        debug: bool = False,
+    ) -> None:
+        """Crea el logger `name`, o reutiliza el ya configurado con ese nombre.
+
+        La configuración es idempotente por nombre: solo se realiza la primera vez.
+        En llamadas posteriores con el mismo nombre se reutiliza el logger ya
+        configurado y se ignoran `debug` y `file`. No se modifica el logger raíz.
+
+        Args:
+            name: Nombre del logger.
+            file: Ruta del fichero de log, con rotación diaria y 7 copias. Si es
+                `None`, solo se escribe por consola. Se crean los directorios que
+                falten.
+            debug: Si `True`, activa el nivel `DEBUG` (por defecto, `INFO`).
+
+        Raises:
+            ValueError: Si `name` está vacío o `file` no tiene un nombre de
+                fichero válido.
+
+        Examples:
+            >>> log = Logger("ejemplo")
+            >>> log.info("Procesando %(n)s ficheros", n=3)
+            [INFO] Procesando 3 ficheros
+        """
+        if not name.strip():
+            raise ValueError("El nombre del logger no puede estar vacío.")
+        if file is not None and not valid_filename(file.name):
+            raise ValueError(f"Nombre de fichero de log no válido: {file.name!r}.")
+
+        self._logger = logging.getLogger(name)
+        if not self._logger.handlers:
+            self._configure(file=file, debug=debug)
+
+    def error(
+        self,
+        msg: str,
+        exc_info: bool = False,
+        console: bool = True,
+        file: bool = True,
+        **kwargs: object,
+    ) -> None:
+        """Registra un mensaje de nivel error.
+
+        Args:
+            msg: Mensaje a registrar.
+            exc_info: Si `True`, añade la traza de la excepción activa.
+            console: Si `True`, se muestra por consola.
+            file: Si `True`, se escribe en el fichero de log.
+            **kwargs: Valores para interpolar en `msg` con `%(nombre)s`.
+        """
+        self._log(logging.ERROR, msg, console, file, kwargs, exc_info=exc_info)
+
+    def warning(
+        self,
+        msg: str,
+        console: bool = True,
+        file: bool = True,
+        **kwargs: object,
+    ) -> None:
+        """Registra un mensaje de nivel aviso.
+
+        Args:
+            msg: Mensaje a registrar.
+            console: Si `True`, se muestra por consola.
+            file: Si `True`, se escribe en el fichero de log.
+            **kwargs: Valores para interpolar en `msg` con `%(nombre)s`.
+        """
+        self._log(logging.WARNING, msg, console, file, kwargs)
+
+    def info(
+        self,
+        msg: str,
+        console: bool = True,
+        file: bool = True,
+        **kwargs: object,
+    ) -> None:
+        """Registra un mensaje de nivel información.
+
+        Args:
+            msg: Mensaje a registrar.
+            console: Si `True`, se muestra por consola.
+            file: Si `True`, se escribe en el fichero de log.
+            **kwargs: Valores para interpolar en `msg` con `%(nombre)s`.
+        """
+        self._log(logging.INFO, msg, console, file, kwargs)
+
+    def debug(
+        self,
+        msg: str,
+        console: bool = True,
+        file: bool = True,
+        **kwargs: object,
+    ) -> None:
+        """Registra un mensaje de nivel depuración.
+
+        Los contenedores (`dict`, `list`, `tuple`, `set`) pasados como valores
+        se formatean en varias líneas para facilitar su lectura.
+
+        Args:
+            msg: Mensaje a registrar.
+            console: Si `True`, se muestra por consola.
+            file: Si `True`, se escribe en el fichero de log.
+            **kwargs: Valores para interpolar en `msg` con `%(nombre)s`.
+        """
+        values = {name: _prettify(value) for name, value in kwargs.items()}
+        self._log(logging.DEBUG, msg, console, file, values)
+
+    def _configure(self, *, file: Path | None, debug: bool) -> None:
+        # Nivel, handler de consola y, si se pide, handler de fichero rotativo.
+        self._logger.setLevel(logging.DEBUG if debug else logging.INFO)
+        self._logger.propagate = False
+
+        color = sys.stdout.isatty() and "NO_COLOR" not in os.environ
+        console_handler = logging.StreamHandler(sys.stdout)
+        console_handler.setFormatter(_ConsoleFormatter(color=color))
+        console_handler.addFilter(_DestinationFilter("to_console"))
+        self._logger.addHandler(console_handler)
+
+        if file is not None:
+            file.parent.mkdir(parents=True, exist_ok=True)
+            file_handler = TimedRotatingFileHandler(
+                filename=file,
+                when="midnight",
+                backupCount=7,
+                encoding="utf-8",
+            )
+            file_handler.suffix = "%Y-%m-%d"
+            file_handler.setFormatter(
+                logging.Formatter(
+                    fmt="%(asctime)s %(levelname)-10s %(message)s",
+                    datefmt="%Y-%m-%d %H:%M:%S",
+                )
+            )
+            file_handler.addFilter(_DestinationFilter("to_file"))
+            self._logger.addHandler(file_handler)
+
+    def _log(
+        self,
+        level: int,
+        msg: str,
+        console: bool,
+        file: bool,
+        values: Mapping[str, object],
+        *,
+        exc_info: bool = False,
+    ) -> None:
+        # `logging` interpola de forma perezosa: solo si el nivel está activo.
+        # `stacklevel=3` apunta al código que llamó a `info`, `error`...
+        self._logger.log(
+            level,
+            msg,
+            *([values] if values else []),
+            exc_info=exc_info,
+            extra={"to_console": console, "to_file": file},
+            stacklevel=3,
+        )
+
+
+if __name__ == "__main__":
+    log = Logger(name="test")
+    log.info("Información")
+    log.error("Errores")

acodo/utils/__init__.py

@@ -0,0 +1,263 @@
+r"""Módulo de funciones utilitarias que pueden reutilizarse en cualquier aplicación.
+
+Requiere **Python >= 3.13** y no introduce dependencias.
+
+
+Uso rápido
+----------
+
+Forma parte de `acodo` y se importa desde `acodo.utils`:
+
+```python
+from acodo.utils import get_hash, has_required_attrs, parse_slug, to_bytes, valid_email
+
+get_hash("abc")  # ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
+has_required_attrs("texto", ["upper", "lower"])  # True
+parse_slug("¡Hola, Mundo! Ñandú")  # hola-mundo-nandu
+to_bytes("1,5 GiB")  # 1610612736
+valid_email("email_sin_punto@ejemplo-com")  # False
+```
+
+
+Tipos
+-----
+
+`SocialLink` (definida en `acodo.utils.types`) enumera los tipos de enlace de
+red social que reconoce `valid_social_url`.
+
+
+Convenio de nombrado
+--------------------
+Las funciones se agrupan por categoría, cada categoría empieza por un
+prefijo y dentro de cada una van en orden alfabético.
+
+| Prefijo   | Returns       | Categoría |
+|-----------|---------------|-----------|
+| `get_*`   | `Any`         | Obtenedores de valores del entorno, credencial, ID, ... |
+| `has_*`   | `bool`        | Comprobación de presencia de claves, campos o estructura. |
+| `parse_*` | `str`         | Formateado a texto legible (importes, fechas, tamaños, ...). |
+| `to_*`    | `Any \| None` | Conversión de tipo o `None` si no puede. |
+| `valid_*` | `bool`        | Validación de formato o de dominio de un valor. |
+
+
+Errores lanzados
+----------------
+
+Solo se lanza `ValueError` ante argumentos ambiguos o inválidos:
+
+- `get_*` (algoritmo, rango, longitud...)
+- `parse_*` (`lang`),
+- `valid_ip` (`version`)
+- `valid_password`.
+
+
+Enlaces de interés
+------------------
+- [Documentación de Python](https://docs.python.org/3/)
+- [PEP 8: guía de estilo](https://peps.python.org/pep-0008/)
+- [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
+  (estilo de los docstrings)
+- Herramientas de Astral: [uv](https://docs.astral.sh/uv/),
+  [Ruff](https://docs.astral.sh/ruff/) y [ty](https://docs.astral.sh/ty/)
+- [pytest](https://docs.pytest.org/)
+"""  # noqa: E501
+
+from .checkers import (
+    has_required_attrs as has_required_attrs,
+)
+from .checkers import (
+    has_required_fields as has_required_fields,
+)
+from .checkers import (
+    has_required_keys as has_required_keys,
+)
+from .converters import (
+    to_bool as to_bool,
+)
+from .converters import (
+    to_bytes as to_bytes,
+)
+from .converters import (
+    to_date as to_date,
+)
+from .converters import (
+    to_datetime as to_datetime,
+)
+from .converters import (
+    to_decimal as to_decimal,
+)
+from .converters import (
+    to_dict as to_dict,
+)
+from .converters import (
+    to_float as to_float,
+)
+from .converters import (
+    to_int as to_int,
+)
+from .converters import (
+    to_json as to_json,
+)
+from .converters import (
+    to_list as to_list,
+)
+from .converters import (
+    to_path as to_path,
+)
+from .converters import (
+    to_port as to_port,
+)
+from .converters import (
+    to_str as to_str,
+)
+from .converters import (
+    to_timedelta as to_timedelta,
+)
+from .getters import (
+    get_config_dir as get_config_dir,
+)
+from .getters import (
+    get_env as get_env,
+)
+from .getters import (
+    get_file_hash as get_file_hash,
+)
+from .getters import (
+    get_hash as get_hash,
+)
+from .getters import (
+    get_hmac as get_hmac,
+)
+from .getters import (
+    get_now as get_now,
+)
+from .getters import (
+    get_otp as get_otp,
+)
+from .getters import (
+    get_password_hash as get_password_hash,
+)
+from .getters import (
+    get_random_choice as get_random_choice,
+)
+from .getters import (
+    get_random_int as get_random_int,
+)
+from .getters import (
+    get_random_password as get_random_password,
+)
+from .getters import (
+    get_random_token as get_random_token,
+)
+from .getters import (
+    get_uuid as get_uuid,
+)
+from .parsers import (
+    parse_amount as parse_amount,
+)
+from .parsers import (
+    parse_bool as parse_bool,
+)
+from .parsers import (
+    parse_datetime as parse_datetime,
+)
+from .parsers import (
+    parse_percent as parse_percent,
+)
+from .parsers import (
+    parse_size as parse_size,
+)
+from .parsers import (
+    parse_slug as parse_slug,
+)
+from .parsers import (
+    parse_timedelta as parse_timedelta,
+)
+from .types import SocialLink as SocialLink
+from .validators import (
+    valid_bic as valid_bic,
+)
+from .validators import (
+    valid_bool as valid_bool,
+)
+from .validators import (
+    valid_cif as valid_cif,
+)
+from .validators import (
+    valid_date as valid_date,
+)
+from .validators import (
+    valid_datetime as valid_datetime,
+)
+from .validators import (
+    valid_dni as valid_dni,
+)
+from .validators import (
+    valid_domain as valid_domain,
+)
+from .validators import (
+    valid_duration as valid_duration,
+)
+from .validators import (
+    valid_email as valid_email,
+)
+from .validators import (
+    valid_filename as valid_filename,
+)
+from .validators import (
+    valid_hex_color as valid_hex_color,
+)
+from .validators import (
+    valid_iban as valid_iban,
+)
+from .validators import (
+    valid_ip as valid_ip,
+)
+from .validators import (
+    valid_json as valid_json,
+)
+from .validators import (
+    valid_mac as valid_mac,
+)
+from .validators import (
+    valid_nie as valid_nie,
+)
+from .validators import (
+    valid_nif as valid_nif,
+)
+from .validators import (
+    valid_passport as valid_passport,
+)
+from .validators import (
+    valid_password as valid_password,
+)
+from .validators import (
+    valid_phone as valid_phone,
+)
+from .validators import (
+    valid_port as valid_port,
+)
+from .validators import (
+    valid_postal_code as valid_postal_code,
+)
+from .validators import (
+    valid_slug as valid_slug,
+)
+from .validators import (
+    valid_social_url as valid_social_url,
+)
+from .validators import (
+    valid_url as valid_url,
+)
+from .validators import (
+    valid_uuid as valid_uuid,
+)
+
+__all__ = [
+    "checkers",
+    "converters",
+    "getters",
+    "parsers",
+    "types",
+    "validators",
+]

acodo/utils/checkers.py

@@ -0,0 +1,80 @@
+"""Comprobaciones: verifican que los objetos cumplan los requisitos.
+
+Las funciones `has_*` devuelven `bool`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Collection, Hashable, Iterable, Mapping
+    from typing import Any
+
+
+# =============================================================================
+#  Comprobaciones
+# =============================================================================
+
+
+def has_required_attrs(raw: object, required_attrs: Iterable[str]) -> bool:
+    """Comprueba que el objeto tiene todos los atributos requeridos.
+
+    Args:
+        raw: Objeto a verificar.
+        required_attrs: Nombres de los atributos requeridos.
+
+    Returns:
+        `True` si el objeto tiene todos los atributos requeridos.
+
+    Examples:
+        >>> has_required_attrs("texto", ["upper", "lower"])
+        True
+        >>> has_required_attrs("texto", ["append"])
+        False
+    """
+    return all(hasattr(raw, attr) for attr in required_attrs)
+
+
+def has_required_fields(
+    raw: Collection[Any],
+    required_fields: Iterable[Any],
+) -> bool:
+    """Comprueba que la colección tiene todos los campos requeridos.
+
+    Args:
+        raw: Colección a verificar.
+        required_fields: Campos requeridos.
+
+    Returns:
+        `True` si la colección tiene todos los campos requeridos.
+
+    Examples:
+        >>> has_required_fields(["a", "b", "c"], ["a", "c"])
+        True
+        >>> has_required_fields({"a", "b"}, ["a", "z"])
+        False
+    """
+    return all(field in raw for field in required_fields)
+
+
+def has_required_keys(
+    raw: Mapping[Hashable, Any],
+    required_keys: Iterable[Hashable],
+) -> bool:
+    """Comprueba que el diccionario tiene todas las llaves requeridas.
+
+    Args:
+        raw: Diccionario a verificar.
+        required_keys: Llaves requeridas.
+
+    Returns:
+        `True` si el diccionario tiene todas las llaves requeridas.
+
+    Examples:
+        >>> has_required_keys({"name": "Ana", "age": 30}, ["name"])
+        True
+        >>> has_required_keys({"name": "Ana"}, ["name", "age"])
+        False
+    """
+    return all(key in raw for key in required_keys)