test: improve session module testing and documentation (v3.5.5)

Testing improvements:
- Add comprehensive test coverage for session filtering functionality
- Test DST transitions, timezone handling, and edge cases
- Fix 11 bugs discovered through TDD methodology
- Achieve 163/163 tests passing with 88% coverage
- Reduce cyclomatic complexity in 4 functions
- Fix all MyPy type annotation errors

Documentation updates:
- Complete rewrite of session documentation for accuracy
- Remove references to non-existent methods
- Update all examples to use correct async patterns
- Create 5 new working example scripts
- Add comprehensive README with 935 lines of examples

Bug fixes:
- Fix DST transition detection for edge cases
- Handle naive datetime objects correctly
- Fix BREAK session detection logic
- Fix DataFrame boolean evaluation in examples
- Fix Polars correlation calculation methods
- Add proper type checking for dictionary operations

Code quality:
- Make 4 sync functions private for async compliance
- Add type annotations throughout
- Fix IDE type checking issues with pragmas
- Pass all ruff, mypy, and bandit checks

Breaking changes:
- None - maintains backward compatibility

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: TexasCoding

.secrets.baseline

@@ -133,7 +133,7 @@
         "filename": "CHANGELOG.md",
         "hashed_secret": "89a6cfe2a229151e8055abee107d45ed087bbb4f",
         "is_verified": false,
-        "line_number": 2107
+        "line_number": 2149
       }
     ],
     "README.md": [
@@ -325,5 +325,5 @@
       }
     ]
   },
-  "generated_at": "2025-08-31T20:27:03Z"
+  "generated_at": "2025-09-01T00:25:00Z"
 }

CHANGELOG.md

@@ -14,6 +14,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migration guides will be provided for all breaking changes
 - Semantic versioning (MAJOR.MINOR.PATCH) is strictly followed
 
+## [3.5.5] - 2025-01-21
+
+### ✅ Testing
+
+**Comprehensive Sessions Module Testing**:
+- **163 Tests Passing**: Complete test suite for sessions module with 88% coverage
+- **TDD Methodology**: All tests validate expected behavior, not current implementation
+- **Bug Fixes**: Fixed 11 critical bugs including DST transitions, naive datetime handling, and BREAK session detection
+- **Async Compliance**: Made 4 sync functions private to maintain 100% async public API
+- **Complexity Reduction**: Refactored 4 high-complexity functions using helper methods
+- **Type Safety**: Fixed all MyPy type annotation errors with proper generic types
+
+### 📝 Documentation
+
+**Sessions Documentation Overhaul**:
+- **Complete Guide**: Created comprehensive README.md for sessions module with working examples
+- **5 Example Scripts**: Created tested, working examples for all session functionality:
+  - `01_basic_session_filtering.py` - Basic filtering and market status
+  - `02_session_statistics.py` - Statistics and analytics
+  - `03_session_indicators.py` - Session-aware indicators
+  - `04_session_comparison.py` - RTH vs ETH comparison
+  - `05_multi_instrument_sessions.py` - Multi-instrument management
+- **API Accuracy**: Fixed all incorrect method signatures and usage patterns
+- **DataFrame Safety**: Added proper None checks and `.is_empty()` evaluations throughout
+
+### 🐛 Fixed
+
+**Session Module Bugs**:
+- **DST Transitions**: Fixed edge cases during daylight saving time transitions
+- **Naive Datetime Handling**: Properly handle naive datetimes with timezone awareness
+- **BREAK Session Detection**: Fixed incorrect BREAK period detection logic
+- **DataFrame Evaluation**: Fixed "ambiguous truth value" errors with proper boolean checks
+- **Correlation Calculation**: Fixed Polars Series correlation method usage
+- **Type Conversions**: Added safe type conversions with None checks
+
+### 🔧 Changed
+
+- **Public API**: Made sync utility functions private with underscore prefix to maintain async consistency
+- **Example Organization**: Moved all session examples to dedicated `examples/sessions/` directory
+- **Documentation Structure**: Renamed guide to README.md for automatic GitHub display
+- **Error Handling**: Improved error messages and added comprehensive troubleshooting section
+
 ## [3.5.4] - 2025-01-31
 
 ### 🚀 Added

README.md

