financegy 0.1.0__tar.gz → 1.5__tar.gz

financegy-1.5/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: financegy
+Version: 1.5
+Summary: Unofficial Python library for accessing GSE (Guyana Stock Exchange) financial data
+Author-email: Ezra Minty <ezranminty@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/xbze3/financegy
+Project-URL: Issues, https://github.com/xbze3/financegy/issues
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: beautifulsoup4
+Requires-Dist: pandas
+Requires-Dist: openpyxl
+Dynamic: license-file
+
+# 🏦 FinanceGY
+
+**FinanceGY** is an unofficial Python library for accessing financial data from the **Guyana Stock Exchange (GSE)**. It provides a simple and consistent interface for retrieving information on traded securities, recent trade data, and session details, all programmatically.
+
+---
+
+## Installation
+
+```bash
+pip install financegy
+```
+
+---
+
+## Quick Start
+
+```python
+import financegy
+
+# Get a list of all traded securities
+securities = financegy.get_securities()
+
+# Get the name of a security by its ticker symbol
+security_name = financegy.get_security_by_symbol("DDL")
+
+# Get the most recent trade data for a security
+recent_trade = financegy.get_recent_trade("DDL")
+
+# Get all trade data for the most recent year
+recent_year = financegy.get_security_recent_year("DDL")
+
+# Get trade data for a specific trading session
+session_trades = financegy.get_session_trades("1136")
+
+# Get session trade data for a specific security
+security_session_trade = financegy.get_security_session_trade("DDL", "1136")
+
+# Search for securities by name or symbol
+search_results = financegy.search_securities("DDL")
+
+# Get all trades for a given year
+year_trades = financegy.get_trades_for_year("DDL", "2019")
+
+# Get historical trades within a date range - (yyyy) / (mm/yyyy) / (dd/mm/yyyy)
+historical_trades = financegy.get_historical_trades(
+    symbol="DDL",
+    start_date="01/06/2020",
+    end_date="01/2022"
+)
+```
+
+---
+
+## Data Retrieval
+
+| Function                                                             | Description                                                                                                            |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `get_securities()`                                                   | Returns a list of all currently traded securities on the GSE.                                                          |
+| `get_security_by_symbol(symbol: str)`                                | Retrieves the full name of a security using its ticker symbol (e.g., `"DDL"` → `"Demerara Distillers Limited"`).       |
+| `get_recent_trade(symbol: str)`                                      | Returns the most recent trade information for the given security.                                                      |
+| `get_security_recent_year(symbol: str)`                              | Fetches all trade data for the most recent year of the selected security.                                              |
+| `get_session_trades(session: str)`                                   | Retrieves trade data for all securities during a specific trading session.                                             |
+| `get_security_session_trade(symbol: str, session: str)`              | Retrieves trade data for a specific security in a given trading session.                                               |
+| `search_securities(query: str)`                                      | Searches for securities whose names or ticker symbols match the given query.                                           |
+| `get_trades_for_year(symbol: str, year: str)`                        | Returns all trade records for a specific security during a given year.                                                 |
+| `get_historical_trades(symbol: str, start_date: str, end_date: str)` | Fetches historical trade data for a security within the specified date range (`dd/mm/yyyy`, `mm/yyyy`, `yyyy` format). |
+
+---
+
+### Data Utilities
+
+| Function                                                               | Description                                                                                                                                              |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `to_dataframe(data)`                                                   | Converts a list (or dictionary) of trade data into a Pandas DataFrame for easy analysis. Raises `TypeError` if the data is not properly formatted.       |
+| `save_to_csv(data, filename: str = "output.csv", path: str = None)`    | Saves the given data to a CSV file. By default, the file is saved to the current working directory. Returns `True` after saving successfully.            |
+| `save_to_excel(data, filename: str = "output.xlsx", path: str = None)` | Saves the given data to an Excel `.xlsx` file. By default, the file is saved to the current working directory. Returns `True` after saving successfully. |
+
+---
+
+## Caching System
+
+FinanceGY includes a lightweight local caching system designed to speed up repeated requests and reduce unnecessary calls.
+
+Whenever you call a data retrieval function (such as `get_securities()` or `get_recent_trade()`), FinanceGY automatically checks whether a cached response already exists for that specific query:
+
+-   If a valid cache file (less than 7 days old since sessions are held once per week) is found, the result is returned instantly from the cache.
+-   If the cache is missing, disabled, or older than one week, FinanceGY fetches fresh data from the GSE and updates the cache automatically.
+
+All cache files are stored in a local `cache/` directory as small JSON files containing the retrieved data and a timestamp.
+
+You can manually clear all cached data at any time:
+
+```python
+import financegy
+
+financegy.clear_cache()
+```
+
+This will delete all cached files and force the next data request to fetch fresh data directly from the source.
+
+If you prefer to bypass the cache for a specific call, simply pass `use_cache=False` to any function. For example:
+
+```python
+# Force a fresh fetch from the GSE, ignoring cached data
+recent_trade = financegy.get_recent_trade("DDL", use_cache=False)
+```
+
+By default, caching is enabled for all supported functions unless explicitly turned off.
+
+---
+
+## License
+
+This project is licensed under the **MIT License**
+
+---
+
+## Example Use Case
+
+```python
+import financegy
+
+ddl_recent = financegy.get_security_recent("DDL")
+print(ddl_recent)
+```

