pycharting 0.2.7__tar.gz → 0.2.8__tar.gz

{pycharting-0.2.7 → pycharting-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pycharting
-Version: 0.2.7
+Version: 0.2.8
 Summary: High-performance financial charting library for OHLC data visualization with technical indicators
 Home-page: https://github.com/alihaskar/pycharting
 License: MIT

{pycharting-0.2.7 → pycharting-0.2.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pycharting"
-version = "0.2.7"
+version = "0.2.8"
 description = "High-performance financial charting library for OHLC data visualization with technical indicators"
 authors = ["ali askar <26202651+alihaskar@users.noreply.github.com>"]
 readme = "README.md"
@@ -19,13 +19,9 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Visualization",
 ]
 
-# expose the public package as `pycharting` and ship internal modules as top-level packages
+# expose the public package as `pycharting`
 packages = [
-    { include = "pycharting", from = "src" },
-    { include = "api", from = "src" },
-    { include = "core", from = "src" },
-    { include = "data", from = "src" },
-    { include = "web", from = "src" },
+    { include = "pycharting", from = "src" }
 ]
 
 [tool.poetry.dependencies]
@@ -43,4 +39,4 @@ httpx = ">=0.27.0,<0.29.0"
 
 [build-system]
 requires = ["poetry-core>=1.9.0"]
-build-backend = "poetry.core.masonry.api"
+build-backend = "poetry.core.masonry.api"

pycharting-0.2.8/src/pycharting/__init__.py

@@ -0,0 +1,49 @@
+"""
+PyCharting: Interactive Financial Charting Library.
+
+This package provides a high-performance, interactive charting solution for financial data
+(OHLC), designed to handle large datasets efficiently. It uses a local server architecture
+to render charts in the web browser, allowing for smooth zooming, panning, and analysis.
+
+Key Features:
+- **High Performance:** Capable of handling millions of data points using efficient data slicing.
+- **Interactive:** Zoom, pan, and inspect data in real-time.
+- **Flexible:** Support for overlays (e.g., Moving Averages) and subplots (e.g., RSI, Volume).
+- **Easy to Use:** Simple Python API similar to matplotlib or plotly.
+
+Usage:
+    The main entry point is the `plot` function.
+
+    ```python
+    from pycharting import plot, stop_server
+    import numpy as np
+
+    # Prepare your data (numpy arrays or pandas Series)
+    index = np.arange(100)
+    open_data = np.random.rand(100) + 100
+    high_data = open_data + 1
+    low_data = open_data - 1
+    close_data = open_data + 0.5
+
+    # Create and open the chart
+    plot(index, open_data, high_data, low_data, close_data)
+
+    # ... keep the script running if needed ...
+    # input("Press Enter to stop...")
+    # stop_server()
+    ```
+
+Exports:
+    - `plot`: Main function to create and display charts.
+    - `stop_server`: Function to gracefully shut down the local chart server.
+    - `get_server_status`: Function to check the status of the background server.
+"""
+
+from typing import Any, Dict  # re-exported types are only for type checkers
+
+from .api.interface import plot, stop_server, get_server_status  # type: ignore F401
+
+__all__ = ["plot", "stop_server", "get_server_status", "__version__"]
+
+# Keep this in sync with pyproject.toml
+__version__ = "0.2.8"

{pycharting-0.2.7/src → pycharting-0.2.8/src/pycharting}/api/interface.py

@@ -1,4 +1,19 @@
-"""Main Python API interface for PyCharting."""
+"""
+Main User Interface for PyCharting.
+
+This module exposes the high-level functions that users interact with to create charts,
+manage the server, and check status. It bridges the gap between the user's data (numpy/pandas)
+and the internal server/data management logic.
+
+The primary function is `plot()`, which orchestrates:
+1. Validating and ingesting user data via `DataManager`.
+2. Starting (or reusing) the background `ChartServer`.
+3. Constructing the visualization URL.
+4. Opening the chart in the user's default web browser.
+
+It also provides utilities for manual server control (`stop_server`, `get_server_status`)
+and Jupyter notebook integration.
+"""
 
 import webbrowser
 import time
@@ -7,9 +22,9 @@ from typing import Optional, Dict, Any, Union
 import numpy as np
 import pandas as pd
 
-from data.ingestion import DataManager
-from core.lifecycle import ChartServer
-from api.routes import _data_managers
+from pycharting.data.ingestion import DataManager
+from pycharting.core.lifecycle import ChartServer
+from pycharting.api.routes import _data_managers
 
 logger = logging.getLogger(__name__)
 
@@ -31,42 +46,65 @@ def plot(
     server_timeout: float = 2.0,
 ) -> Dict[str, Any]:
     """
-    Create and display an interactive OHLC chart.
-    
-    This is the main entry point for PyCharting. It creates a chart server,
-    loads your data, and opens it in your default web browser.
-    
+    Generate and display an interactive OHLC (Open-High-Low-Close) financial chart.
+
+    This function is the primary interface for PyCharting. It performs the following steps:
+    1.  **Data Ingestion:** Converts input lists, pandas Series, or numpy arrays into optimized internal formats.
+    2.  **Server Management:** Checks if a background chart server is running. If not, it starts one on a separate thread.
+    3.  **Session Registration:** Stores the provided data under a `session_id`. This allows multiple charts to coexist
+        or data to be updated.
+    4.  **Browser Launch:** Automatically opens the default web browser to the generated chart URL.
+
+    The chart is rendered using a high-performance web frontend capable of handling millions of data points via
+    dynamic data slicing.
+
     Args:
-        index: Time or index values for x-axis
-        open: Opening prices
-        high: High prices
-        low: Low prices
-        close: Closing prices
-        overlays: Optional dict of overlay series (e.g., moving averages)
-        subplots: Optional dict of subplot series (e.g., volume, indicators)
-        session_id: Unique identifier for this chart session
-        port: Server port (None for auto-discovery)
-        open_browser: Whether to automatically open the browser
-        server_timeout: Seconds to wait for server startup
-        
+        index (Union[np.ndarray, pd.Series, list]): The x-axis data (timestamps or integer indices). Must have the same length as price arrays.
+        open (Union[np.ndarray, pd.Series, list]): Opening prices.
+        high (Union[np.ndarray, pd.Series, list]): Highest prices during the interval.
+        low (Union[np.ndarray, pd.Series, list]): Lowest prices during the interval.
+        close (Union[np.ndarray, pd.Series, list]): Closing prices.
+        overlays (Optional[Dict[str, Union[np.ndarray, pd.Series, list]]]): A dictionary of additional series to plot *over* the main price chart.
+            Keys are labels (e.g., "SMA 50"), values are data arrays. Useful for Moving Averages, Bollinger Bands, etc.
+        subplots (Optional[Dict[str, Union[np.ndarray, pd.Series, list]]]): A dictionary of series to plot in separate panels *below* the main chart.
+            Keys are labels (e.g., "RSI", "Volume"), values are data arrays.
+        session_id (str): A unique identifier for this dataset. Use different IDs to keep multiple charts active simultaneously.
+            Defaults to "default".
+        port (Optional[int]): Specific port to run the server on. If `None` (default), a free port is automatically found.
+        open_browser (bool): If `True` (default), automatically launches the system's default web browser to view the chart.
+        server_timeout (float): Maximum time (in seconds) to wait for the server to start before proceeding. Defaults to 2.0.
+
     Returns:
-        Dict with server info including URL and status
-        
+        Dict[str, Any]: A dictionary containing execution details:
+            - `status`: "success" or "error".
+            - `url`: The full URL to view the chart.
+            - `server_url`: The base URL of the server.
+            - `session_id`: The session ID used.
+            - `data_points`: Number of data points loaded.
+            - `server_running`: Boolean indicating if the server is active.
+
     Example:
         ```python
         import numpy as np
         from pycharting import plot
-        
-        # Generate sample data
-        n = 100
+
+        # 1. Prepare Data
+        n = 1000
         index = np.arange(n)
         close = np.cumsum(np.random.randn(n)) + 100
-        open = close + np.random.randn(n) * 0.5
-        high = np.maximum(open, close) + np.abs(np.random.randn(n))
-        low = np.minimum(open, close) - np.abs(np.random.randn(n))
+        open_p = close + np.random.randn(n) * 0.5
+        high = np.maximum(open_p, close) + np.abs(np.random.randn(n))
+        low = np.minimum(open_p, close) - np.abs(np.random.randn(n))
         
-        # Create interactive chart
-        plot(index, open, high, low, close)
+        # 2. Add Indicators
+        sma = np.convolve(close, np.ones(20)/20, mode='same')
+        
+        # 3. Plot with Overlay
+        plot(
+            index, open_p, high, low, close,
+            overlays={"SMA 20": sma},
+            session_id="my-analysis"
+        )
         ```
     """
     global _active_server
@@ -177,16 +215,19 @@ def plot(
 
 def stop_server():
     """
-    Stop the active chart server.
-    
-    Call this to manually stop the server when you're done viewing charts.
-    The server also auto-stops after 5 minutes of inactivity.
-    
+    Manually shut down the active chart server.
+
+    While the server has an auto-shutdown feature (triggered after a timeout when no clients are connected),
+    this function allows for immediate, manual cleanup. This is useful in scripts or notebooks where you want
+    to ensure resources are freed immediately after a session.
+
+    If no server is running, this function does nothing and prints a message.
+
     Example:
         ```python
         from pycharting import stop_server
-        
-        # When done with all charts
+
+        # ... after done with analysis ...
         stop_server()
         ```
     """
@@ -202,17 +243,23 @@ def stop_server():
 
 def get_server_status() -> Dict[str, Any]:
     """
-    Get the status of the active chart server.
-    
+    Retrieve the current status of the background chart server.
+
+    This is useful for debugging connection issues or checking if a session is still active.
+
     Returns:
-        Dict with server status information
-        
+        Dict[str, Any]: A dictionary containing:
+            - `running`: Boolean indicating if the server process is alive.
+            - `server_info`: Dictionary of host, port, and connection details (or None).
+            - `active_sessions`: Count of currently loaded datasets/sessions.
+
     Example:
         ```python
         from pycharting import get_server_status
         
         status = get_server_status()
-        print(status)
+        if status['running']:
+            print(f"Server running at {status['server_info']['url']}")
         ```
     """
     global _active_server

{pycharting-0.2.7/src → pycharting-0.2.8/src/pycharting}/api/routes.py

@@ -1,4 +1,15 @@
-"""API routes for PyCharting data fetching and control."""
+"""
+API Routes Definition for PyCharting.
+
+This module defines the REST API endpoints that the frontend JavaScript uses to:
+1. Fetch sliced and diced OHLC data (`/data`).
+2. Manage data sessions (`/sessions`).
+3. Check system status (`/status`).
+4. Initialize demo data (`/data/init`).
+
+The data is served from the in-memory `_data_managers` registry, which is populated
+by the main Python process via `src.api.interface.plot()`.
+"""
 
 from typing import Optional, Dict, Any
 from fastapi import APIRouter, HTTPException, Query
@@ -42,18 +53,25 @@ async def get_data(
     session_id: str = Query("default", description="Session identifier for data source"),
 ):
     """
-    Fetch OHLC data chunk for the specified range.
-    
+    Retrieve a specific slice of OHLC data.
+
+    This endpoint is optimized for high-performance frontend rendering. Instead of sending the full dataset
+    at once (which could be millions of points), the frontend requests only the necessary chunk
+    based on the current zoom level and viewport.
+
     Args:
-        start_index: Starting index (inclusive)
-        end_index: Ending index (exclusive), None for end of data
-        session_id: Session identifier for data source
-        
+        start_index (int): The zero-based index of the first data point to retrieve.
+        end_index (Optional[int]): The zero-based index of the last data point (exclusive).
+            If None, retrieves data until the end of the series.
+        session_id (str): The ID of the data session to query.
+
     Returns:
-        DataResponse with OHLC data and metadata
-        
+        DataResponse: A JSON object containing parallel arrays for index, open, high, low, close,
+        overlays, and subplots for the requested range.
+
     Raises:
-        HTTPException: If session not found or invalid parameters
+        HTTPException(404): If the specified session_id does not exist.
+        HTTPException(500): If an internal error occurs during data slicing.
     """
     # Check if session exists
     if session_id not in _data_managers:
@@ -91,19 +109,19 @@ async def initialize_data(
     session_id: str = Query("default", description="Session identifier"),
 ):
     """
-    Initialize a data session (placeholder for demo).
-    
-    In production, this would accept data upload or configuration.
-    For now, it creates a demo dataset.
-    
+    Initialize a demo data session.
+
+    This endpoint is primarily used for testing or the standalone demo mode.
+    It generates synthetic random walk data and registers it under the given session ID.
+
     Args:
-        session_id: Session identifier
-        
+        session_id (str): The ID to assign to the new session.
+
     Returns:
-        Session information
+        dict: Status message and session details.
     """
     import numpy as np
-    from data.ingestion import DataManager
+    from pycharting.data.ingestion import DataManager
     
     try:
         # Generate demo OHLC data
@@ -163,10 +181,11 @@ async def initialize_data(
 @router.get("/sessions")
 async def list_sessions():
     """
-    List active data sessions.
-    
+    List all currently active data sessions.
+
     Returns:
-        List of active session IDs with metadata
+        dict: A dictionary containing a list of session objects, each with metadata
+        like the number of data points and active features (overlays, subplots).
     """
     sessions = []
     for session_id, dm in _data_managers.items():
@@ -186,16 +205,18 @@ async def list_sessions():
 @router.delete("/sessions/{session_id}")
 async def delete_session(session_id: str):
     """
-    Delete a data session.
-    
+    Remove a data session from memory.
+
+    This frees up resources associated with a specific dataset.
+
     Args:
-        session_id: Session identifier to delete
-        
+        session_id (str): The ID of the session to remove.
+
     Returns:
-        Success message
-        
+        dict: Confirmation message.
+
     Raises:
-        HTTPException: If session not found
+        HTTPException(404): If the session ID is not found.
     """
     if session_id not in _data_managers:
         raise HTTPException(

{pycharting-0.2.7/src → pycharting-0.2.8/src/pycharting}/core/lifecycle.py

@@ -1,4 +1,15 @@
-"""Server lifecycle management for PyCharting."""
+"""
+Server Lifecycle Management for PyCharting.
+
+This module manages the background execution and lifecycle of the PyCharting server.
+Since the main Python script (e.g., a data science notebook or script) needs to remain responsive,
+the chart server runs in a separate background thread.
+
+This module handles:
+- **Thread Management:** Starting and stopping the server in a daemon thread.
+- **Heartbeat Monitoring:** Checking for WebSocket connections from the frontend.
+- **Auto-Shutdown:** Automatically stopping the server when the browser tab is closed (connection lost) to prevent orphaned processes.
+"""
 
 import threading
 import time
@@ -7,17 +18,25 @@ from typing import Optional, Dict, Any
 from datetime import datetime
 import uvicorn
 from fastapi import WebSocket, WebSocketDisconnect
-from .server import create_app, find_free_port
+from pycharting.core.server import create_app, find_free_port
 
 logger = logging.getLogger(__name__)
 
 
 class ChartServer:
     """
-    Manages the lifecycle of the PyCharting server.
-    
-    Runs Uvicorn in a background thread and provides auto-shutdown
-    capability when WebSocket connections are lost.
+    A controller for managing the PyCharting background server.
+
+    This class encapsulates the logic for running the FastAPI/Uvicorn server in a separate thread.
+    It includes a heartbeat mechanism that monitors a WebSocket connection from the frontend.
+    If the frontend disconnects (e.g., user closes the tab), the server can automatically shut down
+    after a configurable timeout.
+
+    Attributes:
+        host (str): The hostname to bind to.
+        port (int): The port to bind to.
+        auto_shutdown_timeout (float): Time in seconds to wait before shutting down after connection loss.
+        app (FastAPI): The underlying FastAPI application instance.
     """
     
     def __init__(
@@ -27,12 +46,13 @@ class ChartServer:
         auto_shutdown_timeout: float = 5.0,
     ):
         """
-        Initialize ChartServer.
-        
+        Initialize the ChartServer controller.
+
         Args:
-            host: Host to bind the server to
-            port: Port to use (None for auto-discovery)
-            auto_shutdown_timeout: Seconds to wait before auto-shutdown after disconnect
+            host (str): Host to bind the server to. Defaults to "127.0.0.1".
+            port (Optional[int]): Port to use. If None, an available port is found automatically.
+            auto_shutdown_timeout (float): Seconds to wait before auto-shutdown after the last client disconnects.
+                Defaults to 5.0 seconds.
         """
         self.host = host
         self.port = port or find_free_port()
@@ -122,13 +142,24 @@ class ChartServer:
     
     def start_server(self) -> Dict[str, Any]:
         """
-        Start the server in a background thread.
-        
+        Start the web server in a background daemon thread.
+
+        This method:
+        1. Checks if the server is already running.
+        2. Starts the Uvicorn server in a separate thread.
+        3. Starts a monitor thread to check for WebSocket heartbeats.
+        4. Waits briefly to ensure the server is up.
+
         Returns:
-            Dict with server information (host, port, url)
-            
+            Dict[str, Any]: A dictionary containing connection details:
+                - `host`: The server host.
+                - `port`: The server port.
+                - `url`: The full HTTP URL to the server.
+                - `ws_url`: The WebSocket URL for heartbeats.
+                - `running`: Boolean status.
+
         Raises:
-            RuntimeError: If server is already running
+            RuntimeError: If the server is already running.
         """
         if self._running:
             raise RuntimeError("Server is already running")
@@ -169,7 +200,12 @@ class ChartServer:
         }
     
     def stop_server(self):
-        """Stop the server gracefully."""
+        """
+        Gracefully stop the background server and monitor threads.
+
+        This method signals the server to shut down, closes the Uvicorn loop,
+        and joins the background threads. It is safe to call multiple times.
+        """
         if not self._running:
             logger.warning("Server is not running")
             return

{pycharting-0.2.7/src → pycharting-0.2.8/src/pycharting}/core/server.py

@@ -1,4 +1,18 @@
-"""FastAPI server for PyCharting."""
+"""
+Core Server Module for PyCharting.
+
+This module implements the FastAPI-based web server that powers the interactive charts.
+It handles serving static assets (HTML, JS, CSS) and providing API endpoints for data retrieval.
+The server is designed to run locally and provide a seamless bridge between the Python runtime
+and the browser-based visualization.
+
+Key Responsibilities:
+- **Port Management:** Automatically finding available ports for the server.
+- **Application Factory:** Creating and configuring the FastAPI application instance.
+- **Static File Serving:** Serving the frontend assets required for the chart UI.
+- **API Routing:** Connecting API routes to the application.
+- **Server Execution:** Launching the Uvicorn server.
+"""
 
 import socket
 import logging
@@ -20,17 +34,27 @@ logger = logging.getLogger(__name__)
 
 def find_free_port(start_port: int = 8000, end_port: int = 9000) -> int:
     """
-    Find a free port in the specified range.
-    
+    Find an available TCP port in the specified range.
+
+    This utility function iterates through a range of ports to find one that is currently
+    not in use. This is crucial for ensuring the chart server can start without conflicts,
+    even if the default port is occupied or multiple instances are running.
+
     Args:
-        start_port: Starting port number to search from
-        end_port: Ending port number to search to
-        
+        start_port (int): The starting port number to search from (inclusive). Defaults to 8000.
+        end_port (int): The ending port number to search to (exclusive). Defaults to 9000.
+
     Returns:
-        Free port number
-        
+        int: An available port number found within the range.
+
     Raises:
-        RuntimeError: If no free port is found in range
+        RuntimeError: If no free port can be found in the specified range.
+
+    Example:
+        ```python
+        port = find_free_port(8000, 8010)
+        print(f"Found free port: {port}")
+        ```
     """
     for port in range(start_port, end_port):
         try:
@@ -46,10 +70,21 @@ def find_free_port(start_port: int = 8000, end_port: int = 9000) -> int:
 
 def create_app() -> FastAPI:
     """
-    Create and configure the FastAPI application.
-    
+    Create and configure the FastAPI application instance.
+
+    This factory function initializes the FastAPI app with necessary configurations:
+    - Sets up metadata (title, description, version).
+    - Configures CORS (Cross-Origin Resource Sharing) to allow local browser access.
+    - Mounts the static files directory to serve the frontend application.
+    - Configures the root endpoint to serve the main HTML entry point.
+    - Includes the API router for data endpoints.
+    - Sets up global exception handlers and health check endpoints.
+
+    The application is stateless regarding data; data is managed via the `_data_managers`
+    registry in `src.api.routes` which is accessed by the API routes included here.
+
     Returns:
-        Configured FastAPI application instance
+        FastAPI: The fully configured FastAPI application ready to be run by Uvicorn.
     """
     app = FastAPI(
         title="PyCharting",
@@ -136,7 +171,7 @@ def create_app() -> FastAPI:
         """
     
     # Include API routes
-    from api.routes import router as api_router
+    from pycharting.api.routes import router as api_router
     app.include_router(api_router)
     
     # Health check endpoint
@@ -175,13 +210,35 @@ def run_server(
     reload: bool = False,
 ) -> None:
     """
-    Run the PyCharting server.
-    
+    Launch the PyCharting web server.
+
+    This function is the main entry point for running the server directly (e.g., for development).
+    It handles port selection, application creation, and starting the Uvicorn server process.
+
+    In the library usage context, this is typically managed by `src.core.lifecycle.ChartServer`,
+    which runs this logic in a background thread. However, this function can be used to run
+    the server in the main thread (blocking) or for testing purposes.
+
     Args:
-        host: Host to bind to
-        port: Port to use. If None and auto_port is True, finds a free port
-        auto_port: If True, automatically find a free port if specified port is unavailable
-        reload: Enable auto-reload for development
+        host (str): The hostname or IP address to bind the server to. Defaults to "127.0.0.1".
+        port (Optional[int]): The specific port to use. If `None`, a free port will be found automatically
+            unless `auto_port` is False.
+        auto_port (bool): If True (default), automatically finds an alternative free port if the specified
+            (or default) port is unavailable.
+        reload (bool): If True, enables Uvicorn's auto-reload feature. Useful for development.
+            Defaults to False.
+
+    Returns:
+        None: This function blocks until the server stops.
+
+    Example:
+        ```python
+        # Run server on localhost, finding a free port automatically
+        run_server()
+
+        # Run on a specific port
+        run_server(port=8080)
+        ```
     """
     # Determine port
     if port is None:

pycharting-0.2.7/src/pycharting/__init__.py

@@ -1,17 +0,0 @@
-"""Public package for the PyCharting library.
-
-This module re-exports the main Python API surface so that users can do:
-
-    from pycharting import plot, stop_server, get_server_status
-"""
-
-from typing import Any, Dict  # re-exported types are only for type checkers
-
-from api.interface import plot, stop_server, get_server_status  # type: ignore F401
-
-__all__ = ["plot", "stop_server", "get_server_status", "__version__"]
-
-# Keep this in sync with pyproject.toml
-__version__ = "0.2.3"
-
-