How noviscient/formidium-api-python works
Project type and purpose
• This is a *client-library* (SDK) that wraps HTTP calls to the Formidium REST API.
• Its purpose is to expose a clean Python interface (API class in formidium.py) so downstream code can invoke methods like trades() and positions() without dealing with raw HTTP logic.
File structure
• Top-level files:
• formidium.py — core Python module implementing the API wrapper
• tests.py — end-to-end tests for the wrapper methods
• .env.example & README — configuration guidance
• pyproject.toml & requirements.txt — dependency management
• UV lock files & instructions for environment management (uv.lock)
• No “frontend” or “backend” per se—this is purely a library + test harness.
Extract key details from the README
• Uses UV (Astral’s environment manager) to install dependencies into a .venv.
• Expects a .env file with credentials to drive the HTTP calls.
• Tests are run via pytest against a live or mocked API endpoint.
Main components and relationships
a. Components:
• Developer / Consumer Code — your own application or scripts that import formidium.API.
• The formidium module — contains the API class, credential loader, HTTP client logic (e.g., requests).
• Environment Manager (UV + virtualenv) — ensures reproducible Python environment and installed deps.
• Configuration Layer — .env file → loaded at runtime, populating API credentials.
• External Service — the Formidium REST API endpoints on the Internet.
• Test Harness — pytest, using tests.py to validate wrapper behavior.
b. Interactions:
1. Developer writes code → instantiates API(base_url, api_key, passphrase, api_secret).
2. API module loads credentials from .env if not passed explicitly.
3. API methods construct HTTP requests → sent over the network to Formidium’s endpoints.
4. Formidium responds with JSON → API parses response and returns Python objects.
5. Tests invoke API methods in a controlled environment to assert correctness.
6. UV manages the Python runtime and dependencies so that formidium.py and tests.py run in a consistent environment.
c. Architectural patterns & design principles
• Single Responsibility — API class only handles request construction/response parsing.
• Dependency Injection — credentials and base URL can be passed in or loaded from .env.
• Environment Isolation — UV + virtualenv ensure “it works on my machine” consistency.
• Test-Driven Approach — tests.py as the integration test suite against live or stubbed endpoints.
d. Technologies & frameworks to annotate
• Python 3.x runtime
• UV (Astral) for env management
• virtualenv (the .venv folder)
• requests (or similar HTTP client) as a library inside formidium.py
• pytest for testing
• .env for runtime configuration
Detail
• Break formidium.py into sub-components if desired: Authentication, Request Builder, Response Parser.
• .env loader as a distinct step in the flow.
1. Environment Layer (UV → .venv → Python interpreter)
2. Library Layer (formidium module broken into config loader, HTTP client, business methods)
3. External Layer (Formidium REST API)
4. Consumer Layer (Developer application code + pytest tests)