update documentation

Author: TexasCoding

src/project_x_py/__init__.py

@@ -1,24 +1,96 @@
 """
 ProjectX Python SDK for Trading Applications
 
-A comprehensive Python SDK for the ProjectX Trading Platform Gateway API, providing developers
-with tools to build sophisticated trading strategies and applications. This library offers
-comprehensive access to:
-
-- Market data retrieval and real-time streaming
-- Account management and authentication
-- Order placement, modification, and cancellation
-- Position management and portfolio analytics
-- Trade history and execution analysis
-- Advanced technical indicators and market analysis
-- Level 2 orderbook depth and market microstructure
+Author: @TexasCoding
+Date: 2025-08-02
+
+Overview:
+    A comprehensive Python SDK for the ProjectX Trading Platform Gateway API, providing
+    developers with tools to build sophisticated trading strategies and applications.
+    This library offers comprehensive access to real-time market data, order management,
+    position tracking, and advanced analytics for algorithmic trading.
+
+Key Features:
+    - Real-time market data streaming and historical data access
+    - Comprehensive order management (market, limit, stop, bracket orders)
+    - Position tracking and portfolio analytics
+    - Level 2 orderbook depth and market microstructure analysis
+    - Advanced technical indicators and pattern recognition
+    - Risk management and position sizing tools
+    - Multi-timeframe data management and analysis
+    - WebSocket-based real-time updates and event handling
+
+Core Components:
+    - ProjectX: Main client for API interactions and authentication
+    - OrderManager: Order placement, modification, and tracking
+    - PositionManager: Position monitoring, analytics, and risk management
+    - OrderBook: Level 2 market depth analysis and order flow
+    - RealtimeDataManager: Multi-timeframe real-time data processing
+    - ProjectXRealtimeClient: WebSocket-based real-time connections
+
+Trading Capabilities:
+    - Market data retrieval and real-time streaming
+    - Account management and authentication
+    - Order placement, modification, and cancellation
+    - Position management and portfolio analytics
+    - Trade history and execution analysis
+    - Advanced technical indicators and market analysis
+    - Level 2 orderbook depth and market microstructure
+    - Risk management and position sizing
+
+Example Usage:
+    ```python
+    from project_x_py import ProjectX, OrderManager, PositionManager
+
+    # Basic client setup
+    async with ProjectX.from_env() as client:
+        await client.authenticate()
+
+        # Get market data
+        bars = await client.get_bars("MGC", days=5)
+        instrument = await client.get_instrument("MGC")
+
+        # Place orders
+        order_manager = OrderManager(client)
+        response = await order_manager.place_market_order(
+            contract_id=instrument.id,
+            side=0,  # Buy
+            size=1,
+        )
+
+        # Track positions
+        position_manager = PositionManager(client)
+        positions = await position_manager.get_all_positions()
+
+        # Create complete trading suite
+        suite = await create_trading_suite(
+            instrument="MGC", project_x=client, timeframes=["1min", "5min", "15min"]
+        )
+    ```
+
+Architecture Benefits:
+    - Async-first design for high-performance trading applications
+    - Comprehensive error handling and retry logic
+    - Rate limiting and connection management
+    - Real-time data processing with WebSocket integration
+    - Modular design for flexible trading system development
+    - Type-safe operations with comprehensive validation
 
 **Important**: This is a development toolkit/SDK, not a trading strategy itself.
 It provides the infrastructure to help developers create their own trading applications
 that integrate with the ProjectX platform.
 
+Version: 2.0.5
 Author: TexasCoding
-Date: January 2025
+
+See Also:
+    - `client`: Main client for API interactions
+    - `order_manager`: Order management and tracking
+    - `position_manager`: Position monitoring and analytics
+    - `orderbook`: Level 2 market depth analysis
+    - `realtime_data_manager`: Real-time data processing
+    - `indicators`: Technical analysis and indicators
+    - `utils`: Utility functions and calculations
 """
 
 from typing import Any

src/project_x_py/client/__init__.py

@@ -1,6 +1,9 @@
 """
 Async ProjectX Python SDK - Core Async Client Module
 
+Author: @TexasCoding
+Date: 2025-08-02
+
 This module contains the async version of the ProjectX client class for the ProjectX Python SDK.
 It provides a comprehensive asynchronous interface for interacting with the ProjectX Trading Platform
 Gateway API, enabling developers to build high-performance trading applications.

src/project_x_py/client/auth.py

@@ -1,6 +1,9 @@
 """
 Authentication and account management for ProjectX async clients.
 
