financegy 1.5__py3-none-any.whl → 2.0__py3-none-any.whl

financegy/__init__.py

@@ -1,34 +1,48 @@
 """FinanceGY - a Python library for accessing data from the Guyana Stock Exchange."""
 
-from importlib.metadata import version, PackageNotFoundError
+from financegy.cache.cache_manager import clear_cache
+from financegy.utils.utils import save_to_csv, to_dataframe, save_to_excel
 
-from financegy.modules.securities import(
+from financegy.modules.securities import (
     get_securities,
     get_security_by_symbol,
     get_recent_trade,
+    get_previous_close,
+    get_price_change,
+    get_price_change_percent,
     get_security_recent_year,
     get_session_trades,
+    get_sessions_average_price,
+    get_average_price,
+    get_sessions_volatility,
+    get_ytd_high_low,
+    get_latest_session_for_symbol,
     get_security_session_trade,
     search_securities,
     get_trades_for_year,
-    get_historical_trades
+    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",
     "get_recent_trade",
+    "get_previous_close",
+    "get_price_change",
+    "get_price_change_percent",
     "get_security_recent_year",
     "get_session_trades",
+    "get_sessions_average_price",
+    "get_average_price",
     "get_security_session_trade",
+    "get_latest_session_for_symbol",
+    "get_sessions_volatility",
+    "get_ytd_high_low",
     "search_securities",
     "get_trades_for_year",
     "get_historical_trades",
     "clear_cache",
     "save_to_csv",
     "to_dataframe",
-    "save_to_excel"
+    "save_to_excel",
 ]

financegy/cache/cache_manager.py

@@ -5,20 +5,18 @@ 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_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)
@@ -36,18 +34,17 @@ def load_cache(func_name, *args, max_age_days=7, **kwargs):
 
     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)
+        json.dump({"timestamp": datetime.now().isoformat(), "value": value}, f)
 
-def clear_cache():
+
+def clear_cache(silent: bool = False):
     """Completely clears the FinanceGY cache directory."""
     if not os.path.exists(CACHE_DIR):
         print("No cache directory found.")
@@ -55,8 +52,9 @@ def clear_cache():
 
     try:
         shutil.rmtree(CACHE_DIR)
-        print("Cache cleared successfully.")
+        if not silent:
+            print("\nCache cleared successfully.")
         return True
-        
+
     except Exception as e:
-        print(f"Failed to clear cache: {e}")
+        print(f"Failed to clear cache: {e}")

financegy/config.py

@@ -1,7 +1,7 @@
-__version__ = "0.1.0"
+__version__ = "2.0"
 
 BASE_URL = "https://guyanastockexchangeinc.com"
 HEADERS = {
     "User-Agent": f"FinanceGY/{__version__} (https://github.com/xbze3/financegy)"
 }
-REQUEST_TIMEOUT = 10
+REQUEST_TIMEOUT = 10

financegy/core/parser.py

@@ -1,5 +1,8 @@
 from bs4 import BeautifulSoup
 from datetime import datetime
+from financegy.helpers.to_float import to_float
+from financegy.helpers.safe_text import safe_text
+
 
 def parse_get_securities(html: str):
     """Extract security info"""
@@ -10,25 +13,26 @@ def parse_get_securities(html: str):
 
         if not security_info_html:
             return []
-        
+
         security_info = []
         securities = security_info_html.find_all("div", class_="security group")
 
         for security in securities:
-            symbol = security.find_all("div", class_="acronym inline")[0].get_text(strip=True)
-            name = security.find_all("div", class_="name inline")[0].get_text(strip=True)
+            symbol = security.find_all("div", class_="acronym inline")[0].get_text(
+                strip=True
+            )
+            name = security.find_all("div", class_="name inline")[0].get_text(
+                strip=True
+            )
 
-            security_info.append({
-                "symbol": symbol,
-                "name": name
-            })
+            security_info.append({"symbol": symbol, "name": name})
 
-        
         return security_info
-    
+
     except Exception as e:
         print(f"[parse_get_securities] Error parsing securities: {e}")
 
+
 def parse_get_security_recent_year(html: str):
     """Extract selected security's trade info from current year"""
 