financegy-1.5/README.md

@@ -0,0 +1,125 @@
+# 🏦 FinanceGY
+
+**FinanceGY** is an unofficial Python library for accessing financial data from the **Guyana Stock Exchange (GSE)**. It provides a simple and consistent interface for retrieving information on traded securities, recent trade data, and session details, all programmatically.
+
+---
+
+## Installation
+
+```bash
+pip install financegy
+```
+
+---
+
+## Quick Start
+
+```python
+import financegy
+
+# Get a list of all traded securities
+securities = financegy.get_securities()
+
+# Get the name of a security by its ticker symbol
+security_name = financegy.get_security_by_symbol("DDL")
+
+# Get the most recent trade data for a security
+recent_trade = financegy.get_recent_trade("DDL")
+
+# Get all trade data for the most recent year
+recent_year = financegy.get_security_recent_year("DDL")
+
+# Get trade data for a specific trading session
+session_trades = financegy.get_session_trades("1136")
+
+# Get session trade data for a specific security
+security_session_trade = financegy.get_security_session_trade("DDL", "1136")
+
+# Search for securities by name or symbol
+search_results = financegy.search_securities("DDL")
+
+# Get all trades for a given year
+year_trades = financegy.get_trades_for_year("DDL", "2019")
+
+# Get historical trades within a date range - (yyyy) / (mm/yyyy) / (dd/mm/yyyy)
+historical_trades = financegy.get_historical_trades(
+    symbol="DDL",
+    start_date="01/06/2020",
+    end_date="01/2022"
+)
+```
+
+---
+
+## Data Retrieval
+
+| Function                                                             | Description                                                                                                            |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `get_securities()`                                                   | Returns a list of all currently traded securities on the GSE.                                                          |
+| `get_security_by_symbol(symbol: str)`                                | Retrieves the full name of a security using its ticker symbol (e.g., `"DDL"` → `"Demerara Distillers Limited"`).       |
+| `get_recent_trade(symbol: str)`                                      | Returns the most recent trade information for the given security.                                                      |
+| `get_security_recent_year(symbol: str)`                              | Fetches all trade data for the most recent year of the selected security.                                              |
+| `get_session_trades(session: str)`                                   | Retrieves trade data for all securities during a specific trading session.                                             |
+| `get_security_session_trade(symbol: str, session: str)`              | Retrieves trade data for a specific security in a given trading session.                                               |
+| `search_securities(query: str)`                                      | Searches for securities whose names or ticker symbols match the given query.                                           |
+| `get_trades_for_year(symbol: str, year: str)`                        | Returns all trade records for a specific security during a given year.                                                 |
+| `get_historical_trades(symbol: str, start_date: str, end_date: str)` | Fetches historical trade data for a security within the specified date range (`dd/mm/yyyy`, `mm/yyyy`, `yyyy` format). |
+
+---
+
+### Data Utilities
+
+| Function                                                               | Description                                                                                                                                              |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `to_dataframe(data)`                                                   | Converts a list (or dictionary) of trade data into a Pandas DataFrame for easy analysis. Raises `TypeError` if the data is not properly formatted.       |
+| `save_to_csv(data, filename: str = "output.csv", path: str = None)`    | Saves the given data to a CSV file. By default, the file is saved to the current working directory. Returns `True` after saving successfully.            |
+| `save_to_excel(data, filename: str = "output.xlsx", path: str = None)` | Saves the given data to an Excel `.xlsx` file. By default, the file is saved to the current working directory. Returns `True` after saving successfully. |
+
+---
+
+## Caching System
+
+FinanceGY includes a lightweight local caching system designed to speed up repeated requests and reduce unnecessary calls.
+
+Whenever you call a data retrieval function (such as `get_securities()` or `get_recent_trade()`), FinanceGY automatically checks whether a cached response already exists for that specific query:
+
+-   If a valid cache file (less than 7 days old since sessions are held once per week) is found, the result is returned instantly from the cache.
+-   If the cache is missing, disabled, or older than one week, FinanceGY fetches fresh data from the GSE and updates the cache automatically.
+
+All cache files are stored in a local `cache/` directory as small JSON files containing the retrieved data and a timestamp.
+
+You can manually clear all cached data at any time:
+
+```python
+import financegy
+
+financegy.clear_cache()
+```
+
+This will delete all cached files and force the next data request to fetch fresh data directly from the source.
+
+If you prefer to bypass the cache for a specific call, simply pass `use_cache=False` to any function. For example:
+
+```python
+# Force a fresh fetch from the GSE, ignoring cached data
+recent_trade = financegy.get_recent_trade("DDL", use_cache=False)
+```
+
+By default, caching is enabled for all supported functions unless explicitly turned off.
+
+---
+
+## License
+
+This project is licensed under the **MIT License**
+
+---
+
+## Example Use Case
+
+```python
+import financegy
+
+ddl_recent = financegy.get_security_recent("DDL")
+print(ddl_recent)
+```

{financegy-0.1.0 → financegy-1.5}/financegy/__init__.py

@@ -14,6 +14,9 @@ from financegy.modules.securities import(
     get_historical_trades
 )
 
