acodo 0.3.0__tar.gz

acodo-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 isidro-rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

acodo-0.3.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: acodo
+Version: 0.3.0
+Summary: Utilidades puras del framework Acodo: validación, conversión, parseo y logger.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Project-URL: Changelog, https://github.com/isidro-rodriguez/acodo/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://isidro-rodriguez.github.io/acodo/
+Project-URL: Repository, https://github.com/isidro-rodriguez/acodo
+Description-Content-Type: text/markdown
+
+# acodo
+
+Biblioteca de utilidades de Acodo para **Python >= 3.13**. No tiene
+dependencias externas: solo usa la biblioteca estándar.
+
+> Antes se publicaba como `acodo-framework`; ese nombre queda obsoleto.
+
+## 🚀 Instalación
+
+Desde [PyPI](https://pypi.org/project/acodo/):
+
+```bash
+uv add acodo
+```
+
+## 🛠️ Uso
+
+```python
+from acodo.logger import Logger
+from acodo.utils import to_bool, valid_email
+
+to_bool("sí")  # True
+valid_email("hola")  # False
+
+log = Logger("miapp")
+log.info("Procesando %(n)s ficheros", n=3)
+```
+
+## 📦 Módulos
+
+- `acodo.utils`: funciones agrupadas por prefijo (`get_*`, `has_*`, `parse_*`,
+  `to_*`, `valid_*`) y el tipo `SocialLink`. Convenciones y errores en el docstring
+  del paquete.
+- `acodo.logger`: `Logger`; consola y/o fichero con rotación diaria.
+
+`acodo.logger` depende de `acodo.utils`, nunca al revés.
+
+## 📁 Estructura
+
+```bash
+src/acodo/
+├── utils/
+│   ├── checkers.py       # has_*
+│   ├── converters.py     # to_*
+│   ├── getters.py        # get_*
+│   ├── parsers.py        # parse_*
+│   ├── types.py          # SocialLink
+│   └── validators.py     # valid_*
+└── logger/
+    └── logger.py         # Logger
+```
+
+## 🧪 Desarrollo
+
+```bash
+uv sync
+uv run ruff format .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
+
+Los hooks de `pre-commit` cubren formato, lint, tipos y tests; la etapa `pre-push` añade
+cobertura y la construcción de la documentación, que vive en `docs/` y se genera con
+[Zensical](https://zensical.org) (`uv run zensical serve` / `uv run zensical build`).
+
+## Enlaces
+
+- Repositorio: <https://github.com/isidro-rodriguez/acodo>
+- Documentación: <https://isidro-rodriguez.github.io/acodo/>
+- PyPI: <https://pypi.org/project/acodo/>
+- Plantilla de proyecto: <https://github.com/isidro-rodriguez/acodo-template>
+
+## Licencia
+
+[MIT](https://github.com/isidro-rodriguez/acodo/blob/main/LICENSE).

acodo-0.3.0/README.md

@@ -0,0 +1,76 @@
+# acodo
+
+Biblioteca de utilidades de Acodo para **Python >= 3.13**. No tiene
+dependencias externas: solo usa la biblioteca estándar.
+
+> Antes se publicaba como `acodo-framework`; ese nombre queda obsoleto.
+
+## 🚀 Instalación
+
+Desde [PyPI](https://pypi.org/project/acodo/):
+
+```bash
+uv add acodo
+```
+
+## 🛠️ Uso
+
+```python
+from acodo.logger import Logger
+from acodo.utils import to_bool, valid_email
+
+to_bool("sí")  # True
+valid_email("hola")  # False
+
+log = Logger("miapp")
+log.info("Procesando %(n)s ficheros", n=3)
+```
+
+## 📦 Módulos
+
+- `acodo.utils`: funciones agrupadas por prefijo (`get_*`, `has_*`, `parse_*`,
+  `to_*`, `valid_*`) y el tipo `SocialLink`. Convenciones y errores en el docstring
+  del paquete.
+- `acodo.logger`: `Logger`; consola y/o fichero con rotación diaria.
+
+`acodo.logger` depende de `acodo.utils`, nunca al revés.
+
+## 📁 Estructura
+
+```bash
+src/acodo/
+├── utils/
+│   ├── checkers.py       # has_*
+│   ├── converters.py     # to_*
+│   ├── getters.py        # get_*
+│   ├── parsers.py        # parse_*
+│   ├── types.py          # SocialLink
+│   └── validators.py     # valid_*
+└── logger/
+    └── logger.py         # Logger
+```
+
+## 🧪 Desarrollo
+
+```bash
+uv sync
+uv run ruff format .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
+
+Los hooks de `pre-commit` cubren formato, lint, tipos y tests; la etapa `pre-push` añade
+cobertura y la construcción de la documentación, que vive en `docs/` y se genera con
+[Zensical](https://zensical.org) (`uv run zensical serve` / `uv run zensical build`).
+
+## Enlaces
+
+- Repositorio: <https://github.com/isidro-rodriguez/acodo>
+- Documentación: <https://isidro-rodriguez.github.io/acodo/>
+- PyPI: <https://pypi.org/project/acodo/>
+- Plantilla de proyecto: <https://github.com/isidro-rodriguez/acodo-template>
+
+## Licencia
+
+[MIT](https://github.com/isidro-rodriguez/acodo/blob/main/LICENSE).

acodo-0.3.0/pyproject.toml

@@ -0,0 +1,121 @@
+[project]
+name = "acodo"
+version = "0.3.0"
+description = "Utilidades puras del framework Acodo: validación, conversión, parseo y logger."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Changelog = "https://github.com/isidro-rodriguez/acodo/blob/main/CHANGELOG.md"
+Documentation = "https://isidro-rodriguez.github.io/acodo/"
+Repository = "https://github.com/isidro-rodriguez/acodo"
+
+[dependency-groups]
+dev = [
+    "mkdocstrings-python>=2.0.9",
+    "pre-commit>=4.7.0",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.17.1",
+    "ty>=0.0.89",
+    "zensical>=0.0.71",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+omit = [
+    "*/tests/*",
+    "*/__init__.py",
+]
+
+[tool.coverage.report]
+exclude_also = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]
+
+[tool.pytest.ini_options]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--import-mode=importlib",
+    "--doctest-modules",
+]
+markers = [
+    """slow: marks tests as slow (deselect with '-m "not slow"')""",
+    "integration: marks tests as integration tests",
+]
+python_classes = ["Test*"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+testpaths = [
+    "src",
+    "tests",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "N",
+    "UP",
+    "B",
+    "SIM",
+    "C4",
+    "PERF",
+    "PTH",
+    "RUF",
+    "D",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = ["acodo"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+
+[tool.ty.environment]
+python-version = "3.13"
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+]
+
+[tool.ty.analysis]
+strict-equality-semantics = true
+strict-generic-narrowing = true
+
+[tool.ty.rules]
+possibly-unresolved-reference = "error"
+unused-ignore-comment = "warn"
+
+[tool.uv.build-backend]
+module-name = "acodo"

acodo-0.3.0/pyproject.toml.orig

@@ -0,0 +1,103 @@
+# pyproject.toml
+[project]
+name = "acodo"
+version = "0.3.0"
+description = "Utilidades puras del framework Acodo: validación, conversión, parseo y logger."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+
+# Sin dependencias en tiempo de ejecución: solo biblioteca estándar.
+dependencies = []
+
+[project.urls]
+Changelog = "https://github.com/isidro-rodriguez/acodo/blob/main/CHANGELOG.md"
+Documentation = "https://isidro-rodriguez.github.io/acodo/"
+Repository = "https://github.com/isidro-rodriguez/acodo"
+
+[dependency-groups]
+dev = [
+  "mkdocstrings-python>=2.0.9",
+  "pre-commit>=4.7.0",
+  "pytest>=9.1.1",
+  "pytest-cov>=7.1.0",
+  "ruff>=0.17.1",
+  "ty>=0.0.89",
+  "zensical>=0.0.71",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+# --- Cobertura (pytest-cov) --------------------------------------------------
+[tool.coverage.run]
+source = ["src"]
+branch = true
+omit = [
+  "*/tests/*",
+  "*/__init__.py",
+]
+
+[tool.coverage.report]
+exclude_also = [
+  "pragma: no cover",
+  "if TYPE_CHECKING:",
+  "if __name__ == .__main__.:",
+]
+
+# --- pytest ------------------------------------------------------------------
+[tool.pytest.ini_options]
+addopts = ["-ra", "--strict-markers", "--import-mode=importlib", "--doctest-modules"]
+markers = [
+  "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+  "integration: marks tests as integration tests",
+]
+python_classes = ["Test*"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+testpaths = ["src", "tests"]
+
+# --- Ruff: formato y linting -------------------------------------------------
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "C4", "PERF", "PTH", "RUF", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = ["acodo"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D"]
+
+# --- ty: comprobación de tipos de Astral -------------------------------------
+[tool.ty.environment]
+python-version = "3.13"
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.ty.analysis]
+strict-equality-semantics = true
+strict-generic-narrowing = true
+
+[tool.ty.rules]
+possibly-unresolved-reference = "error"
+unused-ignore-comment = "warn"
+
+[tool.uv.build-backend]
+module-name = "acodo"

acodo-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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")