Plynt

Plynt is a modular, framework-agnostic Python library for building external API clients and services.

The name plynt is inspired by a plinth in architecture:

the solid base a structure stands on.

Plynt aims to be exactly that - a stable, minimal layer for long-lived, maintainable integrations with external HTTP APIs.

---

Project Goal

Plynt provides a reusable foundation for creating Python clients and services that communicate with external HTTP APIs. It is designed to be:

• Framework-agnostic (works with FastAPI, Django, Starlette, or stand-alone)
• Modular (install only what you need)
• Sync + Async (single codebase, no duplication)
• Minimal core dependencies
• ORM-like developer experience for APIs

See docs/architecture/adr/0001-architecture-principles.md for the full architecture principles and docs/architecture/adr/0002-layered-architecture.md for the conceptual layers.

---

What Plynt Is

Plynt provides core building blocks for API clients and service layers, focusing on:

• clear structure
• predictable behavior
• minimal magic
• explicit configuration

Plynt is not a web framework and does not replace tools like FastAPI, Flask, or Django. Instead, it complements them as a foundation for external service integration.

---

What Plynt Is Not

Plynt intentionally avoids:

• tight coupling to any web framework
• heavy abstractions
• hidden lifecycle behavior
• opinionated application structure

If you want a batteries-included framework, Plynt is probably not what you’re looking for.

---

Documentation

• Architecture Overview
• Architecture ADR Index
• Architecture Principles
• Layered Architecture
• Dependency Policy
• Product Vision
• Product Requirements
• Product Roadmap
• Generic LLM Connector Guide
• Salesforce Integration Guide
• Contributing

---

Intended Use Cases

• Microservices
• Internal APIs
• Platform / shared service libraries
• Long-running backend services
• Teams that want consistency without lock-in

---

Project Status

Plynt is in the 0.x release line. Documented public APIs follow the compatibility and deprecation policy in ADR-0027. Experimental capabilities are explicitly identified; Salesforce CDC still requires validation against a real org before production use.

---

Installation

Supports Python 3.12-3.15 on Linux, with 3.14 as the development default. Other environments are outside the current tested support contract.

pip install plynt

Optional extras:

pip install "plynt[httpx]"       # httpx2 transport backend
pip install "plynt[salesforce]"  # Salesforce REST connector

Canonical extras matrix

Extra	Installs	Typical use
httpx	httpx2 transport backend	Core HTTP transport for sync and async clients
grpc	gRPC and protobuf runtimes	Async gRPC clients and transports
django	Django adapter support + httpx2	Django integration helpers and cache adapters
drf	DRF adapter support + Django + httpx2	DRF service mixins and exception mapping patterns
fastapi	FastAPI adapter support + httpx2	FastAPI dependency wiring for plynt clients
salesforce	HTTP, signing, validation, Avro	REST, bulk, AI; combine with grpc for CDC

pip install "plynt[grpc,salesforce]"  # Experimental Salesforce CDC

OAuth2 configuration and lifecycle helpers are included in the package. There is no separate oauth extra. See the installation reference for all profiles.

Public API surface

Plynt treats package exports in plynt.base and plynt.http as the main public contract boundaries for core usage.

• Prefer importing from these package roots instead of internal submodules.
• Internal module paths may evolve as long as public exports remain compatible.
• Compatibility and deprecation policy is defined in ADR-0027.

---

Authentication

Plynt supports typed auth configuration via settings.auth.

Supported config types:

• BearerAuthConfig
• BasicAuthConfig
• OAuth2ClientCredentialsConfig
• OAuth2JWTBearerConfig (RFC 7523)
• OAuth2PasswordConfig (legacy)

JWT Bearer in core is dependency-light:

• The core middleware handles the OAuth2 token lifecycle.
• JWT signing is supplied via assertion_factory.
• You can use any signing implementation that returns a non-empty JWT string.

Example using typed settings + JWT Bearer:

from plynt.http.auth import AuthConfig, OAuth2JWTBearerConfig
from plynt.http.settings import HTTPSettings


def build_assertion() -> str:
    # Use your own signer implementation (PyJWT, jose, HSM client, etc.).
    return "<signed-jwt>"


class MySettings(HTTPSettings):
    @property
    def auth(self) -> AuthConfig | None:
        return OAuth2JWTBearerConfig(
            token_url="https://auth.example.com/oauth/token",
            assertion_factory=build_assertion,
            cache_key_material="my-issuer:service-account",
            scope="api.read api.write",
            ttl_leeway=30,
        )

For Salesforce-specific JWT claim construction and signing guidance, see docs/connectors/salesforce/README.md and docs/connectors/salesforce/architecture/adr/sf-0006-jwt-bearer-auth.md.

---

Roadmap

See docs/product/roadmap.md for the full roadmap, including what is implemented, what is planned, and what is explicitly out of scope.

High-level planned areas:

• Flask adapter, conditional on demonstrated demand
• SOAP transport (plynt[soap]) as long-term extension

Shipped connector highlights:

• Django, DRF, and FastAPI framework adapters are implemented.
• Async gRPC primitives and experimental Salesforce Pub/Sub CDC are implemented; real-org CDC validation remains open.
• Generic AI / LLM connector (plynt.connectors.llm) with neutral request, completion, and streaming chunk contract models.

---

Philosophy

Plynt follows a simple rule:

If it’s not essential for the foundation, it doesn’t belong here.

---

License

MIT