+from financegy.cache.cache_manager import clear_cache
+from financegy.utils.utils import save_to_csv, to_dataframe, save_to_excel
+
 __all__ = [
     "get_securities",
     "get_security_by_symbol",
@@ -23,5 +26,9 @@ __all__ = [
     "get_security_session_trade",
     "search_securities",
     "get_trades_for_year",
-    "get_historical_trades"
+    "get_historical_trades",
+    "clear_cache",
+    "save_to_csv",
+    "to_dataframe",
+    "save_to_excel"
 ]

financegy-1.5/financegy/cache/cache_manager.py

@@ -0,0 +1,62 @@
+import os, json, hashlib
+from datetime import datetime, timedelta
+import shutil
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+CACHE_DIR = os.path.join(SCRIPT_DIR, "cache")
+
+def make_cache_key(func_name, *args, **kwargs):
+    """Create a unique hash for the given function call."""
+
+    key_data = {
+        "func": func_name,
+        "args": args,
+        "kwargs": kwargs
+    }
+
+    key_string = json.dumps(key_data, sort_keys=True, default=str)
+    hashed = hashlib.md5(key_string.encode()).hexdigest()
+
+    return f"{func_name}_{hashed}.json"
+
+def load_cache(func_name, *args, max_age_days=7, **kwargs):
+    os.makedirs(CACHE_DIR, exist_ok=True)
+    cache_file = make_cache_key(func_name, *args, **kwargs)
+    cache_path = os.path.join(CACHE_DIR, cache_file)
+
+    if not os.path.exists(cache_path):
+        return None
+
+    with open(cache_path, "r") as f:
+        data = json.load(f)
+
+    timestamp = datetime.fromisoformat(data["timestamp"])
+    if datetime.now() - timestamp > timedelta(days=max_age_days):
+        return None
+
+    return data["value"]
+
+def save_cache(func_name, value, *args, **kwargs):
+    os.makedirs(CACHE_DIR, exist_ok=True)
+    cache_file = make_cache_key(func_name, *args, **kwargs)
+    cache_path = os.path.join(CACHE_DIR, cache_file)
+
+    with open(cache_path, "w") as f:
+        json.dump({
+            "timestamp": datetime.now().isoformat(),
+            "value": value
+        }, f)
+
+def clear_cache():
+    """Completely clears the FinanceGY cache directory."""
+    if not os.path.exists(CACHE_DIR):
+        print("No cache directory found.")
+        return False
+
+    try:
+        shutil.rmtree(CACHE_DIR)
+        print("Cache cleared successfully.")
+        return True
+        
+    except Exception as e:
+        print(f"Failed to clear cache: {e}")

{financegy-0.1.0 → financegy-1.5}/financegy/core/parser.py

@@ -217,16 +217,37 @@ def parse_get_trades_for_year(year: str, html: str):
         print(f"[parse_get_security_recent_year] Error parsing HTML: {e}")
         return None
 
+from datetime import datetime
+from bs4 import BeautifulSoup
 
 def parse_get_historical_trades(start_date: str, end_date: str, html: str):
     """Parse historical trade data from HTML between given dates (DD/MM/YYYY)"""
 
+    def normalize_date(date_str: str) -> str:
+        parts = date_str.split("/")
+        if len(parts) == 1:
+            day, month, year = "01", "01", parts[0]
+        elif len(parts) == 2:
+            day, month, year = "01", parts[0], parts[1]
+        elif len(parts) == 3:
+            day, month, year = parts
+        else:
+            raise ValueError(f"Invalid date format: {date_str}")
+
+        try:
+            datetime(int(year), int(month), int(day))
+        except ValueError as e:
+            raise ValueError(f"Invalid date generated from {date_str}: {e}")
+
+        return f"{day.zfill(2)}/{month.zfill(2)}/{year}"
+
     try:
+        start_date = normalize_date(start_date)
+        end_date = normalize_date(end_date)
         start = datetime.strptime(start_date, "%d/%m/%Y")
         end = datetime.strptime(end_date, "%d/%m/%Y")
 
         soup = BeautifulSoup(html, "html.parser")
-
         year_sections = soup.find_all("div", class_="year slide")
         if not year_sections:
             raise ValueError("No 'div.year.slide' sections found in HTML.")
@@ -242,8 +263,8 @@ def parse_get_historical_trades(start_date: str, end_date: str, html: str):
             if not year_id or not year_id.isdigit():
                 continue
 
-            year = int(year_id)
-            if year < start.year or year > end.year:
+            year_int = int(year_id)
+            if year_int < start.year or year_int > end.year:
                 continue
 
             trades = section.find_all("tr", class_="trade")
@@ -270,7 +291,6 @@ def parse_get_historical_trades(start_date: str, end_date: str, html: str):
                     })
 
         trade_data.sort(key=lambda x: datetime.strptime(x["date"], "%d/%m/%Y"))
-
         return trade_data
 
     except Exception as e:

{financegy-0.1.0 → financegy-1.5}/financegy/modules/securities.py

@@ -1,13 +1,26 @@
 from financegy.core import request_handler, parser
+from financegy.cache import cache_manager
 
-def get_securities():
+def get_securities(use_cache=True):
     """Get names of all currently traded securities"""
