# jawah/niquests architecture

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

- Interactive diagram: https://gitdiagram.com/jawah/niquests
- Repository: https://github.com/jawah/niquests

## Overview

##### Project Type and Purpose
- Niquests is a robust HTTP client library written in Python. It is designed for making HTTP requests (both synchronous and asynchronous) while offering next-generation features such as HTTP/2, HTTP/3, multiplexing, DNS enhancements, and a rich set of extensions.
- The README emphasizes that Niquests is meant to be a safer, faster, and more feature-rich alternative to Requests, primarily targeting developers needing advanced networking capabilities. Note that it is a library (with a strong emphasis on the networking stack) rather than a full web application or microservice-based system.

##### File Structure
- Top-Level Files & Directories: The project contains configuration files (.gitignore, Makefile, pyproject.toml, etc.), documentation (docs/), continuous integration and contribution guides (.github/), and tests (tests/).
- Source Code: The core code lives in the src/niquests directory. This directory is modularized into various components such as:
- API layers (api.py, async_api.py)
- Session management (sessions.py, async_session.py)
- Adapters and Connection Handling (adapters.py, packages.py)
- Core functionalities like cookies, authentication, request/response models, hooks, etc.
- Extensions in the extensions subdirectory (providing advanced features like OCSP and TLS handling).
- Utility modules (_async.py, _compat.py, _constant.py, _typing.py, etc.).
- Tests: The tests directory includes unit tests for every defined functionality, ensuring the client works in both asynchronous and synchronous modes.

##### README for Key Insights
- The README provides details on the client’s API usage (both sync and async), examples, benchmarking comparisons, and highlights advanced features like multiplexing, DNS over variants, and TLS enhancements.
- The feature tables and code snippets indicate that the design focuses on multiple layers of abstraction (user interface, session management, adapters, extension hooks, and low-level networking).

##### Establish the Main Components
- Client API Interface:
- Synchronous API (api.py)
- Asynchronous API (async_api.py)
- Session Management:
- Regular sessions (sessions.py)
- Asynchronous sessions (async_session.py)
- Request Flow Core:
- Adapters to handle version-specific protocols (adapters.py)
- Utility functions (utils.py)
- Models and status codes (models.py, status_codes.py)
- Exception handling (exceptions.py)
- Extensions and Advanced Features:
- Extensions for OCSP and TLS optimizations (extensions/ folder with _async_ocsp.py, _ocsp.py, _picotls.py)
- Additional hooks and cookie management (hooks.py, cookies.py, auth.py)
- Infrastructure & Integration Components:
- Integration with network fine tuning and DNS settings (likely spread across utils and possibly within sessions)
- Vendor dependencies and compatibility layers (e.g., in _vendor and _compat modules)
- Testing & Documentation Layers:
- Test suite (tests/)
- Documentation configurations (docs/)

##### Relationships & Interactions
- The public-facing client API (sync and async) accepts HTTP requests and passes them to session management objects which in turn use adapters to manage low-level connections.
- The adapters interact with the underlying networking libraries and incorporate functionalities such as connection pooling, multiplexing, and protocol negotiation (HTTP/2, HTTP/3).
- Extensions and hooks enhance the request/response cycle by injecting optional features (like OCSP verification, custom DNS behaviors, and TLS improvements).
- Utility modules assist all layers with common functions, error handling, and type utilities.
- The test suite validates these components ensuring they interact correctly, while CI workflows (GitHub workflows) help maintain code quality.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client API Interface
    subgraph "Client API Interface"
        subgraph "Synchronous API"
            SyncAPI_A("api.py"):::sync
            SyncAPI_S("sessions.py"):::sync
            SyncAPI_A --> SyncAPI_S
        end
        subgraph "Asynchronous API"
            AsyncAPI_A("async_api.py"):::async
            AsyncAPI_S("async_session.py"):::async
            AsyncAPI_A --> AsyncAPI_S
        end
        APIAggregator("Client API Aggregator")
    end

    %% Connections from API Interface to Aggregator
    SyncAPI_A --> APIAggregator
    SyncAPI_S --> APIAggregator
    AsyncAPI_A --> APIAggregator
    AsyncAPI_S --> APIAggregator

    %% Request Handling Core
    subgraph "Request Handling Core"
        Adapters("Adapters"):::core
        Utils("Utilities"):::core
        Models("Models"):::core
        StatusCodes("Status Codes"):::core
        Exceptions("Exceptions"):::core
        Adapters --> Utils
        Utils --> Models
        Models --> StatusCodes
        StatusCodes --> Exceptions
    end

    %% Extensions & Advanced Features
    subgraph "Extensions & Advanced Features"
        Extensions("Extensions"):::extension
        Hooks("Hooks"):::extension
        Cookies("Cookies"):::extension
        Auth("Auth"):::extension
        Hooks --> Cookies
        Cookies --> Auth
    end

    %% Networking & Connection Management
    Networking("Networking & Connection Management"):::network

    %% Support Layer
    subgraph "Support"
        Tests("Tests"):::support
        DocsCI("Documentation & CI"):::support
    end

    %% Flow Connections
    APIAggregator -->|"sends_request"| Adapters
    Exceptions -->|"triggers_extensions"| Extensions
    Adapters --> Utils
    Utils --> Models
    Models --> StatusCodes
    StatusCodes --> Exceptions
    Exceptions --> Networking
    Extensions --> Networking
    Networking -->|"response"| APIAggregator
    APIAggregator -->|"validated_by"| Tests
    APIAggregator -->|"validated_by"| DocsCI

    %% Styles
    classDef sync fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef async fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef extension fill:#e6ccff,stroke:#663399,stroke-width:2px;
    classDef network fill:#fff2cc,stroke:#cc9900,stroke-width:2px;
    classDef support fill:#d9ead3,stroke:#38761d,stroke-width:2px;

    %% Click Events
    click SyncAPI_A "https://github.com/jawah/niquests/blob/main/src/niquests/api.py"
    click SyncAPI_S "https://github.com/jawah/niquests/blob/main/src/niquests/sessions.py"
    click AsyncAPI_A "https://github.com/jawah/niquests/blob/main/src/niquests/async_api.py"
    click AsyncAPI_S "https://github.com/jawah/niquests/blob/main/src/niquests/async_session.py"
    click Adapters "https://github.com/jawah/niquests/blob/main/src/niquests/adapters.py"
    click Utils "https://github.com/jawah/niquests/blob/main/src/niquests/utils.py"
    click Models "https://github.com/jawah/niquests/blob/main/src/niquests/models.py"
    click StatusCodes "https://github.com/jawah/niquests/blob/main/src/niquests/status_codes.py"
    click Exceptions "https://github.com/jawah/niquests/blob/main/src/niquests/exceptions.py"
    click Extensions "https://github.com/jawah/niquests/tree/main/src/niquests/extensions/"
    click Hooks "https://github.com/jawah/niquests/blob/main/src/niquests/hooks.py"
    click Cookies "https://github.com/jawah/niquests/blob/main/src/niquests/cookies.py"
    click Auth "https://github.com/jawah/niquests/blob/main/src/niquests/auth.py"
    click Tests "https://github.com/jawah/niquests/tree/main/tests/"
    click DocsCI "https://github.com/jawah/niquests/tree/main/docs/"
```
