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

financegy/modules/securities.py

@@ -1,5 +1,7 @@
 from financegy.core import request_handler, parser
 from financegy.cache import cache_manager
+import math
+
 
 def get_securities(use_cache=True):
     """Get names of all currently traded securities"""
@@ -16,7 +18,8 @@ def get_securities(use_cache=True):
 
     cache_manager.save_cache(func_name, html)
 
-    return parser.parse_get_securities(html);
+    return parser.parse_get_securities(html)
+
 
 def get_security_by_symbol(symbol: str, use_cache=True):
     """Get the security details by its ticker symbol"""
@@ -26,11 +29,16 @@ def get_security_by_symbol(symbol: str, use_cache=True):
     symbol = symbol.strip().upper()
 
     return next(
-        (security['name'] for security in securities if security["symbol"].upper() == symbol),
+        (
+            security["name"]
+            for security in securities
+            if security["symbol"].upper() == symbol
+        ),
         None,
     )
 
-def get_security_recent_year(symbol:str, use_cache=True):
+
+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"
@@ -50,11 +58,12 @@ def get_security_recent_year(symbol:str, use_cache=True):
 
     return parser.parse_get_security_recent_year(html)
 
+
 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(" ", "-")
 
@@ -70,6 +79,197 @@ def get_recent_trade(symbol: str, use_cache=True):
 
     return parser.parse_get_recent_trade(html)
 
+
+def get_previous_close(symbol: str, use_cache=True):
+    """Get the most recent closing price for any of the traded securities"""
+
+    func_name = "get_previous_close"
+
+    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_previous_close(cached)
+
+    path = "/security/" + security_name
+    html = request_handler.fetch_page(path)
+
+    cache_manager.save_cache(func_name, html, symbol)
+
+    return parser.parse_get_previous_close(html)
+
+
+def get_price_change(symbol: str, use_cache=True):
+    """Get absolute price difference between the most recent trade and the previous session close."""
+
+    func_name = "get_price_change"
+
+    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_price_change(cached)
+
+    path = "/security/" + security_name
+    html = request_handler.fetch_page(path)
+
+    cache_manager.save_cache(func_name, html, symbol)
+
+    return parser.parse_get_price_change(html)
+
+
+def get_price_change_percent(symbol: str, use_cache=True):
+    """Get the percentage price change between the most recent trade and the previous session close."""
+
+    func_name = "get_price_change_percent"
+
+    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_price_change_percent(cached)
+
+    path = "/security/" + security_name
+    html = request_handler.fetch_page(path)
+
+    cache_manager.save_cache(func_name, html, symbol)
+
+    return parser.parse_get_price_change_percent(html)
+
+
+def get_latest_session_for_symbol(symbol: str, use_cache: bool = True):
+    """
+    Fetch the security page, parse the most recent trade, return its session as int.
+    """
+
+    func_name = "get_latest_session_for_symbol"
+    symbol = symbol.strip().upper()
+
+    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)
+
+    recent = parser.parse_get_recent_trade(html)
+
+    if not recent or not recent.get("session"):
+        raise ValueError(f"Could not determine latest session for {symbol}")
+
+    return recent
+
+
+def get_sessions_average_price(
+    symbol: str, session_start: str, session_end: str, use_cache=True
+):
+    """Get the average last traded price of the security over a specified session range."""
+
+    func_name = "get_sessions_average_price"
+
+    start = int(session_start)
+    end = int(session_end)
+    symbol = symbol.strip().upper()
+
+    if end < start:
+        raise ValueError("session_end must be >= session_start")
+
+    prices_by_session: dict[int, float] = {}
+
+    for session in range(start, end + 1):
+
+        html = None
+        if use_cache:
+            html = cache_manager.load_cache(func_name, symbol, session)
+
+        if not html:
+            path = f"/financial_session/{session}/"
+            html = request_handler.fetch_page(path)
+            cache_manager.save_cache(func_name, html, symbol, session)
+
+        price = parser.parse_get_sessions_average_price(symbol, html)
+
+        if price is None:
+            continue
+
+        prices_by_session[session] = price
+
+    if not prices_by_session:
+        raise ValueError(f"No prices found for {symbol} in sessions {start}..{end}")
+
+    avg = round(sum(prices_by_session.values()) / len(prices_by_session), 2)
+
+    return {
+        "symbol": symbol,
+        "session_start": start,
+        "session_end": end,
+        "observations": len(prices_by_session),
+        "average_price": avg,
+        "prices_by_session": prices_by_session,
+    }
+
+
+def get_average_price(symbol: str, session_number: int, use_cache=True):
+    """Average LTP over the most recent `session_number` sessions (ending at latest session)."""
+
+    func_name = "get_average_price"
+    symbol = symbol.strip().upper()
+
+    if session_number <= 0:
+        raise ValueError("session_number must be a positive integer")
+
+    latest = get_latest_session_for_symbol(symbol, use_cache=use_cache)
+    end = int(latest["session"])
+    start = max(1, end - session_number + 1)
+
+    prices_by_session: dict[int, float] = {}
+
+    for session in range(start, end + 1):
+        html = None
+
+        if use_cache:
+            html = cache_manager.load_cache(func_name, symbol, session)
+
+        if not html:
+            path = f"/financial_session/{session}/"
+            html = request_handler.fetch_page(path)
+            cache_manager.save_cache(func_name, html, symbol, session)
+
+        price = parser.parse_get_average_price(symbol, html)
+        if price is None:
+            continue
+
+        prices_by_session[session] = price
+
+    if not prices_by_session:
+        raise ValueError(f"No prices found for {symbol} in sessions {start}..{end}")
+
+    avg = round(sum(prices_by_session.values()) / len(prices_by_session), 2)
+
+    return {
+        "symbol": symbol,
+        "latest_session": latest,
+        "session_number_requested": session_number,
+        "session_start": start,
+        "session_end": end,
+        "observations": len(prices_by_session),
+        "average_price": avg,
+        "prices_by_session": prices_by_session,
+    }
+
+
 def get_session_trades(session: str, use_cache=True):
     """Get the session trade data for all the available securities"""
 