@@ -38,35 +42,34 @@ def parse_get_security_recent_year(html: str):
         security_info_html = soup.find("div", class_="year slide")
         if not security_info_html:
             raise ValueError("Could not find 'div.year.slide' section in HTML.")
-        
+
         trade_data = []
 
         trades = security_info_html.find_all("tr", class_="trade")
         if not trades:
             raise ValueError("No trade rows found for this security.")
-        
-        def safe_text(parent, class_name):
-            cell = parent.find("td", class_=class_name)
-            return cell.get_text(strip=True) if cell else None
-        
+
         for trade in trades:
-            trade_data.append({
-            "session": safe_text(trade, "session"),
-            "date": safe_text(trade, "date"),
-            "ltp": safe_text(trade, "name"),
-            "best_bid": safe_text(trade, "best bid"),
-            "vol_bid": safe_text(trade, "vol bid"),
-            "best_offer": safe_text(trade, "best offer"),
-            "vol_offer": safe_text(trade, "vol offer"),
-            "opening_price": safe_text(trade, "opening price"),
-            })
+            trade_data.append(
+                {
+                    "session": safe_text(trade, "session"),
+                    "session_date": safe_text(trade, "date"),
+                    "last_trade_price": safe_text(trade, "name"),
+                    "eps": safe_text(trade, "best bid"),
+                    "pe_ratio": safe_text(trade, "vol bid"),
+                    "dividends_paid_last_12_months": safe_text(trade, "best offer"),
+                    "dividend_yield": safe_text(trade, "vol offer"),
+                    "notes": safe_text(trade, "opening price"),
+                }
+            )
 
         return trade_data
-    
+
     except Exception as e:
         print(f"[parse_get_security_recent_year] Error parsing HTML: {e}")
         return None
 
+
 def parse_get_recent_trade(html: str):
     """Extract selected security's most recent trade info"""
     try:
@@ -82,27 +85,253 @@ def parse_get_recent_trade(html: str):
 
         recent = trades[-1]
 
-        def safe_text(parent, class_name):
-            cell = parent.find("td", class_=class_name)
-            return cell.get_text(strip=True) if cell else None
-
         recent_info = {
             "session": safe_text(recent, "session"),
-            "date": safe_text(recent, "date"),
-            "ltp": safe_text(recent, "name"),
-            "best_bid": safe_text(recent, "best bid"),
-            "vol_bid": safe_text(recent, "vol bid"),
-            "best_offer": safe_text(recent, "best offer"),
-            "vol_offer": safe_text(recent, "vol offer"),
-            "opening_price": safe_text(recent, "opening price"),
+            "session_date": safe_text(recent, "date"),
+            "last_trade_price": safe_text(recent, "name"),
+            "eps": safe_text(recent, "best bid"),
+            "pe_ratio": safe_text(recent, "vol bid"),
+            "dividends_paid_last_12_months": safe_text(recent, "best offer"),
+            "dividend_yield": safe_text(recent, "vol offer"),
+            "notes": safe_text(recent, "opening price"),
         }
 
         return recent_info
 
     except Exception as e:
