api-session
api-session is a small module providing an extended requests.Session class to work with JSON APIs.
It aims at factoring the common parts of these clients while staying very lightweight (<100 SLOC). It only augments
the requests.Session class, so the base methods are still available.
We use it at Bixoto as a basis for JSON API clients such as PyMagento.
Features
- Base URL: the base API URL is given only once on object creation; subsequent calls use
.get("/path") - Read-only flag: if given, prevents the API from doing
POSTand similar calls - Offline flag: if given, prevents the API from doing any call. This is useful for tests.
requests.Sessioninheritance: the class inherits fromrequests.Session, so it stays 100% compatible with it- Response bodies are included in exception messages for 4xx errors. This behavior can be customized.
Install
pip install api-session
With uv:
uv add api-session
With Poetry:
poetry add api-session
Dependency: Python 3.10+.
- Versions 1.6.x and above require Python 3.10+
- Versions 1.5.x require Python 3.9+
- Versions 1.4.x and below require Python 3.8+
Usage
from api_session import APISession
# The only requirement is to pass the base URL of the API you want to use.
# This does not prevent you from calling other URLs.
#
# Remember this is just an augmented `requests.Session()` object.
client = APISession("https://httpbin.org")
# All requests methods are available:
client.get("https://example.com")
client.head("https://example.com")
client.post("https://example.com")
client.put("https://example.com")
client.delete("https://example.com")
client.options("https://example.com")
# In addition, *_api methods call the base URL:
client.get_api("/foo") # GET https://httpbin.org/foo
client.head_api("/foo") # HEAD https://httpbin.org/foo
client.post_api("/foo") # POST https://httpbin.org/foo
client.put_api("/foo") # PUT https://httpbin.org/foo
client.delete_api("/foo") # DELETE https://httpbin.org/foo
client.options_api("/foo") # OPTIONS https://httpbin.org/foo
# For JSON API, use the _*_json_api methods. They call `.json()` on the response:
client.get_json_api("/foo") # equivalent of client.get("https://httpbin.org/foo").json()
client.post_json_api("/bar") # equivalent of client.post("https://httpbin.org/bar").json()
client.put_json_api("/baz") # equivalent of client.put("https://httpbin.org/baz").json()
client.delete_json_api("/qux") # equivalent of client.delete("https://httpbin.org/qux").json()
A typical usage is to inherit from the session to implement an API client class:
from typing import Any
from api_session import APISession
class FooApiClient(APISession):
def __init__(self, token: str, **kwargs):
# Set the base URL used by all API calls
super().__init__(base_url="https://foo-api.example.com/v1", **kwargs)
# Add your own setup, like headers
self.headers["Authorization"] = f"Bearer {token}"
def get_stuff(self) -> list[dict]:
return self.get_json_api("/get-stuff")
def create_stuff(self, stuff: dict[str, Any]) -> bool:
return self.post_json_api("/create-stuff", json=stuff)
# Then use it:
my_client = FooApiClient("my-token")
my_client.create_stuff({"foo": "bar"}) # => True
for thing in my_client.get_stuff():
print(thing)
FAQ
What about cookies?
Cookies are persisted in the session object, just like with requests.Session.
Metadata
Release files for api-session 1.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| api_session-1.7.0.tar.gz | 52.6 kB | Without provenance | Details for api_session-1.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| api_session-1.7.0-py3-none-any.whl | Python 3 | none | any | Details for api_session-1.7.0-py3-none-any.whl |
Total release size: 59.1 kB
Release files / api_session-1.7.0.tar.gz
| Download URL | api_session-1.7.0.tar.gz |
|---|---|
| Size | 52.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
473f09393c9772bf4a5b0bdad9ac1e40d85d22a9801679114e4c26a4c60c83ad
|
|
BLAKE2b-256 checksum How to use checksums |
21495f82c3b11c3a005f77afb02b3bbb9ccfb4deb587f4977edd83e181870427
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / api_session-1.7.0-py3-none-any.whl
| Download URL | api_session-1.7.0-py3-none-any.whl |
|---|---|
| Size | 6.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3458de51e37fb5324d396554d2f9eb0b6de7323da6ba89f5d6705b4b45e322ba
|
|
BLAKE2b-256 checksum How to use checksums |
1115833c1092323ed9a1bf6616218fcf62223701cdd9b1421ee9de682528216d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for api-session 1.7.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.