Agent skill

requests

Synchronous HTTP client for sending HTTP requests and handling responses.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/skills-skilldoai-skilldo-19

SKILL.md

Imports

python
import requests
from requests import Session
from requests.auth import HTTPBasicAuth, HTTPDigestAuth, AuthBase
from requests.exceptions import (
    RequestException,
    Timeout,
    ConnectTimeout,
    ReadTimeout,
    ConnectionError,
    HTTPError,
    TooManyRedirects,
    JSONDecodeError,
)

Core Patterns

GET with query params + status checking ✅ Current

python
from __future__ import annotations

import requests


def fetch_repo(owner: str, repo: str) -> dict:
    url = "https://api.github.com/repos/{owner}/{repo}".format(owner=owner, repo=repo)
    r = requests.get(url, params={"per_page": 1}, timeout=10)
    r.raise_for_status()
    return r.json()


if __name__ == "__main__":
    data = fetch_repo("psf", "requests")
    print(data["full_name"])
  • Use params= for query strings; call Response.raise_for_status() before trusting the body.

POST JSON body ✅ Current

python
from __future__ import annotations

import requests


def create_widget(api_base: str, token: str, name: str) -> dict:
    url = f"{api_base}/post"
    headers = {"Authorization": f"Bearer {token}"}

    r = requests.post(
        url,
        json={"name": name},
        headers=headers,
        timeout=10,
    )
    r.raise_for_status()
    return r.json()


if __name__ == "__main__":
    # Example: using httpbin.org/post to echo back JSON
    api_base = "https://httpbin.org"
    token = "testtoken123"
    name = "mywidget"
    result = create_widget(api_base, token, name)
    # httpbin.org returns JSON with keys: json, headers, url, etc.
    assert isinstance(result, dict)
    # The JSON body should be echoed back under "json"
    assert result.get("json") == {"name": name}
    # The Authorization header should be present (case-insensitive)
    headers = result.get("headers", {})
    authval = headers.get("Authorization") or headers.get("authorization")
    assert authval and token in authval
    # The URL should end with /post
    assert result.get("url", "").endswith("/post")
    print("✓ POST JSON body pattern ok")
  • Prefer json= for JSON request bodies (sets JSON encoding; also sets an appropriate Content-Type).

Reuse connections with Session ✅ Current

python
from __future__ import annotations

import requests


def fetch_many(urls: list[str]) -> list[tuple[str, int]]:
    results: list[tuple[str, int]] = []
    with requests.Session() as s:
        s.headers.update({"User-Agent": "example-client/1.0"})
        for url in urls:
            r = s.get(url, timeout=10)
            results.append((r.url, r.status_code))
    return results


if __name__ == "__main__":
    out = fetch_many(["https://httpbin.org/get", "https://example.com/"])
    print(out)
  • Use requests.Session() (or requests.session()) for connection pooling and shared headers/cookies.

Streaming download to disk ✅ Current

python
from __future__ import annotations

import requests


def download_file(url: str, path: str) -> None:
    with requests.get(url, stream=True, timeout=30) as r:
        r.raise_for_status()
        with open(path, "wb") as f:
            for chunk in r.iter_content(chunk_size=1024 * 128):
                if chunk:  # filter out keep-alive chunks
                    f.write(chunk)


if __name__ == "__main__":
    download_file("https://httpbin.org/bytes/1024", "out.bin")
    print("Wrote out.bin")
  • For large responses, use stream=True and Response.iter_content(); write to a binary file.

Auth: Basic/Digest/custom AuthBase ✅ Current

python
from __future__ import annotations

import requests
from requests.auth import AuthBase, HTTPBasicAuth, HTTPDigestAuth


class BearerAuth(AuthBase):
    def __init__(self, token: str) -> None:
        self._token = token

    def __call__(self, r: requests.PreparedRequest) -> requests.PreparedRequest:
        r.headers["Authorization"] = f"Bearer {self._token}"
        return r


