rust-py-scheduler 0.2.3__tar.gz

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

@@ -0,0 +1,387 @@
+# Base structure autogenerated by maturin v1.14.0
+# (maturin generate-ci github), then extended with a `test` job that runs the
+# Rust and Python suites on every push/PR. Every wheel build — and the
+# release — depends on `test`, so a change that breaks the tests never gets
+# packaged or published.
+name: CI / Release
+
+# ⚠️ O nome deste arquivo é parte da configuração de publicação. O trusted
+# publisher cadastrado no PyPI amarra `release.yml`; renomear aqui quebra a
+# release até o cadastro ser refeito. Era `CI.yml` até 12/08/2026.
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    tags:
+      # `v*`, não `*`. Com o filtro aberto, QUALQUER tag empurrada disparava o
+      # job de release — que só checa `startsWith(github.ref, 'refs/tags/')` —
+      # e uma tag de anotação qualquer teria ido ao PyPI. Os outros quatro
+      # projetos sempre usaram `v*`.
+      - 'v*'
+  pull_request:
+  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@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+      - name: Rust unit tests
+        # --no-default-features drops the extension-module feature so the test
+        # binary can link against libpython on the runner.
+        env:
+          PYO3_PYTHON: python
+        run: cargo test --no-default-features --lib
+      - name: Build, install the extension, and run Python tests
+        # `pip install` drives the maturin build backend, so it compiles the
+        # Rust extension and installs it (plus the dev extras) into the
+        # runner's Python — no virtualenv needed, unlike `maturin develop`.
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev]"
+          python -m pytest
+
+  linux:
+    runs-on: ${{ matrix.platform.runner }}
+    needs: [test, lint]
+    strategy:
+      # Sem isto, um alvo que cai CANCELA os irmãos. Foi o que escondeu o
+      # estado de armv7/s390x/ppc64le quando o build x86 quebrou no 403 do
+      # vault.centos.org, em 12/08/2026: uma falha apagou o diagnóstico
+      # das outras cinco.
+      fail-fast: false
+      matrix:
+        platform:
+          - runner: ubuntu-22.04
+            target: x86_64
+          - runner: ubuntu-22.04
+            target: x86
+          - runner: ubuntu-22.04
+            target: aarch64
+          - runner: ubuntu-22.04
+            target: armv7
+          - runner: ubuntu-22.04
+            target: s390x
+          - runner: ubuntu-22.04
+            target: ppc64le
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+          manylinux: auto
+      - name: Upload wheels
+        uses: actions/upload-artifact@v6
+        with:
+          name: wheels-linux-${{ matrix.platform.target }}
+          path: dist
+
+  musllinux:
+    runs-on: ${{ matrix.platform.runner }}
+    needs: [test, lint]
+    strategy:
+      # Uma falha não pode apagar o diagnóstico das outras.
+      fail-fast: false
+      matrix:
+        platform:
+          - runner: ubuntu-22.04
+            target: x86_64
+          - runner: ubuntu-22.04
+            target: x86
+          - runner: ubuntu-22.04
+            target: aarch64
+          - runner: ubuntu-22.04
+            target: armv7
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+          manylinux: musllinux_1_2
+      - name: Upload wheels
+        uses: actions/upload-artifact@v6
+        with:
+          name: wheels-musllinux-${{ matrix.platform.target }}
+          path: dist
+
+  windows:
+    runs-on: ${{ matrix.platform.runner }}
+    needs: [test, lint]
+    strategy:
+      # Uma falha não pode apagar o diagnóstico das outras.
+      fail-fast: false
+      matrix:
+        platform:
+          - runner: windows-latest
+            target: x64
+            python_arch: x64
+          - runner: windows-latest
+            target: x86
+            python_arch: x86
+          - runner: windows-11-arm
+            target: aarch64
+            python_arch: arm64
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          architecture: ${{ matrix.platform.python_arch }}
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+      - name: Upload wheels
+        uses: actions/upload-artifact@v6
+        with:
+          name: wheels-windows-${{ matrix.platform.target }}
+          path: dist
+
+  macos:
+    runs-on: ${{ matrix.platform.runner }}
+    needs: [test, lint]
+    strategy:
+      # Uma falha não pode apagar o diagnóstico das outras.
+      fail-fast: false
+      matrix:
+        platform:
+          - runner: macos-15-intel
+            target: x86_64
+          - runner: macos-latest
+            target: aarch64
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+      - name: Upload wheels
+        uses: actions/upload-artifact@v6
+        with:
+          name: wheels-macos-${{ matrix.platform.target }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - name: Upload sdist
+        uses: actions/upload-artifact@v6
+        with:
+          name: wheels-sdist
+          path: dist
+
+  # Ensaio da troca OIDC, sem tocar no índice de produção. Descobre um
+  # publisher mal cadastrado num lugar onde nada é irreversível — 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 owner/repo, workflow `release.yml` e environment `testpypi`.
+  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@v7
+        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
+
+  release:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    # Só tag. Antes este job também rodava em `workflow_dispatch` porque o
+    # atestado de artefato vivia aqui; o ensaio manual virou o job acima, então
+    # a guarda pôde ficar estrita — e os `if:` que cada passo repetia sumiram.
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: [lint, test, linux, musllinux, windows, macos, sdist]
+
+    # Trusted publishing (OIDC): o `UV_PUBLISH_TOKEN` deixou de existir. 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.
+    # Era o último dos cinco publicando com segredo de longa duração.
+    #
+    # ⚠️ Os três valores precisam bater EXATAMENTE com o publisher cadastrado
+    # em PyPI → Manage → Publishing:
+    #   owner/repo .... robertolima-dev/rust-py-scheduler
+    #   workflow ...... release.yml   (renomeado de CI.yml em 12/08/2026)
+    #   environment ... pypi
+    environment: pypi
+    permissions:
+      # Troca OIDC do trusted publishing e assinatura do atestado.
+      id-token: write
+      contents: write
+      attestations: write
+
+    steps:
+      # `dist/` com merge-multiple, no lugar dos diretórios `wheels-*/` que a
+      # forma antiga produzia — é o layout que os outros quatro projetos usam,
+      # e o que `packages-dir` da action oficial espera.
+      - uses: actions/download-artifact@v7
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      # Atestado do Actions (sigstore), independente dos atestados PEP 740 que
+      # o publicador gera depois — sistemas diferentes, ambos úteis.
+      - name: Generate artifact attestation
+        uses: actions/attest@v4
+        with:
+          subject-path: 'dist/*'
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install the verification dependency
+        run: python -m pip install --upgrade requests
+
+      # A sanity check before anything leaves the runner: publishing an
+      # incomplete set is worse than not publishing, because PyPI never lets a
+      # filename be reused — a half-uploaded version can only be completed,
+      # never replaced.
+      - 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 15 \
+            || { echo "::error::só $wheels wheels; esperado >= 15 (6 linux, 4 musl, 3 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 — faz o papel que o `--check-url` do `uv publish`
+      # fazia aqui antes.
+      #
+      # São dois passos explícitos em vez de um wrapper de retry porque o
+      # trusted publishing exige a action oficial, e ela não dá para acionar
+      # por linha de comando de dentro do `nick-fields/retry`.
+      - 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
+
+      # Proves the release is actually complete, rather than trusting an exit
+      # code that a partial upload can still produce.
+      - name: Verify every file reached PyPI
+        run: |
+          set -euo pipefail
+          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-scheduler/{version}/json"
+          for attempt in range(6):          # PyPI's JSON API is cached
+              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_scheduler-0.2.3/.gitignore

@@ -0,0 +1,7 @@
+/target
+.venv/
+__pycache__/
+*.pyc
+*.so
+*.pyd
+.pytest_cache/

rust_py_scheduler-0.2.3/CHANGELOG.md

@@ -0,0 +1,218 @@
+# Changelog
+
+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] — 2026-08-12
+
+Migração para trusted publishing. Nada muda no comportamento da biblioteca.
+Era o último dos cinco `rust_py_*` publicando com segredo de longa duração.
+
+### Alterado
+
+- **Publicação por trusted publishing (OIDC)**, no lugar de
+  `secrets.PYPI_API_TOKEN` + `uv publish`. O GitHub emite um JWT curto
+  afirmando repositório, workflow e ref, e o PyPI o troca por um token de
+  upload válido por poucos minutos e restrito a este projeto. O upload passou
+  a ser dois `pypa/gh-action-pypi-publish` explícitos com
+  `skip-existing: true`, que faz o papel que o `--check-url` do `uv publish`
+  fazia: tornar a segunda tentativa segura.
+
+  Diferente do `rust_py_monitor`, aqui **não havia bug a consertar** — o
+  `uv publish` já transmitia o metadado de licença corretamente, e a 0.2.2 saiu
+  com `license_expression: MIT`. Esta migração é higiene de segredo e
+  convergência de forma.
+
+  ⚠️ **Depende de cadastro no PyPI**, com os valores batendo exatamente:
+  `robertolima-dev` / `rust-py-scheduler` / `release.yml` / `pypi`. Sem o
+  publisher, o job falha na troca do token — depois de construir tudo e antes
+  de qualquer arquivo sair do runner.
+
+- **`CI.yml` renomeado para `release.yml`.** O trusted publisher cadastrado no
+  PyPI amarra o nome do arquivo de workflow, então o rename precisou vir
+  **antes** do cadastro — renomear depois obrigaria a cadastrar de novo. Alinha
+  com os outros quatro projetos e é pré-requisito do `release.yml` único do
+  template (**P3-1**).
+
+- **Artefatos passam por `dist/`** (`merge-multiple: true`) no lugar dos
+  diretórios `wheels-*/`. É o layout que `packages-dir` espera e o que os
+  outros quatro já usam. Os dois passos de verificação e o atestado foram
+  ajustados para o novo caminho.
+
+- **O job de release ficou restrito a tag.** Antes ele também rodava em
+  `workflow_dispatch`, porque o atestado de artefato vivia nele; o ensaio
+  manual virou um job próprio (`publish-testpypi`, apontando para o TestPyPI),
+  então a guarda pôde ficar estrita e os `if:` repetidos em cada passo sumiram.
+
+### Corrigido
+
+- **Filtro de tag fechado para `v*`.** Era `'*'`, ou seja, **qualquer** tag
+  empurrada disparava o workflow — e o job de release só checava
+  `startsWith(github.ref, 'refs/tags/')`, que é verdadeiro para qualquer tag.
+  Uma tag de anotação, de rascunho ou de qualquer outra finalidade teria ido
+  ao PyPI. Os outros quatro projetos sempre usaram `v*`.
+
+- **`fail-fast: false` nas quatro matrizes de build.** O padrão do GitHub
+  cancela os alvos irmãos quando um cai. Em 12/08/2026 o build `x86` quebrou
+  num 403 do `vault.centos.org` (CentOS 7 EOL, instabilidade de mirror) e
+  levou junto o diagnóstico de `armv7`, `s390x` e `ppc64le` — não dava para
+  saber se tinham falhado ou apenas sido interrompidos. Uma falha não pode
+  apagar a informação das outras.
+
+## [0.2.2] - 2026-08-12
+
+Correção do passo de verificação pós-upload, mais o trabalho de licença e lint
+de 12/08/2026 (**P1-4** e **P1-6**).
+
+### Adicionado
+
+- **`LICENSE`** (MIT). O projeto declarava MIT no `Cargo.toml` e no
+  `pyproject.toml` desde sempre, mas o texto não existia no repositório
+  (**P1-4**). Era o único dos cinco cujo metadado no PyPI já estava certo
+  (`license_expression: MIT`, graças à maturin 1.14 que ele já exigia) e ainda
+  assim sem o arquivo — metadado e texto são coisas separadas.
+- **Job `lint`** (`cargo fmt --check` + `cargo clippy -D warnings`) no
+  `CI.yml`, com `needs: [test, lint]` nos jobs de build e no de publicação —
+  o lint barra a release, igual ao `test`. Toolchain fixa em `1.88.0`.
+- **`clippy.toml` e `Makefile`** compartilhados com os outros quatro
+  `rust_py_*`. O `clippy.toml` sobe `too-many-arguments-threshold` para 10, e
+  é o que silencia os dois `too_many_arguments` deste projeto: `add_job()` leva
+  8 parâmetros porque a API Python leva 8 (`retry_backoff`, `timeout`,
+  `max_instances` e afins). Reagrupar em struct pioraria a API que o usuário vê.
+
+### Corrigido
+
+- **Formatação.** `cargo fmt --all` aplicado (12 blocos divergentes). Os 55
+  testes Rust seguem passando.
+
+- **Declaração de licença no formato do PEP 639.** Entrou
+  `license-files = ["LICENSE"]` e o classifier `License :: OSI Approved` saiu,
+  por ser mutuamente exclusivo com `License-Expression` no Metadata 2.4.
+
+### Corrigido — pipeline
+
+- **Falso negativo na verificação pós-publicação.** O passo comparava
+  `glob("wheels-*/*")` com o que estava no PyPI, o que conta qualquer arquivo
+  que apareça nos diretórios de artefato — não só distribuições. O passo agora
+  só considera `*.whl` e `*.tar.gz`, os únicos tipos de arquivo que o PyPI
+  hospeda. Foi o `rust_py_rate_limit` que expôs o problema: lá o publicador
+  deixa um `.publish.attestation` por distribuição, e a verificação reprovou
+  uma release que tinha subido inteira.
+
+**Não vai ao PyPI sozinha:** a 0.2.0 está lá completa e a 0.2.1/0.2.2 só mexem
+no pipeline. Os números ficam reservados e saem com a próxima mudança que valha
+uma tag.
+
+## [0.2.1] — não publicada
+
+Versão de infraestrutura: nada muda no comportamento da biblioteca.
+
+**Não foi ao PyPI de propósito.** A 0.2.0 está completa lá (ver a nota abaixo)
+e esta versão só mexe no pipeline de publicação, então uma release dela seria
+ruído para quem usa a biblioteca — as melhorias já valem no próximo release,
+que herda o workflow. O número fica reservado aqui e sai junto com a próxima
+mudança que valha uma tag.
+
+### Corrigido
+
+- **O upload aguenta o 500 do PyPI.** A publicação da 0.2.0 morreu num
+  `500 Internal Server Error` do `upload.pypi.org` no meio da fila, deixando
+  11 dos 16 arquivos publicados — faltaram a wheel musllinux x86_64, as três
+  de Windows e o sdist. O passo de publicação agora tem retry (4 tentativas).
+- **O retry ficou seguro.** O `uv publish` só pula arquivos que consegue
+  confirmar que já estão no índice; sem `--check-url` uma segunda tentativa
+  podia falhar de vez nos arquivos que já tinham subido. O parâmetro foi
+  acrescentado.
+- **Conferência dos dois lados.** O job de release valida o conjunto de
+  artefatos **antes** de publicar (aborta se faltar o sdist ou se houver menos
+  wheels que o esperado) e confere contra a API do PyPI **depois**, listando
+  nome por nome o que não chegou.
+
+### Nota sobre a 0.2.0
+
+A 0.2.0 chegou ao PyPI com 11 dos 16 arquivos por causa do erro descrito
+acima, e **foi completada por um re-run em 11/08/2026** — hoje tem os 16
+arquivos, com sdist. Ou seja, a 0.2.0 é válida e é a versão a usar; esta 0.2.1
+não muda uma linha da biblioteca, só o pipeline que a publica.
+
+## [0.2.0] - 2026-08-11
+
+Quatro correções de P0 do BACKLOG2, todas no mesmo release porque as três
+últimas mexem no mesmo caminho de execução.
+
+### Corrigido
+
+- **Deriva acumulada no intervalo (P0-3).** O reagendamento usava
+  `Instant::now()` depois de o callback terminar, então o período real era
+  `intervalo + duração do callback`: um `every("60s")` com callback de 5s
+  rodava a cada 65s e perdia ~1h de execuções por dia. Agora o próximo
+  deadline é ancorado no deadline que acabou de disparar, mantendo a cadência
+  na grade `t0 + n * intervalo`.
+- **Retry em rajada (P0-4a).** As tentativas disparavam coladas, sem espera —
+  `max_retries=5` contra uma API fora do ar virava 6 chamadas em sequência,
+  martelando o serviço que já estava caído. Agora há backoff exponencial com
+  jitter entre as tentativas.
+- **Um job pendurado congelava o scheduler (P0-4b).** Os callbacks rodavam em
+  sequência dentro do loop de agendamento, que é single-thread: um callback
+  travado parava *todos* os outros jobs. Agora existe um pool de workers e o
+  loop só despacha.
+- **Mutex envenenado derrubava tudo em cascata (P0-5).** Havia 14
+  `.expect("... mutex poisoned")` em caminho de produção. Bastava uma thread
+  entrar em pânico segurando o lock para toda chamada seguinte (`add_job`,
+  `remove_job`, `list_jobs`, o próprio loop) entrar em pânico, permanentemente.
+  Agora todos recuperam com `unwrap_or_else(|p| p.into_inner())`.
+
+### Adicionado
+
+- `Scheduler(max_workers=4)` — tamanho do pool de workers.
+- `every(...)` e `cron(...)` aceitam:
+  - `retry_backoff=0.5` — base do backoff exponencial entre tentativas. A
+    espera dobra a cada tentativa, é limitada a 30s e recebe jitter. `0`
+    restaura o comportamento anterior (imediato).
+  - `timeout=None` — segundos após os quais o scheduler para de esperar por
+    uma execução.
+  - `max_instances=1` — quantas execuções do mesmo job podem se sobrepor.
+- **Política de misfire.** Quando um job fica para trás em um ou mais ciclos
+  inteiros, ele pula para o próximo deadline futuro e roda uma vez — em vez de
+  disparar de uma vez todas as execuções perdidas.
+- **Coalescing.** Com `max_instances` saturado, o tick que vence é descartado e
+  contado em `coalesced_count`, em vez de enfileirar execuções que o job nunca
+  vai alcançar.
+- `list_jobs()` ganhou as chaves `retry_backoff`, `timeout`, `max_instances`,
+  `running`, `coalesced_count` e `timeout_count`.
+
+### Alterado — atenção ao atualizar
+
+- **O padrão de retry mudou.** Antes as tentativas eram imediatas; agora
+  esperam `retry_backoff` (0,5s de base) entre elas. Código que dependia de
+  `max_retries` resolver dentro do mesmo tick precisa ou de mais tempo, ou de
+  `retry_backoff=0`.
+- **Callbacks agora rodam em threads de worker**, não na thread que chamou
+  `run()`. Callback que dependia de estado preso a uma thread específica
+  (`threading.local`, por exemplo) precisa ser revisto. Dois callbacks do mesmo
+  job não se sobrepõem por padrão (`max_instances=1`), mas callbacks de jobs
+  diferentes agora podem rodar ao mesmo tempo.
+- `Scheduler()` continua funcionando sem argumento; `max_workers` tem padrão.
+
+### Limitação conhecida
+
+- **`timeout` não mata o callback.** Não existe forma segura de interromper
+  código Python arbitrário a partir de outra thread. O que o timeout faz é
+  limitar a exposição do *scheduler*: marca a execução como estourada, devolve
+  a vaga de `max_instances` e para de contabilizá-la. A thread do worker segue
+  presa dentro do Python até o callback retornar por conta própria — ou seja,
+  um job que pendura para sempre custa um worker para sempre. Por isso
+  `shutdown()` pode bloquear esperando um callback assim.
+
+## [0.1.5]
+
+### Adicionado
+
+- `Scheduler` com `every()` / `cron()`, nas formas de chamada direta e de
+  decorator.
+- Expressões cron de 5 campos, avaliadas no fuso local.
+- `list_jobs()`, `remove_job()`, `run()`, `start_background()`, `shutdown()`.
+- `max_retries` por job.
+- Integrações para FastAPI e Django.