financegy 0.1.0__tar.gz → 1.3__tar.gz

{financegy-0.1.0 → financegy-1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: financegy
-Version: 0.1.0
+Version: 1.3
 Summary: Unofficial Python library for accessing GSE (Guyana Stock Exchange) financial data
 Author-email: Ezra Minty <ezranminty@gmail.com>
 License: MIT
@@ -105,6 +105,38 @@ Fetches historical trade data for a security within the specified date range (`d
 
 ---
 
+## 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 help 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**

{financegy-0.1.0 → financegy-1.3}/README.md

@@ -91,6 +91,38 @@ Fetches historical trade data for a security within the specified date range (`d
 
 ---
 
+## 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 help 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**

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

@@ -14,6 +14,8 @@ from financegy.modules.securities import(
     get_historical_trades
 )
 
+from financegy.cache.cache_manager import clear_cache
+
 __all__ = [
     "get_securities",
     "get_security_by_symbol",
@@ -23,5 +25,6 @@ __all__ = [
     "get_security_session_trade",
     "search_securities",
     "get_trades_for_year",
-    "get_historical_trades"
+    "get_historical_trades",
+    "clear_cache"
 ]

financegy-1.3/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.3}/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-0.1.0 → financegy-1.3}/financegy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: financegy
-Version: 0.1.0
+Version: 1.3
 Summary: Unofficial Python library for accessing GSE (Guyana Stock Exchange) financial data
 Author-email: Ezra Minty <ezranminty@gmail.com>
 License: MIT
@@ -105,6 +105,38 @@ Fetches historical trade data for a security within the specified date range (`d
 
 ---
 
+## 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 help 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**

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

@@ -8,6 +8,7 @@ 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-0.1.0 → financegy-1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "financegy"
-version = "0.1.0"
+version = "1.3"
 description = "Unofficial Python library for accessing GSE (Guyana Stock Exchange) financial data"
 authors = [{ name = "Ezra Minty", email = "ezranminty@gmail.com" }]
 dependencies = ["requests", "beautifulsoup4"]

{financegy-0.1.0 → financegy-1.3}/tests/test_securities.py

@@ -5,7 +5,7 @@ def test_get_securities():
     assert isinstance(result, list)
 
 def test_get_security_by_symbol():
-    result = get_security_by_symbol(symbol="ddl")
+    result = get_security_by_symbol(symbol="ddl")    
     assert isinstance(result, (str, type(None)))
 
 def test_get_recent_trade():
@@ -13,25 +13,30 @@ def test_get_recent_trade():
     assert isinstance(result, (dict, type(None)))
 
 def test_get_security_recent_year():
-    result = get_security_recent_year(symbol="ddl")
+    result = get_security_recent_year(symbol="RBL")
     assert isinstance(result, (list, type(None)))
     
 def test_get_session_trades():
-    result = get_session_trades(session="1136")
+    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_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")
+    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="01/06/2020", end_date="01/01/2022")
-    assert isinstance(result, (list, type(None)))
+    assert isinstance(result, (list, type(None)))
+
+def test_search_securities():
+    result = search_securities(query="ddl")
+    assert isinstance(result, list)
+
+# def test_clear_cache():
+#     result = clear_cache()
+#     assert isinstance(result, bool)
+