+Author: @TexasCoding
+Date: 2025-08-02
+
 Overview:
     This module implements the complete authentication lifecycle for ProjectX, including
     secure login using API key and username, JWT token handling, account selection, and
@@ -21,6 +24,7 @@
     import asyncio
     from project_x_py import ProjectX
 
+
     async def main():
         async with ProjectX.from_env() as client:
             await client.authenticate()
@@ -29,6 +33,7 @@ async def main():
             for acc in accounts:
                 print(acc.name, acc.balance)
 
+
     asyncio.run(main())
     ```
 
@@ -75,12 +80,35 @@ def __init__(self) -> None:
         self.account_info: Account | None = None
 
     async def _refresh_authentication(self: "ProjectXClientProtocol") -> None:
-        """Refresh authentication if token is expired or about to expire."""
+        """
+        Refresh authentication if token is expired or about to expire.
+
+        This method checks if the current authentication token needs refreshing
+        based on its expiration time and initiates a full re-authentication
+        if necessary. It's used internally to maintain session validity during
+        long-running operations without requiring explicit user intervention.
+
+        The refresh logic is controlled by the _should_refresh_token method,
+        which implements the token expiration policy (currently refreshing
+        when a token is within 5 minutes of expiration).
+        """
         if self._should_refresh_token():
             await self.authenticate()
 
     def _should_refresh_token(self: "ProjectXClientProtocol") -> bool:
-        """Check if token should be refreshed."""
+        """
+        Check if the authentication token should be refreshed.
+
+        This method determines whether the current JWT token needs to be refreshed
+        based on its expiration time. It implements the token refresh policy by
+        checking:
+
+        1. If no token expiry exists (not authenticated or expiry unknown)
+        2. If the token is within 5 minutes of expiration (configurable buffer)
+
+        Returns:
+            bool: True if token refresh is needed, False otherwise
+        """
         if not self.token_expiry:
             return True
 
@@ -191,7 +219,25 @@ async def authenticate(self: "ProjectXClientProtocol") -> None:
         )
 
     async def _ensure_authenticated(self: "ProjectXClientProtocol") -> None:
-        """Ensure client is authenticated before making API calls."""
+        """
+        Ensure client is authenticated before making API calls.
+
+        This method checks the authentication state and token validity before
+        allowing API operations to proceed. If the client is not authenticated
+        or if the authentication token is expired/about to expire, it will
+        automatically trigger the full authentication flow.
+
+        The method performs two key checks:
+        1. Whether the client has successfully authenticated (_authenticated flag)
+        2. Whether the token needs refreshing (via _should_refresh_token)
+
+        This provides a seamless authentication experience by handling token
+        expiration transparently without requiring explicit refresh calls.
+
+        Note:
+            This method is called internally by API methods and doesn't need
+            to be called directly in normal usage.
+        """
         if not self._authenticated or self._should_refresh_token():
             await self.authenticate()
 

src/project_x_py/client/base.py

@@ -1,6 +1,9 @@
 """
 ProjectX async base client: context-managed lifecycle, mixin composition, and helpers.
 
+Author: @TexasCoding
+Date: 2025-08-02
+
 Overview:
     Defines the foundational async client for ProjectX by combining all core functional
     mixins (auth, HTTP, cache, market data, trading) into a single context-managed class.
@@ -21,11 +24,13 @@
     import asyncio
     from project_x_py import ProjectX
 
+
     async def main():
         async with ProjectX.from_env() as client:
             await client.authenticate()
             print(client.get_account_info())
 
+
     asyncio.run(main())
     ```
 

src/project_x_py/client/cache.py

@@ -1,6 +1,9 @@
 """
 In-memory caching for instrument and market data with TTL and performance tracking.
 
+Author: @TexasCoding
+Date: 2025-08-02
+
 Overview:
     Provides efficient, per-symbol in-memory caching for instrument metadata and historical
     market data. Uses time-based TTL (time-to-live) for automatic expiry and memory cleanup,
@@ -67,7 +70,20 @@ def __init__(self) -> None:
         self.cache_hit_count = 0
 
     async def _cleanup_cache(self: "ProjectXClientProtocol") -> None:
-        """Clean up expired cache entries."""
+        """
+        Clean up expired cache entries to manage memory usage.
+
+        This method removes expired entries from both instrument and market data caches
+        based on the configured TTL (time-to-live). It helps prevent unbounded memory
+        growth during long-running sessions by:
+
+        1. Removing instrument cache entries that have exceeded their TTL
+        2. Removing market data cache entries that have exceeded their TTL
+        3. Triggering garbage collection when a significant number of entries are removed
+
+        The method is called periodically during normal API operations and updates
+        the last_cache_cleanup timestamp to track when cleanup was last performed.
+        """
         current_time = time.time()
 
         # Clean instrument cache

src/project_x_py/client/http.py

@@ -1,6 +1,9 @@
 """
 Async HTTP/2 client, rate-limiting, and robust error handling for ProjectX SDK.
 
