How uname-yang/pysnowball works
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.