-        print(f"[parse_get_security_recent] Error parsing HTML: {e}")
+        print(f"[parse_get_recent_trade] Error parsing HTML: {e}")
+        return None
+
+
+def parse_get_previous_close(html: str):
+    """Extract selected security's most recent closing price"""
+    try:
+        soup = BeautifulSoup(html, "html.parser")
+
+        security_info_html = soup.find("div", class_="year slide")
+        if not security_info_html:
+            raise ValueError("Could not find 'div.year.slide' section in HTML.")
+
+        trades = security_info_html.find_all("tr", class_="trade")
+        if not trades:
+            raise ValueError("No trade rows found for this security.")
+
+        recent = trades[-1]
+
+        previous_close = {
+            "last_trade_price": safe_text(recent, "name"),
+        }
+
+        return previous_close
+
+    except Exception as e:
+        print(f"[parse_get_previous_close] Error parsing HTML: {e}")
+        return None
+
+
+def parse_get_price_change(html: str):
+    """Extract selected security's absolute price difference between the most recent trade and the previous session close"""
+
+    try:
+        soup = BeautifulSoup(html, "html.parser")
+
+        security_info_html = soup.find("div", class_="year slide")
+        if not security_info_html:
+            raise ValueError("Could not find 'div.year.slide' section in HTML.")
+
+        trades = security_info_html.find_all("tr", class_="trade")
+        if not trades:
+            raise ValueError("No trade rows found for this security.")
+
+        recent = trades[-1]
+        previous = trades[-2]
+
+        price_change = {
+            "recent_trade": {
+                "session": safe_text(recent, "session"),
+                "session_date": safe_text(recent, "date"),
+                "last_trade_price": safe_text(recent, "name"),
+            },
+            "previous_trade": {
+                "session": safe_text(previous, "session"),
+                "session_date": safe_text(previous, "date"),
+                "last_trade_price": safe_text(previous, "name"),
+            },
+            "price_difference": f"{(
+                to_float(safe_text(recent, 'name'))
+                - to_float(safe_text(previous, 'name'))
+            )}",
+        }
+
+        return price_change
+
+    except Exception as e:
+        print(f"[parse_get_price_change] Error parsing HTML: {e}")
+        return None
+
+
+def parse_get_price_change_percent(html: str):
+    """Extract selected security's percentage price difference between the most recent trade and the previous session close"""
+
+    try:
+        soup = BeautifulSoup(html, "html.parser")
+
+        security_info_html = soup.find("div", class_="year slide")
+        if not security_info_html:
+            raise ValueError("Could not find 'div.year.slide' section in HTML.")
+
+        trades = security_info_html.find_all("tr", class_="trade")
+        if not trades:
+            raise ValueError("No trade rows found for this security.")
+
+        recent = trades[-1]
+        previous = trades[-2]
+
+        price_change_percent = {
+            "recent_trade": {
+                "session": safe_text(recent, "session"),
+                "session_date": safe_text(recent, "date"),
+                "last_trade_price": safe_text(recent, "name"),
+            },
+            "previous_trade": {
+                "session": safe_text(previous, "session"),
+                "session_date": safe_text(previous, "date"),
+                "last_trade_price": safe_text(previous, "name"),
+            },
+            "price_change_percent": f"{round(((to_float(safe_text(recent, 'name')) - to_float(safe_text(previous, 'name'))) /  to_float(safe_text(previous, 'name'))) * 100, 2)}",
+        }
+
+        return price_change_percent
+
+    except Exception as e:
+        print(f"[parse_get_price_change_percent] Error parsing HTML: {e}")
+        return None
+
+
+def parse_get_sessions_average_price(symbol: str, html: str):
+    """Extract average traded price of the security over a specified session range."""
+
+    try:
+        soup = BeautifulSoup(html, "html.parser")
+
+        session_div = soup.find("div", class_="session")
+        if not session_div:
+            raise ValueError("Could not find 'div.session' section in HTML.")
+
+        rows = session_div.find_all("tr", class_="trade")
+        if not rows:
+            raise ValueError("No trade rows found in session data.")
+
+        for row in rows:
+            row_symbol = safe_text(row, "mnemonic")
+            if row_symbol == symbol:
+                return to_float(safe_text(row, "name"))
+
+        return None
+
+    except Exception as e:
+        print(f"[parse_get_sessions_average_price] Error parsing HTML: {e}")
         return None