def demo_auth() -> None:
    # Basic auth (tuple shorthand also works: auth=("user", "pass"))
    r1 = requests.get("https://httpbin.org/basic-auth/user/pass", auth=HTTPBasicAuth("user", "pass"), timeout=10)
    print(r1.status_code)

    # Digest auth
    r2 = requests.get("https://httpbin.org/digest-auth/auth/user/pass", auth=HTTPDigestAuth("user", "pass"), timeout=10)
    print(r2.status_code)

    # Custom auth
    r3 = requests.get("https://httpbin.org/bearer", auth=BearerAuth("secret-token"), timeout=10)
    print(r3.status_code)


if __name__ == "__main__":
    demo_auth()
  • Use auth=("user","pass") or HTTPBasicAuth for Basic; HTTPDigestAuth for Digest; subclass AuthBase for custom schemes.

Configuration

  • Timeouts: No default timeout; always pass timeout= (float seconds or (connect, read) tuple) to avoid hanging indefinitely.
  • Redirects: Followed by default for GET/OPTIONS; can control with allow_redirects= (e.g., requests.get(..., allow_redirects=False)).
  • TLS verification: Verified by default (verify=True). Override per request with verify=False (discouraged) or verify="/path/to/ca-bundle.pem".
  • Proxies: Configure via proxies= dict or environment variables (e.g., HTTPS_PROXY, HTTP_PROXY, NO_PROXY) when Session.trust_env is True.
  • Environment / netrc: By default, Requests may consult environment and .netrc for credentials when auth= is not provided. Disable by setting Session.trust_env = False.
  • Response encoding: Requests infers encoding from headers; set Response.encoding manually only when you know the correct encoding before accessing Response.text.

Pitfalls

Wrong: assuming JSON decoding implies HTTP success

python
from __future__ import annotations

import requests

r = requests.get("https://httpbin.org/status/500", timeout=10)
data = r.json()  # may succeed/fail independently of HTTP status
print(data)

Right: check HTTP status first

python
from __future__ import annotations

import requests

r = requests.get("https://httpbin.org/status/500", timeout=10)
r.raise_for_status()
print(r.json())

Wrong: calling Response.json() on empty/invalid JSON (e.g., 204)

python
from __future__ import annotations

import requests

r = requests.get("https://httpbin.org/status/204", timeout=10)
print(r.json())  # raises requests.exceptions.JSONDecodeError

Right: handle 204 and JSONDecodeError explicitly

python
from __future__ import annotations

import requests
from requests.exceptions import JSONDecodeError

r = requests.get("https://httpbin.org/status/204", timeout=10)

if r.status_code == 204:
    print(None)
else:
    try:
        print(r.json())
    except JSONDecodeError:
        print(None)

Wrong: using Response.raw without stream=True

python
from __future__ import annotations

import requests

r = requests.get("https://httpbin.org/bytes/10", timeout=10)
raw_bytes = r.raw.read()  # not the intended pattern without stream=True
print(raw_bytes)

Right: stream=True and iter_content()

python
from __future__ import annotations

import requests

with requests.get("https://httpbin.org/bytes/10", stream=True, timeout=10) as r:
    r.raise_for_status()
    data = b"".join(r.iter_content(chunk_size=4))
    print(data)

Wrong: unexpected credential sending via netrc/env when auth= is not set

python
from __future__ import annotations

import requests

s = requests.Session()
# May consult environment (.netrc, proxy env vars, etc.) by default:
r = s.get("https://example.com/private", timeout=10)
print(r.status_code)

Right: disable environment-based behavior when you must control auth explicitly

python
from __future__ import annotations

import requests

s = requests.Session()
s.trust_env = False
r = s.get("https://example.com/private", timeout=10)
print(r.status_code)

References

