data-retrieval-module 1.0.0__tar.gz → 1.0.2__tar.gz

{data_retrieval_module-1.0.0 → data_retrieval_module-1.0.2}/CHANGELOG.md

@@ -42,6 +42,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CI/CD ready setup
 - Package publishing configuration
 
+## [1.0.1] - 2026-01-25
+
+### Added
+- Foreign Exchange data provider module
+  - `Forex_DataProvider_Base` abstract base class for forex data providers
+  - `ForexPython_DataProvider` concrete implementation using Python libraries
+  - `Forex_DataProvider_Wrapper` wrapper for enhanced functionality
+- Utility modules
+  - `date_utils` module for date/time utilities
+- Enhanced data provider wrapper functionality
+- Examples for forex data sources
+
+### Features
+- **Forex Data Support**: Complete foreign exchange data provider framework
+- **Utility Functions**: Date and time utilities for data processing
+- **Enhanced Wrappers**: Improved data provider wrapper capabilities
+- **Example Code**: Forex data source examples and usage patterns
+
+### Documentation
+- Added forex provider documentation
+- Updated package exports to include new modules
+- Enhanced examples with forex data sources
+
 ## [Unreleased]
 
 ### Planned

{data_retrieval_module-1.0.0 → data_retrieval_module-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-retrieval-module
-Version: 1.0.0
+Version: 1.0.2
 Summary: A standardized interface for data providers with sync and async support
 Author-email: AbigailWilliams1692 <abigail.williams@example.com>
 Maintainer-email: AbigailWilliams1692 <abigail.williams@example.com>
@@ -28,6 +28,7 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typing-extensions>=4.0.0; python_version < "3.10"
+Requires-Dist: forex-python>=1.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"

{data_retrieval_module-1.0.0 → data_retrieval_module-1.0.2}/data_retrieval/__init__.py

@@ -28,7 +28,17 @@ from data_retrieval.model.exceptions import (
 from data_retrieval.data_provider.rest_api import RestAPI_DataProvider
 
 # Database providers
-from data_retrieval.data_provider.database import Database_DataProvider
+from data_retrieval.data_provider.database import (
+    Database_DataProvider,
+    SQLite3_DataProvider,
+)
+
+# Foreign Exchange providers
+from data_retrieval.foreign_exchange import (
+    Forex_DataProvider_Base,
+    ForexPython_DataProvider,
+    Forex_DataProvider_Wrapper,
+)
 
 #######################################################################
 # Public API
@@ -51,11 +61,17 @@ __all__ = [
     
     # Database providers
     "Database_DataProvider",
+    "SQLite3_DataProvider",
+    
+    # Foreign Exchange providers
+    "Forex_DataProvider_Base",
+    "ForexPython_DataProvider",
+    "Forex_DataProvider_Wrapper",
 ]
 
 #######################################################################
 # Version Information
 #######################################################################
-__version__ = "1.0.0"
+__version__ = "1.0.2"
 __author__ = "AbigailWilliams1692"
-__email__ = "abigail.williams@example.com"
+__email__ = "alfred.xy1020@gmail.com"

data_retrieval_module-1.0.2/data_retrieval/data_provider/__init__.py

@@ -0,0 +1,5 @@
+#######################################################################
+# Project: Data Retrieval Module
+# File: __init__.py
+# Description: Data provider package initialization
+#######################################################################

data_retrieval_module-1.0.2/data_retrieval/data_provider/database/__init__.py

@@ -0,0 +1,4 @@
+from .database_data_provider import Database_DataProvider
+from .sqlite3_data_provider import SQLite3_DataProvider
+
+__all__ = ["Database_DataProvider", "SQLite3_DataProvider"]

data_retrieval_module-1.0.2/data_retrieval/data_provider/database/database_data_provider.py

@@ -0,0 +1,121 @@
+#######################################################################
+# Project: Data Retrieval Module
+# File: db_provider.py
+# Description: Database data provider implementations
+# Author: AbigailWilliams1692
+# Created: 2026-01-14
+# Updated: 2026-01-19
+#######################################################################
+
+#######################################################################
+# Import Packages
+#######################################################################
+# Standard Packages
+import datetime
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+# Third-party Packages
+
+# Local Packages
+from data_retrieval.model.data_provider import DataProvider
+
+
+#######################################################################
+# Database Data Provider (Synchronous)
+#######################################################################
+class Database_DataProvider(DataProvider, ABC):
+    """
+    Base class for database data providers.
+
+    This class extends the DataProvider base class to provide database-specific
+    functionality for synchronous data retrieval operations. It serves as a
+    foundation for implementing various database connection types and query
+    operations.
+    """
+
+    ###################################################################
+    # Class Attributes
+    ###################################################################
+    __name = "Database_DataProvider"
+    __type = "Database_DataProvider"
+        
+    ###################################################################
+    # Constructor Method
+    ###################################################################
+    def __init__(
+        self,
+        instance_id: Optional[int] = None,
+        logger: Optional[logging.Logger] = None,
+        log_level: Optional[int] = logging.INFO,
+        **config,
+    ) -> None:
+        """
+        Initialize the Database_DataProvider with the given parameters.
+
+        :param instance_id: Unique identifier for this provider instance.
+        :param logger: Logger instance for logging operations.
+        :param log_level: Logging level for the provider.
+        :param config: Additional configuration parameters for the database connection.
+        """
+        # Super Initialize
+        super().__init__(
+            instance_id=instance_id,
+            logger=logger,
+            log_level=log_level,
+            **config    
+        )
+
+    ###################################################################
+    # Utility Methods
+    ###################################################################
+    def format_sql_query(self, sql: str, params: Dict[str, Any]) -> str:
+        """
+        Format the SQL query string with the given key-value pairs.
+
+        :param sql: the SQL query template string with placeholders.
+        :param params: Dict[str, Any]: a Dictionary of key-value pairs used to parametrize the SQL query.
+        :return: the formatted SQL query string. 
+        """
+        for key, value in params.items():
+            placeholder = ":" + key
+
+            # Covert the value to string based on its type
+            if isinstance(value, str):
+                value_to_replace = "'" + str(value) + "'"
+            elif isinstance(value, (int, float)):
+                value_to_replace = str(value)
+            elif isinstance(value, datetime.date):
+                value_to_replace = "'" + value.strftime("%Y-%m-%d") + "'"
+            elif isinstance(value, List):
+                value_to_replace = "'" + self.stringify_a_list_of_items_with_apostrophe(item_list=value) + "'"
+            else:
+                raise TypeError(f"Unsupported value type: {type(value)} for parameter '{key}'")
+
+            # Replace all the placeholders in the SQL string
+            sql = sql.replace(placeholder, value_to_replace, count=-1)
+
+        return sql
+
+    @staticmethod
+    def stringify_a_list_of_items_with_apostrophe(item_list: List[Any]) -> str:
+        """
+        Convert a list of items into a comma-separated string with each item wrapped in apostrophes.
+        
+        :param item_list: List of items to convert.
+        :return: String representation of items wrapped in apostrophes and separated by commas.
+        """
+        item_str_list = [f"'{str(item)}'" for item in item_list]
+        return ",".join(item_str_list)
+
+    @staticmethod
+    def generate_markers(size: int, marker: str = "?") -> str:
+        """
+        Generate placeholder markers joined by ','.
+        
+        :param size: Number of markers to generate.
+        :param marker: Marker string to use (default is "?").
+        :return: String of markers joined by commas.
+        """
+        return ",".join([marker] * size)

data_retrieval_module-1.0.2/data_retrieval/data_provider/database/sqlite3_data_provider.py

@@ -0,0 +1,388 @@
+#!/usr/bin/env python3
+########################################################################
+# File: database_service.py
+# Description: SQLite3 database data provider
+# Author: AbigailWilliams1692
+# Creation Date: 2026-01-29
+# Version: 1.0.0
+# License: MIT License
+########################################################################
+
+########################################################################
+# Import Libraries
+########################################################################
+# Standard Packages
+import logging
+import sqlite3
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+# Third-party Packages
+from data_retrieval.data_provider.database.database_data_provider import (
+    Database_DataProvider,
+)
+
+
+########################################################################
+# SQLite3 Data Provider Class
+########################################################################
+class SQLite3FetchMode(str, Enum):
+    """
+    Enum for fetch modes.
+    """
+    ALL = "all"
+    ONE = "one"
+    MANY = "many"
+    LAST_ID = "last_id"
+    NONE = "none"
+
+
+class SQLite3_DataProvider(Database_DataProvider):
+    """
+    SQLite3 data provider class.
+    """
+
+    ###################################################################
+    # Class Attributes
+    ###################################################################
+    __name = "SQLite3_DataProvider"
+
+    ###################################################################
+    # Constructor Method
+    ###################################################################
+    def __init__(
+        self,
+        db_file_path: str,
+        instance_id: Optional[int] = None,
+        logger: Optional[logging.Logger] = None,
+        log_level: Optional[int] = logging.INFO,
+        **config,
+    ) -> None:
+        """
+        Initialize the DatabaseService with the given parameters.
+
+        :param db_file_path: Path to the SQLite database file (.db).
+        :param instance_id: Unique identifier for this provider instance.
+        :param logger: Logger instance for logging operations.
+        :param log_level: Logging level for the provider.
+        :param config: Additional configuration parameters.
+        """
+        # Super Initialize
+        super().__init__(
+            instance_id=instance_id,
+            logger=logger,
+            log_level=log_level,
+            **config,
+        )
+
+        # Initialize the DatabaseService attributes
+        ## Store the database path
+        self._db_file_path = db_file_path
+        ## Initialize the cursor
+        self._cursor: Optional[sqlite3.Cursor] = None
+        ## Connect to the datbase file
+        self.connect()
+
+        # Update data methods
+        self.update_data_methods(
+            new_methods={
+                "execute": self.execute,
+                "execute_many": self.execute_many,
+                "fetch_one": self.fetch_one,
+                "fetch_many": self.fetch_many,
+                "fetch_all": self.fetch_all,
+            }
+        )
+    
+    ###################################################################
+    # Getter & Setter Methods
+    ###################################################################
+    def get_db_file_path(self) -> str:
+        """
+        Get the database file path.
+
+        :return: The path to the SQLite database file.
+        """
+        return self._db_file_path
+
+    def set_db_file_path(self, db_file_path: str) -> None:
+        """
+        Set the database file path.
+
+        :param db_file_path: The path to the SQLite database file.
+        :return: None.
+        """
+        self._db_file_path = db_file_path
+
+    def get_cursor(self) -> Optional[sqlite3.Cursor]:
+        """
+        Get the database cursor.
+
+        :return: The SQLite cursor object.
+        """
+        return self._cursor
+
+    def set_cursor(self, cursor: sqlite3.Cursor) -> None:
+        """
+        Set the database cursor.
+
+        :param cursor: The SQLite cursor object.
+        :return: None.
+        """
+        self._cursor = cursor
+
+    ###################################################################
+    # Connection Methods
+    ###################################################################
+    def _connect(self, *args, **kwargs) -> None:
+        """
+        Connect to the SQLite database.
+
+        Creates a connection to the SQLite database file specified by db_file_path.
+        If the file does not exist, SQLite will create it.
+
+        :param args: Positional arguments (unused).
+        :param kwargs: Keyword arguments (unused).
+        :return: None.
+        :raises sqlite3.Error: If connection fails.
+        """
+        # Connect to the database
+        conn = sqlite3.connect(self.get_db_file_path())
+        
+        # Set row factory to return rows as sqlite3.Row objects
+        conn.row_factory = sqlite3.Row
+        
+        # Set connection and cursor
+        self.set_connection(connection=conn)
+        self.set_cursor(conn.cursor())
+
+    def _disconnect(self) -> None:
+        """
+        Disconnect from the SQLite database.
+
+        Closes the cursor and connection to the database.
+
+        :param args: Positional arguments (unused).
+        :param kwargs: Keyword arguments (unused).
+        :return: None.
+        :raises sqlite3.Error: If disconnection fails.
+        """
+        if self._cursor is not None:
+            self._cursor.close()
+            self._cursor = None
+
+        conn = self.get_connection()
+        if conn is not None:
+            conn.close()
+            self.set_connection(connection=None)
+
+    ###################################################################
+    # Core Instance Method: Execute
+    ###################################################################
+    def execute(
+        self,
+        sql: str,
+        params: Optional[Union[Tuple, Dict[str, Any]]] = None,
+        fetch_mode: str = SQLite3FetchMode.ALL,
+        commit: bool = True,
+        **kwargs,
+    ) -> Any:
+        """
+        Execute a SQL query on the SQLite database.
+
+        :param sql: The SQL query string to execute.
+        :param params: Optional parameters for parameterized queries.
+                       Can be a tuple for positional params or dict for named params.
+        :param fetch: Fetch mode - "all", "one", "many", or "none".
+                      - "all": Fetch all results (fetchall).
+                      - "one": Fetch single result (fetchone).
+                      - "many": Fetch specified number of results (fetchmany).
+                      - "none": Don't fetch results (for INSERT/UPDATE/DELETE).
+        :param commit: Whether to commit the transaction after execution.
+        :param kwargs: Additional keyword arguments.
+                       - fetch_size: Number of rows to fetch when fetch="many".
+        :return: Query results based on fetch mode, or lastrowid for INSERT operations.
+        :raises sqlite3.Error: If query execution fails.
+        :raises ValueError: If invalid fetch mode is specified.
+        """
+        # Check if the database is connected
+        self.check_db_connection()
+
+        # Get the connection and the cursor
+        conn = self.get_connection()
+        cursor = self.get_cursor()
+
+        # Execute the query with or without parameters
+        if params is not None:
+            cursor.execute(sql, params)
+        else:
+            cursor.execute(sql)
+
+        # Commit if requested
+        if commit:
+            conn.commit()
+
+        # Fetch results based on mode
+        if fetch_mode == "all":
+            return cursor.fetchall()
+        elif fetch_mode == "one":
+            return cursor.fetchone()
+        elif fetch_mode == "many":
+            fetch_size = kwargs.get("fetch_size", 100)
+            return cursor.fetchmany(fetch_size)
+        elif fetch_mode == "last_id":
+            return cursor.lastrowid
+        elif fetch_mode == "none":
+            return None
+        else:
+            raise ValueError(f"Invalid fetch mode: {fetch_mode}. Must be 'all', 'one', 'many', or 'none'.")
+
+    def execute_many(
+        self,
+        sql: str,
+        params_list: List[Union[Tuple, Dict[str, Any]]],
+        fetch_mode: str = "all",
+        commit: bool = True,
+    ) -> None:
+        """
+        Execute a SQL statement on the SQLite database multiple times with different parameters.
+
+        :param sql: The SQL statement to execute.
+        :param params_list: List of parameter tuples or dicts.
+        :param commit: Whether to commit the transaction (default: True).
+        :return: None.
+        """
+        # Check if the database is connected
+        self.check_db_connection()
+
+        # Get the connection and the cursor
+        conn = self.get_connection()
+        cursor = self.get_cursor()
+
+        # Execute the query with multiple parameter groups
+        cursor.executemany(sql, params_list)
+
+        # Commit if requested
+        if commit:
+            conn.commit()
+
+        # Fetch results based on mode
+        if fetch_mode == "all":
+            return cursor.fetchall()
+        elif fetch_mode == "one":
+            return cursor.fetchone()
+        elif fetch_mode == "many":
+            fetch_size = kwargs.get("fetch_size", 100)
+            return cursor.fetchmany(fetch_size)
+        elif fetch_mode == "last_id":
+            return cursor.lastrowid
+        elif fetch_mode == "none":
+            return None
+        else:
+            raise ValueError(f"Invalid fetch mode: {fetch_mode}. Must be 'all', 'one', 'many', or 'none'.")
+
+    ###################################################################
+    # Core Instance Methods: Fetch One/Many/All
+    ###################################################################
+    def fetch_one(
+        self,
+        sql: str,
+        params: Optional[Union[Tuple, Dict[str, Any]]] = None,
+    ) -> Optional[sqlite3.Row]:
+        """
+        Execute a SELECT query and fetch a single result.
+
+        :param sql: The SQL SELECT query.
+        :param params: Optional parameters for parameterized queries.
+        :return: Single result row or None.
+        """
+        return self.execute(sql=sql, params=params, fetch="one")
+
+    def fetch_many(
+        self,
+        sql: str,
+        params: Optional[Union[Tuple, Dict[str, Any]]] = None,
+        fetch_size: int = 100,
+    ) -> List[sqlite3.Row]:
+        """
+        Execute a SELECT query and fetch multiple results.
+
+        :param sql: The SQL SELECT query.
+        :param params: Optional parameters for parameterized queries.
+        :param fetch_size: Number of rows to fetch (default: 100).
+        :return: List of result rows.
+        """
+        return self.execute(sql=sql, params=params, fetch="many", fetch_size=fetch_size)
+
+    def fetch_all(
+        self,
+        sql: str,
+        params: Optional[Union[Tuple, Dict[str, Any]]] = None,
+    ) -> List[sqlite3.Row]:
+        """
+        Execute a SELECT query and fetch all results.
+
+        :param sql: The SQL SELECT query.
+        :param params: Optional parameters for parameterized queries.
+        :return: List of all result rows.
+        """
+        return self.execute(sql=sql, params=params, fetch="all")
+
+    ###################################################################
+    # Core Instance Method: Commit
+    ###################################################################
+    def commit(self) -> None:
+        """
+        Commit the current transaction.
+        """
+        self.check_db_connection()
+        self.get_connection().commit()
+
+    ###################################################################
+    # Core Instance Method: Rollback
+    ###################################################################
+    def rollback(self) -> None:
+        """
+        Rollback the current transaction.
+
+        :return: None.
+        """
+        self.check_db_connection()
+        self.get_connection().rollback()
+
+    ###################################################################
+    # Utility Methods
+    ###################################################################
+    def check_db_connection(self) -> None:
+        """
+        Check connection and raise sqlite3.OperationalError if not connected.
+        """
+        if not self.is_connected():
+            raise sqlite3.OperationalError("Database is not connected. Call connect() first.")
+
+    def table_exists(self, table_name: str) -> bool:
+        """
+        Check if a table exists in the database.
+
+        :param table_name: Name of the table to check.
+        :return: True if table exists, False otherwise.
+        """
+        sql = """
+            SELECT name 
+            FROM sqlite_master 
+            WHERE type='table' 
+            AND name=?
+        """
+        result = self.fetch_one(sql=sql, params=(table_name,))
+        return result is not None
+
+    def get_table_info(self, table_name: str) -> List[sqlite3.Row]:
+        """
+        Get column information for a table.
+
+        :param table_name: Name of the table.
+        :return: List of column information rows.
+        """
+        self.check_db_connection()
+        sql = f"PRAGMA table_info({table_name})"
+        return self.fetch_all(sql=sql)

data_retrieval_module-1.0.2/data_retrieval/data_provider/rest_api/__init__.py

@@ -0,0 +1,12 @@
+#######################################################################
+# Project: Data Retrieval Module
+# File: __init__.py
+# Description: REST API data provider package initialization
+# Author: AbigailWilliams1692
+# Created: 2026-01-14
+# Updated: 2026-01-18
+#######################################################################
+
+from .rest_api_data_provider import RestAPI_DataProvider
+
+__all__ = ["RestAPI_DataProvider"]