@@ -87,6 +287,7 @@ def get_session_trades(session: str, use_cache=True):
 
     return parser.parse_get_session_trades(html)
 
+
 def get_security_session_trade(symbol: str, session: str, use_cache=True):
     """Get the session trade data for a given security"""
 
@@ -106,6 +307,114 @@ def get_security_session_trade(symbol: str, session: str, use_cache=True):
 
     return parser.parse_get_security_session_trade(symbol, html)
 
+
+def get_sessions_volatility(symbol: str, session_number: int, use_cache=True):
+    """
+    Volatility over the last `sessions` observed prices, ending at the latest session.
+    Uses log returns and returns weekly volatility (std dev of weekly returns).
+    """
+
+    symbol = symbol.strip().upper()
+
+    if session_number <= 1:
+        raise ValueError(
+            "session_number must be >= 2 (need at least 2 prices to compute returns)."
+        )
+
+    latest = get_latest_session_for_symbol(symbol, use_cache=use_cache)
+    latest_session = int(latest["session"])
+
+    target_prices = session_number
+    prices: list[float] = []
+    prices_by_session: dict[int, float] = {}
+
+    func_name = "get_sessions_volatility"
+
+    session = latest_session
+    safety_limit = latest_session - (session_number * 5)
+
+    while session >= 1 and session >= safety_limit and len(prices) < target_prices:
+
+        html = None
+        if use_cache:
+            html = cache_manager.load_cache(func_name, symbol, session)
+
+        if not html:
+            path = f"/financial_session/{session}/"
+            html = request_handler.fetch_page(path)
+            cache_manager.save_cache(func_name, html, symbol, session)
+
+        price = parser.parse_get_session_ltp(symbol, html)
+
+        if price is not None:
+            prices.append(price)
+            prices_by_session[session] = price
+
+        session -= 1
+
+    if len(prices) < 2:
+        raise ValueError(
+            f"Not enough price data found for {symbol} to compute volatility."
+        )
+
+    prices.reverse()
+
+    returns = []
+    for i in range(1, len(prices)):
+        prev_p = prices[i - 1]
+        cur_p = prices[i]
+        if prev_p and prev_p > 0 and cur_p and cur_p > 0:
+            returns.append(math.log(cur_p / prev_p))
+
+    if len(returns) < 2:
+        raise ValueError("Not enough valid returns to compute volatility.")
+
+    mean = sum(returns) / len(returns)
+    variance = sum((r - mean) ** 2 for r in returns) / (len(returns) - 1)
+    weekly_vol = round(math.sqrt(variance), 2)
+
+    annualized_vol = round(weekly_vol * math.sqrt(52), 2)
+
+    return {
+        "symbol": symbol,
+        "latest_session": latest_session,
+        "requested_sessions": session_number,
+        "prices_found": len(prices),
+        "returns_count": len(returns),
+        "weekly_volatility": weekly_vol,
+        "annualized_volatility": annualized_vol,
+        "prices_by_session": dict(sorted(prices_by_session.items())),
+    }
+
+
+def get_ytd_high_low(symbol: str, use_cache: bool = True):
+    """Return year-to-date highest and lowest traded prices for the security."""
+
+    func_name = "get_ytd_high_low"
+    symbol = symbol.strip().upper()
+
+    security_name = get_security_by_symbol(symbol)
+    security_name = security_name.lower().replace(" ", "-")
+
+    html = None
+    if use_cache:
+        html = cache_manager.load_cache(func_name, symbol)
+
+    if not html:
+        path = f"/security/{security_name}/"
+        html = request_handler.fetch_page(path)
+        cache_manager.save_cache(func_name, html, symbol)
+
+    result = parser.parse_get_ytd_high_low(html)
+    if not result:
+        raise ValueError(f"Could not compute YTD high/low for {symbol}")
+
+    return {
+        "symbol": symbol,
+        **result,
+    }
+
+
 def get_trades_for_year(symbol: str, year: str, use_cache=True):
     """Get security trade information from a specific year"""
 
