Plugins

Plugins extend a client instance with reusable, composable behavior. Rather than wiring the same interceptors into every project, you register a plugin once and it applies to every request the instance makes.

All plugins implement the Plugin protocol — a single install(client) method — and are registered via .plugin().

api.plugin(SomePlugin(...))

That's the entire surface area. Everything else is convention.

Built-in Plugins

Authentication Plugin (AuthPlugin)

Injects an Authorization header into every outgoing request on the instance. Supports static tokens for simple cases and a token_provider callback for tokens that expire and need to be refreshed at runtime.

from axios_python import AuthPlugin
import axios_python

api = axios_python.create({"base_url": "https://api.github.com"})

# Injects `Authorization: Bearer super-secret-key` on every request
api.plugin(AuthPlugin(scheme="Bearer", token="super-secret-key"))

from axios_python import AuthPlugin
import axios_python

api = axios_python.create({"base_url": "https://api.github.com"})

# Called before each request — ideal for short-lived tokens
def get_fresh_token() -> str:
    return token_store.retrieve()  # env var, secret manager, refresh endpoint

api.plugin(AuthPlugin(scheme="Bearer", token_provider=get_fresh_token))

Cache Plugin (CachePlugin)

Caches GET responses in memory for a configurable TTL. Subsequent requests to the same URL and query parameters within that window skip the network entirely and return the cached response.

from axios_python import CachePlugin

# Cache GET responses for 120 seconds, evicting least-recently-used entries after 256
api.plugin(CachePlugin(ttl=120, max_size=256))

api.get("/reports/summary")  # Network request — response cached
api.get("/reports/summary")  # Served from cache instantly

Logger Plugin (LoggerPlugin)

Emits structured log lines for every request and response via Python's built-in logging module. Output integrates with any handler already configured in your application — file handlers, structlog, cloud log forwarders, all of it.

import logging
from axios_python import LoggerPlugin

logging.basicConfig(level=logging.INFO)
api.plugin(LoggerPlugin(level=logging.INFO))

api.get("https://httpbin.org/get")
# INFO:axios_python.logger:--> GET https://httpbin.org/get
# INFO:axios_python.logger:<-- 200 OK https://httpbin.org/get (1,204 bytes, 83ms)

Composing Plugins

Plugins stack. Register as many as you need in any order — each one calls install() against the same client instance and adds its own interceptors or middleware to the pipeline.

from axios_python import AuthPlugin, CachePlugin, LoggerPlugin

api = axios_python.create({"base_url": "https://api.myapp.com"})

api.plugin(LoggerPlugin(level=logging.DEBUG))
api.plugin(AuthPlugin(scheme="Bearer", token_provider=vault.get_token))
api.plugin(CachePlugin(ttl=60, max_size=512))

# Every request now: logs the outgoing call, injects auth,
# checks the cache, logs the response.

Writing a Custom Plugin

To write your own plugin, implement an object with a single install(client: AxiosPython) method. Inside it, register interceptors or middleware against the provided client — the same APIs available anywhere else.

from axios_python import AxiosPython

class CorrelationIdPlugin:
    """Attaches a unique X-Correlation-Id to every outgoing request."""

    def install(self, client: AxiosPython) -> None:
        import uuid

        def attach_correlation_id(config: dict) -> dict:
            config["headers"]["X-Correlation-Id"] = str(uuid.uuid4())
            return config

        client.interceptors.request.use(attach_correlation_id)


api.plugin(CorrelationIdPlugin())

The install method receives the fully configured client, so you can introspect its existing config before deciding what to register. If your plugin needs teardown logic (closing a connection pool, flushing a buffer), implement an optional uninstall(client) method — axios_python will call it when the client is closed.

For a complete walkthrough of building and distributing plugins, see the Plugin Authoring guide.