# uname-yang/pysnowball architecture

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

- Interactive diagram: https://gitdiagram.com/uname-yang/pysnowball
- Repository: https://github.com/uname-yang/pysnowball

## Overview

##### Project Type and Purpose
- This is an open-source Python client library (“pysnowball”) that wraps the undocumented Snowball (Xueqiu) App REST APIs.
- It provides Python functions to fetch real-time and historical market data (stocks, funds, indices, convertible bonds, user watchlists, etc.).
- It’s not a web service or full-stack app—it's a pure client SDK that communicates with Snowball’s HTTP endpoints.

##### File Structure Analysis
- Top level:
- APIs/ – markdown docs for each REST endpoint (serves as reference)
- pysnowball/ – Python package modules implementing API calls
- tests/ – unit tests (currently tests/test_fund.py)
- setup.py – packaging
- Key modules:
- token.py – manages user’s authentication token
- api_ref.py – central registry of endpoint URLs and parameter schemas
- utls.py – HTTP request helper (build headers, parse JSON)
- fund.py, finance.py, realtime.py, index.py, etc. – one module per Snowball domain
- There are no backend services, databases, or frontends—only outbound HTTP to Snowball.

a. Main Components
1. User Application (your Python script)
2. Pysnowball Client Library
– TokenManager (token.py)
– EndpointRegistry (api_ref.py)
– HTTP Client (utls.py)
– Domain Modules (fund.py, realtime.py, index.py, etc.)
– Test Suite (tests/)
3. External Snowball REST API (HTTPS endpoints)
4. Documentation Artifacts (APIs/*.md)

b. Component Relationships and Data Flow
- The User Application imports pysnowball modules and calls e.g. ball.set_token(...) → stored in TokenManager.
- A domain call (e.g. ball.kline(…)) invokes Domain Module → looks up URL and params in EndpointRegistry → constructs HTTP request using HTTP Client (utls) + Token header → sends HTTPS request to Snowball API → receives JSON → returns parsed data to User.
- Tests drive Domain Modules, mocking or hitting real endpoints, verifying responses.

c. Architectural Patterns and Principles
- Modular packaging: one Python module per API domain for maintainability.
- Single responsibility: TokenManager only handles auth, utls only handles HTTP, api_ref only lists endpoints.
- Extensibility: add new API domains by creating new module + adding docs in APIs/.
- Dependency injection: Domain Modules depend on api_ref and utls but are loosely coupled.

d. Technologies and Libraries
- Python 3.x
- requests (implied by utls.py) or built-in urllib
- pytest or unittest for tests
- setuptools for packaging

##### Detail Level
- Every module category:
- Core (token, api_ref, utls)
- Domain (fund, realtime, finance, index, etc.)
- Packaging (setup.py, requirements.txt)
- Documentation (APIs/*.md)
- Tests (tests/)
- Do not clutter with every function—group by module/domain.
- How new modules fit into the overall package.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Application
    subgraph "User Application"
        UA["Python Script"]:::external
    end

    %% Pysnowball Library
    subgraph "Pysnowball Library"
        subgraph "Core Modules"
            TM["TokenManager"]:::core
            ER["EndpointRegistry"]:::core
            HC["HTTP Client"]:::core
        end
        subgraph "Domain Modules"
            FM["fund"]:::domain
            FN["finance"]:::domain
            RT["realtime"]:::domain
            IN["index"]:::domain
            BD["bond"]:::domain
            CP["capital"]:::domain
            CS["cons"]:::domain
            CB["cube"]:::domain
            F10["f10"]:::domain
            HX["hkex"]:::domain
            RP["report"]:::domain
            SG["suggest"]:::domain
            US["user"]:::domain
        end
        Packaging["Packaging"]:::packaging
        Docs["Documentation"]:::docs
        Tests["Test Suite"]:::tests
    end

    %% External API
    ExtAPI["Snowball REST API"]:::external

    %% Connections
    UA -->|"set_token()"| TM
    UA -->|"calls domain functions"| FM
    FM -->|"lookup URL/params"| ER
    FN -->|"lookup URL/params"| ER
    RT -->|"lookup URL/params"| ER
    IN -->|"lookup URL/params"| ER
    BD -->|"lookup URL/params"| ER
    CP -->|"lookup URL/params"| ER
    CS -->|"lookup URL/params"| ER
    CB -->|"lookup URL/params"| ER
    F10 -->|"lookup URL/params"| ER
    HX -->|"lookup URL/params"| ER
    RP -->|"lookup URL/params"| ER
    SG -->|"lookup URL/params"| ER
    US -->|"lookup URL/params"| ER

    FM -->|"use HTTP client"| HC
    FN -->|"use HTTP client"| HC
    RT -->|"use HTTP client"| HC
    IN -->|"use HTTP client"| HC
    BD -->|"use HTTP client"| HC
    CP -->|"use HTTP client"| HC
    CS -->|"use HTTP client"| HC
    CB -->|"use HTTP client"| HC
    F10 -->|"use HTTP client"| HC
    HX -->|"use HTTP client"| HC
    RP -->|"use HTTP client"| HC
    SG -->|"use HTTP client"| HC
    US -->|"use HTTP client"| HC

    HC -->|"HTTPS request"| ExtAPI
    ExtAPI -->|"JSON response"| HC
    HC -->|"parsed data"| FM
    HC -->|"parsed data"| FN
    HC -->|"parsed data"| RT
    HC -->|"parsed data"| IN
    HC -->|"parsed data"| BD
    HC -->|"parsed data"| CP
    HC -->|"parsed data"| CS
    HC -->|"parsed data"| CB
    HC -->|"parsed data"| F10
    HC -->|"parsed data"| HX
    HC -->|"parsed data"| RP
    HC -->|"parsed data"| SG
    HC -->|"parsed data"| US

    Tests -->|"invokes modules"| FM
    Tests -->|"invokes modules"| FN

    %% Click Events
    click TM "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/token.py"
    click ER "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/api_ref.py"
    click HC "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/utls.py"
    click FM "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/fund.py"
    click FN "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/finance.py"
    click RT "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/realtime.py"
    click IN "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/index.py"
    click BD "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/bond.py"
    click CP "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/capital.py"
    click CS "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/cons.py"
    click CB "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/cube.py"
    click F10 "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/f10.py"
    click HX "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/hkex.py"
    click RP "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/report.py"
    click SG "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/suggest.py"
    click US "https://github.com/uname-yang/pysnowball/blob/master/pysnowball/user.py"
    click Docs "https://github.com/uname-yang/pysnowball/tree/master/APIs/"
    click Packaging "https://github.com/uname-yang/pysnowball/blob/master/setup.py"
    click Tests "https://github.com/uname-yang/pysnowball/tree/master/tests/"

    %% Styles
    classDef core fill:#B3D7F3,stroke:#1F618D,color:#1B4F72
    classDef domain fill:#D7E6F9,stroke:#2874A6,color:#1B2631
    classDef external fill:#FAD7A0,stroke:#D68910,color:#6E2C00
    classDef docs fill:#F7DC6F,stroke:#B7950B,stroke-dasharray: 5 5
    classDef packaging fill:#D5F5E3,stroke:#229954,color:#145A32
    classDef tests fill:#F5B7B1,stroke:#C0392B,color:#641E16
```