-    
+
+
+def parse_get_average_price(symbol: str, html: str):
+    """
+    From a /financial_session/{session}/ page, return the last_trade_price (LTP)
+    for the given symbol. Returns None if not found/unparseable.
+    """
+    try:
+        soup = BeautifulSoup(html, "html.parser")
+
+        session_div = soup.find("div", class_="session")
+        if not session_div:
+            raise ValueError("Could not find 'div.session' section in HTML.")
+
+        rows = session_div.find_all("tr", class_="trade")
+        if not rows:
+            raise ValueError("No trade rows found in session data.")
+
+        for row in rows:
+            row_symbol = safe_text(row, "mnemonic")
+            if row_symbol == symbol:
+                return to_float(safe_text(row, "name"))
+
+        return None
+    except Exception as e:
+        print(f"[parse_get_average_price] Error parsing HTML: {e}")
+        return None
+
+
+def parse_get_session_ltp(symbol: str, html: str):
+    """From a /financial_session/{session}/ page, return LTP for symbol."""
+
+    try:
+        soup = BeautifulSoup(html, "html.parser")
+
+        session_div = soup.find("div", class_="session")
+        if not session_div:
+            return None
+
+        rows = session_div.find_all("tr", class_="trade")
+        if not rows:
+            return None
+
+        for row in rows:
+            if safe_text(row, "mnemonic") == symbol:
+                return to_float(safe_text(row, "name"))
+
+        return None
+    except Exception as e:
+        print(f"[parse_get_session_ltp] Error parsing HTML: {e}")
+        return None
+
+
+def parse_get_ytd_high_low(html: str):
+    """
+    Parse the current-year trade rows in the security page HTML and return
+    YTD high/low with session/date metadata.
+    """
+
+    try:
+        year = str(datetime.now().year)
+
+        trades = parse_get_trades_for_year(year, html)
+        if not trades:
+            return None
+
+        best_high = None
+        best_low = None
+
+        for t in trades:
+            price = to_float(t.get("last_trade_price"))
+            if price is None:
+                continue
+
+            entry = {
+                "price": price,
+                "session": t.get("session"),
+                "session_date": t.get("session_date"),
+            }
+
+            if best_high is None or price > best_high["price"]:
+                best_high = entry
+
+            if best_low is None or price < best_low["price"]:
+                best_low = entry
+
+        if best_high is None or best_low is None:
+            return None
+
+        return {
+            "year": int(year),
+            "high": best_high,
+            "low": best_low,
+        }
+
+    except Exception as e:
+        print(f"[parse_get_ytd_high_low] Error parsing HTML: {e}")
+        return None
+
+
 def parse_get_session_trades(html: str):
     """Extract session data for all securities"""
 
@@ -117,29 +346,28 @@ def parse_get_session_trades(html: str):
         if not sessions:
             raise ValueError("No session data found.")
 
-        def safe_text(parent, class_name):
-            cell = parent.find("td", class_=class_name)
-            return cell.get_text(strip=True) if cell else None
-
         session_data = []
 
         for session in sessions:
-            session_data.append({
-            "symbol": safe_text(session, "mnemonic"),
-            "ltp": safe_text(session, "name"),
-            "best_bid": safe_text(session, "best bid"),
-            "vol_bid": safe_text(session, "vol bid"),
-            "best_offer": safe_text(session, "best offer"),
-            "vol_offer": safe_text(session, "vol offer"),
-            "opening_price": safe_text(session, "opening price"),
-            })
+            session_data.append(
+                {
+                    "symbol": safe_text(session, "mnemonic"),
+                    "last_trade_price": safe_text(session, "name"),
+                    "eps": safe_text(session, "best bid"),
+                    "pe_ratio": safe_text(session, "vol bid"),
+                    "dividends_paid_last_12_months": safe_text(session, "best offer"),
+                    "dividend_yield": safe_text(session, "vol offer"),
+                    "notes": safe_text(session, "opening price"),
+                }
+            )
 
         return session_data
-    
+
     except Exception as e:
         print(f"[parse_get_securities_session] Error parsing HTML: {e}")
         return None
-    
+
+
 def parse_get_security_session_trade(symbol: str, html: str):
     """Extract session data for given security"""
 
@@ -153,32 +381,28 @@ def parse_get_security_session_trade(symbol: str, html: str):
         sessions = sessions_info_html.find_all("tr", class_="trade")
         if not sessions:
             raise ValueError("No session data found.")
-        
-        def safe_text(parent, class_name):
-            cell = parent.find("td", class_=class_name)
-            return cell.get_text(strip=True) if cell else None
-
 
         for session in sessions:
             session_symbol = safe_text(session, "mnemonic")
 
-            if (session_symbol == symbol):
+            if session_symbol == symbol:
                 session_data = {
                     "symbol": safe_text(session, "mnemonic"),
-                    "ltp": safe_text(session, "name"),
-                    "best_bid": safe_text(session, "best bid"),
-                    "vol_bid": safe_text(session, "vol bid"),
-                    "best_offer": safe_text(session, "best offer"),
-                    "vol_offer": safe_text(session, "vol offer"),
-                    "opening_price": safe_text(session, "opening price"),
+                    "last_trade_price": safe_text(session, "name"),
+                    "eps": safe_text(session, "best bid"),
+                    "pe_ratio": safe_text(session, "vol bid"),
+                    "dividends_paid_last_12_months": safe_text(session, "best offer"),
+                    "dividend_yield": safe_text(session, "vol offer"),
+                    "notes": safe_text(session, "opening price"),
                 }