@@ -128,6 +437,7 @@ def get_trades_for_year(symbol: str, year: str, use_cache=True):
 
     return parser.parse_get_trades_for_year(year, html)
 
+
 def get_historical_trades(symbol: str, start_date: str, end_date: str, use_cache=True):
     """Get historical trade data for a date range"""
 
@@ -150,6 +460,7 @@ def get_historical_trades(symbol: str, start_date: str, end_date: str, use_cache
 
     return parser.parse_get_historical_trades(start_date, end_date, html)
 
+
 def search_securities(query: str, use_cache=True):
     """Search securities by symbol or name (partial match)"""
 
@@ -157,8 +468,9 @@ def search_securities(query: str, use_cache=True):
     all_securities = get_securities()
 
     matches = [
-        sec for sec in all_securities
+        sec
+        for sec in all_securities
         if query in sec["symbol"].lower() or query in sec["name"].lower()
     ]
 
-    return matches
+    return matches

financegy/utils/utils.py

@@ -0,0 +1,61 @@
+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, silent: bool = False
+):
+    """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)
+
+    if not silent:
+        print(f"\nSaved CSV to: {full_path}")
+
+    return True
+
+
+def save_to_excel(
+    data: dict | list[dict],
+    filename: str = "output.xlsx",
+    path: str = None,
+    silent: bool = False,
+):
+    """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)
+
+    if not silent:
+        print(f"\nSaved Excel Document to: {full_path}")
+
+    return True