+
+    func_name = "get_securities"
+
+    if use_cache:
+        cached = cache_manager.load_cache(func_name)
+        if cached:
+            return parser.parse_get_securities(cached)
+
     path = "/securities/"
     html = request_handler.fetch_page(path)
+
+    cache_manager.save_cache(func_name, html)
+
     return parser.parse_get_securities(html);
 
-def get_security_by_symbol(symbol: str):
+def get_security_by_symbol(symbol: str, use_cache=True):
     """Get the security details by its ticker symbol"""
+
     securities = get_securities()
 
     symbol = symbol.strip().upper()
@@ -17,70 +30,127 @@ def get_security_by_symbol(symbol: str):
         None,
     )
 
-def get_security_recent_year(symbol:str):
+def get_security_recent_year(symbol:str, use_cache=True):
     """Get the most recent year's trade data for any of the traded securities"""
 
+    func_name = "get_security_recent_year"
+
     security_name = get_security_by_symbol(symbol)
     security_name = security_name.lower().replace(" ", "-")
 
+    if use_cache:
+        cached = cache_manager.load_cache(func_name, symbol)
+        if cached:
+            return parser.parse_get_security_recent_year(cached)
+
     path = "/security/" + security_name
     html = request_handler.fetch_page(path)
+
+    cache_manager.save_cache(func_name, html, symbol)
+
     return parser.parse_get_security_recent_year(html)
 
-def get_recent_trade(symbol: str):
+def get_recent_trade(symbol: str, use_cache=True):
     """Get the most recent trade data for any of the traded securities"""
+
+    func_name = "get_recent_trade"
     
     security_name = get_security_by_symbol(symbol)
     security_name = security_name.lower().replace(" ", "-")
 
+    if use_cache:
+        cached = cache_manager.load_cache(func_name, symbol)
+        if cached:
+            return parser.parse_get_recent_trade(cached)
+
     path = "/security/" + security_name
     html = request_handler.fetch_page(path)
+
+    cache_manager.save_cache(func_name, html, symbol)
+
     return parser.parse_get_recent_trade(html)
 
-def get_session_trades(session: str):
+def get_session_trades(session: str, use_cache=True):
     """Get the session trade data for all the available securities"""
 
+    func_name = "get_session_trades"
+
+    if use_cache:
+        cached = cache_manager.load_cache(func_name, session)
+        if cached:
+            return parser.parse_get_session_trades(cached)
+
     path = f"/financial_session/{session}/"
     html = request_handler.fetch_page(path)
+
+    cache_manager.save_cache(func_name, html, session)
+
     return parser.parse_get_session_trades(html)
 
-def get_security_session_trade(symbol: str, session: str):
+def get_security_session_trade(symbol: str, session: str, use_cache=True):
     """Get the session trade data for a given security"""
 
+    func_name = "get_security_session_trade"
+
     symbol = symbol.strip().upper()
 
+    if use_cache:
+        cached = cache_manager.load_cache(func_name, symbol, session)
+        if cached:
+            return parser.parse_get_security_session_trade(symbol, cached)
+
     path = f"/financial_session/{session}/"
     html = request_handler.fetch_page(path)
-    return parser.parse_get_security_session_trade(symbol, html)
 
+    cache_manager.save_cache(func_name, html, symbol, session)
+
+    return parser.parse_get_security_session_trade(symbol, html)
 
-def get_trades_for_year(symbol: str, year: str):
+def get_trades_for_year(symbol: str, year: str, use_cache=True):
     """Get security trade information from a specific year"""
 
+    func_name = "get_trades_for_year"
+
     symbol = symbol.strip().upper()
 
+    if use_cache:
+        cached = cache_manager.load_cache(func_name, symbol, year)
+        if cached:
+            return parser.parse_get_trades_for_year(year, cached)
+
     security_name = get_security_by_symbol(symbol)
     security_name = security_name.lower().replace(" ", "-")
 
     path = f"/security/{security_name}/"
     html = request_handler.fetch_page(path)
 
+    cache_manager.save_cache(func_name, html, symbol, year)
+
     return parser.parse_get_trades_for_year(year, html)
 
-def get_historical_trades(symbol: str, start_date: str, end_date: str):
+def get_historical_trades(symbol: str, start_date: str, end_date: str, use_cache=True):
     """Get historical trade data for a date range"""
 
+    func_name = "get_historical_trades"
+
     symbol = symbol.strip().upper()
 
+    if use_cache:
+        cached = cache_manager.load_cache(func_name, symbol, start_date, end_date)
+        if cached:
+            return parser.parse_get_historical_trades(start_date, end_date, cached)
+
     security_name = get_security_by_symbol(symbol)
     security_name = security_name.lower().replace(" ", "-")
 
     path = f"/security/{security_name}/"
     html = request_handler.fetch_page(path)
 
+    cache_manager.save_cache(func_name, html, symbol, start_date, end_date)
+
     return parser.parse_get_historical_trades(start_date, end_date, html)
 
-def search_securities(query: str):
+def search_securities(query: str, use_cache=True):
     """Search securities by symbol or name (partial match)"""
 
     query = query.lower().strip()

financegy-1.5/financegy/utils/utils.py

