API Initialization

The stolgo library provides a structured approach to initializing connections with various financial data providers, such as Nasdaq and Samco. Initialization involves configuring connection parameters like timeouts and retries, establishing sessions, and handling authentication where required. This process ensures that subsequent data requests are executed through stable, pre-configured communication channels.

The library utilizes a centralized request handling mechanism through the stolgo.request module, which abstracts the complexities of HTTP sessions and error handling. This allows specific data provider classes to focus on endpoint-specific logic while inheriting robust connection management.

Sources: lib/stolgo/request.py, lib/stolgo/nasdaq.py:46-51, lib/stolgo/samco.py:76-96

Core Request Architecture

At the heart of stolgo's API initialization is the RequestUrl class. It initializes a requests.Session object configured with custom adapters to handle timeouts and retries automatically.

Connection Parameters

Initialization across the library relies on several default constants to ensure consistent network behavior:

Sources: lib/stolgo/request.py:7-8, lib/stolgo/nasdaq.py:11-12

Session Management

The RequestUrl class uses a TimeoutHTTPAdapter and a Retry strategy from urllib3 to manage HTTP connections. This includes a backoff_factor of 1 and a status_forcelist that targets common server errors (429, 500, 502, 503, 504).

The diagram shows the sequence of steps taken to prepare a network session for data fetching.
Sources: lib/stolgo/request.py:53-70

Provider-Specific Initialization

Nasdaq Initialization

The Nasdaq class initializes by determining the request execution mode. It supports both standard RequestUrl (using the requests library) and a Curl mode for executing requests via system subprocesses.

• Standard Mode: Uses RequestUrl for managed HTTP sessions.
• Cloud Mode: Uses the Curl class, which constructs and executes shell commands for environments where the requests library might be restricted.

Sources: lib/stolgo/nasdaq.py:46-51, lib/stolgo/request.py:38-50

Samco Initialization and Authentication

Unlike the public Nasdaq API, Samco requires a session-based login. The initialization of the Samco class triggers an immediate authentication flow.

1. Credential Setup: Takes user_id, password, and yob (Year of Birth).
2. Login Request: Sends a POST request to the Samco login URL.
3. Token Storage: Upon success, extracts the sessionToken from the response.
4. Header Configuration: Updates DATA_HEADER with the x-session-token for all subsequent authenticated requests.

The sequence diagram illustrates the automated authentication flow occurring during Samco object instantiation.
Sources: lib/stolgo/samco.py:76-96, lib/stolgo/samco.py:44-48

Data Range Initialization

API calls for data fetching require initialized date ranges. The stolgo.helper module provides logic to normalize start dates, end dates, and periods before they are passed to the API endpoints.

• Default Range: If no dates are provided, initialization defaults to 250 days.
• Formatting: Dates are converted to pandas.Timestamp objects and formatted according to the provider's requirements (e.g., %Y-%m-%d for Nasdaq).

Sources: lib/stolgo/helper.py:53-83, lib/stolgo/nasdaq.py:14, lib/stolgo/samco.py:41-42

Summary

API Initialization in stolgo is a multi-layered process that transitions from low-level network session configuration in request.py to high-level provider authentication in samco.py. By centralizing the request logic and providing helper utilities for date normalization, the library ensures that API interactions are resilient, authenticated, and consistent across different financial data sources.