financegy-2.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: financegy
+Version: 2.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
+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
+
+# --------------------------
+# Core Data Retrieval
+# --------------------------
+
+# Get a list of all traded securities
+securities = financegy.get_securities()
+
+# Get the full 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 the most recent closing/last trade price (same most-recent session)
+previous_close = financegy.get_previous_close("DDL")
+
+# Get absolute price change vs previous session close
+price_change = financegy.get_price_change("DDL")
+
+# Get percent price change vs previous session close
+price_change_percent = financegy.get_price_change_percent("DDL")
+
+# Get all trade data for the most recent year (for the security)
+recent_year_trades = financegy.get_security_recent_year("DDL")
+
+# Get trade data for a specific trading session (all securities)
+session_trades = financegy.get_session_trades("1136")
+
+# Get trade data for a specific security in a session
+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 specific year
+year_trades = financegy.get_trades_for_year("DDL", "2019")
+
+# Get historical trades within a date range — supports: yyyy / mm/yyyy / dd/mm/yyyy
+historical_trades = financegy.get_historical_trades(
+    symbol="DDL",
+    start_date="01/06/2020",
+    end_date="01/2022"
+)
+
+# --------------------------
+# Analytics / Calculations
+# --------------------------
+
+# Get the latest session info (dict returned from most recent trade)
+latest_session = financegy.get_latest_session_for_symbol("DDL")
+
+# Average last traded price over a session range (inclusive)
+avg_price_range = financegy.get_sessions_average_price("DDL", "1100", "1136")
+
+# Average last traded price over the last N sessions (ending at latest session)
+avg_price_latest = financegy.get_average_price("DDL", 30)
+
+# Volatility over the last N sessions (weekly log-return volatility + annualized)
+volatility = financegy.get_sessions_volatility("DDL", 30)
+
+# Year-to-date high and low traded prices
+ytd_high_low = financegy.get_ytd_high_low("DDL")
+
+# --------------------------
+# Utilities
+# --------------------------
+
+# Convert results to a DataFrame
+df = financegy.to_dataframe(securities)
+
+# Export to CSV / Excel
+financegy.save_to_csv(securities, filename="securities.csv", silent=True)
+financegy.save_to_excel(securities, filename="securities.xlsx", silent=True)
+
+# Clear FinanceGY cache directory
+financegy.clear_cache(silent=True)
+```
+
+---
+
+## API Reference
+
+### Core Data Retrieval
+
+| Function                                              | Description                                                                                           |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `get_securities()`                                    | Returns all currently traded securities on the GSE.                                                   |
+| `get_security_by_symbol(symbol)`                      | Returns the full security name for a ticker symbol (e.g., `"DDL"` → `"Demerara Distillers Limited"`). |
+| `get_recent_trade(symbol)`                            | Returns the most recent trade information for the given security.                                     |
+| `get_security_recent_year(symbol)`                    | Returns all trade data for the most recent year available for the selected security.                  |
+| `get_session_trades(session)`                         | Returns trade data for **all** securities during a specific trading session.                          |
+| `get_security_session_trade(symbol, session)`         | Returns trade data for a **specific** security during a specific session.                             |
+| `search_securities(query)`                            | Searches securities whose names or ticker symbols match the given query (partial match).              |
+| `get_trades_for_year(symbol, year)`                   | Returns all trade records for a specific security during a given year.                                |
+| `get_historical_trades(symbol, start_date, end_date)` | Returns historical trades within the specified date range (`dd/mm/yyyy`, `mm/yyyy`, or `yyyy`).       |
+
+### Analytics / Calculation Functions
+
+| Function                                                         | Description                                                                                      |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `get_previous_close(symbol)`                                     | Returns the most recent closing/last trade price for the security.                               |
+| `get_price_change(symbol)`                                       | Returns absolute price difference between the most recent trade and the previous session close.  |
+| `get_price_change_percent(symbol)`                               | Returns percent price change between the most recent trade and the previous session close.       |
+| `get_latest_session_for_symbol(symbol)`                          | Returns the latest trade dict for the symbol (includes the latest `session`).                    |
+| `get_sessions_average_price(symbol, session_start, session_end)` | Returns the average last traded price over a session range (inclusive).                          |
+| `get_average_price(symbol, session_number)`                      | Returns the average last traded price over the last **N** sessions ending at the latest session. |
+| `get_sessions_volatility(symbol, session_number)`                | Returns volatility over the last **N** sessions using log returns (weekly + annualized).         |
+| `get_ytd_high_low(symbol)`                                       | Returns year-to-date highest and lowest traded prices for the security.                          |
+
+### Utilities
+
+| Function                                                               | Description                                                     |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `to_dataframe(data)`                                                   | Converts FinanceGY list/dict results into a `pandas.DataFrame`. |
+| `save_to_csv(data, filename="output.csv", path=None, silent=False)`    | Saves data to a CSV file.                                       |
+| `save_to_excel(data, filename="output.xlsx", path=None, silent=False)` | Saves data to an Excel file.                                    |
+| `clear_cache(silent=False)`                                            | Completely clears the FinanceGY cache directory.                |
+
+---
+
+## 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-2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+financegy/__init__.py,sha256=d9oZzZVzAazdSqhHX3IdHV9bOChYMreOhmXaG64z8hE,1334
+financegy/config.py,sha256=0kiLrY4FI07_wvpQcBlgzeMNLmDwaBa2dHV9rKk9rVM,193
+financegy/cache/cache_manager.py,sha256=c-VW3tk2A-Z-hMrTN4d_OOB6Zse9r-hrAcNhpBY6Sjo,1840
+financegy/core/parser.py,sha256=tU6bFDVTW6ztKeDWQBL7RuxJGTIjeGuMk3SUF_lTWKY,18181
+financegy/core/request_handler.py,sha256=g0C0R-nvIvicAhxnCEAtTU8buVtzUn8725EERvBA6ZU,276
+financegy/helpers/safe_text.py,sha256=pskFh-ejjVAR8f_NBL5x3EwuBtd9OocAKN6ozqNDPhs,141
+financegy/helpers/to_float.py,sha256=PV0VCFE6KxWXa_5KBQv8eRDJuJ8UrmMtgzlSWDZSkL8,249
+financegy/modules/securities.py,sha256=_1f0-aZI7xWH5ndk5KSRVkqage3OpMbxaIod4W1xBy8,14687
+financegy/utils/utils.py,sha256=mqbjZ4em_a7rZyDgCjFswspEIL_WUPOXa8siAuxZuoY,1434
+financegy-2.0.dist-info/licenses/LICENSE,sha256=HGLhx0fI215whUzIvTFdFivB447d_IdIIIRncUCQaEs,1088
+financegy-2.0.dist-info/METADATA,sha256=x6PofU0FCiuMlzfUSdL58B7h11n-2_KVGt2uhvzsb4o,9674
+financegy-2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+financegy-2.0.dist-info/top_level.txt,sha256=TpdYDxtK61m5xnvvzbqnDVJ82gphEqxnXN_Ur8rjvxQ,10
+financegy-2.0.dist-info/RECORD,,

{financegy-1.3.dist-info → financegy-2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any