Migration from v2.31.x

  • Python support: Requests 2.32.5 drops Python 3.8 support. If you must run on 3.8, pin <2.32.5 temporarily and upgrade Python.
  • TLS/adapter changes (2.32.0–2.32.2): If you maintain a custom HTTPAdapter, Requests introduced a new public method for connection acquisition with TLS context (get_connection_with_tls_context) and considers get_connection deprecated in Requests >=2.32.0. Update adapter overrides accordingly.
  • TLS behavior (2.32.5): SSLContext caching introduced in 2.32.0 was reverted in 2.32.5; retest performance and any assumptions about TLS context reuse.
  • Security (2.31.0): If you use proxy URLs with credentials, ensure you are on >=2.31.0 to avoid potential Proxy-Authorization leakage on HTTPS redirects; rotate proxy credentials after upgrading.

API Reference

  • requests.get(url, params=None, **kwargs) - Send a GET request; common kwargs: headers, timeout, auth, cookies, allow_redirects, proxies, verify, cert, stream.
  • requests.post(url, data=None, json=None, **kwargs) - Send a POST request; prefer json= for JSON bodies.
  • requests.put(url, data=None, **kwargs) - Send a PUT request.
  • requests.patch(url, data=None, **kwargs) - Send a PATCH request.
  • requests.delete(url, **kwargs) - Send a DELETE request.
  • requests.head(url, **kwargs) - Send a HEAD request (often with allow_redirects=).
  • requests.options(url, **kwargs) - Send an OPTIONS request.
  • requests.request(method, url, **kwargs) - Generic request entry point for custom/variable methods.
  • requests.Session() - Persistent session with connection pooling; use .get()/.post() etc.; configure headers, cookies, proxies, verify, trust_env.
  • requests.session() - Convenience constructor returning a requests.Session.
  • requests.Response - Response object; key attributes/methods: .status_code, .headers, .url, .text, .content, .encoding, .json(), .raise_for_status(), .iter_content(), .raw (with stream=True).
  • requests.RequestException - Base exception for Requests errors.
  • requests.Timeout / requests.ConnectTimeout / requests.ReadTimeout - Timeout exceptions; use timeout= to control.
  • requests.ConnectionError - Network-level failure.
  • requests.HTTPError - Raised by Response.raise_for_status() on 4xx/5xx.
  • requests.TooManyRedirects - Raised when redirect limit is exceeded.
  • requests.exceptions.JSONDecodeError - Raised by Response.json() on invalid/empty JSON.
  • requests.codes - Status code lookup (e.g., requests.codes.ok).

Current Library State (from source analysis)

API Surface

