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

financegy/__init__.py

@@ -23,6 +23,13 @@ from financegy.modules.securities import (
     get_historical_trades,
 )
 
+from financegy.modules.portfolio import (
+    calculate_position_value,
+    calculate_position_return,
+    calculate_position_return_percent,
+    calculate_portfolio_summary,
+)
+
 __all__ = [
     "get_securities",
     "get_security_by_symbol",
@@ -41,6 +48,10 @@ __all__ = [
     "search_securities",
     "get_trades_for_year",
     "get_historical_trades",
+    "calculate_position_value",
+    "calculate_position_return",
+    "calculate_position_return_percent",
+    "calculate_portfolio_summary",
     "clear_cache",
     "save_to_csv",
     "to_dataframe",

financegy/config.py

@@ -1,4 +1,4 @@
-__version__ = "2.0"
+__version__ = "3.0"
 
 BASE_URL = "https://guyanastockexchangeinc.com"
 HEADERS = {

financegy/helpers/to_float.py

@@ -1,6 +1,3 @@
-# Function to convert GSE price string to float type
-
-
 def to_float(value):
     if value is None:
         return None

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: financegy
-Version: 2.0
+Version: 3.0
 Summary: Unofficial Python library for accessing GSE (Guyana Stock Exchange) financial data
 Author-email: Ezra Minty <ezranminty@gmail.com>
 License: MIT

financegy-3.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+financegy/__init__.py,sha256=SY0WDJGydD-9fU9i3Yff2WI8mrreGfFy22XSlSEPlJI,1664
+financegy/config.py,sha256=lAuUzlFaa7qQ4CN2LVHRQ93LQ7jbhaC95Voz6PpGh_k,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=VVE3fkHzIE2un6zD50au_U2b_Luh13p3-T84fxEE6Xo,191
+financegy/modules/portfolio.py,sha256=HFWw1FenJ_pABQhF7OlpP6OXuLCiyQBmwyXLrj-g6WQ,5483
+financegy/modules/securities.py,sha256=_1f0-aZI7xWH5ndk5KSRVkqage3OpMbxaIod4W1xBy8,14687
+financegy/utils/utils.py,sha256=mqbjZ4em_a7rZyDgCjFswspEIL_WUPOXa8siAuxZuoY,1434
+financegy-3.0.dist-info/licenses/LICENSE,sha256=HGLhx0fI215whUzIvTFdFivB447d_IdIIIRncUCQaEs,1088
+financegy-3.0.dist-info/METADATA,sha256=XwV5KpXYnrTusYQKWzHnFwgD4KFNWWggmFwBD1kaKzM,9674
+financegy-3.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+financegy-3.0.dist-info/top_level.txt,sha256=TpdYDxtK61m5xnvvzbqnDVJ82gphEqxnXN_Ur8rjvxQ,10
+financegy-3.0.dist-info/RECORD,,

financegy-2.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-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,,