googleapis-without-429 0.1.0__tar.gz

googleapis_without_429-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # Callable from the release workflow, so a tag runs the very same checks
+  # rather than a second copy of them that can drift.
+  workflow_call:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: tests (python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v7
+      # Pinned to the full version: this action publishes no major-tag alias.
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: make test
+
+  quality:
+    name: lint, format and types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Pinned to the full version: this action publishes no major-tag alias.
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: make lint
+      - run: make check-format
+      - run: make typecheck
+
+  build:
+    name: package builds and installs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Pinned to the full version: this action publishes no major-tag alias.
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+      - run: uv build
+      # Nothing in git stops a file from reaching an artefact: internal notes
+      # are excluded through .git/info/exclude, which no build backend reads.
+      - run: uv run --no-sync python scripts/check_sdist.py
+      # Installing the built wheel into a clean environment is the only check
+      # that catches a file missing from the package but present on disk.
+      - name: install the built wheel into a clean environment
+        run: |
+          uv run --isolated --no-project --with dist/*.whl \
+            python -c "import googleapis_without_429 as m; print(m.__version__)"

googleapis_without_429-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,101 @@
+name: Release
+
+# Publishing uses PyPI Trusted Publishing: GitHub mints a short-lived OIDC
+# token for this specific workflow in this specific repository, and PyPI
+# verifies it. No API token is stored anywhere, so there is none to leak.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: Index to publish to
+        type: choice
+        default: testpypi
+        options: [testpypi, pypi]
+
+jobs:
+  checks:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      # A tag that disagrees with the packaged version publishes something
+      # nobody can find again. Cheap to check, expensive to discover later.
+      - name: Tag must match the packaged version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(python3 -c "import tomllib, pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          if [ "$tag" != "$version" ]; then
+            echo "::error::tag v$tag does not match project version $version"
+            exit 1
+          fi
+          echo "tag and version agree: $version"
+
+      - run: uv build
+      - run: uv run --no-sync python scripts/check_sdist.py
+      - run: uv run --isolated --no-project --with twine twine check dist/*
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: distributions
+          path: dist/
+
+  publish-testpypi:
+    if: github.event_name == 'workflow_dispatch' && inputs.repository == 'testpypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/googleapis-without-429
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: startsWith(github.ref, 'refs/tags/v') || inputs.repository == 'pypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/googleapis-without-429
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.2
+
+  github-release:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/download-artifact@v8
+        with:
+          name: distributions
+          path: dist/
+      - uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true

googleapis_without_429-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Build output
+build/
+dist/
+*.egg-info/
+
+# Bytecode
+__pycache__/
+*.py[cod]
+
+# Virtual environments
+.venv/
+venv/
+
+# Tool caches and coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# macOS writes these into every directory it opens
+.DS_Store

googleapis_without_429-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+# Runs on commit. The same checks run again in CI, because a hook can be
+# skipped with --no-verify and a pipeline cannot.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.6
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        # --no-sync matters: a plain `uv run` reconciles uv.lock with
+        # pyproject.toml, and a hook that rewrites a file mid-commit fails.
+        entry: uv run --no-sync mypy
+        language: system
+        pass_filenames: false
+        types: [python]

googleapis_without_429-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0] - 2026-09-09
+
+### Added
+
+- `WeightedSlidingWindow`: thread-safe core limiter that counts cost rather
+  than calls, so one implementation covers both request-counted APIs (Sheets)
+  and quota-unit APIs (Gmail).
+- `ApiProfile` and the `SHEETS` profile: per-API data describing the host, its
+  separate read and write quotas, and how a call maps to one of them. Limits
+  are overridable with `SHEETS.with_limits(read=300, write=300)`, since real
+  quotas depend on the project and Google revises them.
+- `RateLimitedSession`: an `AuthorizedSession` that paces itself against a
+  profile's quotas and retries a 429 with equal-jitter backoff, honouring
+  `Retry-After` when the server sends one. Requests to hosts without a profile
+  pass through untouched, so token refreshes do not consume the API's quota.
+  Drop it into any client that accepts a session, such as gspread.
+- `DRIVE` profile, covering the half of gspread that is not Sheets: creating,
+  deleting, sharing and finding a spreadsheet by title all go to the Drive API.
+  Drive meters weighted quota units in one shared bucket rather than counting
+  requests in two, so a listing costs twenty times a single item read.
+- Profiles can claim path prefixes, since `www.googleapis.com` serves several
+  APIs and a host alone no longer identifies which quota applies.
+- `QuotaLimiter`: the quota buckets on their own, for code that does not go
+  through a `requests` session. `limiter.limit(SHEETS, "write")` works both as
+  a context manager and as a decorator, and `limiter.bucket(...)` exposes the
+  underlying window for anything this library does not model. A session's own
+  buckets are reachable through `session.limiter`.
+
+[Unreleased]: https://github.com/pavlosambur/googleapis-without-429/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/pavlosambur/googleapis-without-429/releases/tag/v0.1.0

googleapis_without_429-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pavlo Sambur
+
+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.

googleapis_without_429-0.1.0/Makefile

@@ -0,0 +1,32 @@
+# One definition of what "checked" means. CI calls these same targets, so a
+# green local run and a green pipeline cannot drift apart.
+.DEFAULT_GOAL := help
+.PHONY: help install lint format check-format typecheck test package check
+
+help:  ## Show the available targets
+	@grep -E '^[a-z-]+:.*?## ' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'
+
+install:  ## Install the project and its development dependencies
+	uv sync
+
+lint:  ## Report lint violations
+	uv run ruff check .
+
+format:  ## Reformat the code in place
+	uv run ruff format .
+
+check-format:  ## Verify formatting without changing anything
+	uv run ruff format --check .
+
+typecheck:  ## Run the type checker
+	uv run mypy
+
+test:  ## Run the test suite with coverage
+	uv run pytest --cov
+
+package:  ## Build the distributions and check what they contain
+	uv build
+	uv run --no-sync python scripts/check_sdist.py
+
+check: lint check-format typecheck test package  ## Everything the pipeline runs

googleapis_without_429-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.5
+Name: googleapis-without-429
+Version: 0.1.0
+Summary: Drop-in transport for Google API clients that stays inside the quota instead of recovering from 429.
+Project-URL: Homepage, https://github.com/pavlosambur/googleapis-without-429
+Project-URL: Repository, https://github.com/pavlosambur/googleapis-without-429
+Project-URL: Issues, https://github.com/pavlosambur/googleapis-without-429/issues
+Project-URL: Changelog, https://github.com/pavlosambur/googleapis-without-429/blob/main/CHANGELOG.md
+Author-email: Pavlo Sambur <samburp@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 429,google-api,google-sheets,gspread,quota,rate-limiting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: google-auth>=2.0
+Requires-Dist: requests>=2.31
+Description-Content-Type: text/markdown
+
+# googleapis-without-429
+
+[![CI](https://github.com/pavlosambur/googleapis-without-429/actions/workflows/ci.yml/badge.svg)](https://github.com/pavlosambur/googleapis-without-429/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://github.com/pavlosambur/googleapis-without-429)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Stay inside Google API quotas instead of recovering from `429 Too many
+requests`. One argument, and the rest of your code is unchanged.
+
+```python
+import gspread
+from googleapis_without_429 import RateLimitedSession
+
+session = RateLimitedSession(credentials)  # <- the only change
+gc = gspread.authorize(credentials, session=session)
+
+sheet = gc.open("My Sheet").sheet1
+for row in rows:
+    sheet.append_row(row)  # waits when the quota is spent, then continues
+```
+
+No decorators to add, no calls to rewrite, no `sleep()` sprinkled through the
+loop. The session knows what Google's quotas are and paces itself.
+
+## Install
+
+```bash
+pip install googleapis-without-429
+```
+
+Requires Python 3.10 or newer.
+
+## The problem
+
+Google's per-minute quotas are small. Sheets allows **60 reads and 60 writes
+per minute per user** — a loop that appends rows hits that in a minute of
+ordinary work, and the script dies partway through with half the data written.
+
+The official advice is exponential backoff, and every retry library implements
+it. But backoff is a reaction *after* the failure: it recovers, it does not
+prevent. The better first move is not to exceed the quota at all, and to keep
+retries as the second line of defence.
+
+That is what this does. It tracks what you have spent against a sliding window
+and blocks the call that would go over, instead of letting Google reject it.
+
+## What is covered
+
+| API | Quota | How it is metered |
+|---|---|---|
+| Sheets | 60 reads + 60 writes per minute | separate buckets; every call costs 1, batches included |
+| Drive | 325,000 quota units per minute | one shared bucket; a call costs 5 to 200 units |
+
+Together these cover [gspread](https://github.com/burnash/gspread) completely —
+which needs both, since Sheets moves the cell data while Drive owns the file:
+
+| gspread call | Goes to |
+|---|---|
+| `open_by_key`, `open_by_url` | Sheets |
+| `worksheet.get`, `get_all_values`, `batch_get` | Sheets |
+| `append_row`, `update`, `clear`, `batch_update` | Sheets |
+| `open("title")`, `openall`, `list_spreadsheet_files` | Drive, then Sheets |
+| `create`, `copy`, `del_spreadsheet`, `share` | Drive |
+
+Nothing else is covered yet: Gmail, Calendar and Docs have no profile, and
+`google-api-python-client` uses a different transport. Both are on the roadmap.
+A request to any host without a profile passes through untouched — including
+the token refresh your credentials perform, which must not eat the quota of the
+API you are actually calling.
+
+## This does not remove the need for retries
+
+It reduces 429s. It does not eliminate them, and any library claiming otherwise
+is overselling.
+
+The reason is that the two sides count differently. This library slides a
+window over the timestamps of *your* calls. Google meters *fixed* windows whose
+boundaries you cannot see. So 60 calls that look perfectly spaced from here can
+land as 30 in the tail of one of Google's minutes and 30 in the head of the
+next — and the second batch is over the limit even though our counter says
+there is room.
+
+Being strict about our own window makes us conservative, never reckless: we may
+allow fewer calls than Google would, never more. But the boundary mismatch is
+real, so a retry on 429 is built in and on by default:
+
+```python
+RateLimitedSession(
+    credentials,
+    max_attempts=5,  # total tries per request, including the first
+    backoff_base=1.0,  # ceiling for the first retry delay, in seconds
+    backoff_cap=60.0,  # the ceiling stops doubling here
+)
+```
+
+Delays use equal jitter: half the ceiling is always waited and the rest is
+randomised. The guaranteed half matters — a 429 means the window has not
+reopened yet, so a delay that comes out near zero only buys another 429. A
+`Retry-After` header, if the server sends one, wins over the computed delay.
+
+## Adjusting the limits
+
+The shipped numbers are Google's documented defaults, and defaults go stale.
+Real quotas depend on the project, on when it was created, and Google revises
+them — Drive's changed on 1 May 2026, and projects already using the API kept
+the previous ones. So overriding is a first-class operation:
+
+```python
+from googleapis_without_429 import DRIVE, SHEETS, RateLimitedSession
+
+session = RateLimitedSession(
+    credentials,
+    [
+        SHEETS.with_limits(read=300, write=300),  # the per-project ceiling
+        DRIVE.with_limits(units=12_000),  # an older project
+    ],
+)
+```
+
+The defaults are the **per-user** quotas, which is what a single script runs
+into. Raise them to the per-project ceiling only if the job really is the only
+thing using that project. A misspelled bucket name raises rather than being
+quietly ignored, so a typo cannot leave you believing a limit was raised.
+
+Check what your project actually has in the Cloud Console under
+**APIs & Services → Quotas**; it can differ from the documentation.
+
+## Without a session
+
+If the calls are not made through a `requests` session — a hand-rolled client,
+a worker, an API this library has no adapter for — use the limiter directly. It
+is both a context manager and a decorator:
+
+```python
+from googleapis_without_429 import SHEETS, QuotaLimiter
+
+limiter = QuotaLimiter([SHEETS])
+
+
+@limiter.limit(SHEETS, "write")
+def push_batch(rows): ...
+
+
+with limiter.limit(SHEETS, "read"):
+    ...
+```
+
+And the raw window underneath, when nothing above fits:
+
+```python
+limiter.bucket(SHEETS, "write").acquire(cost=1)
+limiter.bucket(SHEETS, "write").used  # what is currently counted
+```
+
+A session exposes its own limiter the same way, so you can pace a call it does
+not make itself:
+
+```python
+session.limiter.bucket(SHEETS, "read").acquire()
+```
+
+## Adding an API
+
+A profile is data, not code: a host, a map of buckets to limits, and a function
+that says which bucket a call belongs to and what it costs.
+
+```python
+from googleapis_without_429 import ApiProfile, QuotaLimiter
+
+
+def resolve_docs(http_method, path, query):
+    return ("read" if http_method == "GET" else "write"), 1
+
+
+DOCS = ApiProfile(
+    name="docs",
+    host="docs.googleapis.com",
+    limits={"read": 300, "write": 60},
+    resolve=resolve_docs,
+)
+
+limiter = QuotaLimiter([DOCS])
+```
+
+Two things worth knowing before writing one:
+
+- **The HTTP method is not the whole story.** Sheets sends several reads as
+  POST (`:getByDataFilter`, `:batchGetByDataFilter`, `developerMetadata:search`)
+  because they carry a request body. Charging those to the write bucket burns
+  one of only 60 writes a minute. The published
+  [discovery document](https://developers.google.com/discovery/v1/reference)
+  for an API lists every method with its real HTTP verb and path.
+- **A host may serve several APIs.** Drive lives on `www.googleapis.com`
+  alongside others, so its profile claims `path_prefixes=("/drive/",
+  "/upload/drive/")`. Leave that empty only when the host belongs to one API.
+
+Profiles for other Google APIs are very welcome as pull requests — that is the
+cheapest way for this library to grow, and it needs no changes to the core.
+
+## Development
+
+```bash
+uv sync                      # install the project and its dev dependencies
+make check                   # everything CI runs: lint, format, types, tests
+uv run pre-commit install    # optional: fast checks on every commit
+```
+
+Individual steps: `make lint`, `make check-format`, `make typecheck`,
+`make test`. CI calls the same targets, so a green local run means a green
+pipeline. The test suite needs no credentials and makes no network calls.
+
+## Roadmap
+
+- An adapter for `google-api-python-client`, which uses an httplib2-style
+  transport rather than a `requests` session
+- A Gmail profile — its quota units range from 2 to 100 per call, which is what
+  the weighted core was built for
+- Async support
+
+## License
+
+MIT