json
{
  "library_category": "http_client",
  "apis": [
    {
      "name": "requests.get",
      "type": "function",
      "signature": "get(url, params=None, **kwargs)",
      "signature_truncated": false,
      "return_type": "Response",
      "module": "requests.api",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "type_hints": {
        "url": {
          "base_type": "str",
          "is_optional": false,
          "default_value": null
        },
        "params": {
          "base_type": "dict or bytes",
          "is_optional": true,
          "default_value": "None"
        }
      }
    },
    {
      "name": "requests.post",
      "type": "function",
      "signature": "post(url, data=None, json=None, **kwargs)",
      "signature_truncated": false,
      "return_type": "Response",
      "module": "requests.api",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "type_hints": {
        "url": {
          "base_type": "str",
          "is_optional": false,
          "default_value": null
        },
        "data": {
          "base_type": "dict or bytes",
          "is_optional": true,
          "default_value": "None"
        },
        "json": {
          "base_type": "Any",
          "is_optional": true,
          "default_value": "None"
        }
      }
    },
    {
      "name": "requests.put",
      "type": "function",
      "signature": "put(url, data=None, **kwargs)",
      "signature_truncated": false,
      "return_type": "Response",
      "module": "requests.api",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      }
    },
    {
      "name": "requests.patch",
      "type": "function",
      "signature": "patch(url, data=None, **kwargs)",
      "signature_truncated": false,
      "return_type": "Response",
      "module": "requests.api",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      }
    },
    {
      "name": "requests.delete",
      "type": "function",
      "signature": "delete(url, **kwargs)",
      "signature_truncated": false,
      "return_type": "Response",
      "module": "requests.api",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      }
    },
    {
      "name": "requests.head",
      "type": "function",
      "signature": "head(url, **kwargs)",
      "signature_truncated": false,
      "return_type": "Response",
      "module": "requests.api",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      }
    },
    {
      "name": "requests.options",
      "type": "function",
      "signature": "options(url, **kwargs)",
      "signature_truncated": false,
      "return_type": "Response",
      "module": "requests.api",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      }
    },
    {
      "name": "requests.request",
      "type": "function",
      "signature": "request(method, url, **kwargs)",
      "signature_truncated": false,
      "return_type": "Response",
      "module": "requests.api",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "type_hints": {
        "method": {
          "base_type": "str",
          "is_optional": false,
          "default_value": null
        },
        "url": {
          "base_type": "str",
          "is_optional": false,
          "default_value": null
        }
      }
    },
    {
      "name": "requests.Session",
      "type": "class",
      "signature": "Session()",
      "signature_truncated": false,
      "return_type": "Session",
      "module": "requests.sessions",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": [],
        "abstract": false
      }
    },
    {
      "name": "requests.session",
      "type": "function",
      "signature": "session()",
      "signature_truncated": false,
      "return_type": "Session",
      "module": "requests.sessions",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      }
    },
    {
      "name": "requests.Request",
      "type": "class",
      "signature": "Request(method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)",
      "signature_truncated": true,
      "return_type": "Request",
      "module": "requests.models",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": [],
        "abstract": false
      }
    },
    {
      "name": "requests.PreparedRequest",
      "type": "class",
      "signature": "PreparedRequest()",
      "signature_truncated": false,
      "return_type": "PreparedRequest",
      "module": "requests.models",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": [],
        "abstract": false
      }
    },
    {
      "name": "requests.Response",
      "type": "class",
      "signature": "Response()",
      "signature_truncated": false,
      "return_type": "Response",
      "module": "requests.models",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": [],
        "abstract": false
      }
    },
    {
      "name": "requests.codes",
      "type": "descriptor",
      "signature": "codes",
      "signature_truncated": false,
      "return_type": "module",
      "module": "requests.status_codes",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      }
    },
    {
      "name": "requests.ConnectionError",
      "type": "class",
      "signature": "ConnectionError(*args, **kwargs)",
      "signature_truncated": false,
      "return_type": "ConnectionError",
      "module": "requests.exceptions",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": ["RequestException"],
        "abstract": false
      }
    },
    {
      "name": "requests.ConnectTimeout",
      "type": "class",
      "signature": "ConnectTimeout(*args, **kwargs)",
      "signature_truncated": false,
      "return_type": "ConnectTimeout",
      "module": "requests.exceptions",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": ["Timeout"],
        "abstract": false
      }
    },
    {
      "name": "requests.FileModeWarning",
      "type": "class",
      "signature": "FileModeWarning(*args, **kwargs)",
      "signature_truncated": false,
      "return_type": "FileModeWarning",
      "module": "requests.exceptions",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": ["Warning"],
        "abstract": false
      }
    },
    {
      "name": "requests.HTTPError",
      "type": "class",
      "signature": "HTTPError(*args, **kwargs)",
      "signature_truncated": false,
      "return_type": "HTTPError",
      "module": "requests.exceptions",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": ["RequestException"],
        "abstract": false
      }
    },
    {
      "name": "requests.JSONDecodeError",
      "type": "class",
      "signature": "JSONDecodeError(*args, **kwargs)",
      "signature_truncated": false,
      "return_type": "JSONDecodeError",
      "module": "requests.exceptions",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": ["ValueError"],
        "abstract": false
      }
    },
    {
      "name": "requests.ReadTimeout",
      "type": "class",
      "signature": "ReadTimeout(*args, **kwargs)",
      "signature_truncated": false,
      "return_type": "ReadTimeout",
      "module": "requests.exceptions",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": ["Timeout"],
        "abstract": false
      }
    },
    {
      "name": "requests.RequestException",
      "type": "class",
      "signature": "RequestException(*args, **kwargs)",
      "signature_truncated": false,
      "return_type": "RequestException",
      "module": "requests.exceptions",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": ["Exception"],
        "abstract": false
      }
    },
    {
      "name": "requests.Timeout",
      "type": "class",
      "signature": "Timeout(*args, **kwargs)",
      "signature_truncated": false,
      "return_type": "Timeout",
      "module": "requests.exceptions",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": ["RequestException"],
        "abstract": false
      }
    },
    {
      "name": "requests.TooManyRedirects",
      "type": "class",
      "signature": "TooManyRedirects(*args, **kwargs)",
      "signature_truncated": false,
      "return_type": "TooManyRedirects",
      "module": "requests.exceptions",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": ["RequestException"],
        "abstract": false
      }
    },
    {
      "name": "requests.URLRequired",
      "type": "class",
      "signature": "URLRequired(*args, **kwargs)",
      "signature_truncated": false,
      "return_type": "URLRequired",
      "module": "requests.exceptions",
      "publicity_score": "high",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      },
      "class_hierarchy": {
        "bases": ["RequestException"],
        "abstract": false
      }
    },
    {
      "name": "requests.utils.super_len",
      "type": "function",
      "signature": "super_len(o)",
      "signature_truncated": false,
      "return_type": "int",
      "module": "requests.utils",
      "publicity_score": "medium",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      }
    },
    {
      "name": "requests.utils.get_auth_from_url",
      "type": "function",
      "signature": "get_auth_from_url(url)",
      "signature_truncated": false,
      "return_type": "Tuple[str, str]",
      "module": "requests.utils",
      "publicity_score": "medium",
      "module_type": "public",
      "decorators": [],
      "deprecation": {
        "is_deprecated": false
      }
    }
    // ... more utils, cookies, structures, etc. could be listed here depending on __all__ and documentation
  ]
}

