pfund-blocks 0.0.1__tar.gz

pfund_blocks-0.0.1/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.3
+Name: pfund-blocks
+Version: 0.0.1
+Summary: Building blocks for `pfund`
+Author: softwareentrepreneer
+Author-email: softwareentrepreneer <softwareentrepreneer+pfund-blocks@gmail.com>
+Requires-Dist: pydantic>=2.14.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+[pfund]: https://github.com/PFund-Software-Ltd/pfund
+
+# pfund-blocks
+Building blocks for [pfund]

pfund_blocks-0.0.1/README.md

@@ -0,0 +1,4 @@
+[pfund]: https://github.com/PFund-Software-Ltd/pfund
+
+# pfund-blocks
+Building blocks for [pfund]

pfund_blocks-0.0.1/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "pfund-blocks"
+version = "0.0.1"
+description = "Building blocks for `pfund`"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = ["pydantic>=2.14.0"]
+
+[[project.authors]]
+name = "softwareentrepreneer"
+email = "softwareentrepreneer+pfund-blocks@gmail.com"
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+exclude-newer = "14 days"
+
+[tool.uv.exclude-newer-package]
+uv_build = false
+pfund-kit = false
+
+[tool.uv.build-backend]
+module-name = "pfund_blocks"
+module-root = "src"

pfund_blocks-0.0.1/pyproject.toml.orig

