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

financegy/modules/portfolio.py

@@ -0,0 +1,157 @@
+from decimal import Decimal, InvalidOperation, ROUND_HALF_UP
+from financegy.modules import securities
+
+
+def _to_decimal(value, field_name="value"):
+    """
+    Convert strings/numbers to Decimal safely.
+    Handles commas like "3,000.0".
+    """
+    try:
+        clean_value = str(value).replace(",", "")
+        return Decimal(clean_value)
+    except (InvalidOperation, TypeError) as e:
+        raise ValueError(f"Invalid {field_name}: {value}") from e
+
+
+def calculate_position_value(symbol: str, shares):
+    try:
+        shares = _to_decimal(shares, "shares")
+        if shares <= 0:
+            raise ValueError("Shares must be greater than zero")
+
+        last_trade = securities.get_recent_trade(symbol)
+        last_trade_price = _to_decimal(
+            last_trade.get("last_trade_price"), "last_trade_price"
+        )
+
+        position_value = last_trade_price * shares
+
+        return {
+            "last_trade": last_trade,
+            "position_value": str(position_value),
+        }
+
+    except (ValueError, KeyError, TypeError) as e:
+        raise ValueError(f"[calculate_position_value] Invalid input or data: {e}")
+
+
+def calculate_position_return(symbol: str, shares, purchase_price):
+    try:
+        shares = _to_decimal(shares, "shares")
+        purchase_price = _to_decimal(purchase_price, "purchase_price")
+
+        if shares <= 0:
+            raise ValueError("Shares must be greater than zero")
+        if purchase_price <= 0:
+            raise ValueError("Purchase price must be greater than zero")
+
+        last_trade = securities.get_recent_trade(symbol)
+        last_trade_price = _to_decimal(
+            last_trade.get("last_trade_price"), "last_trade_price"
+        )
+
+        position_return = (last_trade_price - purchase_price) * shares
+
+        return {
+            "last_trade": last_trade,
+            "position_return": str(position_return),
+        }
+
+    except (ValueError, KeyError, TypeError) as e:
+        raise ValueError(f"[calculate_position_return] Invalid input or data: {e}")
+
+
+def calculate_position_return_percent(symbol, shares, purchase_price):
+    try:
+        shares = _to_decimal(shares, "shares")
+        purchase_price = _to_decimal(purchase_price, "purchase_price")
+
+        if shares <= 0:
+            raise ValueError("Shares must be greater than zero")
+        if purchase_price <= 0:
+            raise ValueError("Purchase price must be greater than zero")
+
+        last_trade = securities.get_recent_trade(symbol)
+        last_trade_price = _to_decimal(
+            last_trade.get("last_trade_price"), "last_trade_price"
+        )
+
+        return_percent = (
+            (last_trade_price - purchase_price) / purchase_price
+        ) * Decimal("100")
+
+        return {
+            "last_trade": last_trade,
+            "position_return_percent": str(round(return_percent, 2)),
+        }
+
+    except (ValueError, KeyError, TypeError) as e:
+        raise ValueError(
+            f"[calculate_position_return_percent] Invalid input or data: {e}"
+        )
+
+
+def calculate_portfolio_summary(positions: list[dict]):
+    try:
+        total_invested = Decimal("0")
+        total_value = Decimal("0")
+        detailed_positions = []
+
+        for pos in positions:
+            symbol = pos["symbol"]
+            shares = _to_decimal(pos.get("shares"), f"shares for {symbol}")
+            purchase_price = _to_decimal(
+                pos.get("purchase_price"), f"purchase_price for {symbol}"
+            )
+
+            if shares <= 0:
+                raise ValueError(f"Invalid shares for {symbol}")
+            if purchase_price <= 0:
+                raise ValueError(f"Invalid purchase price for {symbol}")
+
+            last_trade = securities.get_recent_trade(symbol)
+            last_trade_price = _to_decimal(
+                last_trade.get("last_trade_price"), f"last_trade_price for {symbol}"
+            )
+
+            invested = shares * purchase_price
+            current_value = shares * last_trade_price
+            gain_loss = current_value - invested
+
+            total_invested += invested
+            total_value += current_value
+
+            detailed_positions.append(
+                {
+                    "symbol": symbol,
+                    "shares": str(shares),
+                    "purchase_price": str(purchase_price),
+                    "last_trade_price": str(last_trade_price),
+                    "invested": str(invested),
+                    "current_value": str(current_value),
+                    "gain_loss": str(gain_loss),
+                }
+            )
+
+        total_gain_loss = total_value - total_invested
+
+        if total_invested != 0:
+            return_percent = (
+                total_gain_loss / total_invested * Decimal("100")
+            ).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+        else:
+            return_percent = Decimal("0.00")
+
+        return {
+            "summary": {
+                "total_invested": str(total_invested),
+                "current_value": str(total_value),
+                "total_gain_loss": str(total_gain_loss),
+                "return_percent": str(return_percent),
+            },
+            "positions": detailed_positions,
+        }
+
+    except (ValueError, KeyError, TypeError) as e:
+        raise ValueError(f"[calculate_portfolio_summary] Invalid portfolio data: {e}")

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

@@ -1,6 +1,7 @@
 import os
 import pandas as pd
 
+
 def to_dataframe(data: dict | list[dict]):
     """Output as Dataframe"""
 
@@ -8,13 +9,16 @@ def to_dataframe(data: dict | list[dict]):
         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]      
+        data = [data]
 
     return pd.DataFrame(data)
 
-def save_to_csv(data, filename: str = "output.csv", path: str = None):
+
+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:
@@ -28,13 +32,20 @@ def save_to_csv(data, filename: str = "output.csv", path: str = None):
 
     df.to_csv(full_path, index=False)
 
-    print(f"Saved CSV to: {full_path}")
+    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):
+
+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:
@@ -43,10 +54,8 @@ def save_to_excel(data: dict | list[dict], filename: str = "output.xlsx", 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
-
 
+    if not silent:
+        print(f"\nSaved Excel Document to: {full_path}")
 
+    return True