Notes:

  • This extraction focuses on the canonical public API (as indicated by requests/__init__.py and __all__ patterns).
  • Many internal/compatibility APIs are omitted unless directly promoted/documented. If you want lower-level or internal APIs (such as from requests.utils), let me know.
  • Type hints and signatures are inferred from documentation and standard usage patterns, as direct type hints in these modules are partial.
  • If you need the full details of every method/property on classes like Response or Session, specify, and a more granular breakdown can be provided.
  • No deprecations or removals are present in the core HTTP API as of v2.32.5.
  • No route decorators, CLI, ORM, or async patterns are detected, confirming http_client as the category.

Migration

Breaking Changes from v2.31.x and v2.32.0–v2.32.5

  • Dropped Python 3.8 support: Requests 2.32.5 requires Python 3.9+. If you must run on 3.8, pin <2.32.5 temporarily and upgrade Python as soon as possible.
  • Custom HTTPAdapter changes (2.32.0–2.32.2): If you maintain a custom HTTPAdapter, use the new get_connection_with_tls_context method instead of the now-deprecated get_connection. See the Requests changelog and PR #6710 for migration examples.
  • TLS context caching reverted (2.32.5): SSLContext caching introduced in 2.32.0 is reverted in 2.32.5. If you relied on global SSLContext reuse (e.g., for performance or TLS session features), retest your code for any impact.
  • Security fix (2.31.0): If you use proxy URLs with embedded credentials, upgrade to >=2.31.0 to avoid possible Proxy-Authorization header leakage on HTTPS redirects. Rotate proxy credentials after upgrading.

No core HTTP API endpoints were removed or had their signatures changed in 2.32.x.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results