@@ -0,0 +1,52 @@
+import os
+import pandas as pd
+
+def to_dataframe(data: dict | list[dict]):
+    """Output as Dataframe"""
+
+    if isinstance(data, list) and not all(isinstance(item, dict) for item in data):
+        raise TypeError("All items in the list must be dictionaries")
+    elif not isinstance(data, (dict, list)):
+        raise TypeError("data must be a dict or a list of dicts")
+    
+    if isinstance(data, dict):
+        data = [data]      
+
+    return pd.DataFrame(data)
+
+def save_to_csv(data, filename: str = "output.csv", path: str = None):
+    """Save a list of dicts to CSV"""
+
+    if path is None:
+        path = os.getcwd()
+    else:
+        path = os.path.abspath(path)
+
+    full_path = os.path.join(path, filename)
+
+    df = to_dataframe(data)
+
+    df.to_csv(full_path, index=False)
+
+    print(f"Saved CSV to: {full_path}")
+
+    return True
+
+def save_to_excel(data: dict | list[dict], filename: str = "output.xlsx", path: str = None):
+    """Save data to an Excel spreadsheet."""
+    
+    if path is None:
+        path = os.getcwd()
+    else:
+        path = os.path.abspath(path)
+
+    full_path = os.path.join(path, filename)
+    df = to_dataframe(data)
+    df.to_excel(full_path, index=False)
+    
+    print(f"Saved Excel Document to: {full_path}")
+    
+    return True
+
+
+

financegy-1.5/financegy.egg-info/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: financegy
+Version: 1.5
+Summary: Unofficial Python library for accessing GSE (Guyana Stock Exchange) financial data
+Author-email: Ezra Minty <ezranminty@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/xbze3/financegy
+Project-URL: Issues, https://github.com/xbze3/financegy/issues
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: beautifulsoup4
+Requires-Dist: pandas
+Requires-Dist: openpyxl
+Dynamic: license-file
+
+# 🏦 FinanceGY
+
+**FinanceGY** is an unofficial Python library for accessing financial data from the **Guyana Stock Exchange (GSE)**. It provides a simple and consistent interface for retrieving information on traded securities, recent trade data, and session details, all programmatically.
+
+---
+
+## Installation
+
+```bash
+pip install financegy
+```
+
+---
+
+## Quick Start
+
+```python
+import financegy
+
+# Get a list of all traded securities
+securities = financegy.get_securities()
+
+# Get the name of a security by its ticker symbol
+security_name = financegy.get_security_by_symbol("DDL")
+
+# Get the most recent trade data for a security
+recent_trade = financegy.get_recent_trade("DDL")
+
+# Get all trade data for the most recent year
+recent_year = financegy.get_security_recent_year("DDL")
+
+# Get trade data for a specific trading session
+session_trades = financegy.get_session_trades("1136")
+
+# Get session trade data for a specific security
+security_session_trade = financegy.get_security_session_trade("DDL", "1136")
+
+# Search for securities by name or symbol
+search_results = financegy.search_securities("DDL")
+
+# Get all trades for a given year
+year_trades = financegy.get_trades_for_year("DDL", "2019")
+
+# Get historical trades within a date range - (yyyy) / (mm/yyyy) / (dd/mm/yyyy)
+historical_trades = financegy.get_historical_trades(
+    symbol="DDL",
+    start_date="01/06/2020",
+    end_date="01/2022"
+)
+```
+
+---
+
+## Data Retrieval
+
+| Function                                                             | Description                                                                                                            |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `get_securities()`                                                   | Returns a list of all currently traded securities on the GSE.                                                          |
+| `get_security_by_symbol(symbol: str)`                                | Retrieves the full name of a security using its ticker symbol (e.g., `"DDL"` → `"Demerara Distillers Limited"`).       |
+| `get_recent_trade(symbol: str)`                                      | Returns the most recent trade information for the given security.                                                      |
+| `get_security_recent_year(symbol: str)`                              | Fetches all trade data for the most recent year of the selected security.                                              |
+| `get_session_trades(session: str)`                                   | Retrieves trade data for all securities during a specific trading session.                                             |
+| `get_security_session_trade(symbol: str, session: str)`              | Retrieves trade data for a specific security in a given trading session.                                               |
+| `search_securities(query: str)`                                      | Searches for securities whose names or ticker symbols match the given query.                                           |
+| `get_trades_for_year(symbol: str, year: str)`                        | Returns all trade records for a specific security during a given year.                                                 |
+| `get_historical_trades(symbol: str, start_date: str, end_date: str)` | Fetches historical trade data for a security within the specified date range (`dd/mm/yyyy`, `mm/yyyy`, `yyyy` format). |
+
+---
+
+### Data Utilities
+
+| Function                                                               | Description                                                                                                                                              |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `to_dataframe(data)`                                                   | Converts a list (or dictionary) of trade data into a Pandas DataFrame for easy analysis. Raises `TypeError` if the data is not properly formatted.       |
+| `save_to_csv(data, filename: str = "output.csv", path: str = None)`    | Saves the given data to a CSV file. By default, the file is saved to the current working directory. Returns `True` after saving successfully.            |
+| `save_to_excel(data, filename: str = "output.xlsx", path: str = None)` | Saves the given data to an Excel `.xlsx` file. By default, the file is saved to the current working directory. Returns `True` after saving successfully. |
+
+---
+
+## Caching System
+
+FinanceGY includes a lightweight local caching system designed to speed up repeated requests and reduce unnecessary calls.
+
+Whenever you call a data retrieval function (such as `get_securities()` or `get_recent_trade()`), FinanceGY automatically checks whether a cached response already exists for that specific query:
+
+-   If a valid cache file (less than 7 days old since sessions are held once per week) is found, the result is returned instantly from the cache.
+-   If the cache is missing, disabled, or older than one week, FinanceGY fetches fresh data from the GSE and updates the cache automatically.
+
+All cache files are stored in a local `cache/` directory as small JSON files containing the retrieved data and a timestamp.
+
+You can manually clear all cached data at any time:
+
+```python
+import financegy
+
+financegy.clear_cache()
+```
+
+This will delete all cached files and force the next data request to fetch fresh data directly from the source.
+
+If you prefer to bypass the cache for a specific call, simply pass `use_cache=False` to any function. For example:
+
+```python
+# Force a fresh fetch from the GSE, ignoring cached data
+recent_trade = financegy.get_recent_trade("DDL", use_cache=False)
+```
+
+By default, caching is enabled for all supported functions unless explicitly turned off.
+
+---
+
+## License
+
+This project is licensed under the **MIT License**
+
+---
+
+## Example Use Case
+
+```python
+import financegy
+
+ddl_recent = financegy.get_security_recent("DDL")
+print(ddl_recent)
+```

