# qarnot/qarnot-sdk-python architecture

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

- Interactive diagram: https://gitdiagram.com/qarnot/qarnot-sdk-python
- Repository: https://github.com/qarnot/qarnot-sdk-python

## Overview

##### Project type and purpose
- From the README and file tree, this is an open-source Python SDK for Qarnot’s cloud computing service.
- Purpose: expose Qarnot compute and storage REST APIs via a convenient Python interface, enabling users to create/manage tasks, pools, buckets, quotas, secrets, etc.

##### File structure
- Top-level packaging and CI:
- setup.py, pyproject.toml, setup.cfg, MANIFEST.in – package metadata & build
- .github, .gitlab, CI YAMLs – continuous integration & publishing
- Source code:
- qarnot/ – core SDK modules
– connection.py – handles authentication, endpoint resolution, HTTP session
– job.py, task.py, pool.py, bucket.py, storage.py, etc. – one module per API resource
– _util.py, _retry.py, _filter.py – shared utilities (pagination, retries, filters)
- versioneer.py – version management
- Documentation:
- doc/source/api – Sphinx-generated per-module API docs
- Tests:
- test/ – unit tests targeting each resource module

##### README for additional insights
- Describes core usage: create Connection, create and run a Task, fetch stdout
- Points to Docker-batch payloads, digital-boiler nodes on the cloud

##### Detail without overthinking
- Every logical component/module identified in the file tree

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Python SDK"
        direction TB
        conn["Connection Manager"]:::sdk
        http["HTTP/REST Client"]:::sdk
        retry["Retry Strategy"]:::util
        pag["Pagination Utility"]:::util
        version["Version Management"]:::util
        task["Task Module"]:::resource
        job["Job Module"]:::resource
        pool["Pool Module"]:::resource
        bucket["Bucket Module"]:::resource
        adv_bucket["Advanced Bucket Module"]:::resource
        storage["Storage Module"]:::resource
        quotas["Computing Quotas Module"]:::resource
        secrets["Secrets Management Module"]:::resource
        carbon["Carbon Facts Module"]:::resource
        priv["Privileges Module"]:::resource
        sched["Scheduling Type Module"]:::resource
        net_rule["Forced Network Rule Module"]:::resource
        hw["Hardware Constraint Module"]:::resource
        error["Error Handling"]:::util
        helper["Helper Utilities"]:::util
    end

    subgraph "External Dependencies"
        direction TB
        docker["Docker Runtime"]:::external
        http_lib["HTTP Transport (requests)"]:::external
    end

    subgraph "Qarnot Cloud"
        direction TB
        gateway["API Gateway"]:::cloud
        subgraph "Backend Services"
            direction TB
            compute["Compute Service"]:::cloud
            storage_svc["Storage Service"]:::cloud
            billing["Quota & Billing Service"]:::cloud
            secrets_svc["Secrets Management Service"]:::cloud
            monitoring["Monitoring & Carbon Facts Service"]:::cloud
        end
    end

    subgraph "Documentation & Testing"
        direction TB
        docs["SDK Documentation"]:::doc
        tests["Unit Tests"]:::test
    end

    subgraph "Packaging & CI/CD"
        direction TB
        pkg["Packaging & Build Config"]:::infra
        ci["CI/CD Workflows"]:::infra
    end

    conn -->|authenticate| gateway
    http -->|REST calls| gateway
    retry -->|applied to| http
    pag -->|applied to| http
    helper -->|used by| conn
    version -.-> helper

    task -->|uses| http
    job -->|uses| http
    pool -->|uses| http
    bucket -->|uses| http
    adv_bucket -->|uses| http
    storage -->|uses| http
    quotas -->|uses| http
    secrets -->|uses| http
    carbon -->|uses| http
    priv -->|uses| http
    sched -->|uses| http
    net_rule -->|uses| http
    hw -->|uses| http
    error -->|handles| http

    gateway -->|forwards| compute
    gateway -->|forwards| storage_svc
    gateway -->|forwards| billing
    gateway -->|forwards| secrets_svc
    gateway -->|forwards| monitoring

    compute -->|dispatch tasks to| docker
    storage_svc -->|store/retrieve| docker

    http_lib -->|used by| http

    docs -->|document modules| task
    docs -->|document modules| job
    docs -->|document modules| pool
    docs -->|document modules| bucket

    tests -->|test| task
    tests -->|test| job
    tests -->|test| pool
    tests -->|test| bucket
    tests -->|test| helper

    pkg -->|defines| helper
    ci -->|runs| tests

    classDef sdk fill:#D6EAF8,stroke:#3498DB,stroke-width:1px
    classDef resource fill:#E8DAEF,stroke:#9B59B6,stroke-width:1px
    classDef util fill:#FDEBD0,stroke:#E67E22,stroke-width:1px
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:1px
    classDef cloud fill:#FADBD8,stroke:#C0392B,stroke-width:1px
    classDef doc fill:#FEF9E7,stroke:#F1C40F,stroke-width:1px
    classDef test fill:#EBDEF0,stroke:#8E44AD,stroke-width:1px
    classDef infra fill:#ECF0F1,stroke:#7F8C8D,stroke-width:1px

    click conn "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/connection.py"
    click http "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/_util.py"
    click retry "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/_retry.py"
    click pag "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/_filter.py"
    click pag "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/paginate.py"
    click version "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/_version.py"
    click version "https://github.com/qarnot/qarnot-sdk-python/blob/master/versioneer.py"
    click task "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/task.py"
    click job "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/job.py"
    click pool "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/pool.py"
    click bucket "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/bucket.py"
    click adv_bucket "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/advanced_bucket.py"
    click storage "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/storage.py"
    click quotas "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/computing_quotas.py"
    click secrets "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/secrets.py"
    click carbon "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/carbon_facts.py"
    click priv "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/privileges.py"
    click sched "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/scheduling_type.py"
    click net_rule "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/forced_network_rule.py"
    click hw "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/hardware_constraint.py"
    click error "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/error.py"
    click error "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/exceptions.py"
    click helper "https://github.com/qarnot/qarnot-sdk-python/blob/master/qarnot/helper.py"
    click docs "https://github.com/qarnot/qarnot-sdk-python/tree/master/doc/source/api/"
    click tests "https://github.com/qarnot/qarnot-sdk-python/tree/master/test/"
    click pkg "https://github.com/qarnot/qarnot-sdk-python/blob/master/setup.py"
    click pkg "https://github.com/qarnot/qarnot-sdk-python/blob/master/setup.cfg"
    click pkg "https://github.com/qarnot/qarnot-sdk-python/blob/master/pyproject.toml"
    click pkg "https://github.com/qarnot/qarnot-sdk-python/blob/master/MANIFEST.in"
    click ci "https://github.com/qarnot/qarnot-sdk-python/blob/master/.github/workflows/python-publish.yml"
    click ci "https://github.com/qarnot/qarnot-sdk-python/blob/master/.gitlab-ci.yml"
```
