Issue #1566 - add support for a @hookable decorator to HTTPClient.request() (extensible elsewhere)

.github/CONTRIBUTING.md

@@ -19,7 +19,9 @@
 
 ## Tests
 
-To run tests, add your credentials to `tests/creds.json` and run
+To run tests, add your credentials to `tests/creds.json`. The credentials JSON block can be auto-generated from your Google Cloud console.
+
+then run:
 
 ```bash
 GS_CREDS_FILENAME="tests/creds.json" GS_RECORD_MODE="all" tox -e py -- -k "<specific test to run>"

.github/workflows/main.yaml

@@ -17,15 +17,15 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python: ["3.8", "3.9", "3.10", "3.11", "3.x"]
+        python: ["3.13", "3.14"]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python }}
       - run: pip install -U pip
       - run: pip install -U bandit pyupgrade pip-audit tox setuptools
-      - run: bandit --recursive --skip B105,B110,B311,B605,B607 --exclude ./.tox .
+      - run: bandit --recursive --skip B105,B110,B311,B605,B607,B101 --exclude ./.tox .
       - run: tox -e lint
       - run: tox -e py
       - run: shopt -s globstar && pyupgrade --py3-only **/*.py # --py36-plus

.gitignore

@@ -20,3 +20,4 @@ docs/build/
 
 # local virtualenv
 venv/
+.venv/

Makefile

@@ -0,0 +1,75 @@
+# Developer convenience targets. Individual lint tools run through `uv run`
+# against the project .venv, with flags mirroring tox.ini, so `make lint`
+# matches the tools in `tox -e lint`. `make ci` reproduces the full CI
+# lint_python job (lint + tests + security + build + docs) via tox and uvx.
+
+.DEFAULT_GOAL := help
+
+BLACK_EXCLUDE := ./env|gspread/__init__.py
+CODESPELL_SKIP := .tox,.git,./docs/build,.mypy_cache,./env,./.venv
+
+# Extra args passed through to pytest, e.g. `make test ARGS="tests/cell_test.py -x"`
+ARGS ?=
+
+.PHONY: help install test lint format black flake8 isort codespell mypy bandit pyupgrade pip-audit doc build ci clean
+
+help: ## Show this help
+	@echo "Available targets:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
+
+install: ## Create the .venv (Python 3.14.6) and install runtime + test + lint deps
+	uv venv --python 3.14.6
+	uv pip install -e . -r test-requirements.txt -r lint-requirements.txt
+
+test: ## Run the offline test suite (ARGS=... passthrough to pytest)
+	uv run pytest tests/ $(ARGS)
+
+lint: black flake8 isort codespell mypy ## Run the linters/formatters/type check (mirrors tox -e lint)
+
+format: ## Auto-format code with black and isort
+	uv run black --extend-exclude="$(BLACK_EXCLUDE)" .
+	uv run isort .
+
+black: ## Check formatting with black
+	uv run black --check --diff --extend-exclude="$(BLACK_EXCLUDE)" .
+
+flake8: ## Run flake8
+	uv run flake8 .
+
+isort: ## Check import ordering with isort
+	uv run isort --check-only .
+
+codespell: ## Check spelling with codespell
+	uv run codespell --skip="$(CODESPELL_SKIP)" .
+
+mypy: ## Run mypy type checks
+	uv run mypy --install-types --non-interactive --ignore-missing-imports ./gspread ./tests
+
+bandit: ## Run the bandit security scan (as CI does)
+	uv run bandit --recursive --skip B105,B110,B311,B605,B607,B101 --exclude ./.tox,./.venv .
+
+pyupgrade: ## Check for outdated Python syntax on tracked files (as CI does)
+	uvx pyupgrade --py3-only $(shell git ls-files '*.py')
+
+pip-audit: ## Audit dependencies for known vulnerabilities (as CI does; non-fatal)
+	-uvx pip-audit --ignore-vuln PYSEC-2023-228 --ignore-vuln PYSEC-2022-43012 --ignore-vuln GHSA-5rjg-fvgr-3xxf --ignore-vuln GHSA-48p4-8xcf-vxj5 --ignore-vuln GHSA-pq67-6m6q-mj2v
+
+doc: ## Build the documentation (mirrors tox -e doc)
+	uvx --with tox-uv tox -e doc
+
+build: ## Build the sdist and wheel
+	uv build
+
+ci: ## Reproduce the full CI lint_python job locally (lint + tests + security + build + docs)
+	uv run bandit --recursive --skip B105,B110,B311,B605,B607,B101 --exclude ./.tox,./.venv .
+	uvx --with tox-uv tox -e lint
+	uvx --with tox-uv tox -e py
+	uvx pyupgrade --py3-only $(shell git ls-files '*.py')
+	-uvx pip-audit --ignore-vuln PYSEC-2023-228 --ignore-vuln PYSEC-2022-43012 --ignore-vuln GHSA-5rjg-fvgr-3xxf --ignore-vuln GHSA-48p4-8xcf-vxj5 --ignore-vuln GHSA-pq67-6m6q-mj2v
+	uvx --with tox-uv tox -e build
+	uvx --with tox-uv tox -e doc
+
+clean: ## Remove caches and build artifacts
+	rm -rf .mypy_cache .pytest_cache dist *.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} +

docs/advanced.rst

@@ -1,6 +1,43 @@
 Advanced Usage
 ==============
 
+Request Hooks
+---------------------
+
+The ``gspread`` http_client object has the ability to add callback function hooks on request events.
+
+- Before the method executes ``add_before_hook``
+- After successful execution ``add_success_hook``
+- When exceptions occur ``add_exception_hook``
+- When timeouts occur ``add_timeout_hook``
+- When retryable errors occur (http codes that signal retryable errors) ``add_retry_hook``
+- After execution regardless of success/failure ``add_after_hook``
+
+Callback hooks allow for things like logging to occur in the consuming code.
+
+    import logging
+
+    log = logging.getLogger(__name__)
+
+    def before_callback(method_name, args, kwargs, result):
+        log.info(f"Request started: {args[0].upper()}: {args[1]}")
+
+    def after_callback(method_name, args, kwargs, result):
+        log.info(f"Request ended: OK? {result.ok}")
+
+    ...
+
+    gc = gspread.authorize(creds)
+    gc.http_client.add_before_hook("request", before_callback)
+    gc.http_client.add_after_callback("request", after_callback)
+
+    gc.open_by_key(sheets_doc_key)
+
+Example Output:
+
+    INFO  __main__ Request started: GET: https://sheets.googleapis.com/v4/spreadsheets/19DxqGsxQyCyNWS_kbDnvvWaZS5ahWCOzQSB0j-yHzOU
+    INFO  __main__ Request ended: OK? True
+
 Custom Authentication
 ---------------------
 

gspread/__init__.py

@@ -1,7 +1,7 @@
 """Google Spreadsheets Python API"""
 
-__version__ = "6.2.1"
-__author__ = "Anton Burnashev"
+__version__ = "6.2.2rc2"
+__author__ = "Anton Burnashev (bklaas fork)"
 
 
 from .auth import (