turnero 0.1.0__tar.gz

turnero-0.1.0/.github/workflows/pruebas.yml

@@ -0,0 +1,50 @@
+# Las pruebas en cada push y en cada pull request.
+#
+# En un repositorio PÚBLICO los minutos de GitHub Actions con los
+# runners estándar son gratis e ilimitados. Por eso este fichero no
+# cuesta dinero y el repositorio es público a propósito.
+#
+# POR QUÉ 3.9 CORRE EN OTRA MÁQUINA QUE LAS DEMÁS
+# -----------------------------------------------
+# La primera ejecución, el 2 de noviembre de 2026, salió roja. No por
+# el código: 3.11 y 3.13 pasaron las 20 pruebas, y en 3.9 ni siquiera
+# llegaron a lanzarse. Lo que falló fue el paso de ANTES,
+# actions/setup-python, porque `ubuntu-latest` ya no trae Python 3.9.
+#
+# Había dos salidas. Quitar 3.9 de la matriz era la cómoda, pero
+# entonces pyproject diría `requires-python = ">=3.9"` sin que nadie
+# lo hubiera comprobado nunca: justo la clase de afirmación que este
+# paquete no quiere hacer. La otra es correr esa versión en la máquina
+# donde sí existe. Es la que está aquí.
+#
+# Si algún día ubuntu-22.04 desaparece, hay que elegir otra vez: o se
+# encuentra dónde correr 3.9, o se sube el mínimo a 3.10 en
+# pyproject.toml y se quitan sus clasificadores. Lo que NO vale es
+# dejar de probarla y seguir diciendo que funciona.
+name: pruebas
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  pytest:
+    runs-on: ${{ matrix.so }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python: "3.9"
+            so: ubuntu-22.04
+          - python: "3.11"
+            so: ubuntu-latest
+          - python: "3.13"
+            so: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

turnero-0.1.0/.github/workflows/publicar.yml

@@ -0,0 +1,80 @@
+# Publicar en PyPI sin que exista ningún token en ninguna parte.
+#
+# POR QUÉ ASÍ
+# -----------
+# Lo normal es crear un token en PyPI, guardarlo en ~/.pypirc o en los
+# secretos del repositorio, y subir el paquete desde ahí. Funciona, y
+# tiene un problema: existe un secreto. Un secreto que se puede copiar,
+# pegar donde no debe y acabar en un repositorio público. En este
+# proyecto eso no es una hipótesis — la clave de football-data de
+# Sportalyze acabó en el historial público de git y lo único que cerró
+# aquello fue anularla en el proveedor.
+#
+# Esto es «Trusted Publishing»: PyPI confía en ESTE flujo de trabajo,
+# de ESTE repositorio, y GitHub le entrega un carné de identidad de un
+# solo uso (OIDC) cada vez que corre. No hay nada que guardar, nada que
+# rotar y nada que filtrar. Si alguien se lleva una copia del
+# repositorio, no se lleva con ella la capacidad de publicar.
+#
+# CÓMO SE PUBLICA UNA VERSIÓN
+# ---------------------------
+#     git tag v0.1.0
+#     git push origin v0.1.0
+#
+# Y ya. Nada más es necesario, y nada menos: la etiqueta es el gesto
+# que dice «esto es una versión».
+name: publicar
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  construir:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      # La etiqueta y la versión del paquete tienen que decir lo mismo.
+      # Si no, se publica una v0.1.1 que por dentro dice 0.1.0 y en PyPI
+      # eso no se arregla nunca: una versión publicada no se puede
+      # borrar ni reemplazar. Mejor parar aquí.
+      - name: La etiqueta tiene que coincidir con la versión
+        run: |
+          ETIQUETA="${GITHUB_REF_NAME#v}"
+          VERSION=$(sed -n 's/^version *= *"\(.*\)"/\1/p' pyproject.toml | head -1)
+          echo "etiqueta: $ETIQUETA   pyproject: $VERSION"
+          if [ "$ETIQUETA" != "$VERSION" ]; then
+            echo "::error::La etiqueta dice $ETIQUETA y pyproject.toml dice $VERSION."
+            exit 1
+          fi
+
+      - run: pip install -e ".[dev]"
+
+      # No se publica nada que no pase sus propias pruebas. Las de las
+      # tres versiones de Python ya corrieron en el push; esto es el
+      # último cerrojo antes de que salga de aquí.
+      - run: pytest -q
+
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: paquete
+          path: dist/
+
+  publicar:
+    needs: construir
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write          # esto es lo que sustituye al token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: paquete
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

turnero-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.DS_Store
+
+# Las instrucciones de publicación son para Félix, no para quien se
+# instale el paquete. Fuera del repositorio público a propósito.
+COMO_PUBLICAR.txt

turnero-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Registro de cambios
+
+## 0.1.0 — primera versión
+
+Primera publicación. Sale de un servicio en producción, no de un ejemplo:
+el limitador que hacía falta para abrir [Sportalyze](https://sportalyze.onrender.com)
+a la gente con una clave de diez peticiones por minuto.
+
+- `Turnero`: ventana deslizante, `espera_maxima` configurable, `HayCola`
+  con los segundos dentro, gestor de contexto y `espera_estimada()` que
+  no gasta turno.
+- `UnViaje`: agrupación de llamadas idénticas simultáneas, con `shield`
+  para que cancelar a uno no deje tirados a los demás.
+- Veinte pruebas, sin red. Una prueba retirada por no poder fallar; el
+  motivo está en el código y en el README.

turnero-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Félix Ramírez Ramírez
+
+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.

turnero-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: turnero
+Version: 0.1.0
+Summary: Límite de peticiones por ventana y agrupación de llamadas idénticas, para asyncio.
+Author: Félix Ramírez Ramírez
+License: MIT License
+        
+        Copyright (c) 2026 Félix Ramírez Ramírez
+        
+        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.
+License-File: LICENSE
+Keywords: api,asyncio,rate-limit,single-flight,sliding-window
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Spanish
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# turnero
+
+**Límite de peticiones por ventana y agrupación de llamadas idénticas, para `asyncio`.**
+Sin dependencias. Veinte pruebas. En castellano.
+
+```bash
+pip install turnero
+```
+
+---
+
+## El problema
+
+Tu proveedor te deja **diez peticiones por minuto**. No diez por visitante: diez en total.
+
+En tu portátil, probando tú solo, nunca lo tocas. El día que compartes el enlace y entran
+cinco personas a la vez, se las comen y todas reciben un error.
+
+Un semáforo no sirve: limita cuántas cosas pasan **a la vez**, no cuántas pasan **por minuto**.
+Puedes tener una sola petición en vuelo y aun así pasarte, si haces sesenta seguidas y rápidas.
+
+## Las dos piezas
+
+```python
+import asyncio
+from turnero import Turnero, UnViaje, HayCola
+
+turnero = Turnero(cuantas=9, ventana=60)   # nueve de diez: ver abajo
+viajes  = UnViaje()
+
+async def traer_equipo(id_equipo):
+    return await viajes.haz(f"equipo:{id_equipo}", lambda: _traer(id_equipo))
+
+async def _traer(id_equipo):
+    await turnero.turno()                  # espera lo justo, o lanza HayCola
+    ...tu petición de verdad...
+```
+
+**`Turnero`** — ventana deslizante. Recuerda cuándo salió cada petición y no deja salir la
+siguiente hasta que la más vieja caduca. Si la espera supera `espera_maxima` (20 s por defecto),
+lanza `HayCola` con el número de segundos, para que puedas escribir *«vuelve en 12 segundos»*
+en vez de un error genérico.
+
+**`UnViaje`** — si cinco llamadas con la misma clave coinciden en el tiempo, sale **una** y las
+otras cuatro se cuelgan de ella. En producción esto ahorró más peticiones que el propio
+limitador, de largo: en una web abierta todo el mundo mira las mismas cosas.
+
+También vale como gestor de contexto:
+
+```python
+async with turnero:
+    ...tu petición...
+```
+
+## Por qué nueve y no diez
+
+El contador de tu proveedor va por su ventana y su reloj; el tuyo va por el tuyo. Dos peticiones
+separadas por un cuarto de segundo pueden caer en el mismo minuto suyo aunque no caigan en el
+tuyo.
+
+Dejar uno de margen cuesta un turno y evita el error. Con nueve de diez no he visto un 429
+nunca; rozando el tope, sí.
+
+---
+
+## Lo que NO resuelve
+
+Esto es tan importante como lo anterior, así que va en el README y no en una nota al pie.
+
+**Vive en la memoria de UN proceso.** Con dos procesos, dos *workers* o dos máquinas, cada uno
+lleva su cuenta y entre los dos se pasan del límite. Para eso hace falta un contador compartido
+(Redis o similar) y esto no lo es. Si despliegas con más de un *worker*, `turnero` no te está
+protegiendo.
+
+**`UnViaje` no es una caché.** Agrupa sólo lo **simultáneo**. En cuanto la petición termina, la
+siguiente vuelve a salir. Si quieres recordar la respuesta, pon una caché delante; son cosas
+distintas y hacen falta las dos.
+
+**No reintenta ni respeta `Retry-After`.** Si el proveedor te dice que no, eso lo decides tú
+arriba.
+
+## Lo que no está probado
+
+En `tests/test_turnero.py` había una prueba que decía comprobar que el `sleep` está fuera del
+cerrojo. Al romper el código a propósito, **siguió en verde**: no comprobaba nada. La he
+borrado y he dejado escrito el motivo en su sitio.
+
+La razón de tener el `sleep` fuera del cerrojo sigue siendo buena —si durmiera dentro, el
+turnero dejaría de ser concurrente y se convertiría en una cola de uno en uno— pero es un
+argumento de diseño que **no he sabido fijar con una prueba**. Prefiero decirlo a dejar una
+prueba verde que miente.
+
+---
+
+## Pruebas
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+Veinte pruebas, sin red. Cada una se escribió rompiendo el código a propósito y comprobando
+que se ponía roja; lo que rompió cada una está anotado en su propio docstring.
+
+De los tres sabotajes probados al publicar, dos pusieron la suite en rojo y uno no — ese está
+contado arriba.
+
+## Licencia
+
+MIT. Félix Ramírez Ramírez, 2026.

turnero-0.1.0/README.md

@@ -0,0 +1,110 @@
+# turnero
+
+**Límite de peticiones por ventana y agrupación de llamadas idénticas, para `asyncio`.**
+Sin dependencias. Veinte pruebas. En castellano.
+
+```bash
+pip install turnero
+```
+
+---
+
+## El problema
+
+Tu proveedor te deja **diez peticiones por minuto**. No diez por visitante: diez en total.
+
+En tu portátil, probando tú solo, nunca lo tocas. El día que compartes el enlace y entran
+cinco personas a la vez, se las comen y todas reciben un error.
+
+Un semáforo no sirve: limita cuántas cosas pasan **a la vez**, no cuántas pasan **por minuto**.
+Puedes tener una sola petición en vuelo y aun así pasarte, si haces sesenta seguidas y rápidas.
+
+## Las dos piezas
+
+```python
+import asyncio
+from turnero import Turnero, UnViaje, HayCola
+
+turnero = Turnero(cuantas=9, ventana=60)   # nueve de diez: ver abajo
+viajes  = UnViaje()
+
+async def traer_equipo(id_equipo):
+    return await viajes.haz(f"equipo:{id_equipo}", lambda: _traer(id_equipo))
+
+async def _traer(id_equipo):
+    await turnero.turno()                  # espera lo justo, o lanza HayCola
+    ...tu petición de verdad...
+```
+
+**`Turnero`** — ventana deslizante. Recuerda cuándo salió cada petición y no deja salir la
+siguiente hasta que la más vieja caduca. Si la espera supera `espera_maxima` (20 s por defecto),
+lanza `HayCola` con el número de segundos, para que puedas escribir *«vuelve en 12 segundos»*
+en vez de un error genérico.
+
+**`UnViaje`** — si cinco llamadas con la misma clave coinciden en el tiempo, sale **una** y las
+otras cuatro se cuelgan de ella. En producción esto ahorró más peticiones que el propio
+limitador, de largo: en una web abierta todo el mundo mira las mismas cosas.
+
+También vale como gestor de contexto:
+
+```python
+async with turnero:
+    ...tu petición...
+```
+
+## Por qué nueve y no diez
+
+El contador de tu proveedor va por su ventana y su reloj; el tuyo va por el tuyo. Dos peticiones
+separadas por un cuarto de segundo pueden caer en el mismo minuto suyo aunque no caigan en el
+tuyo.
+
+Dejar uno de margen cuesta un turno y evita el error. Con nueve de diez no he visto un 429
+nunca; rozando el tope, sí.
+
+---
+
+## Lo que NO resuelve
+
+Esto es tan importante como lo anterior, así que va en el README y no en una nota al pie.
+
+**Vive en la memoria de UN proceso.** Con dos procesos, dos *workers* o dos máquinas, cada uno
+lleva su cuenta y entre los dos se pasan del límite. Para eso hace falta un contador compartido
+(Redis o similar) y esto no lo es. Si despliegas con más de un *worker*, `turnero` no te está
+protegiendo.
+
+**`UnViaje` no es una caché.** Agrupa sólo lo **simultáneo**. En cuanto la petición termina, la
+siguiente vuelve a salir. Si quieres recordar la respuesta, pon una caché delante; son cosas
+distintas y hacen falta las dos.
+
+**No reintenta ni respeta `Retry-After`.** Si el proveedor te dice que no, eso lo decides tú
+arriba.
+
+## Lo que no está probado
+
+En `tests/test_turnero.py` había una prueba que decía comprobar que el `sleep` está fuera del
+cerrojo. Al romper el código a propósito, **siguió en verde**: no comprobaba nada. La he
+borrado y he dejado escrito el motivo en su sitio.
+
+La razón de tener el `sleep` fuera del cerrojo sigue siendo buena —si durmiera dentro, el
+turnero dejaría de ser concurrente y se convertiría en una cola de uno en uno— pero es un
+argumento de diseño que **no he sabido fijar con una prueba**. Prefiero decirlo a dejar una
+prueba verde que miente.
+
+---
+
+## Pruebas
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+Veinte pruebas, sin red. Cada una se escribió rompiendo el código a propósito y comprobando
+que se ponía roja; lo que rompió cada una está anotado en su propio docstring.
+
+De los tres sabotajes probados al publicar, dos pusieron la suite en rojo y uno no — ese está
+contado arriba.
+
+## Licencia
+
+MIT. Félix Ramírez Ramírez, 2026.

turnero-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "turnero"
+version = "0.1.0"
+description = "Límite de peticiones por ventana y agrupación de llamadas idénticas, para asyncio."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Félix Ramírez Ramírez" }]
+keywords = ["rate-limit", "asyncio", "sliding-window", "single-flight", "api"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Natural Language :: Spanish",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.21"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/turnero"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

turnero-0.1.0/src/turnero/__init__.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+"""turnero — límite por ventana y un viaje por petición, para asyncio.
+
+    from turnero import Turnero, UnViaje, HayCola
+
+    turnero = Turnero(cuantas=9, ventana=60)   # nueve de diez: el margen
+    viajes  = UnViaje()
+
+    async def traer(id):
+        return await viajes.haz(id, lambda: _traer_de_verdad(id))
+
+    async def _traer_de_verdad(id):
+        await turnero.turno()
+        ...
+
+Lo que NO resuelve, y está escrito también en el README: el turnero
+vive en la memoria de UN proceso. Con dos procesos o dos máquinas, cada
+uno lleva su cuenta y entre los dos se pasan del límite. Para eso hace
+falta algo compartido (Redis o similar) y esto no lo es.
+"""
+from .errores import HayCola
+from ._turnero import Turnero, ESPERA_MAXIMA_POR_DEFECTO
+from ._un_viaje import UnViaje
+
+__all__ = ["Turnero", "UnViaje", "HayCola", "ESPERA_MAXIMA_POR_DEFECTO"]
+__version__ = "0.1.0"

turnero-0.1.0/src/turnero/_turnero.py

@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+"""El turnero: una ventana deslizante que reparte turnos.
+
+POR QUÉ EXISTE ESTO Y NO USO UN SEMÁFORO
+----------------------------------------
+Un semáforo limita cuántas cosas pasan A LA VEZ. Lo que limita una API
+es cuántas pasan POR MINUTO, que es otra cosa: puedes tener una sola
+petición en vuelo y aun así pasarte del límite si haces sesenta
+seguidas y rápidas.
+
+Lo que hace falta es una ventana deslizante: recordar cuándo salió
+cada petición y no dejar salir la número N+1 hasta que la primera
+tenga más de `ventana` segundos. Eso es todo lo que hay aquí.
+
+LA DECISIÓN QUE MÁS SE DISCUTE
+------------------------------
+Si tu proveedor te deja diez por minuto, configura NUEVE.
+
+Su contador va por su ventana y su reloj; el tuyo va por el tuyo. Dos
+peticiones separadas por un cuarto de segundo pueden caer en el mismo
+minuto suyo aunque no caigan en el tuyo. Dejar uno de margen cuesta un
+turno y evita el error. En producción, con nueve de diez, no he visto
+un 429; rozando el tope, sí.
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+from collections import deque
+
+from .errores import HayCola
+
+ESPERA_MAXIMA_POR_DEFECTO = 20.0
+"""Más de esto esperando y se prefiere avisar. Veinte segundos es
+mucho para una web y poco para perder la petición."""
+
+
+class Turnero:
+    """Reparte turnos para no pasarse de un límite por ventana.
+
+        turnero = Turnero(cuantas=9, ventana=60)
+        await turnero.turno()      # espera lo justo, o lanza HayCola
+        ...tu petición...
+
+    También vale como gestor de contexto:
+
+        async with turnero:
+            ...tu petición...
+    """
+
+    def __init__(self, cuantas: int = 9, ventana: float = 60.0,
+                 espera_maxima: float = ESPERA_MAXIMA_POR_DEFECTO):
+        if cuantas < 1:
+            raise ValueError("cuantas tiene que ser 1 o más")
+        if ventana <= 0:
+            raise ValueError("ventana tiene que ser mayor que cero")
+        self.cuantas = cuantas
+        self.ventana = float(ventana)
+        self.espera_maxima = float(espera_maxima)
+        self._salidas: deque[float] = deque()
+        self._cerrojo = asyncio.Lock()
+
+    # ── por dentro ──────────────────────────────────────────────
+    def _limpiar(self, ahora: float) -> None:
+        """Olvida las salidas que ya no cuentan para la ventana."""
+        while self._salidas and ahora - self._salidas[0] >= self.ventana:
+            self._salidas.popleft()
+
+    # ── por fuera ───────────────────────────────────────────────
+    def espera_estimada(self) -> float:
+        """Cuánto habría que esperar AHORA. No pide turno ni lo gasta.
+
+        Sirve para decidir antes de llamar: si esto devuelve 12, puedes
+        enseñar «hay cola» sin bloquear a nadie.
+        """
+        ahora = time.monotonic()
+        self._limpiar(ahora)
+        if len(self._salidas) < self.cuantas:
+            return 0.0
+        return max(0.0, self.ventana - (ahora - self._salidas[0]))
+
+    @property
+    def en_la_ventana(self) -> int:
+        """Cuántas peticiones cuentan ahora mismo dentro de la ventana."""
+        self._limpiar(time.monotonic())
+        return len(self._salidas)
+
+    async def turno(self) -> None:
+        """Espera a que toque. Lanza HayCola si la espera es absurda.
+
+        El cerrojo sólo cubre mirar y apuntar, nunca el sleep: si
+        durmiera con el cerrojo cogido, el turnero dejaría de ser
+        concurrente y se convertiría en una cola de uno en uno.
+        """
+        while True:
+            async with self._cerrojo:
+                ahora = time.monotonic()
+                self._limpiar(ahora)
+                if len(self._salidas) < self.cuantas:
+                    self._salidas.append(ahora)
+                    return
+                falta = self.ventana - (ahora - self._salidas[0]) + 0.05
+            if falta > self.espera_maxima:
+                raise HayCola(falta, self.cuantas, self.ventana)
+            await asyncio.sleep(min(falta, 1.0))
+
+    async def __aenter__(self) -> "Turnero":
+        await self.turno()
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        return None
+
+    def __repr__(self) -> str:
+        return (f"Turnero(cuantas={self.cuantas}, ventana={self.ventana:g}, "
+                f"en_la_ventana={len(self._salidas)})")

turnero-0.1.0/src/turnero/_un_viaje.py

@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+"""Un viaje por petición: si varios piden lo mismo a la vez, sale una.
+
+ESTO AHORRA MÁS TURNOS QUE EL PROPIO LÍMITE
+-------------------------------------------
+Lo normal, en una web abierta, es que todo el mundo mire las mismas
+cosas. Si cinco visitantes abren la misma página en el mismo segundo,
+el turnero reparte cinco turnos para traer cinco veces lo mismo.
+
+Con esto sale UNA petición y las otras cuatro se cuelgan de ella. En
+producción ahorró más peticiones que el limitador, de largo.
+
+POR QUÉ `shield`
+----------------
+Si el primero que pidió se cancela —cierra la pestaña, se le va la
+conexión—, los otros cuatro NO pueden quedarse colgados de una tarea
+muerta. `asyncio.shield` hace que cancelar la espera no cancele el
+viaje: el que se va se va, y los que quedan reciben su respuesta.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Awaitable, Callable, Dict, Hashable
+
+
+class UnViaje:
+    """Agrupa llamadas idénticas simultáneas en una sola.
+
+        viajes = UnViaje()
+        datos = await viajes.haz("equipo:81", lambda: traer(81))
+
+    Lo que agrupa es la CLAVE: dos llamadas con la misma clave a la vez
+    comparten resultado; con claves distintas, no se tocan.
+    """
+
+    def __init__(self) -> None:
+        self._en_vuelo: Dict[Hashable, asyncio.Future] = {}
+
+    @property
+    def en_vuelo(self) -> int:
+        """Cuántas peticiones distintas están saliendo ahora mismo."""
+        return len(self._en_vuelo)
+
+    async def haz(self, clave: Hashable,
+                  hacer: Callable[[], Awaitable[Any]]) -> Any:
+        """Ejecuta `hacer()` una sola vez por clave simultánea.
+
+        `hacer` es una función SIN argumentos que devuelve una
+        corutina. Se pide así, y no la corutina ya creada, porque si
+        hay que descartarla quedaría una corutina sin esperar y Python
+        avisa por consola.
+        """
+        pendiente = self._en_vuelo.get(clave)
+        if pendiente is not None:
+            return await asyncio.shield(pendiente)
+
+        tarea = asyncio.ensure_future(hacer())
+        self._en_vuelo[clave] = tarea
+        try:
+            return await asyncio.shield(tarea)
+        finally:
+            # Sólo lo quita quien lo puso: si el primero se canceló y
+            # otro ya empezó un viaje nuevo con la misma clave, borrar
+            # a ciegas tiraría el viaje bueno.
+            if self._en_vuelo.get(clave) is tarea:
+                self._en_vuelo.pop(clave, None)

turnero-0.1.0/src/turnero/errores.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""Los errores que este paquete puede lanzar.
+
+Tienen clase propia a propósito. Quien usa la librería necesita poder
+distinguir «hay cola, espera» de «esto se ha roto», porque son dos
+mensajes distintos para el usuario final y dos decisiones distintas
+para el programa.
+"""
+from __future__ import annotations
+
+
+class HayCola(Exception):
+    """La espera sería más larga de lo que se ha dicho que se tolera.
+
+    No es un fallo: es el turnero diciendo que prefiere contestar a
+    tener a alguien mirando una ruedecita. Trae el número para que
+    arriba se pueda escribir «vuelve en N segundos» en vez de un
+    error genérico.
+    """
+
+    def __init__(self, espera: float, cuantas: int, ventana: float):
+        self.espera = espera
+        self.cuantas = cuantas
+        self.ventana = ventana
+        super().__init__(
+            f"hay cola: habría que esperar {espera:.0f} segundos. "
+            f"El límite configurado es de {cuantas} peticiones "
+            f"cada {ventana:.0f} segundos, compartidas por todo el mundo."
+        )

turnero-0.1.0/tests/test_juntos.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""Los dos a la vez, que es como se usan de verdad."""
+import asyncio
+
+from turnero import Turnero, UnViaje
+
+
+async def test_veinte_visitantes_pidiendo_cinco_cosas_gastan_cinco_turnos():
+    """El caso real: mucha gente mirando las mismas pocas páginas.
+
+    Sin agrupar serían veinte turnos y se comerían el límite. Con los
+    dos juntos son cinco, uno por cosa distinta.
+    """
+    turnero = Turnero(cuantas=9, ventana=60.0)
+    viajes = UnViaje()
+
+    async def traer(clave):
+        await turnero.turno()
+        await asyncio.sleep(0.02)
+        return clave
+
+    async def pedir(clave):
+        return await viajes.haz(clave, lambda: traer(clave))
+
+    peticiones = [pedir(f"cosa{i % 5}") for i in range(20)]
+    res = await asyncio.gather(*peticiones)
+
+    assert len(res) == 20
+    assert turnero.en_la_ventana == 5

turnero-0.1.0/tests/test_turnero.py

@@ -0,0 +1,133 @@
+# -*- coding: utf-8 -*-
+"""Pruebas del turnero.
+
+Sin red y sin esperas largas: las ventanas son de décimas de segundo.
+Cada prueba se escribió rompiendo el código a propósito primero, para
+comprobar que se ponía roja. Lo que rompió cada una está anotado.
+"""
+import asyncio
+import time
+
+import pytest
+
+from turnero import Turnero, HayCola
+
+
+async def test_por_debajo_del_limite_no_se_espera():
+    t = Turnero(cuantas=5, ventana=60.0)
+    ini = time.monotonic()
+    for _ in range(5):
+        await t.turno()
+    assert time.monotonic() - ini < 0.2
+
+
+async def test_pasado_el_limite_se_espera_lo_justo():
+    """SABOTAJE: quitar el `+ 0.05` del cálculo de `falta` dejaba que
+    la cuarta saliera un pelo antes de que caducara la primera."""
+    t = Turnero(cuantas=3, ventana=0.5)
+    for _ in range(3):
+        await t.turno()
+    ini = time.monotonic()
+    await t.turno()
+    esperado = time.monotonic() - ini
+    assert 0.3 < esperado < 1.2, f"esperó {esperado:.2f}s"
+
+
+async def test_la_ventana_se_vacia_sola():
+    t = Turnero(cuantas=2, ventana=0.3)
+    await t.turno(); await t.turno()
+    assert t.en_la_ventana == 2
+    await asyncio.sleep(0.35)
+    assert t.en_la_ventana == 0
+    assert t.espera_estimada() == 0.0
+
+
+async def test_si_la_cola_es_absurda_se_avisa_en_vez_de_colgar():
+    """SABOTAJE: devolver None en vez de lanzar hacía que la petición
+    saliera igual, saltándose el límite en silencio."""
+    t = Turnero(cuantas=1, ventana=60.0, espera_maxima=1.0)
+    await t.turno()
+    with pytest.raises(HayCola) as e:
+        await t.turno()
+    assert e.value.espera > 1.0
+    assert e.value.cuantas == 1
+
+
+async def test_el_aviso_trae_los_numeros_para_el_usuario():
+    t = Turnero(cuantas=2, ventana=30.0, espera_maxima=0.5)
+    await t.turno(); await t.turno()
+    with pytest.raises(HayCola) as e:
+        await t.turno()
+    texto = str(e.value)
+    assert "2" in texto and "30" in texto
+
+
+async def test_la_espera_estimada_no_pide_turno():
+    """SABOTAJE: si espera_estimada apuntara la salida, consultar el
+    estado gastaría turnos y la web se limitaría a sí misma."""
+    t = Turnero(cuantas=3, ventana=60.0)
+    for _ in range(10):
+        t.espera_estimada()
+    assert t.en_la_ventana == 0
+    for _ in range(3):
+        await t.turno()
+    assert t.espera_estimada() > 0
+
+
+async def test_el_limite_se_respeta_con_muchos_a_la_vez():
+    """Veinte tareas a la vez contra un límite de cinco: salen cinco.
+    SABOTAJE: quitar el cerrojo dejaba pasar a varias entre el mirar
+    y el apuntar, y salían siete u ocho."""
+    t = Turnero(cuantas=5, ventana=60.0, espera_maxima=0.2)
+    async def intentar():
+        try:
+            await t.turno()
+            return True
+        except HayCola:
+            return False
+    salidas = await asyncio.gather(*[intentar() for _ in range(20)])
+    assert sum(salidas) == 5
+    assert t.en_la_ventana == 5
+
+
+async def test_sirve_como_gestor_de_contexto():
+    t = Turnero(cuantas=2, ventana=60.0)
+    async with t:
+        pass
+    assert t.en_la_ventana == 1
+
+
+# AQUÍ HABÍA UNA PRUEBA QUE NO PROTEGÍA NADA
+#
+# Se llamaba test_no_duerme_con_el_cerrojo_cogido y decía comprobar que
+# el `await asyncio.sleep(...)` de Turnero.turno() está FUERA del
+# `async with self._cerrojo`.
+#
+# Al sabotear el código —metiendo el sleep dentro del cerrojo— la
+# prueba siguió en VERDE. O sea que no comprobaba lo que decía.
+#
+# El motivo: con una ventana corta, cuando el que duerme se despierta
+# la ventana ya ha caducado entera, así que el siguiente entra rápido
+# de las dos maneras. Los tiempos salen casi iguales con el código
+# bueno y con el roto.
+#
+# La razón de tener el sleep fuera del cerrojo sigue siendo buena —si
+# durmiera dentro, el turnero dejaría de ser concurrente y se
+# convertiría en una cola de uno en uno— pero es un argumento de
+# diseño que NO he sabido fijar con una prueba. Antes que dejar una
+# prueba verde que miente, se borra y se dice.
+#
+# Está en el README, en «lo que no está probado».
+
+
+@pytest.mark.parametrize("cuantas,ventana", [(0, 60), (-1, 60), (5, 0), (5, -1)])
+async def test_configuracion_imposible_se_rechaza_al_construir(cuantas, ventana):
+    """Mejor reventar al arrancar que a las tres de la mañana."""
+    with pytest.raises(ValueError):
+        Turnero(cuantas=cuantas, ventana=ventana)
+
+
+async def test_el_repr_dice_el_estado():
+    t = Turnero(cuantas=4, ventana=10.0)
+    await t.turno()
+    assert "cuantas=4" in repr(t) and "en_la_ventana=1" in repr(t)

turnero-0.1.0/tests/test_un_viaje.py

@@ -0,0 +1,98 @@
+# -*- coding: utf-8 -*-
+"""Pruebas de «un viaje por petición»."""
+import asyncio
+
+import pytest
+
+from turnero import UnViaje
+
+
+async def test_cinco_a_la_vez_son_un_solo_viaje():
+    """SABOTAJE: quitar el registro en `_en_vuelo` → salieron cinco."""
+    viajes = UnViaje()
+    salidas = 0
+
+    async def traer():
+        nonlocal salidas
+        salidas += 1
+        await asyncio.sleep(0.05)
+        return "dato"
+
+    res = await asyncio.gather(*[viajes.haz("a", traer) for _ in range(5)])
+    assert salidas == 1
+    assert res == ["dato"] * 5
+
+
+async def test_claves_distintas_son_viajes_distintos():
+    viajes = UnViaje()
+    salidas = 0
+
+    async def traer():
+        nonlocal salidas
+        salidas += 1
+        await asyncio.sleep(0.02)
+        return salidas
+
+    await asyncio.gather(viajes.haz("a", traer), viajes.haz("b", traer))
+    assert salidas == 2
+
+
+async def test_despues_de_acabar_el_siguiente_vuelve_a_salir():
+    """Agrupar sólo vale para lo SIMULTÁNEO. Esto no es una caché.
+    SABOTAJE: no limpiar `_en_vuelo` al acabar → la segunda tanda
+    devolvía el dato viejo para siempre."""
+    viajes = UnViaje()
+    salidas = 0
+
+    async def traer():
+        nonlocal salidas
+        salidas += 1
+        return salidas
+
+    assert await viajes.haz("a", traer) == 1
+    assert await viajes.haz("a", traer) == 2
+    assert viajes.en_vuelo == 0
+
+
+async def test_si_el_primero_se_cancela_los_demas_cobran():
+    """La razón de `asyncio.shield`.
+    SABOTAJE: quitar el shield → al cancelar el primero, los otros dos
+    se quedaron con CancelledError sin haber pedido nada."""
+    viajes = UnViaje()
+
+    async def traer():
+        await asyncio.sleep(0.1)
+        return "llegó"
+
+    primero = asyncio.create_task(viajes.haz("a", traer))
+    await asyncio.sleep(0.01)
+    otros = [asyncio.create_task(viajes.haz("a", traer)) for _ in range(2)]
+    await asyncio.sleep(0.01)
+    primero.cancel()
+    assert await asyncio.gather(*otros) == ["llegó", "llegó"]
+
+
+async def test_un_fallo_llega_a_todos_los_que_esperan():
+    viajes = UnViaje()
+
+    async def traer():
+        await asyncio.sleep(0.02)
+        raise RuntimeError("la fuente ha dicho que no")
+
+    with pytest.raises(RuntimeError):
+        await asyncio.gather(*[viajes.haz("a", traer) for _ in range(3)])
+    assert viajes.en_vuelo == 0
+
+
+async def test_el_contador_de_en_vuelo_es_de_verdad():
+    viajes = UnViaje()
+
+    async def traer():
+        await asyncio.sleep(0.05)
+        return 1
+
+    t = [asyncio.create_task(viajes.haz(k, traer)) for k in ("a", "b", "c")]
+    await asyncio.sleep(0.01)
+    assert viajes.en_vuelo == 3
+    await asyncio.gather(*t)
+    assert viajes.en_vuelo == 0