-        
+
         return session_data
-    
+
     except Exception as e:
         print(f"[parse_get_security_session] Error parsing HTML: {e}")
         return None
-    
+
+
 def parse_get_trades_for_year(year: str, html: str):
     """Get security trade information from a specific year"""
 
@@ -188,37 +412,33 @@ def parse_get_trades_for_year(year: str, html: str):
         security_info_html = soup.find("div", class_="year slide", id=year)
         if not security_info_html:
             raise ValueError("Could not find 'div.year.slide' section in HTML.")
-        
+
         trade_data = []
 
         trades = security_info_html.find_all("tr", class_="trade")
         if not trades:
             raise ValueError("No trade rows found for this security.")
-        
-        def safe_text(parent, class_name):
-            cell = parent.find("td", class_=class_name)
-            return cell.get_text(strip=True) if cell else None
-        
+
         for trade in trades:
-            trade_data.append({
-            "session": safe_text(trade, "session"),
-            "date": safe_text(trade, "date"),
-            "ltp": safe_text(trade, "name"),
-            "best_bid": safe_text(trade, "best bid"),
-            "vol_bid": safe_text(trade, "vol bid"),
-            "best_offer": safe_text(trade, "best offer"),
-            "vol_offer": safe_text(trade, "vol offer"),
-            "opening_price": safe_text(trade, "opening price"),
-            })
+            trade_data.append(
+                {
+                    "session": safe_text(trade, "session"),
+                    "session_date": safe_text(trade, "date"),
+                    "last_trade_price": safe_text(trade, "name"),
+                    "eps": safe_text(trade, "best bid"),
+                    "pe_ratio": safe_text(trade, "vol bid"),
+                    "dividends_paid_last_12_months": safe_text(trade, "best offer"),
+                    "dividend_yield": safe_text(trade, "vol offer"),
+                    "notes": safe_text(trade, "opening price"),
+                }
+            )
 
         return trade_data
-    
+
     except Exception as e:
         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)"""
@@ -254,10 +474,6 @@ def parse_get_historical_trades(start_date: str, end_date: str, html: str):
 
         trade_data = []
 
-        def safe_text(parent, class_name):
-            cell = parent.find("td", class_=class_name)
-            return cell.get_text(strip=True) if cell else None
-
         for section in year_sections:
             year_id = section.get("id")
             if not year_id or not year_id.isdigit():
@@ -279,18 +495,22 @@ def parse_get_historical_trades(start_date: str, end_date: str, html: str):
                     continue
 
                 if start <= trade_date <= end:
-                    trade_data.append({
-                        "session": safe_text(trade, "session"),
-                        "date": date_text,
-                        "ltp": safe_text(trade, "name"),
-                        "best_bid": safe_text(trade, "best bid"),
-                        "vol_bid": safe_text(trade, "vol bid"),
-                        "best_offer": safe_text(trade, "best offer"),
-                        "vol_offer": safe_text(trade, "vol offer"),
-                        "opening_price": safe_text(trade, "opening price"),
-                    })
-
-        trade_data.sort(key=lambda x: datetime.strptime(x["date"], "%d/%m/%Y"))
+                    trade_data.append(
+                        {
+                            "session": safe_text(trade, "session"),
+                            "session_date": safe_text(trade, "date"),
+                            "last_trade_price": safe_text(trade, "name"),
+                            "eps": safe_text(trade, "best bid"),
+                            "pe_ratio": safe_text(trade, "vol bid"),
+                            "dividends_paid_last_12_months": safe_text(
+                                trade, "best offer"
+                            ),
+                            "dividend_yield": safe_text(trade, "vol offer"),
+                            "notes": safe_text(trade, "opening price"),
+                        }
+                    )
+
+        trade_data.sort(key=lambda x: datetime.strptime(x["session_date"], "%d/%m/%Y"))
         return trade_data
 
     except Exception as e:

financegy/helpers/safe_text.py

@@ -0,0 +1,3 @@
+def safe_text(parent, class_name):
+    cell = parent.find("td", class_=class_name)
+    return cell.get_text(strip=True) if cell else None