{financegy-0.1.0 → financegy-1.5}/financegy.egg-info/SOURCES.txt

@@ -8,7 +8,9 @@ financegy.egg-info/SOURCES.txt
 financegy.egg-info/dependency_links.txt
 financegy.egg-info/requires.txt
 financegy.egg-info/top_level.txt
+financegy/cache/cache_manager.py
 financegy/core/parser.py
 financegy/core/request_handler.py
 financegy/modules/securities.py
+financegy/utils/utils.py
 tests/test_securities.py

{financegy-0.1.0 → financegy-1.5}/financegy.egg-info/requires.txt

@@ -1,2 +1,4 @@
 requests
 beautifulsoup4
+pandas
+openpyxl

{financegy-0.1.0 → financegy-1.5}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "financegy"
-version = "0.1.0"
+version = "1.5"
 description = "Unofficial Python library for accessing GSE (Guyana Stock Exchange) financial data"
 authors = [{ name = "Ezra Minty", email = "ezranminty@gmail.com" }]
-dependencies = ["requests", "beautifulsoup4"]
+dependencies = ["requests", "beautifulsoup4", "pandas", "openpyxl"]
 readme = "README.md"
 license = { text = "MIT" }
 

financegy-1.5/tests/test_securities.py

@@ -0,0 +1,57 @@
+from financegy import *
+import pandas as pd
+
+# def test_get_securities():
+#     result = get_securities()
+#     assert isinstance(result, list)
+
+# def test_get_security_by_symbol():
+#     result = get_security_by_symbol(symbol="ddl")    
+#     assert isinstance(result, (str, type(None)))
+
+# def test_get_recent_trade():
+#     result = get_recent_trade(symbol="ddl")
+#     assert isinstance(result, (dict, type(None)))
+
+# def test_get_security_recent_year():
+#     result = get_security_recent_year(symbol="RBL")
+#     assert isinstance(result, (list, type(None)))
+    
+# def test_get_session_trades():
+#     result = get_session_trades(session="1135")
+#     assert isinstance(result, (list, type(None)))
+
+# def test_get_security_session_trade():
+#     result = get_security_session_trade(symbol="ddl", session="1136")
+#     assert isinstance(result, (dict, type(None)))
+
+# def test_get_trades_for_year():
+#     result = get_trades_for_year(symbol="ddl", year="2020")
+#     assert isinstance(result, (list, type(None)))
+
+# def test_get_historical_trades():
+#     result = get_historical_trades(symbol="ddl", start_date="06/2020", end_date="01/2022")
+#     assert isinstance(result, (list, type(None)))
+
+# def test_search_securities():
+#     result = search_securities(query="ddl")
+#     assert isinstance(result, list)
+    
+# def test_to_dataframe():
+#     result = to_dataframe(get_securities())
+#     assert isinstance(result, pd.DataFrame)
+
+# def test_save_to_csv():
+#     result = get_securities()
+#     save_to_csv(result)
+#     assert isinstance(result, list)
+
+# def test_save_excel():
+#     result = get_securities()
+#     save_to_excel(result)
+#     assert isinstance(result, list)
+
+
+# def test_clear_cache():
+#     result = clear_cache()
+#     assert isinstance(result, bool)

financegy-0.1.0/PKG-INFO