+Author: @TexasCoding
+Date: 2025-08-02
+
 Overview:
     Implements the async HTTP/2 client logic for ProjectX API access, including connection
     pooling, automatic retry on transient errors, and adaptive rate limiting. All API calls
@@ -21,11 +24,13 @@
     import asyncio
     from project_x_py import ProjectX
 
+
     async def main():
         async with ProjectX.from_env() as client:
             status = await client.get_health_status()
             print(status["api_status"], status["client_stats"]["api_calls"])
 
+
     asyncio.run(main())
     ```
 
@@ -119,7 +124,20 @@ async def _create_client(self: "ProjectXClientProtocol") -> httpx.AsyncClient:
         return client
 
     async def _ensure_client(self: "ProjectXClientProtocol") -> httpx.AsyncClient:
-        """Ensure HTTP client is initialized."""
+        """
+        Ensure HTTP client is initialized and ready for API requests.
+
+        This method lazily initializes the HTTP client when needed, creating a new
+        client instance if one doesn't exist. It's used internally before making
+        any API requests to ensure a valid client connection is available.
+
+        Returns:
+            httpx.AsyncClient: The initialized HTTP client instance
+
+        Note:
+            This method is called automatically by _make_request and doesn't need
+            to be called directly in normal usage.
+        """
         if self._client is None:
             self._client = await self._create_client()
         return self._client

src/project_x_py/client/market_data.py

@@ -1,6 +1,9 @@
 """
 Async instrument search, selection, and historical bar data for ProjectX clients.
 
+Author: @TexasCoding
+Date: 2025-08-02
+
 Overview:
     Provides async methods for instrument discovery, smart contract selection, and retrieval
     of historical OHLCV bar data, with Polars DataFrame output for high-performance analysis.
@@ -21,12 +24,14 @@
     import asyncio
     from project_x_py import ProjectX
 
+
     async def main():
         async with ProjectX.from_env() as client:
             instrument = await client.get_instrument("ES")
             bars = await client.get_bars("ES", days=3, interval=15)
             print(bars.head())
 
+
     asyncio.run(main())
     ```
 
@@ -144,17 +149,30 @@ def _select_best_contract(
         """
         Select the best matching contract from search results.
 
-        This method implements smart contract selection logic for futures:
-        - Exact matches are preferred
-        - For futures, selects the front month contract
-        - For micro contracts, ensures correct symbol (e.g., MNQ for micro Nasdaq)
+        This method implements smart contract selection logic for futures and other
+        instruments, ensuring the most appropriate contract is selected based on
+        the search criteria. The selection algorithm follows these priorities:
+
+        1. Exact symbol match (case-insensitive)
+        2. For futures contracts:
+           - Identifies the base symbol (e.g., "ES" from "ESM23")
+           - Groups contracts by base symbol
+           - Selects the front month contract (chronologically closest expiration)
+        3. For micro contracts, ensures proper matching (e.g., "MNQ" for micro Nasdaq)
+        4. Falls back to the first result if no better match is found
+
+        The futures month codes follow CME convention: F(Jan), G(Feb), H(Mar), J(Apr),
+        K(May), M(Jun), N(Jul), Q(Aug), U(Sep), V(Oct), X(Nov), Z(Dec)
 
         Args:
-            instruments: List of instrument dictionaries from search
-            search_symbol: Original search symbol
+            instruments: List of instrument dictionaries from search results
+            search_symbol: Original search symbol provided by the user
 
         Returns:
-            Best matching instrument dictionary
+            dict[str, Any]: Best matching instrument dictionary with complete contract details
+
+        Raises:
+            ProjectXInstrumentError: If no instruments are found for the given symbol
         """
         if not instruments:
             raise ProjectXInstrumentError(f"No instruments found for: {search_symbol}")