financegy 0.1.0__py3-none-any.whl → 1.3__py3-none-any.whl

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/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/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.dist-info → financegy-1.3.dist-info}/METADATA

@@ -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-1.3.dist-info/RECORD

@@ -0,0 +1,11 @@
+financegy/__init__.py,sha256=c0b1JX1ZkQVxF984dIW-C6E24blvb1cSmmjY4Msh9kY,790
+financegy/config.py,sha256=SD5LpUVZvthUJEN2KxInRzoOLZCgSMXHV-tc1kKSPt8,193
+financegy/cache/cache_manager.py,sha256=l2J7Fj3g0EnkJLGeIMuaslwFI9-6Ipmf4PHJLUMphAU,1859
+financegy/core/parser.py,sha256=w1JBLphaKSbKimQsGkfDMyj69zmIGtGClnqHxWHx-Lc,10259
+financegy/core/request_handler.py,sha256=g0C0R-nvIvicAhxnCEAtTU8buVtzUn8725EERvBA6ZU,276
+financegy/modules/securities.py,sha256=PNEqfot_cqneO0j4muRfYC5sbCUaZaJoKiq1exBXSz4,5233
+financegy-1.3.dist-info/licenses/LICENSE,sha256=HGLhx0fI215whUzIvTFdFivB447d_IdIIIRncUCQaEs,1088
+financegy-1.3.dist-info/METADATA,sha256=1wrYM-4anai8UX3HVbT5wXWb1gLlKvRQ9y2qUFZKYyE,4722
+financegy-1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+financegy-1.3.dist-info/top_level.txt,sha256=TpdYDxtK61m5xnvvzbqnDVJ82gphEqxnXN_Ur8rjvxQ,10
+financegy-1.3.dist-info/RECORD,,

financegy-0.1.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-financegy/__init__.py,sha256=tXwqh9F9KYRVJ8Sv1kTag29GnGNv-NsOYR_P59V6n5w,713
-financegy/config.py,sha256=SD5LpUVZvthUJEN2KxInRzoOLZCgSMXHV-tc1kKSPt8,193
-financegy/core/parser.py,sha256=w1JBLphaKSbKimQsGkfDMyj69zmIGtGClnqHxWHx-Lc,10259
-financegy/core/request_handler.py,sha256=g0C0R-nvIvicAhxnCEAtTU8buVtzUn8725EERvBA6ZU,276
-financegy/modules/securities.py,sha256=yAEX6MchhML9-hwPpEb71j0OS8FP9P2D94xaUHkKTys,3096
-financegy-0.1.0.dist-info/licenses/LICENSE,sha256=HGLhx0fI215whUzIvTFdFivB447d_IdIIIRncUCQaEs,1088
-financegy-0.1.0.dist-info/METADATA,sha256=vDqzfmxMhZLJ9JJcNy2Eoqzt8XH5fDgkNrXc6bI6dcU,3367
-financegy-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-financegy-0.1.0.dist-info/top_level.txt,sha256=TpdYDxtK61m5xnvvzbqnDVJ82gphEqxnXN_Ur8rjvxQ,10
-financegy-0.1.0.dist-info/RECORD,,