@@ -1,121 +0,0 @@
-Metadata-Version: 2.4
-Name: financegy
-Version: 0.1.0
-Summary: Unofficial Python library for accessing GSE (Guyana Stock Exchange) financial data
-Author-email: Ezra Minty <ezranminty@gmail.com>
-License: MIT
-Project-URL: Homepage, https://github.com/xbze3/financegy
-Project-URL: Issues, https://github.com/xbze3/financegy/issues
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests
-Requires-Dist: beautifulsoup4
-Dynamic: license-file
-
-# 🏦 FinanceGY
-
-**FinanceGY** is an unofficial Python library for accessing financial data from the **Guyana Stock Exchange (GSE)**. It provides a simple and consistent interface for retrieving information on traded securities, recent trade data, and session details, all programmatically.
-
----
-
-## Installation
-
-```bash
-pip install financegy
-```
-
----
-
-## Quick Start
-
-```python
-import financegy
-
-# Get a list of all traded securities
-securities = financegy.get_securities()
-
-# Get the name of a security by its ticker symbol
-security_name = financegy.get_security_by_symbol("DDL")
-
-# Get the most recent trade data for a security
-recent_trade = financegy.get_recent_trade("DDL")
-
-# Get all trade data for the most recent year
-recent_year = financegy.get_security_recent_year("DDL")
-
-# Get trade data for a specific trading session
-session_trades = financegy.get_session_trades("1136")
-
-# Get session trade data for a specific security
-security_session_trade = financegy.get_security_session_trade("DDL", "1136")
-
-# Search for securities by name or symbol
-search_results = financegy.search_securities("DDL")
-
-# Get all trades for a given year
-year_trades = financegy.get_trades_for_year("DDL", "2019")
-
-# Get historical trades within a date range (dd/mm/yyyy)
-historical_trades = financegy.get_historical_trades(
-    symbol="DDL",
-    start_date="01/06/2020",
-    end_date="01/01/2022"
-)
-```
-
----
-
-## Function Overview
-
-#### `get_securities()`
-
-Returns a list of all currently traded securities on the Guyana Stock Exchange.
-
-#### `get_security_by_symbol(symbol: str)`
-
-Retrieves the full name of a security using its ticker symbol (e.g., `"DDL"` → `"Demerara Distillers Limited"`).
-
-#### `get_recent_trade(symbol: str)`
-
-Returns the most recent trade information for the given security.
-
-#### `get_security_recent_year(symbol: str)`
-
-Fetches all trade data for the most recent year of the selected security.
-
-#### `get_session_trades(session: str)`
-
-Retrieves trade data for _all_ securities during a specific trading session.
-
-#### `get_security_session_trade(symbol: str, session: str)`
-
-Retrieves trade data for a specific security in a given trading session.
-
-#### `search_securities(query: str)`
-
-Searches for securities whose names or ticker symbols match the given query.
-
-#### `get_trades_for_year(symbol: str, year: str)`
-
-Returns all trade records for a specific security during a given year.
-
-#### `get_historical_trades(symbol: str, start_date: str, end_date: str)`
-
-Fetches historical trade data for a security within the specified date range (`dd/mm/yyyy` format).
-
----
-
-## License
-
-This project is licensed under the **MIT License**
-
----
-
-## Example Use Case
-
-```python
-import financegy
-
-ddl_recent = financegy.get_security_recent("DDL")
-print(ddl_recent)
-```

financegy-0.1.0/README.md

@@ -1,107 +0,0 @@
-# 🏦 FinanceGY
-
-**FinanceGY** is an unofficial Python library for accessing financial data from the **Guyana Stock Exchange (GSE)**. It provides a simple and consistent interface for retrieving information on traded securities, recent trade data, and session details, all programmatically.
-
----
-
-## Installation
-
-```bash
-pip install financegy
-```
-
----
-
-## Quick Start
-
-```python
-import financegy
-
-# Get a list of all traded securities
-securities = financegy.get_securities()
-
-# Get the name of a security by its ticker symbol
-security_name = financegy.get_security_by_symbol("DDL")
-
-# Get the most recent trade data for a security
-recent_trade = financegy.get_recent_trade("DDL")
-
-# Get all trade data for the most recent year
-recent_year = financegy.get_security_recent_year("DDL")
-
-# Get trade data for a specific trading session
-session_trades = financegy.get_session_trades("1136")
-
-# Get session trade data for a specific security
-security_session_trade = financegy.get_security_session_trade("DDL", "1136")
-
-# Search for securities by name or symbol
-search_results = financegy.search_securities("DDL")
-
-# Get all trades for a given year
-year_trades = financegy.get_trades_for_year("DDL", "2019")
-
-# Get historical trades within a date range (dd/mm/yyyy)
-historical_trades = financegy.get_historical_trades(
-    symbol="DDL",
-    start_date="01/06/2020",
-    end_date="01/01/2022"
-)
-```
-
----
-
-## Function Overview
-
-#### `get_securities()`
-
-Returns a list of all currently traded securities on the Guyana Stock Exchange.
-
-#### `get_security_by_symbol(symbol: str)`
-
-Retrieves the full name of a security using its ticker symbol (e.g., `"DDL"` → `"Demerara Distillers Limited"`).
-
-#### `get_recent_trade(symbol: str)`
-
-Returns the most recent trade information for the given security.
-
-#### `get_security_recent_year(symbol: str)`
-
-Fetches all trade data for the most recent year of the selected security.
-
-#### `get_session_trades(session: str)`
-
-Retrieves trade data for _all_ securities during a specific trading session.
-
-#### `get_security_session_trade(symbol: str, session: str)`
-
-Retrieves trade data for a specific security in a given trading session.
-
-#### `search_securities(query: str)`
-
-Searches for securities whose names or ticker symbols match the given query.
-
-#### `get_trades_for_year(symbol: str, year: str)`
-
-Returns all trade records for a specific security during a given year.
-
-#### `get_historical_trades(symbol: str, start_date: str, end_date: str)`
-
-Fetches historical trade data for a security within the specified date range (`dd/mm/yyyy` format).
-
----
-
-## License
-
-This project is licensed under the **MIT License**
-
----
-
-## Example Use Case
-
-```python
-import financegy
-
-ddl_recent = financegy.get_security_recent("DDL")
-print(ddl_recent)
-```

