rust-py-cache 0.2.3__tar.gz → 0.3.0__tar.gz

rust_py_cache-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,389 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# release.yml canônico dos `rust_py_*`  —  P3-1
+#
+# Um arquivo só por projeto: lint, teste, build da matriz, ensaio no TestPyPI e
+# publicação. Substitui o par `ci.yml` + `release.yml` que `cache` e
+# `rate_limit` mantinham, e que tinha um problema silencioso — ver "Por que um
+# workflow só", abaixo.
+#
+# Gerado a partir de `rust_py_template/.github/workflows/release.yml` em
+# 12/08/2026 — o `cache` é o primeiro projeto a adotar o formato unificado.
+# Correção feita aqui deve voltar para o template, senão a divergência
+# recomeça pelo mesmo caminho de sempre.
+#
+# ⚠️ NÃO RENOMEAR ESTE ARQUIVO. O trusted publisher cadastrado no PyPI amarra
+# `release.yml`; renomear quebra a publicação até o cadastro ser refeito.
+#
+# Substituiu o par `ci.yml` + `release.yml` que o `cache` mantinha.
+#
+# ── POR QUE UM WORKFLOW SÓ ───────────────────────────────────────────────────
+# `cache` e `rate_limit` tinham dois arquivos, e a divisão escondia uma
+# inversão: o `ci.yml` deles rodava a suíte RICA (multi-OS, Python 3.10–3.13)
+# em push/PR sem barrar nada, enquanto o `release.yml` barrava a publicação com
+# uma suíte MAGRA (ubuntu, 3.12). Ou seja, o portão do PyPI era o teste mais
+# fraco dos dois. `needs` não atravessa workflow — é a lição do P1-1, aqui numa
+# segunda forma.
+#
+# Este arquivo resolve juntando: a suíte rica é a que barra o release.
+# ─────────────────────────────────────────────────────────────────────────────
+
+name: CI / Release
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]            # `v*`, nunca `*` — ver nota no job `release`
+  pull_request:
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+env:
+  PACKAGE_NAME: rust-py-cache
+  # 2 manylinux + 2 musllinux + 1 windows + 2 macos. O `monitor` soma 4 do
+  # PyPy (11); o `scheduler`, com a matriz longa, chega a 15.
+  MIN_WHEELS: "7"
+
+jobs:
+  # ── PORTÃO 1: lint ─────────────────────────────────────────────────────────
+  # Barra o release junto com o `test`. Nos repositórios de workflow único, um
+  # `lint` vermelho ao lado de uma publicação bem-sucedida seria ilegível — a
+  # leitura tem que ser inequívoca: vermelho significa que não publicou.
+  lint:
+    name: fmt + clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Versão fixa, não "stable". Com `-D warnings`, um clippy mais novo no
+      # runner reprova código que ninguém tocou, e a CI fica vermelha por conta
+      # do calendário. Subir este número vira uma mudança deliberada.
+      - uses: dtolnay/rust-toolchain@1.88.0
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: cargo fmt
+        run: cargo fmt --all -- --check
+      # clippy só checa tipos, não linka, então --all-features é seguro aqui —
+      # diferente do `cargo test`, que precisa de --no-default-features.
+      - name: cargo clippy
+        run: cargo clippy --all-targets --all-features -- -D warnings
+
+  # ── PORTÃO 2: teste ────────────────────────────────────────────────────────
+  # Nada é construído e nada chega ao PyPI antes disto passar. Publicação no
+  # PyPI é irreversível: um wheel ruim não pode ser substituído, só yankado.
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      # A matriz veio do `ci.yml` do `cache` e do `CI.yml` do `rate_limit`, que
+      # tinham a cobertura mais larga dos cinco — e que, por viverem em
+      # workflow separado, não barravam nada. Agora barram.
+      #
+      # O eixo de SO é o do `cache`, reduzido: ele rodava macOS em três versões
+      # de Python, o que dobrava a matriz para provar a mesma coisa. Uma versão
+      # em macOS basta para pegar o que ubuntu não pega (link da extensão,
+      # caminho de arquivo, comportamento de thread). O eixo de Python inteiro
+      # fica no ubuntu, que é onde ele importa.
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: macos-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: Swatinem/rust-cache@v2
+
+      # --no-default-features desliga `extension-module`, que manda o linker
+      # deixar os símbolos da libpython indefinidos. Correto para a wheel, mas
+      # produz um binário de teste que não linka no Linux.
+      #
+      # ⚠️ O `rate_limit` é o único sem seção `[features]` no Cargo.toml — lá
+      # o `extension-module` vem só de `[tool.maturin].features`, e a flag é
+      # inócua. Alinhar o Cargo.toml dele é item pendente.
+      - name: Rust unit tests
+        # Uma vez por SO basta: o core não muda com a versão do Python.
+        if: matrix.python-version == '3.12'
+        env:
+          PYO3_PYTHON: python
+        run: cargo test --no-default-features --lib
+
+      # `pip install` aciona o backend maturin, compila a extensão e a instala
+      # no Python do runner. Ao contrário de `maturin develop`, não exige
+      # virtualenv — armadilha que custou um release do `monitor` (P1-9).
+      # Instalar não-editável faz os testes exercitarem o artefato que embarca.
+      - name: Build, install the extension and run the Python tests
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev]"
+          python -m pytest -q
+
+  # ── BUILD ──────────────────────────────────────────────────────────────────
+  # Guardados por tag OU disparo manual: um push comum não precisa pagar a
+  # matriz inteira, mas o ensaio no TestPyPI precisa dos artefatos.
+  #
+  # `fail-fast: false` em todas as matrizes: sem isso, um alvo que cai CANCELA
+  # os irmãos. Em 12/08/2026 o build x86 do `scheduler` quebrou num 403 do
+  # vault.centos.org e levou junto o diagnóstico de armv7/s390x/ppc64le.
+  #
+  # Nenhum job de build passa `--find-interpreter`: com `abi3-py310` ele não
+  # produz nada a mais. Verificado — o `audit` publicava 7 wheels, todos abi3,
+  # com a flag ligada. É flag morto e confunde quem lê.
+  linux:
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch'
+    needs: [lint, test]
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          # `auto` constrói dentro do container manylinux, para o wheel
+          # declarar um piso de glibc portável em vez do glibc do runner.
+          manylinux: auto
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux-${{ matrix.target }}
+          path: dist
+
+  musllinux:
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch'
+    needs: [lint, test]
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          manylinux: musllinux_1_2
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-musllinux-${{ matrix.target }}
+          path: dist
+
+  windows:
+    runs-on: windows-latest
+    if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch'
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          architecture: x64
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: x64
+          args: --release --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-windows-x64
+          path: dist
+
+  macos:
+    runs-on: macos-latest
+    if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch'
+    needs: [lint, test]
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-macos-${{ matrix.target }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch'
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-sdist
+          path: dist
+
+  # ── ENSAIO ─────────────────────────────────────────────────────────────────
+  # Valida a troca OIDC inteira sem tocar no índice de produção. É onde um
+  # publisher mal cadastrado deve ser descoberto — no PyPI, um nome de arquivo
+  # publicado nunca pode ser reusado.
+  #
+  # ⚠️ Precisa do seu próprio publisher, cadastrado no TestPyPI (conta separada
+  # do PyPI), com environment `testpypi`.
+  #
+  # Sem verificação pós-upload de propósito: o que se valida aqui é a troca de
+  # token, e o TestPyPI expira distribuições — reprovar por um arquivo que o
+  # índice de teste descartou seria alarme falso.
+  publish-testpypi:
+    name: Publish to TestPyPI (ensaio)
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch'
+    needs: [lint, test, linux, musllinux, windows, macos, sdist]
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist
+          skip-existing: true
+
+  # ── PUBLICAÇÃO ─────────────────────────────────────────────────────────────
+  release:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    # SÓ TAG. Sem a cláusula de `workflow_dispatch` que os jobs de build têm —
+    # a assimetria é a proteção: disparo manual vai ao TestPyPI, só a tag chega
+    # ao índice de verdade.
+    #
+    # ⚠️ Isto depende do filtro `tags: ["v*"]` lá em cima. O `scheduler` usava
+    # `'*'`, e como esta guarda só checa `refs/tags/`, QUALQUER tag empurrada
+    # teria publicado. Corrigido em 12/08/2026.
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: [lint, test, linux, musllinux, windows, macos, sdist]
+
+    # Trusted publishing (OIDC): sem `secrets.PYPI_API_TOKEN`. O GitHub emite
+    # um JWT curto afirmando repositório, workflow e ref, e o PyPI o troca por
+    # um token de upload de poucos minutos, restrito a este projeto.
+    #
+    # ⚠️ Os três valores precisam bater EXATAMENTE com o publisher cadastrado
+    # em PyPI → Manage → Publishing:
+    #   owner/repo .... <owner>/<repo>
+    #   workflow ...... release.yml   (o NOME DO ARQUIVO, não o `name:` acima)
+    #   environment ... pypi
+    # Errar qualquer um dá `invalid-publisher`, que é falha segura: acontece na
+    # troca do token, depois de construir tudo e antes de qualquer arquivo sair
+    # do runner.
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install the verification dependency
+        run: python -m pip install --upgrade requests
+
+      # Conferência antes de qualquer coisa sair do runner: publicar um
+      # conjunto incompleto é pior que não publicar, porque o PyPI nunca deixa
+      # reusar um nome de arquivo — uma versão meio-publicada só pode ser
+      # completada, nunca substituída. Aconteceu de verdade: `monitor` 0.4.0
+      # ficou com 37 de 45 arquivos e sem sdist (P1-9).
+      - name: Verify the artifact set is complete
+        run: |
+          set -euo pipefail
+          ls -la dist/
+          test -n "$(find dist -name '*.tar.gz' -print -quit)" \
+            || { echo "::error::sdist ausente — abortando antes de publicar"; exit 1; }
+          wheels=$(find dist -name '*.whl' | wc -l)
+          echo "wheels: $wheels (mínimo ${MIN_WHEELS})"
+          test "$wheels" -ge "${MIN_WHEELS}" \
+            || { echo "::error::só $wheels wheels; esperado >= ${MIN_WHEELS}"; exit 1; }
+
+      # O PyPI devolve 500 transitório com frequência suficiente para importar,
+      # e o upload é arquivo por arquivo: uma falha no meio deixa a versão
+      # publicada pela metade. `skip-existing` torna a segunda tentativa segura
+      # — sem ele, ela morre nos arquivos que já subiram.
+      #
+      # Dois passos explícitos em vez de um wrapper de retry porque o trusted
+      # publishing exige a action oficial, que não dá para acionar por linha de
+      # comando de dentro do `nick-fields/retry`.
+      #
+      # ⚠️ Se a primeira tentativa falhar por `invalid-publisher`, a segunda vai
+      # falhar igual — é erro de configuração, não transitório. Custa 45s de
+      # espera inútil; melhoria conhecida e ainda não feita.
+      - name: Publish to PyPI (attempt 1)
+        id: publish1
+        continue-on-error: true
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          skip-existing: true
+
+      - name: Wait before retrying
+        if: steps.publish1.outcome == 'failure'
+        run: sleep 45
+
+      - name: Publish to PyPI (attempt 2)
+        if: steps.publish1.outcome == 'failure'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          skip-existing: true
+
+      # Prova que a release está completa, em vez de confiar num código de
+      # saída que uma publicação parcial também produz.
+      - name: Verify every file reached PyPI
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import os, sys, glob, time, requests
+          package = os.environ["PACKAGE_NAME"]
+          version = os.environ["GITHUB_REF_NAME"].lstrip("v")
+          # Só .whl e .tar.gz: os únicos tipos que o PyPI hospeda. O
+          # `pypa/gh-action-pypi-publish` deixa um .publish.attestation por
+          # distribuição em dist/ DEPOIS de publicar (atestados PEP 740, que
+          # sobem junto do arquivo e não como arquivo próprio). Um glob amplo
+          # os conta como "faltando" e reprova uma release que deu certo — foi
+          # o alarme falso da rate_limit 0.2.1 (P1-9).
+          local = {
+              os.path.basename(p)
+              for pattern in ("dist/*.whl", "dist/*.tar.gz")
+              for p in glob.glob(pattern)
+          }
+          url = f"https://pypi.org/pypi/{package}/{version}/json"
+          for attempt in range(6):          # a API JSON do PyPI é cacheada
+              response = requests.get(url, timeout=30)
+              if response.status_code == 200:
+                  remote = {f["filename"] for f in response.json()["urls"]}
+                  missing = local - remote
+                  if not missing:
+                      print(f"OK: {len(remote)} arquivos publicados na {version}")
+                      sys.exit(0)
+              else:
+                  missing = local
+              print(f"tentativa {attempt + 1}: faltam {len(missing)}")
+              time.sleep(20)
+          print("::error::faltaram arquivos no PyPI:")
+          for name in sorted(missing):
+              print(f"  - {name}")
+          sys.exit(1)
+          PY

{rust_py_cache-0.2.3 → rust_py_cache-0.3.0}/.gitignore

@@ -5,3 +5,6 @@ __pycache__/
 dist/
 *.egg-info/
 .pytest_cache/
+
+# macOS
+.DS_Store

{rust_py_cache-0.2.3 → rust_py_cache-0.3.0}/CHANGELOG.md

@@ -5,7 +5,78 @@ Todas as mudanças relevantes deste projeto são registradas aqui.
 O formato segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/),
 e o versionamento segue [SemVer](https://semver.org/lang/pt-BR/).
 
-## [0.2.3] — não publicada
+## [0.3.0] — não publicada
+
+Evicção LRU com custo amortizado O(1) (**P2-2**). Inclui também tudo o que
+estava na 0.2.4, que nunca chegou a ser publicada.
+
+### Alterado
+
+- **A evicção LRU passou a remover um lote, não uma entrada.** Até a 0.2.x,
+  achar a entrada menos recentemente usada varria o `DashMap` inteiro — e isso
+  acontecia a **cada** `set` de chave nova com o cache cheio, que é o regime
+  normal de um cache cheio sob escrita. Agora cada varredura remove
+  `max_size / 32` entradas (no mínimo 1), e a próxima só vem depois de outras
+  ~n/32 inserções. Medido com `max_size=100_000`: **~620 µs → ~1,6 µs** por
+  `set` com o cache cheio (com 10 000: ~70 µs → ~1,5 µs). O custo deixou de
+  crescer com o tamanho do cache.
+- A seleção acha o corte com `select_nth_unstable` sobre os carimbos de acesso
+  (sem clonar chaves nem ordenar) e remove com `remove_if`, que recheca o
+  carimbo: uma chave lida por outra thread no meio da varredura fica.
+- Um `Mutex` cobre **só** o caminho de evicção, para várias threads que acham o
+  cache cheio ao mesmo tempo não varrerem em paralelo. `get`/`set` comuns não o
+  tocam.
+
+### Compatibilidade
+
+- Nenhuma API mudou. O que muda de observável, e por isso o minor sobe: logo
+  depois de uma evicção o cache fica ~3% abaixo de `max_size` (antes ficava em
+  `max_size - 1`), e `stats()["evicted"]` cresce em lotes. Com `max_size < 64`
+  o lote é de 1 entrada e o comportamento é idêntico ao anterior.
+- Amostragem estilo Redis, que o backlog sugeria, foi descartada: exigiria
+  acesso aleatório às entradas, que o `DashMap` só expõe pela `raw-api` (tabela
+  interna do hashbrown, iteração `unsafe`).
+
+## [0.2.4] — não publicada
+
+Adoção do `release.yml` unificado do template (**P3-1**). Nada muda no
+comportamento da biblioteca — mas muda, e bastante, o que precisa passar antes
+de uma versão chegar ao PyPI.
+
+### Corrigido
+
+- **O release era barrado pela suíte mais fraca das duas.** O projeto tinha
+  dois workflows, e a divisão escondia uma inversão:
+
+  | | rodava | barrava o release? |
+  | --- | --- | --- |
+  | `ci.yml` | ubuntu + macOS × Python 3.10/3.12/3.13 | **não** |
+  | `release.yml` | ubuntu × Python 3.12 | sim |
+
+  Ou seja, a suíte boa não protegia nada e o portão do PyPI era a magra.
+  `needs` não atravessa workflow — a mesma lição do P1-1, numa segunda forma.
+  Os dois arquivos ainda mantinham o job `lint` duplicado.
+
+  Agora é um workflow só, e quem barra a publicação é
+  **ubuntu × Python 3.10/3.11/3.12/3.13 + macOS × 3.12**.
+
+  ⚠️ O eixo de macOS foi reduzido de três versões de Python para uma. Rodar as
+  três dobrava a matriz para provar a mesma coisa; uma basta para pegar o que
+  o ubuntu não pega (link da extensão, caminhos, threads).
+
+### Adicionado
+
+- **Ensaio no TestPyPI** (`publish-testpypi`, por `workflow_dispatch`), que o
+  projeto não tinha. Valida a troca de token OIDC sem tocar no índice de
+  produção. ⚠️ Exige um publisher próprio cadastrado no TestPyPI.
+- **`fail-fast: false`** nas matrizes: um alvo que cai deixava de cancelar os
+  irmãos e apagar o diagnóstico deles.
+
+### Removido
+
+- **`.github/workflows/ci.yml`**, fundido no `release.yml`.
+
+## [0.2.3] - 2026-08-12
 
 Versão de empacotamento e qualidade: nada muda no comportamento da biblioteca.
 

{rust_py_cache-0.2.3 → rust_py_cache-0.3.0}/Cargo.lock

@@ -202,7 +202,7 @@ dependencies = [
 
 [[package]]
 name = "rust_py_cache"
-version = "0.2.3"
+version = "0.3.0"
 dependencies = [
  "dashmap",
  "pyo3",

{rust_py_cache-0.2.3 → rust_py_cache-0.3.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rust_py_cache"
-version = "0.2.3"
+version = "0.3.0"
 edition = "2021"
 license = "MIT"
 readme = "README.md"

{rust_py_cache-0.2.3 → rust_py_cache-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rust-py-cache
-Version: 0.2.3
+Version: 0.3.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: Implementation :: CPython
@@ -73,7 +73,7 @@ cache.stats()                 # {'hits','misses','sets','deletes','expired','evi
 
 ```python
 # Cap the number of keys. When full and a new key arrives, evict the
-# least-recently-used entry instead of rejecting the write.
+# least-recently-used entries (a ~3% batch) instead of rejecting the write.
 cache = Cache(max_size=1000, eviction_policy="lru")
 cache.eviction_policy            # "lru"
 
@@ -138,7 +138,12 @@ Constructor: `Cache(max_size=None, eviction_policy="reject", cleanup_interval=No
   accessed (`get`/`exists`) or via `cleanup_expired()`. Pass `cleanup_interval` to
   also run a **background** sweeper thread that reclaims expired keys on its own.
 - **Eviction:** with `max_size` + `eviction_policy="lru"`, a full cache evicts the
-  least-recently-used entry (recency updated on every `get` hit) to admit a new key.
+  least-recently-used entries (recency updated on every `get` hit) to admit a new key.
+  It removes them in a **batch** of `max_size / 32` (at least 1) per pass, so the
+  O(n) scan that finds them runs once every ~n/32 inserts instead of on every one —
+  amortized O(1) per write, with no global lock on the `get`/`set` path. A `set` on
+  a full 100k-entry cache went from ~620 µs (one full scan per insert, up to 0.2.x)
+  to ~1.6 µs. Right after a pass the cache sits ~3% below `max_size`.
 
 ## Limitations
 

{rust_py_cache-0.2.3 → rust_py_cache-0.3.0}/README.md

@@ -52,7 +52,7 @@ cache.stats()                 # {'hits','misses','sets','deletes','expired','evi
 
 ```python
 # Cap the number of keys. When full and a new key arrives, evict the
-# least-recently-used entry instead of rejecting the write.
+# least-recently-used entries (a ~3% batch) instead of rejecting the write.
 cache = Cache(max_size=1000, eviction_policy="lru")
 cache.eviction_policy            # "lru"
 
@@ -117,7 +117,12 @@ Constructor: `Cache(max_size=None, eviction_policy="reject", cleanup_interval=No
   accessed (`get`/`exists`) or via `cleanup_expired()`. Pass `cleanup_interval` to
   also run a **background** sweeper thread that reclaims expired keys on its own.
 - **Eviction:** with `max_size` + `eviction_policy="lru"`, a full cache evicts the
-  least-recently-used entry (recency updated on every `get` hit) to admit a new key.
+  least-recently-used entries (recency updated on every `get` hit) to admit a new key.
+  It removes them in a **batch** of `max_size / 32` (at least 1) per pass, so the
+  O(n) scan that finds them runs once every ~n/32 inserts instead of on every one —
+  amortized O(1) per write, with no global lock on the `get`/`set` path. A `set` on
+  a full 100k-entry cache went from ~620 µs (one full scan per insert, up to 0.2.x)
+  to ~1.6 µs. Right after a pass the cache sits ~3% below `max_size`.
 
 ## Limitations
 

{rust_py_cache-0.2.3 → rust_py_cache-0.3.0}/ROADMAP.md

@@ -36,16 +36,21 @@ the stages already shipped and what comes next.
 ### LRU eviction
 
 - ✅ `Cache(max_size=..., eviction_policy="lru")` evicts the **least-recently-used**
-  entry once the cap is hit (recency updated on every `get` hit). Default policy
+  entries once the cap is hit (recency updated on every `get` hit). Default policy
   is `"reject"` (backward compatible). Evictions are surfaced in `stats()` as an
   `evicted` counter.
+- ✅ **v0.3 — amortized O(1) eviction.** Evicts a batch of `max_size / 32` per
+  scan instead of one entry per scan, so a full cache under sustained writes no
+  longer pays an O(n) scan on every new key (~620 µs → ~1.6 µs per `set` at 100k
+  entries).
 
 ## Planned
 
-### v0.3 — LFU eviction
+### v0.4 — LFU eviction
 
 - 🔜 **Least-frequently-used** eviction policy as an alternative to LRU, selectable
-  at construction time (e.g. `Cache(max_size=..., policy="lfu")`).
+  at construction time (e.g. `Cache(max_size=..., policy="lfu")`). Reuses the
+  batch selection from v0.3, keyed on `hits` instead of `last_accessed_at`.
 
 ### v0.5 — Configurable serializer
 

{rust_py_cache-0.2.3 → rust_py_cache-0.3.0}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "maturin"
 
 [project]
 name = "rust-py-cache"
-version = "0.2.3"
+version = "0.3.0"
 description = "An ultra-fast local cache for Python, powered by Rust."
 readme = "README.md"
 requires-python = ">=3.10"

{rust_py_cache-0.2.3 → rust_py_cache-0.3.0}/python/rust_py_cache/__init__.py

@@ -19,4 +19,4 @@ class Cache(_RustCache):
 
 
 __all__ = ["Cache", "hello"]
-__version__ = "0.2.3"
+__version__ = "0.3.0"

{rust_py_cache-0.2.3 → rust_py_cache-0.3.0}/src/cache.rs

@@ -4,6 +4,8 @@
 //! de testar em Rust puro e para separar responsabilidades: `lib.rs` cuida da
 //! ponte com o Python; `cache.rs` cuida do armazenamento.
 
+use std::sync::Mutex;
+
 use dashmap::DashMap;
 
 use crate::entry::CacheEntry;
@@ -15,10 +17,14 @@ pub enum EvictionPolicy {
     /// Rejeita a escrita (`set` devolve `false`). Comportamento padrão.
     #[default]
     Reject,
-    /// Remove a entrada menos recentemente usada (LRU) para abrir espaço.
+    /// Remove as entradas menos recentemente usadas (LRU) para abrir espaço.
     Lru,
 }
 
+/// Fração de `max_size` removida de uma vez quando a LRU precisa abrir espaço
+/// (1/32 ≈ 3%, no mínimo 1 entrada). Ver [`RustCache::evict_lru_batch`].
+const EVICTION_BATCH_DIVISOR: usize = 32;
+
 /// Núcleo concorrente do cache.
 ///
 /// `DashMap` é um `HashMap` thread-safe com *sharding*: ele divide o mapa em
@@ -37,6 +43,11 @@ pub struct RustCache {
     max_size: Option<usize>,
     /// Política aplicada quando o cache enche e chega uma chave nova.
     eviction_policy: EvictionPolicy,
+    /// Serializa só o caminho de evicção: quando várias threads encontram o
+    /// cache cheio ao mesmo tempo, uma varre e as outras, ao entrar, veem que
+    /// já há espaço e seguem — sem N varreduras simultâneas. Não é tocado no
+    /// caminho comum de `get`/`set`.
+    eviction_lock: Mutex<()>,
 }
 
 impl RustCache {
@@ -47,6 +58,7 @@ impl RustCache {
             stats: CacheStats::new(),
             max_size,
             eviction_policy,
+            eviction_lock: Mutex::new(()),
         }
     }
 
@@ -55,17 +67,67 @@ impl RustCache {
         self.eviction_policy
     }
 
-    /// Remove a entrada com o menor `last_accessed_at` (a "menos recentemente
-    /// usada"). Varre o mapa uma vez — O(n) só na evicção (caminho raro: cache
-    /// cheio + chave nova). Conta em `evicted`.
-    fn evict_lru(&self) {
-        let oldest = self
+    /// Abre espaço removendo, de uma vez, as `max / 32` (no mínimo 1) entradas
+    /// menos recentemente usadas. Conta cada uma em `evicted`.
+    ///
+    /// ## Por que em lote
+    ///
+    /// Achar a entrada mais antiga num `DashMap` exige varrer o mapa inteiro —
+    /// não há ordem nem acesso aleatório. Até a 0.2 isso acontecia a **cada**
+    /// `set` de chave nova com o cache cheio, que é o regime normal de um cache
+    /// cheio sob escrita: O(n) por inserção. Removendo ~3% por varredura, a
+    /// próxima varredura só vem depois de outras ~n/32 inserções — custo
+    /// amortizado O(1) (≈ 64 visitas por inserção), sem lock global no caminho
+    /// comum e sem `unsafe` para amostrar shards.
+    ///
+    /// Uma lista LRU exata exigiria um lock global em todo `get`, que é o que o
+    /// `DashMap` existe para evitar. A amostragem estilo Redis exigiria acesso
+    /// aleatório às entradas, que o `DashMap` só oferece pela `raw-api`
+    /// (tabela interna do hashbrown, iteração `unsafe`).
+    ///
+    /// ## Como
+    ///
+    /// 1. Coleta só os `last_accessed_at` (um `Vec<u64>`, sem clonar chaves) e
+    ///    acha o corte do lote com `select_nth_unstable` — O(n), sem ordenar.
+    /// 2. Coleta as chaves com acesso `<= corte` (até o tamanho do lote).
+    /// 3. Remove com `remove_if`, que **recheca** o carimbo: uma chave lida por
+    ///    outra thread entre as fases deixou de ser LRU e fica.
+    fn evict_lru_batch(&self, max: usize) {
+        let _guard = self
+            .eviction_lock
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        // Outra thread pode ter aberto espaço enquanto esperávamos o lock.
+        if self.store.len() < max {
+            return;
+        }
+
+        let mut stamps: Vec<u64> = self
             .store
             .iter()
-            .min_by_key(|e| e.value().last_accessed_at)
-            .map(|e| e.key().clone());
-        if let Some(key) = oldest {
-            if self.store.remove(&key).is_some() {
+            .map(|e| e.value().last_accessed_at)
+            .collect();
+        if stamps.is_empty() {
+            return;
+        }
+        let batch = (max / EVICTION_BATCH_DIVISOR).clamp(1, stamps.len());
+        let (_, &mut cutoff, _) = stamps.select_nth_unstable(batch - 1);
+        drop(stamps);
+
+        let victims: Vec<String> = self
+            .store
+            .iter()
+            .filter(|e| e.value().last_accessed_at <= cutoff)
+            .take(batch)
+            .map(|e| e.key().clone())
+            .collect();
+
+        for key in victims {
+            if self
+                .store
+                .remove_if(&key, |_, v| v.last_accessed_at <= cutoff)
+                .is_some()
+            {
                 self.stats.record_evicted();
             }
         }
@@ -79,14 +141,15 @@ impl RustCache {
     ///
     /// Sobrescrever uma chave existente sempre é permitido. Para uma chave
     /// **nova** com o cache cheio (`max_size`): com `Reject` devolve `false` sem
-    /// inserir; com `Lru` remove a entrada menos recentemente usada e prossegue.
+    /// inserir; com `Lru` remove um lote das menos recentemente usadas (ver
+    /// [`Self::evict_lru_batch`]) e prossegue.
     /// Devolve `true` quando a entrada foi (ou seria) gravada.
     pub fn set(&self, key: String, value: Vec<u8>, expires_at: Option<u64>, now: u64) -> bool {
         if let Some(max) = self.max_size {
             if self.store.len() >= max && !self.store.contains_key(&key) {
                 match self.eviction_policy {
                     EvictionPolicy::Reject => return false,
-                    EvictionPolicy::Lru => self.evict_lru(),
+                    EvictionPolicy::Lru => self.evict_lru_batch(max),
                 }
             }
         }
@@ -314,6 +377,45 @@ mod tests {
         assert!(c.get("c", NOW + 11).is_some());
     }
 
+    #[test]
+    fn lru_evicts_a_batch_of_the_oldest() {
+        // max 64 => lote de 64/32 = 2.
+        let c = RustCache::new(Some(64), EvictionPolicy::Lru);
+        for i in 0..64u64 {
+            c.set(format!("k{i}"), b"v".to_vec(), None, NOW + i);
+        }
+        // k0 e k1 são as mais antigas; tocar em k0 a torna a mais recente.
+        assert!(c.get("k0", NOW + 100).is_some());
+        assert!(c.set("new".into(), b"v".to_vec(), None, NOW + 101));
+        assert_eq!(c.stats().evicted, 2);
+        assert_eq!(c.len(), 63);
+        assert!(c.exists("k0", NOW + 102));
+        assert!(!c.exists("k1", NOW + 102));
+        assert!(!c.exists("k2", NOW + 102));
+        assert!(c.exists("k3", NOW + 102));
+        assert!(c.exists("new", NOW + 102));
+    }
+
+    #[test]
+    fn lru_amortizes_the_scan() {
+        // Escrita sustentada com o cache cheio: o número de varreduras é
+        // ~inserções / lote, não uma por inserção.
+        let max = 1_024;
+        let c = RustCache::new(Some(max), EvictionPolicy::Lru);
+        for i in 0..(max as u64 * 4) {
+            c.set(format!("k{i}"), b"v".to_vec(), None, NOW + i);
+            assert!(c.len() <= max);
+        }
+        let evicted = c.stats().evicted;
+        let batch = (max / EVICTION_BATCH_DIVISOR) as u64;
+        assert_eq!(evicted % batch, 0, "sempre um lote cheio por varredura");
+        // 3 * max inserções além da capacidade => ~3 * 32 varreduras.
+        assert!(evicted / batch <= 3 * EVICTION_BATCH_DIVISOR as u64 + 1);
+        // As sobreviventes são as mais recentes.
+        assert!(c.exists(&format!("k{}", max as u64 * 4 - 1), NOW));
+        assert!(!c.exists("k0", NOW));
+    }
+
     #[test]
     fn no_max_size_never_evicts() {
         let c = RustCache::new(None, EvictionPolicy::Lru);

{rust_py_cache-0.2.3 → rust_py_cache-0.3.0}/src/entry.rs

@@ -18,7 +18,7 @@ pub struct CacheEntry {
     pub expires_at: Option<u64>,
     /// Quando a entrada foi criada (epoch-ms).
     pub created_at: u64,
-    /// Último acesso por `get` bem-sucedido (epoch-ms) — base para LRU futuro.
+    /// Último acesso por `get` bem-sucedido (epoch-ms) — base da evicção LRU.
     pub last_accessed_at: u64,
     /// Quantas vezes esta entrada foi lida — base para LFU futuro.
     pub hits: u64,

{rust_py_cache-0.2.3 → rust_py_cache-0.3.0}/tests/test_eviction.py

@@ -48,6 +48,21 @@ def test_lru_evicts_to_make_room():
     assert cache.stats()["evicted"] == 1
 
 
+def test_lru_evicts_in_batches_and_stays_bounded():
+    # max_size 320 => lote de 10 por varredura.
+    cache = Cache(max_size=320, eviction_policy="lru")
+    for i in range(320):
+        cache.set(f"k{i}", i)
+    cache.set("new", 1)
+    assert cache.stats()["evicted"] == 10
+    assert len(cache) == 311
+    assert cache.get("new") == 1
+    for i in range(5_000):
+        cache.set(f"x{i}", i)
+        assert len(cache) <= 320
+    assert cache.stats()["evicted"] % 10 == 0
+
+
 def test_lru_keeps_recently_used():
     cache = Cache(max_size=2, eviction_policy="lru")
     cache.set("a", 1)

rust_py_cache-0.2.3/.github/workflows/ci.yml

@@ -1,71 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-  workflow_dispatch:
-
-jobs:
-  # O lint faz parte do portão de release, não de um workflow paralelo.
-  # Nos repositórios de workflow único, um `lint` vermelho ao lado de uma
-  # publicação bem-sucedida seria ruído difícil de ler — a leitura passa a ser
-  # inequívoca: vermelho significa que não publicou.
-  #
-  # A toolchain é fixa, não "stable": com `-D warnings`, um clippy mais novo
-  # no runner reprova código que ninguém tocou, e a CI ficaria vermelha por
-  # conta do calendário. Subir este número vira uma mudança deliberada.
-  lint:
-    name: fmt + clippy
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@1.88.0
-        with:
-          components: rustfmt, clippy
-      - uses: Swatinem/rust-cache@v2
-      - name: cargo fmt
-        run: cargo fmt --all -- --check
-      # clippy só checa tipos, não linka, então --all-features é seguro aqui
-      # (diferente do `cargo test`, que precisa de --no-default-features).
-      - name: cargo clippy
-        run: cargo clippy --all-targets --all-features -- -D warnings
-
-  test:
-    name: cargo test + pytest
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-        python-version: ["3.10", "3.12", "3.13"]
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Set up Rust
-        uses: dtolnay/rust-toolchain@stable
-
-      - name: Cache cargo
-        uses: Swatinem/rust-cache@v2
-
-      # --no-default-features desliga extension-module, que manda o linker
-      # deixar os símbolos da libpython indefinidos. Isso é correto para a
-      # wheel, mas produz um binário de teste que não linka no Linux.
-      - name: cargo test
-        env:
-          PYO3_PYTHON: python
-        run: cargo test --no-default-features --lib
-
-      # `pip install` aciona o backend maturin, que compila a extensão e a
-      # instala no Python do runner — sem exigir virtualenv, ao contrário do
-      # `maturin develop`, que aborta quando não encontra um.
-      - name: Build, install the extension and run the Python tests
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install ".[dev]"
-          python -m pytest -q

rust_py_cache-0.2.3/.github/workflows/release.yml

@@ -1,256 +0,0 @@
-name: Release
-
-# Dispara ao publicar uma tag de versão (ex.: v0.1.0). Constrói as wheels para
-# todas as plataformas + sdist e publica no PyPI via Trusted Publishing (OIDC),
-# sem precisar guardar um token no repositório.
-#
-# O `ci.yml` roda em push/PR, mas é um workflow *separado*: um push de tag ia
-# direto para build e publicação sem depender dele. O job `test` abaixo é o que
-# torna a publicação condicionada a uma suíte verde — publicar no PyPI é
-# irreversível, então não pode acontecer sobre código não verificado.
-on:
-  push:
-    tags: ["v*"]
-  workflow_dispatch: {}
-
-permissions:
-  contents: read
-
-jobs:
-  # O lint faz parte do portão de release, não de um workflow paralelo.
-  # Nos repositórios de workflow único, um `lint` vermelho ao lado de uma
-  # publicação bem-sucedida seria ruído difícil de ler — a leitura passa a ser
-  # inequívoca: vermelho significa que não publicou.
-  #
-  # A toolchain é fixa, não "stable": com `-D warnings`, um clippy mais novo
-  # no runner reprova código que ninguém tocou, e a CI ficaria vermelha por
-  # conta do calendário. Subir este número vira uma mudança deliberada.
-  lint:
-    name: fmt + clippy
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@1.88.0
-        with:
-          components: rustfmt, clippy
-      - uses: Swatinem/rust-cache@v2
-      - name: cargo fmt
-        run: cargo fmt --all -- --check
-      # clippy só checa tipos, não linka, então --all-features é seguro aqui
-      # (diferente do `cargo test`, que precisa de --no-default-features).
-      - name: cargo clippy
-        run: cargo clippy --all-targets --all-features -- -D warnings
-
-  test:
-    name: Test (Rust + Python)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-      - name: cargo test
-        env:
-          PYO3_PYTHON: python
-        run: cargo test --no-default-features --lib
-      - name: Build, install the extension and run the Python tests
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install ".[dev]"
-          python -m pytest -q
-
-  # A matriz abaixo substitui um job `build` que rodava em ubuntu/macos/windows
-  # com `maturin build` puro. Aquilo publicava 3 wheels e o de Linux herdava a
-  # glibc do runner, em vez de passar pelo container manylinux. Quem estava em
-  # aarch64, em musl ou em Mac Intel caía no sdist — que exige toolchain Rust.
-  linux:
-    runs-on: ubuntu-latest
-    if: startsWith(github.ref, 'refs/tags/')
-    needs: [test, lint]
-    strategy:
-      matrix:
-        target: [x86_64, aarch64]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: PyO3/maturin-action@v1
-        with:
-          target: ${{ matrix.target }}
-          args: --release --out dist
-          # `auto` constrói dentro do container manylinux, então a wheel
-          # declara um piso de glibc portável em vez do da máquina de build.
-          manylinux: auto
-      - uses: actions/upload-artifact@v4
-        with:
-          name: wheels-linux-${{ matrix.target }}
-          path: dist
-
-  musllinux:
-    runs-on: ubuntu-latest
-    if: startsWith(github.ref, 'refs/tags/')
-    needs: [test, lint]
-    strategy:
-      matrix:
-        target: [x86_64, aarch64]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: PyO3/maturin-action@v1
-        with:
-          target: ${{ matrix.target }}
-          args: --release --out dist
-          manylinux: musllinux_1_2
-      - uses: actions/upload-artifact@v4
-        with:
-          name: wheels-musllinux-${{ matrix.target }}
-          path: dist
-
-  windows:
-    runs-on: windows-latest
-    if: startsWith(github.ref, 'refs/tags/')
-    needs: [test, lint]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          architecture: x64
-      - uses: PyO3/maturin-action@v1
-        with:
-          target: x64
-          args: --release --out dist
-      - uses: actions/upload-artifact@v4
-        with:
-          name: wheels-windows-x64
-          path: dist
-
-  macos:
-    runs-on: macos-latest
-    if: startsWith(github.ref, 'refs/tags/')
-    needs: [test, lint]
-    strategy:
-      matrix:
-        target: [x86_64, aarch64]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: PyO3/maturin-action@v1
-        with:
-          target: ${{ matrix.target }}
-          args: --release --out dist
-      - uses: actions/upload-artifact@v4
-        with:
-          name: wheels-macos-${{ matrix.target }}
-          path: dist
-
-  sdist:
-    runs-on: ubuntu-latest
-    if: startsWith(github.ref, 'refs/tags/')
-    needs: [test, lint]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: PyO3/maturin-action@v1
-        with:
-          command: sdist
-          args: --out dist
-      - uses: actions/upload-artifact@v4
-        with:
-          name: wheels-sdist
-          path: dist
-
-  publish:
-    name: publish to PyPI
-    # Guarda além do gatilho: sem ela, um `workflow_dispatch` a partir de um
-    # branch publicaria no PyPI.
-    if: startsWith(github.ref, 'refs/tags/')
-    needs: [lint, test, linux, musllinux, windows, macos, sdist]
-    runs-on: ubuntu-latest
-    environment: pypi
-    permissions:
-      id-token: write   # necessário para o Trusted Publishing (OIDC)
-    steps:
-      - uses: actions/download-artifact@v4
-        with:
-          pattern: wheels-*
-          merge-multiple: true
-          path: dist
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      # Conferência antes de qualquer coisa sair do runner: publicar um
-      # conjunto incompleto é pior que não publicar, porque o PyPI nunca deixa
-      # reusar um nome de arquivo — uma versão meio-publicada só pode ser
-      # completada, nunca substituída.
-      - name: Verify the artifact set is complete
-        run: |
-          set -euo pipefail
-          ls -la dist/
-          test -n "$(find dist -name '*.tar.gz' -print -quit)" \
-            || { echo "::error::sdist ausente — abortando antes de publicar"; exit 1; }
-          wheels=$(find dist -name '*.whl' | wc -l)
-          echo "wheels: $wheels"
-          test "$wheels" -ge 7 \
-            || { echo "::error::só $wheels wheels; esperado >= 7 (2 linux, 2 musl, 1 win, 2 macos)"; exit 1; }
-
-      # O PyPI devolve 500 transitório com frequência suficiente para importar,
-      # e o upload é arquivo por arquivo: uma falha no meio deixa a versão
-      # publicada pela metade. `skip-existing` é o que torna a segunda
-      # tentativa segura — sem ele, ela morre nos arquivos que já subiram.
-      #
-      # São dois passos explícitos em vez de um wrapper de retry porque o
-      # trusted publishing (OIDC) exige a action oficial, que não dá para
-      # acionar por linha de comando.
-      - name: Publish to PyPI (attempt 1)
-        id: publish1
-        continue-on-error: true
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          packages-dir: dist
-          skip-existing: true
-
-      - name: Wait before retrying
-        if: steps.publish1.outcome == 'failure'
-        run: sleep 45
-
-      - name: Publish to PyPI (attempt 2)
-        if: steps.publish1.outcome == 'failure'
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          packages-dir: dist
-          skip-existing: true
-
-      # Prova que a release está completa, em vez de confiar num código de
-      # saída que uma publicação parcial também produz.
-      - name: Verify every file reached PyPI
-        run: |
-          set -euo pipefail
-          python -m pip install --quiet requests
-          python - <<'PY'
-          import os, sys, glob, time, requests
-          version = os.environ["GITHUB_REF_NAME"].lstrip("v")
-          # Só .whl e .tar.gz: são os únicos tipos de arquivo que o PyPI hospeda.
-          # `pypa/gh-action-pypi-publish` deixa um .publish.attestation por
-          # distribuição em dist/ depois de publicar (atestados PEP 740, que
-          # sobem junto do arquivo, não como arquivo próprio). Um glob amplo os
-          # conta como "faltando no PyPI" e reprova uma release que deu certo.
-          local = {
-              os.path.basename(p)
-              for pattern in ("dist/*.whl", "dist/*.tar.gz")
-              for p in glob.glob(pattern)
-          }
-          url = f"https://pypi.org/pypi/rust-py-cache/{version}/json"
-          for attempt in range(6):          # a API JSON do PyPI é cacheada
-              response = requests.get(url, timeout=30)
-              if response.status_code == 200:
-                  remote = {f["filename"] for f in response.json()["urls"]}
-                  missing = local - remote
-                  if not missing:
-                      print(f"OK: {len(remote)} arquivos publicados na {version}")
-                      sys.exit(0)
-              else:
-                  missing = local
-              print(f"tentativa {attempt + 1}: faltam {len(missing)}")
-              time.sleep(20)
-          print("::error::faltaram arquivos no PyPI:")
-          for name in sorted(missing):
-              print(f"  - {name}")
-          sys.exit(1)
-          PY