@@ -0,0 +1,24 @@
+[project]
+name = "pfund-blocks"
+version = "0.0.1"
+description = "Building blocks for `pfund`"
+readme = "README.md"
+authors = [
+    { name = "softwareentrepreneer", email = "softwareentrepreneer+pfund-blocks@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "pydantic>=2.14.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+exclude-newer = "14 days"
+exclude-newer-package = { uv_build = false, pfund-kit = false }
+
+[tool.uv.build-backend]
+module-name = "pfund_blocks"
+module-root = "src"

pfund_blocks-0.0.1/src/pfund_blocks/entities/markets/__init__.py

@@ -0,0 +1,4 @@
+from pfund_blocks.entities.markets.market_base import BaseMarket
+
+
+__all__ = ["BaseMarket"]

pfund_blocks-0.0.1/src/pfund_blocks/entities/markets/market_base.py

@@ -0,0 +1,40 @@
+from decimal import Decimal
+from datetime import datetime, timedelta
+
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class BaseMarket(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    symbol: str
+    base_asset: str
+    quote_asset: str
+    asset_type: str
+    tick_size: Decimal | None = Field(
+        default=None, description="Tick size, minimum price increment"
+    )
+    lot_size: Decimal | None = Field(
+        default=None, description="Lot size, minimum quantity incrementc"
+    )
+    min_leverage: Decimal | None = Field(default=None, description="Minimum leverage")
+    max_leverage: Decimal | None = Field(default=None, description="Maximum leverage")
+    leverage_step: Decimal | None = Field(
+        default=None, description="Leverage step size"
+    )
+    min_price: Decimal | None = Field(default=None, description="Minimum price")
+    max_price: Decimal | None = Field(default=None, description="Maximum price")
+    min_quantity: Decimal | None = Field(
+        default=None, description="Minimum order quantity"
+    )
+    max_quantity: Decimal | None = Field(
+        default=None, description="Maximum order quantity"
+    )
+    listed_at: datetime | None = Field(
+        default=None, description="Date the market was listed"
+    )
+    expiration: datetime | None = Field(default=None, description="expiration date")
+    settle_currency: str | None = Field(default=None, description="Settlement currency")
+    funding_interval: timedelta | None = Field(
+        default=None, description="Funding interval"
+    )

pfund_blocks-0.0.1/src/pfund_blocks/entities/products/__init__.py

@@ -0,0 +1,13 @@
+from pfund_blocks.entities.products.product_factory import ProductFactory
+from pfund_blocks.entities.products.product_base import BaseProduct, ProductKey
+from pfund_blocks.entities.products.asset_type import AssetType
+from pfund_blocks.entities.products.product_basis import ProductBasis
+
+
+__all__ = [
+    "ProductFactory",
+    "BaseProduct",
+    "ProductKey",
+    "AssetType",
+    "ProductBasis",
+]

pfund_blocks-0.0.1/src/pfund_blocks/entities/products/asset_type.py

@@ -0,0 +1,137 @@
+from typing import Any
+
+from functools import cached_property
+
+from pydantic import BaseModel, ConfigDict, field_validator, model_validator
+
+from pfund_blocks.enums.asset_type import (
+    ASSET_TYPE_ALIASES,
+    AllAssetType,
+    AssetTypeModifier,
+    CryptoAssetType,
+    TraditionalAssetType,
+    PredictionMarketAssetType,
+)
+
+
+class AssetType(BaseModel):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True, frozen=True, ignored_types=(cached_property,)
+    )
+
+    value: str  # e.g. 'STOCK'/'STK', 'INVERSE-FUTURE'/'IFUT', 'CRYPTO' etc.
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_string(cls, data: Any) -> Any:
+        # allow a bare string (e.g. "PERP") to be used wherever an
+        # AssetType is expected, by treating it as the `value` field
+        if isinstance(data, str):
+            return {"value": data.upper()}
+        return data
+
+    @staticmethod
+    def _standardize_asset_type_string(asset_type_string: str) -> str:
+        """
+        Expand aliases (e.g. 'IPERP' -> 'INVERSE-PERPETUAL') into their canonical hyphenated form.
+        """
+        asset_types_and_modifiers = asset_type_string.split("-")
+        standardized_asset_types_and_modifiers = [
+            ASSET_TYPE_ALIASES.get(atm.upper(), atm)
+            for atm in asset_types_and_modifiers
+        ]
+        return "-".join(standardized_asset_types_and_modifiers)
+
+    @staticmethod
+    def _parse_asset_type_string_to_tuple(
+        asset_type_string: str,
+    ) -> tuple[AssetTypeModifier | AllAssetType, ...]:
+        """
+        Convert asset type string (e.g. 'INVERSE-FUTURE') to tuple of AssetTypeModifier and AssetType (e.g. (AssetTypeModifier.INVERSE, AssetType.FUTURE)).
+        """
+        asset_type_string = AssetType._standardize_asset_type_string(asset_type_string)
+        parsed: list[AssetTypeModifier | AllAssetType] = []
+        for atm in asset_type_string.split("-"):
+            if atm in AssetTypeModifier.__members__:
+                parsed.append(AssetTypeModifier[atm])
+            elif atm in AllAssetType.__members__:
+                parsed.append(AllAssetType[atm])
+            # NOTE: some aliases are not in AllAssetType, e.g. 'SPOT' only exists in CryptoAssetType.
+            # The sub-enums' values are AllAssetType members, so normalize to AllAssetType.
+            elif atm in TraditionalAssetType.__members__:
+                parsed.append(AllAssetType(TraditionalAssetType[atm]))
+            elif atm in CryptoAssetType.__members__:
+                parsed.append(AllAssetType(CryptoAssetType[atm]))
+            elif atm in PredictionMarketAssetType.__members__:
+                parsed.append(AllAssetType(PredictionMarketAssetType[atm]))
+            else:
+                raise ValueError(f"Invalid asset type: {atm}")
+        return tuple(parsed)
+
+    @field_validator("value", mode="after")
+    @classmethod
+    def _normalize(cls, v: str) -> str:
+        return "-".join(cls._parse_asset_type_string_to_tuple(v))
+
+    @cached_property
+    def as_tuple(self) -> tuple[AssetTypeModifier | AllAssetType, ...]:
+        return self._parse_asset_type_string_to_tuple(self.value)
+
+    def __eq__(self, other: Any):
+        if isinstance(other, str):
+            other_tuple = self._parse_asset_type_string_to_tuple(other)
+            return self.as_tuple == other_tuple
+        elif isinstance(other, AssetType):
+            return self.as_tuple == other.as_tuple
+        return False
+
+    def __hash__(self) -> int:
+        return hash(self.as_tuple)
+
+    def __contains__(self, item: Any):
+        return item in self.as_tuple
+
+    def __iter__(self):
+        return iter(self.as_tuple)
+
+    def __len__(self):
+        return len(self.as_tuple)
+
+    def __str__(self):
+        return self.value
+
+    def is_inverse(self) -> bool:
+        return AssetTypeModifier.INVERSE in self.as_tuple
+
+    def is_crypto(self) -> bool:
+        return AllAssetType.CRYPTO in self.as_tuple
+
+    def is_future(self) -> bool:
+        return AllAssetType.FUTURE in self.as_tuple
+
+    def is_perpetual(self) -> bool:
+        return AllAssetType.PERPETUAL in self.as_tuple
+
+    def is_option(self) -> bool:
+        return AllAssetType.OPTION in self.as_tuple
+
+    def is_stock(self) -> bool:
+        return AllAssetType.STOCK in self.as_tuple
+
+    def is_etf(self) -> bool:
+        return AllAssetType.ETF in self.as_tuple
+
+    def is_forex(self) -> bool:
+        return AllAssetType.FOREX in self.as_tuple
+
+    def is_bond(self) -> bool:
+        return AllAssetType.BOND in self.as_tuple
+
+    def is_mutual_fund(self) -> bool:
+        return AllAssetType.FUND in self.as_tuple
+
+    def is_commodity(self) -> bool:
+        return AllAssetType.CMDTY in self.as_tuple
+
+    def is_index(self) -> bool:
+        return AllAssetType.INDEX in self.as_tuple

pfund_blocks-0.0.1/src/pfund_blocks/entities/products/mixins/crypto.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+from pfund_blocks.entities.products.mixins.forex import ForexMixin
+
+
+class CryptoMixin(ForexMixin):
+    pass

pfund_blocks-0.0.1/src/pfund_blocks/entities/products/mixins/derivative.py

@@ -0,0 +1,25 @@
+# pyright: reportAttributeAccessIssue=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pfund_blocks.entities.products.product_base import BaseProduct
+
+from decimal import Decimal
+
+
+class DerivativeMixin:
+    underlying: str = ""
+    # TODO: information that requires data fetching or config loading
+    multiplier: Decimal | None = None
+
+    # contract_unit: str | None = None  # e.g. barrels
+    # notional: Decimal | None = None
+    # leverage: Decimal | None = None
+    # initial_margin: Decimal | None = None
+    # maintenance_margin: Decimal | None = None
+    # settlement_type: SettlementType
+
+    def __mixin_post_init__(self: DerivativeMixin | BaseProduct):
+        self.underlying = self.base_asset  # TODO: inaccurate

pfund_blocks-0.0.1/src/pfund_blocks/entities/products/mixins/etf.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pfund_blocks.entities.products.product_base import BaseProduct
+
+
+class ETFMixin:
+    def _create_symbol(self: BaseProduct) -> str:
+        return self.base_asset

pfund_blocks-0.0.1/src/pfund_blocks/entities/products/mixins/forex.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pfund_blocks.entities.products.product_base import BaseProduct
+
+
+class ForexMixin:
+    def _create_symbol(self: BaseProduct) -> str:
+        return self.base_asset + self.quote_asset

pfund_blocks-0.0.1/src/pfund_blocks/entities/products/mixins/future.py

@@ -0,0 +1,35 @@
+# pyright: reportAttributeAccessIssue=false, reportUninitializedInstanceVariable=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pfund_blocks.entities.products.product_base import BaseProduct
+
+from datetime import date
+
+from pfund_blocks.entities.products.mixins.derivative import DerivativeMixin
+
+
+class FutureMixin(DerivativeMixin):
+    expiration: date
+    contract_code: str = ""
+
+    def __mixin_post_init__(self):
+        super().__mixin_post_init__()
+        self.contract_code = self._derive_contract_code()
+
+    def _derive_contract_code(self):
+        from pfund_blocks.enums.month_code import FutureMonthCode
+
+        expiration_year, expiration_month, _ = str(self.expiration).split("-")
+        expiration_year = expiration_year[-2:]
+        month_code = [code.value for code in FutureMonthCode][int(expiration_month) - 1]
+        contract_code = month_code + expiration_year
+        return contract_code
+
+    def _create_symbol(self: FutureMixin | BaseProduct) -> str:
+        """
+        Creates default symbol e.g. ESZ23
+        """
+        return self.base_asset + self.contract_code

pfund_blocks-0.0.1/src/pfund_blocks/entities/products/mixins/index.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pfund_blocks.entities.products.product_base import BaseProduct
+
+
+class IndexMixin:
+    def _create_symbol(self: BaseProduct) -> str:
+        return self.base_asset

pfund_blocks-0.0.1/src/pfund_blocks/entities/products/mixins/inverse.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+
+# TODO
+class InverseMixin:
+    pass

pfund_blocks-0.0.1/src/pfund_blocks/entities/products/mixins/option.py

@@ -0,0 +1,43 @@
+# pyright: reportAttributeAccessIssue=false, reportUninitializedInstanceVariable=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pfund_blocks.entities.products.product_base import BaseProduct
+
+from datetime import date
+from decimal import Decimal
+
+from pydantic import Field, field_validator
+
+from pfund_blocks.entities.products.mixins.derivative import DerivativeMixin
+from pfund_blocks.enums.option_type import OptionType
+from pfund_blocks.utils import trim_trailing_zeros
+
+
+# TODO: add Greeks
+class OptionMixin(DerivativeMixin):
+    expiration: date
+    strike_price: Decimal = Field(ge=0.0)
+    option_type: OptionType
+
+    @field_validator("option_type", mode="before")
+    @classmethod
+    def _uppercase_option_type(cls, option_type: str) -> str:
+        return option_type.upper()
+
+    @field_validator("strike_price", mode="after")
+    @classmethod
+    def _remove_redundant_zeros(cls, strike_price: Decimal) -> Decimal:
+        return trim_trailing_zeros(strike_price)
+
+    def _create_symbol(self: OptionMixin | BaseProduct) -> str:
+        """
+        Creates default symbol e.g. TSLA241213C00075000 following OSI format (Option Symbology Initiative)
+        """
+        expiration = self.expiration.strftime("%y%m%d")  # convert expiration to yymmdd
+        num_of_digits = 8
+        strike_price = str(int(self.strike_price * 1000)).zfill(num_of_digits)
+        symbol = self.base_asset + expiration + self.option_type.value[0] + strike_price
+        return symbol

pfund_blocks-0.0.1/src/pfund_blocks/entities/products/mixins/perpetual.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typing_extensions import override
+
+if TYPE_CHECKING:
+    from pfund_blocks.entities.products.product_base import BaseProduct
+
+from pfund_blocks.entities.products.mixins.future import FutureMixin
+
+
+class PerpetualMixin(FutureMixin):
+    expiration: None = None
+    contract_code: None = None
+
+    @override  # override FutureMixin._derive_contract_code
+    def _derive_contract_code(self) -> None:
+        return None
+
+    @override  # override FutureMixin._create_symbol
+    def _create_symbol(self: FutureMixin | BaseProduct) -> str:
+        """
+        Creates default symbol e.g. ESZ23
+        """
+        return self.base_asset + "_" + self.quote_asset

pfund_blocks-0.0.1/src/pfund_blocks/entities/products/mixins/stock.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pfund_blocks.entities.products.product_base import BaseProduct
+
+
+class StockMixin:
+    def _create_symbol(self: StockMixin | BaseProduct) -> str:
+        return self.base_asset