financegy-0.1.0/financegy.egg-info/PKG-INFO

@@ -1,121 +0,0 @@
-Metadata-Version: 2.4
-Name: financegy
-Version: 0.1.0
-Summary: Unofficial Python library for accessing GSE (Guyana Stock Exchange) financial data
-Author-email: Ezra Minty <ezranminty@gmail.com>
-License: MIT
-Project-URL: Homepage, https://github.com/xbze3/financegy
-Project-URL: Issues, https://github.com/xbze3/financegy/issues
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests
-Requires-Dist: beautifulsoup4
-Dynamic: license-file
-
-# 🏦 FinanceGY
-
-**FinanceGY** is an unofficial Python library for accessing financial data from the **Guyana Stock Exchange (GSE)**. It provides a simple and consistent interface for retrieving information on traded securities, recent trade data, and session details, all programmatically.
-
----
-
-## Installation
-
-```bash
-pip install financegy
-```
-
----
-
-## Quick Start
-
-```python
-import financegy
-
-# Get a list of all traded securities
-securities = financegy.get_securities()
-
-# Get the name of a security by its ticker symbol
-security_name = financegy.get_security_by_symbol("DDL")
-
-# Get the most recent trade data for a security
-recent_trade = financegy.get_recent_trade("DDL")
-
-# Get all trade data for the most recent year
-recent_year = financegy.get_security_recent_year("DDL")
-
-# Get trade data for a specific trading session
-session_trades = financegy.get_session_trades("1136")
-
-# Get session trade data for a specific security
-security_session_trade = financegy.get_security_session_trade("DDL", "1136")
-
-# Search for securities by name or symbol
-search_results = financegy.search_securities("DDL")
-
-# Get all trades for a given year
-year_trades = financegy.get_trades_for_year("DDL", "2019")
-
-# Get historical trades within a date range (dd/mm/yyyy)
-historical_trades = financegy.get_historical_trades(
-    symbol="DDL",
-    start_date="01/06/2020",
-    end_date="01/01/2022"
-)
-```
-
----
-
-## Function Overview
-
-#### `get_securities()`
-
-Returns a list of all currently traded securities on the Guyana Stock Exchange.
-
-#### `get_security_by_symbol(symbol: str)`
-
-Retrieves the full name of a security using its ticker symbol (e.g., `"DDL"` → `"Demerara Distillers Limited"`).
-
-#### `get_recent_trade(symbol: str)`
-
-Returns the most recent trade information for the given security.
-
-#### `get_security_recent_year(symbol: str)`
-
-Fetches all trade data for the most recent year of the selected security.
-
-#### `get_session_trades(session: str)`
-
-Retrieves trade data for _all_ securities during a specific trading session.
-
-#### `get_security_session_trade(symbol: str, session: str)`
-
-Retrieves trade data for a specific security in a given trading session.
-
-#### `search_securities(query: str)`
-
-Searches for securities whose names or ticker symbols match the given query.
-
-#### `get_trades_for_year(symbol: str, year: str)`
-
-Returns all trade records for a specific security during a given year.
-
-#### `get_historical_trades(symbol: str, start_date: str, end_date: str)`
-
-Fetches historical trade data for a security within the specified date range (`dd/mm/yyyy` format).
-
----
-
-## License
-
-This project is licensed under the **MIT License**
-
----
-
-## Example Use Case
-
-```python
-import financegy
-
-ddl_recent = financegy.get_security_recent("DDL")
-print(ddl_recent)
-```

financegy-0.1.0/tests/test_securities.py

@@ -1,37 +0,0 @@
-from financegy import *
-
-def test_get_securities():
-    result = get_securities()
-    assert isinstance(result, list)
-
-def test_get_security_by_symbol():
-    result = get_security_by_symbol(symbol="ddl")
-    assert isinstance(result, (str, type(None)))
-
-def test_get_recent_trade():
-    result = get_recent_trade(symbol="ddl")
-    assert isinstance(result, (dict, type(None)))
-
-def test_get_security_recent_year():
-    result = get_security_recent_year(symbol="ddl")
-    assert isinstance(result, (list, type(None)))
-    
-def test_get_session_trades():
-    result = get_session_trades(session="1136")
-    assert isinstance(result, (list, type(None)))
-
-def test_get_security_session_trade():
-    result = get_security_session_trade(symbol="ddl", session="1136")
-    assert isinstance(result, (dict, type(None)))
-
-def test_search_securities():
-    result = search_securities(query="ddl")
-    assert isinstance(result, list)
-
-def test_get_trades_for_year():
-    result = get_trades_for_year(symbol="ddl", year="2019")
-    assert isinstance(result, (list, type(None)))
-
-def test_get_historical_trades():
-    result = get_historical_trades(symbol="ddl", start_date="01/06/2020", end_date="01/01/2022")
-    assert isinstance(result, (list, type(None)))