# polarsource/polar-python architecture

> Architecture diagram of the GitHub repository polarsource/polar-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/polarsource/polar-python
- Repository: https://github.com/polarsource/polar-python

## Overview

##### Project Type and Purpose
- This is a Python client SDK (“polar-sdk”) for the Polar HTTP and Webhooks API. It is an open‐source, auto‐generated library (via Speakeasy) that provides:
- Pydantic models for request/response schemas
- Endpoint wrappers for synchronous and asynchronous HTTP calls (using httpx)
- Webhook validation helpers
- Configuration (retry, custom HTTP client, server selection, authentication)
- CI/CD pipelines for regeneration, publishing, and documentation

##### File‐Structure Analysis
- Top‐level
- docs/           – API docs, models, per‐resource SDK guides
- src/polar_sdk/   – Main SDK package
– _hooks/        – Codegen/plugin hooks
– httpclient.py  – HTTP client protocols
– models/        – Pydantic models (auto‐generated)
– endpoints (.py) – Resource clients (benefits.py, checkouts.py, etc.)
– utils/         – helpers (serializers, retries, URL building…)
– webhooks/      – validation logic
- scripts/         – README prep, publish
- .github/workflows – CI: sdk_generation, sdk_publish, docs
- pyproject.toml, poetry.toml – packaging & dependencies
- .devcontainer/   – reproducible dev environment

##### Key Insights from README
- Reinforces that this is an SDK, with sections on installation, usage (sync & async), webhooks, retries, error handling, authentication, debugging, pagination, resource management, and CI contribution guidelines.
- Mentions Speakeasy’s code‐generation process and that manual edits are overwritten.

##### Main Components
a. Code‐Generation & CI:
- Speakeasy generator (workflow: OpenAPI spec → auto‐generated models/endpoints)
- GitHub Actions
- Scripts (prepare_readme.py, publish.sh)
b. SDK Package:
- Polar class (entry point)
- HTTP Client abstraction (sync/async httpx)
- Endpoint modules (resources)
- Pydantic models
- Utilities (retries, logging, query params, serializers)
- Webhook validator
c. External Dependencies/Services:
- Polar REST API (production/sandbox)
- Webhooks (incoming HTTP callbacks)
- PyPI (package publishing)

##### Component Interactions
- Developer calls: Polar(...) → instantiates HTTP client → user invokes e.g. polar.customers.list(…)
- Endpoint module builds httpx.Request via httpclient.build_request()
- HTTP client sends request to Polar API server
- JSON response flows back → Pydantic models parse into Python objects → returned to user
- Retries configured at client or call level use utils/retries → intercept HTTP failures
- Webhooks: validate_event consumes raw request payload & headers → verifies signature → outputs Pydantic event model

##### Architectural Patterns & Principles
- Code Generation (Separation of concerns: schema → code)
- Adapter pattern (httpx.Client conforming to HTTP client Protocol)
- Factory (Polar class factory → sync/async clients)
- Model‐View‐Controller is not used; instead a procedural “service‐client” pattern for each resource
- Context‐manager pattern for resource management (closing HTTP connections)
- Pydantic for data validation & (de)serialization

1. Speakeasy generator & GitHub Actions on the left.
6. Bottom‐right: publishing line from CI to PyPI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Tooling & CI"
        SG["Speakeasy Generator"]:::tooling
        GH1["GitHub Actions: SDK Generation"]:::tooling
        GH2["GitHub Actions: SDK Publishing"]:::tooling
        GH3["GitHub Actions: Docs Trigger"]:::tooling
        SC1["Prepare README Script"]:::tooling
        SC2["Publish Script"]:::tooling
    end

    subgraph "Polar SDK Package"
        subgraph "Entry & Config"
            P["Polar (SDK Entry)"]:::sdk
            BS["BaseSDK"]:::sdk
            CF["SDK Config"]:::sdk
        end
        subgraph "HTTP Client"
            HC["httpclient"]:::sdk
        end
        subgraph "Endpoints"
            CUS["customers.py"]:::sdk
            CHK["checkouts.py"]:::sdk
            ORD["orders.py"]:::sdk
            BEN["benefits.py"]:::sdk
        end
        subgraph "Models"
            MOD["models/"]:::sdk
        end
        subgraph "Utils"
            R["retries.py"]:::sdk
            UURL["url.py"]:::sdk
            S["serializers.py"]:::sdk
            Q["queryparams.py"]:::sdk
        end
        subgraph "Webhooks"
            WB["webhooks/"]:::sdk
        end
        V["_version.py"]:::sdk
        HK["_hooks/"]:::sdk
    end

    subgraph "External Services"
        API["Polar API (prod/sandbox)"]:::external
        WH["Webhook Requests"]:::external
        PY["PyPI"]:::external
    end

    GH1 -->|"triggers generate"| SG
    SG -->|"generate→ models"| MOD
    SG -->|"generate→ endpoints"| CUS
    SG -->|"generate→ endpoints"| CHK
    SG -->|"generate→ endpoints"| ORD
    SG -->|"generate→ endpoints"| BEN
    SG -->|"use hooks"| HK

    GH2 -->|"publish→"| PY
    SC2 -->|"publish→"| PY

    P -->|"instantiates"| HC
    P -->|"exposes resource clients"| CUS
    P -->|"exposes resource clients"| CHK
    P -->|"exposes resource clients"| ORD
    P -->|"exposes resource clients"| BEN
    CUS -->|"build_request()"| HC
    CHK -->|"build_request()"| HC
    ORD -->|"build_request()"| HC
    BEN -->|"build_request()"| HC

    HC -->|"sync/async calls"| API
    API -->|"response→ parse"| MOD
    MOD -->|"models returned"| P

    CUS -->|"use helpers"| R
    CUS -->|"use helpers"| UURL
    CUS -->|"use helpers"| S
    CUS -->|"use helpers"| Q

    WH -->|"webhook verify"| WB
    WB -->|"outputs event model"| MOD

    click SG "https://github.com/polarsource/polar-python/tree/main/src/polar_sdk/_hooks/"
    click GH1 "https://github.com/polarsource/polar-python/blob/main/.github/workflows/sdk_generation.yaml"
    click GH2 "https://github.com/polarsource/polar-python/blob/main/.github/workflows/sdk_publish.yaml"
    click GH3 "https://github.com/polarsource/polar-python/blob/main/.github/workflows/trigger_docs.yaml"
    click SC1 "https://github.com/polarsource/polar-python/blob/main/scripts/prepare_readme.py"
    click SC2 "https://github.com/polarsource/polar-python/blob/main/scripts/publish.sh"
    click P "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/sdk.py"
    click BS "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/basesdk.py"
    click CF "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/sdkconfiguration.py"
    click HC "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/httpclient.py"
    click CUS "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/customers.py"
    click CHK "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/checkouts.py"
    click ORD "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/orders.py"
    click BEN "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/benefits.py"
    click MOD "https://github.com/polarsource/polar-python/tree/main/src/polar_sdk/models/"
    click R "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/utils/retries.py"
    click UURL "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/utils/url.py"
    click S "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/utils/serializers.py"
    click Q "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/utils/queryparams.py"
    click WB "https://github.com/polarsource/polar-python/tree/main/src/polar_sdk/webhooks/"
    click V "https://github.com/polarsource/polar-python/blob/main/src/polar_sdk/_version.py"

    classDef tooling fill:#B3E5FC,stroke:#0288D1,color:#000
    classDef sdk fill:#E1BEE7,stroke:#8E24AA,color:#000
    classDef external fill:#C8E6C9,stroke:#388E3C,color:#000
```