@@ -21,9 +21,9 @@ A **high-performance async Python SDK** for the [ProjectX Trading Platform](http
 
 This Python SDK acts as a bridge between your trading strategies and the ProjectX platform, handling all the complex API interactions, data processing, and real-time connectivity.
 
-## 🚀 v3.5.4 - Lorenz Formula Indicator & Test Suite Improvements
+## 🚀 v3.5.5 - Sessions Module Testing & Documentation
 
-**Latest Version**: v3.5.4 - Introduces the Lorenz Formula indicator applying chaos theory to market analysis, plus comprehensive test suite reorganization and enhanced statistics module coverage.
+**Latest Version**: v3.5.5 - Comprehensive testing and documentation improvements for the ETH vs RTH Trading Sessions feature, ensuring production-ready session filtering and analysis.
 
 **Key Benefits**:
 - 🎯 **Multi-Asset Strategies**: Trade ES vs NQ pairs, commodity spreads, sector rotation
@@ -32,7 +32,7 @@ This Python SDK acts as a bridge between your trading strategies and the Project
 - 🛡️ **Backward Compatible**: Existing single-instrument code continues to work
 - ⚡ **Performance Optimized**: Parallel context creation and resource sharing
 
-See [CHANGELOG.md](CHANGELOG.md) for complete v3.5.4 features including the new Lorenz indicator and test improvements.
+See [CHANGELOG.md](CHANGELOG.md) for complete v3.5.5 features including sessions module improvements and comprehensive example scripts.
 
 ### 📦 Production Stability Guarantee
 

docs/api/trading-suite.md

@@ -92,14 +92,14 @@ async def session_setup():
 
     # Custom session times
     from datetime import time
-    import pytz
 
     custom_config = SessionConfig(
         session_type=SessionType.RTH,
-        custom_times=SessionTimes(
+        session_times=SessionTimes(
             rth_start=time(9, 0),
             rth_end=time(15, 30),
-            timezone=pytz.timezone("US/Eastern")
+            eth_start=time(18, 0),
+            eth_end=time(17, 0)
         )
     )
 
@@ -228,13 +228,18 @@ async def multi_instrument_sessions():
     # Set session type for all instruments
     await suite.set_session_type(SessionType.RTH)
 
-    # Get session data for all instruments
+    # Get session data for all instruments (returns dict)
     session_data = await suite.get_session_data("5min", SessionType.RTH)
-    # Returns: {"MNQ": data, "MES": data}
+    # Returns: {"MNQ": DataFrame, "MES": DataFrame}
+
+    for symbol, data in session_data.items():
+        if data is not None and not data.is_empty():
+            print(f"{symbol} RTH bars: {len(data)}")
 
     # Get session statistics for all instruments
     session_stats = await suite.get_session_statistics("5min")
-    # Returns: {"MNQ": stats, "MES": stats}
+    # Returns: {"MNQ": stats_dict, "MES": stats_dict} for multi-instrument
+    # or just stats_dict for single instrument
 
     await suite.disconnect()
 ```
@@ -303,8 +308,7 @@ async def custom_configuration():
 
     # Session configuration (v3.4.0+)
     session_config = SessionConfig(
-        session_type=SessionType.RTH,
-        product="MNQ"  # Product-specific session times
+        session_type=SessionType.RTH
     )
 
     suite = await TradingSuite.create(
@@ -437,7 +441,7 @@ async def data_access():
 ### Session-Aware Data Access (v3.4.0+)
 
 ```python
-from project_x_py.sessions import SessionType
+from project_x_py.sessions import SessionType, SessionConfig
 
 async def session_data_access():
     # Create suite with session configuration
@@ -446,22 +450,22 @@ async def session_data_access():
         timeframes=["1min", "5min"],
         session_config=SessionConfig(session_type=SessionType.RTH)
     )
-    mnq_data = suite["MNQ"].data
-
-    # Get session-specific data
-    rth_data = await mnq_data.get_session_bars("5min", SessionType.RTH)
-    eth_data = await mnq_data.get_session_bars("5min", SessionType.ETH)
+    mnq_context = suite["MNQ"]
 
-    # Session trades
-    rth_trades = await mnq_data.get_session_trades(SessionType.RTH)
+    # Get session-specific data using data manager methods
+    rth_data = await mnq_context.data.get_session_data("5min", SessionType.RTH)
+    eth_data = await mnq_context.data.get_session_data("5min", SessionType.ETH)
 
-    # Session statistics
-    from project_x_py.sessions import SessionStatistics
-    stats = SessionStatistics(suite["MNQ"])
-    rth_stats = await stats.calculate_session_stats(SessionType.RTH)
+    # Get session statistics from data manager
+    session_stats = await mnq_context.data.get_session_statistics("5min")
 
-    print(f"RTH Volatility: {rth_stats['volatility']:.2%}")
-    print(f"RTH Volume: {rth_stats['total_volume']:,}")
+    if session_stats:
+        print(f"RTH Volume: {session_stats.get('rth_volume', 0):,}")
+        print(f"ETH Volume: {session_stats.get('eth_volume', 0):,}")
+        print(f"RTH VWAP: ${session_stats.get('rth_vwap', 0):.2f}")
+        print(f"ETH VWAP: ${session_stats.get('eth_vwap', 0):.2f}")
+        print(f"RTH Range: ${session_stats.get('rth_range', 0):.2f}")
+        print(f"ETH Range: ${session_stats.get('eth_range', 0):.2f}")
 
     await suite.disconnect()
 ```