quantification 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

quantification/core/trader/base_trader.py

@@ -0,0 +1,173 @@
+from tqdm import tqdm
+from typing import TypeVar, Generic, TYPE_CHECKING
+from datetime import date, timedelta, datetime
+
+from .query import Query
+from .report import AssetData, OrderResultData, PeriodData, PointData, BenchmarkData, ReportData
+from .portfolio import Portfolio
+from .collector import Collector
+from .base_order import Result, BaseOrder
+from .base_stage import BaseStage
+from ..asset.cash import RMB
+from ..data.field import Field
+
+from ..env import EnvGetter, Env
+from ..logger import logger
+
+if TYPE_CHECKING:
+    from ..data import BaseAPI
+    from ..asset import BaseBroker, BaseAsset
+    from ..strategy import BaseStrategy
+
+StrategyType = TypeVar("StrategyType", bound="BaseStrategy")
+
+
+class BaseTrader(Generic[StrategyType]):
+    def __init__(
+            self,
+            api: "BaseAPI",
+            init_portfolio: Portfolio,
+            start_date: date,
+            end_date: date,
+            padding: int,
+            stage: type[BaseStage],
+            strategy: StrategyType,
+            brokers: list[type["BaseBroker"]]
+    ):
+        self.api = api
+        self.start_date = start_date
+        self.end_date = end_date
+        self.stage = stage
+        self.strategy = strategy
+        self.portfolio = init_portfolio
+        self.brokers = [broker(api, start_date - timedelta(days=padding), end_date, stage) for broker in brokers]
+        self.query = Query(api, start_date - timedelta(days=padding), end_date)
+
+        self.collector = Collector()
+        self.env: Env | None = None
+        EnvGetter.getter = lambda: self.env
+
+    def match_broker(self, asset: "BaseAsset") -> "BaseBroker|None":
+        for candidate_broker in self.brokers:
+            if candidate_broker.matchable(asset):
+                return candidate_broker
+
+        return None
+
+    @property
+    def timeline(self):
+        current_date = self.start_date
+        while current_date <= self.end_date:
+            for current_stage in self.stage:
+                self.env = Env(date=current_date, time=current_stage.time)
+                self.collector.commence(current_date, current_stage, self.portfolio)
+                yield current_date, current_stage
+            current_date += timedelta(days=1)
+
+    def run(self):
+        for day, stage in self.timeline:
+            logger.trace(f"==========日期:{day}===阶段:{stage}==========")
+            params = {
+                "day": day,
+                "stage": stage,
+                "portfolio": self.portfolio,
+                "context": self.strategy.context,
+                "query": self.query,
+                "trader": self,
+                "strategy": self.strategy
+            }
+
+            hooks = self.strategy.triggered(**params)
+            logger.trace(f"触发的全部hooks:{hooks}")
+
+            for hook in hooks:
+                logger.trace(f"开始运行{hook}")
+                gen = hook(**params)
+                order: BaseOrder | None = None
+                result: Result | None = None
+
+                while True:
+                    try:
+                        order = gen.send(result) if order else next(gen)
+                        logger.trace(f"{hook}发出Order:{order}, 开始匹配Broker")
+
+                        assert isinstance(order, BaseOrder), f"只能yield Order, 实际为{type(order)}"
+
+                        broker = self.match_broker(order.asset)
+
+                        if not broker:
+                            logger.warning(f"{order}没有对应broker, 忽略该order")
+                            result = None
+                            continue
+
+                        logger.trace(f"{broker}开始处理:{order}")
+                        result = broker.execute_order(order)
+                        logger.trace(f"{broker}处理完成:{result}")
+                        self.handle_result(result)
+                    except StopIteration:
+                        logger.trace(f"运行结束{hook}")
+                        break
+
+    def handle_result(self, result: Result):
+        self.portfolio += result.brought
+        self.portfolio -= result.sold
+        self.collector.collect(result, self.portfolio)
+        logger.trace(f"资产增加{result.brought}, 减少{result.sold}")
+
+    def liquidate(self, asset: "BaseAsset", day: date, stage: "BaseStage") -> int:
+        if isinstance(asset, RMB):
+            return asset.amount
+
+        if (broker := self.match_broker(asset)) is None:
+            return -1
+
+        return broker.liquidate_asset(asset, day, stage)
+
+    def report(self, title: str, description: str, benchmark: str) -> ReportData:
+        periods_data = []
+
+        for shard in tqdm(self.collector.shards, "生成报告"):
+            portfolios_data: list[AssetData] = []
+            total_liquidating_value = 0
+            for asset in shard.portfolio:
+                liquidating_value = self.liquidate(asset, shard.day, shard.stage)
+                total_liquidating_value += liquidating_value
+                portfolios_data.append(AssetData.from_asset(asset, liquidating_value=liquidating_value))
+
+            datetime_str = datetime.combine(shard.day, shard.stage.time).isoformat()
+            periods_data.append(PeriodData(
+                datetime=datetime_str,
+                liquidating_value=total_liquidating_value,
+                logs=logger.records.get(datetime_str, []),
+                portfolios=portfolios_data,
+                transactions=[OrderResultData.from_result(result) for result in shard.results]
+            ))
+
+        benchmark_points = [
+            PointData(
+                datetime=index.to_pydatetime().isoformat(),
+                value=row[Field.IN_收盘点位]
+            ) for index, row in self.api.query(
+                start_date=self.start_date,
+                end_date=self.end_date,
+                fields=[Field.IN_收盘点位],
+                index=benchmark,
+            ).iterrows()
+        ]
+
+        return ReportData(
+            title=title,
+            description=description,
+            start_date=self.start_date.isoformat(),
+            end_date=self.end_date.isoformat(),
+            init_value=periods_data[0].liquidating_value,
+            periods=periods_data,
+            benchmark=BenchmarkData(
+                name=benchmark,
+                init_value=benchmark_points[0].value,
+                points=benchmark_points
+            )
+        )
+
+
+__all__ = ["BaseTrader"]

quantification/core/trader/collector.py

@@ -0,0 +1,47 @@
+from datetime import date
+
+from .portfolio import Portfolio
+from .base_order import Result
+from .base_stage import BaseStage
+
+
+class Shard:
+    def __init__(
+            self,
+            day: date,
+            stage: BaseStage,
+            portfolio: Portfolio,
+    ):
+        self.day = day
+        self.stage = stage
+        self.portfolio = portfolio
+        self.results: list[Result] = []
+
+    def collect(self, result: Result):
+        self.results.append(result)
+
+    def __repr__(self):
+        return (
+            f"================{self.day} {self.stage.time}================\n"
+            f"Portfolio: {self.portfolio}\n"
+            f"Results: {self.results}\n"
+        )
+
+    __str__ = __repr__
+
+
+class Collector:
+    def __init__(self):
+        self.shards: list[Shard] = []
+
+    def commence(
+            self,
+            day: date,
+            stage: BaseStage,
+            portfolio: Portfolio,
+    ):
+        self.shards.append(Shard(day, stage, portfolio.copy))
+
+    def collect(self, result: Result, portfolio: Portfolio):
+        self.shards[-1].collect(result)
+        self.shards[-1].portfolio = portfolio.copy

quantification/core/trader/order.py

@@ -0,0 +1,23 @@
+from typing import TYPE_CHECKING, Literal
+
+from .base_order import BaseOrder
+
+if TYPE_CHECKING:
+    from ..asset import Stock
+
+
+class StockOrder(BaseOrder["Stock"]):
+    def __init__(self, asset: "Stock", category: Literal["buy"] | Literal["sell"]):
+        super().__init__(asset, category)
+
+    @property
+    def extra(self):
+        return {}
+
+    def __repr__(self):
+        return f"<股票交易指令 {self.category} {self.asset}>"
+
+    __str__ = __repr__
+
+
+__all__ = ["StockOrder"]

quantification/core/trader/portfolio.py

@@ -0,0 +1,72 @@
+from typing import TypeVar
+
+from ..asset.base_asset import BaseAsset
+
+AssetType = TypeVar('AssetType', bound=BaseAsset)
+
+
+class Portfolio:
+    def __init__(self, *args: BaseAsset):
+        self.assets: list[BaseAsset] = list(args)
+
+    def add(self, asset: BaseAsset):
+        for index in range(len(self.assets)):
+            if self.assets[index] != asset:
+                continue
+
+            self.assets[index] += asset
+            break
+        else:
+            self.assets.append(asset)
+
+    def sub(self, asset: BaseAsset):
+        for index in range(len(self.assets)):
+            if self.assets[index] != asset:
+                continue
+
+            self.assets[index] -= asset
+            break
+        else:
+            raise IndexError(f"{self}没有资产{asset}")
+
+        self.assets = [i for i in self.assets if not (i.is_empty and i.is_closeable)]
+
+    def __add__(self, other: BaseAsset | list[BaseAsset]):
+        if isinstance(other, BaseAsset):
+            self.add(other)
+
+        if isinstance(other, list):
+            for asset in other:
+                assert isinstance(asset, BaseAsset), f"只允许添加资产, 实际为{type(asset)}"
+                self.add(asset)
+
+        return self
+
+    def __sub__(self, other: BaseAsset | list[BaseAsset]):
+        if isinstance(other, BaseAsset):
+            self.sub(other)
+
+        if isinstance(other, list):
+            for asset in other:
+                assert isinstance(asset, BaseAsset), f"只允许添加资产, 实际为{type(asset)}"
+                self.sub(asset)
+
+        return self
+
+    def __getitem__(self, item: type[AssetType]) -> list[AssetType]:
+        return [i for i in self.copy.assets if isinstance(i, item)]
+
+    def __iter__(self):
+        return iter(self.copy.assets)
+
+    @property
+    def copy(self) -> "Portfolio":
+        return Portfolio(*[asset.copy for asset in self.assets])
+
+    def __repr__(self):
+        return f"资产: {self.assets}"
+
+    __str__ = __repr__
+
+
+__all__ = ["Portfolio"]

quantification/core/trader/query.py

@@ -0,0 +1,29 @@
+from typing import TYPE_CHECKING
+from datetime import date, datetime
+
+from ..env import EnvGetter
+
+if TYPE_CHECKING:
+    from ..data import BaseAPI
+
+
+class Query(EnvGetter):
+    def __init__(self, api: "BaseAPI", start_date: date, end_date: date):
+        super().__init__()
+
+        self.api = api
+        self.start_date = start_date
+        self.end_date = end_date
+
+    def __call__(self, **kwargs):
+        assert self.env is not None, "无法获取env"
+
+        params = {
+            "start_date": self.start_date,
+            "end_date": self.end_date,
+        }
+        params.update(kwargs)
+        return self.api.query(**params).on(datetime.combine(self.env.date, self.env.time))
+
+
+__all__ = ['Query']

quantification/core/trader/report.py

@@ -0,0 +1,76 @@
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+
+from ..logger import Record
+
+if TYPE_CHECKING:
+    from .base_order import Result
+    from ..asset import BaseAsset
+
+
+class AssetData(BaseModel):
+    type: str
+    name: str
+    amount: float
+    extra: dict
+
+    @classmethod
+    def from_asset(cls, asset: "BaseAsset", **kwargs) -> "AssetData":
+        return cls(
+            type=asset.type(),
+            name=asset.name(),
+            amount=asset.amount,
+            extra={**asset.extra, **kwargs}
+        )
+
+
+class OrderResultData(BaseModel):
+    order_type: str
+    order_category: str
+    order_asset: AssetData
+    order_extra: dict
+    result_brought: list[AssetData]
+    result_sold: list[AssetData]
+
+    @classmethod
+    def from_result(cls, result: "Result", **kwargs) -> "OrderResultData":
+        return cls(
+            order_type=result.order.type(),
+            order_asset=AssetData.from_asset(result.order.asset),
+            order_category=result.order.category,
+            order_extra={**result.order.extra, **kwargs},
+            result_brought=[AssetData.from_asset(i) for i in result.brought],
+            result_sold=[AssetData.from_asset(i) for i in result.sold],
+        )
+
+
+class PeriodData(BaseModel):
+    datetime: str
+    liquidating_value: float
+
+    logs: list[Record]
+    portfolios: list[AssetData]
+    transactions: list[OrderResultData]
+
+
+class PointData(BaseModel):
+    datetime: str
+    value: float
+
+
+class BenchmarkData(BaseModel):
+    name: str
+    init_value: float
+    points: list[PointData]
+
+
+class ReportData(BaseModel):
+    title: str
+    description: str
+    start_date: str
+    end_date: str
+    init_value: float
+
+    benchmark: BenchmarkData
+    periods: list[PeriodData]

quantification/core/util.py

@@ -0,0 +1,181 @@
+import types
+import inspect
+import functools
+from typing import Callable, Any
+
+from pydantic import ValidationError, create_model, ConfigDict
+from pydantic_core import PydanticUndefined
+
+
+def to_str(x: Callable[..., Any]) -> str:
+    """Convert a callable object to a descriptive string representation.
+
+    Args:
+        x: Any callable object (function, lambda, partial, class, method, etc.)
+
+    Returns:
+        A string representation of the callable.
+    """
+    # 1. Handle functools.partial objects
+    if isinstance(x, functools.partial):
+        func_str = to_str(x.func)
+        args = [repr(a) for a in x.args]
+        keywords = [f"{k}={repr(v)}" for k, v in x.keywords.items()]
+        all_args = ", ".join(args + keywords)
+        return f"functools.partial({func_str}, {all_args})"
+
+    # 2. Handle classes (since classes are callable)
+    if inspect.isclass(x):
+        return f"{x.__module__}.{x.__qualname__}"
+
+    # 3. Handle bound methods (instance methods and class methods)
+    if isinstance(x, (types.MethodType, types.BuiltinMethodType)):
+        method_name = x.__name__
+        owner = x.__self__
+
+        if inspect.isclass(owner):
+            owner_str = owner.__qualname__
+            return f"<bound method {owner_str}.{method_name}>"
+
+        class_name = owner.__class__.__qualname__
+        return f"<bound method {class_name}.{method_name} of {repr(owner)}>"
+
+    if isinstance(x, (types.FunctionType, types.BuiltinFunctionType)):
+        module = x.__module__
+        qualname = x.__qualname__
+
+        if qualname == '<lambda>':
+            try:
+                source = inspect.getsource(x).strip()
+                if '\n' in source:
+                    return f"<lambda at {module}:{x.__code__.co_firstlineno}>"
+                return source
+            except (OSError, TypeError):
+                return "<lambda>"
+
+        return f"{module}.{qualname}"
+
+    # Fallback: Use standard string representation
+    return str(x)
+
+
+def get_function_location(func) -> str:
+    """获取函数的定义位置（文件路径和行号）"""
+    try:
+        # 尝试获取函数的源文件和行号
+        source_file = inspect.getsourcefile(func)
+        lines, start_line = inspect.getsourcelines(func)
+        end_line = start_line + len(lines) - 1
+
+        # 如果是lambda函数，使用特殊格式
+        if func.__name__ == '<lambda>':
+            return f"lambda at {source_file}:{start_line}"
+
+        return f"{source_file}:{start_line}-{end_line}"
+    except Exception:
+        # 如果无法获取位置信息，返回默认值
+        return "<unknown location>"
+
+
+def format_arg_type(value) -> str:
+    """格式化参数类型信息，特别处理类对象"""
+    if inspect.isclass(value):
+        # 对于类对象，显示类名而不是元类
+        return f"<class '{value.__module__}.{value.__qualname__}'>"
+    return str(type(value))
+
+
+def format_annotations(params) -> str:
+    """格式化参数注解信息"""
+    lines = []
+    for name, param in params.items():
+        # 跳过可变关键字参数
+        if param.kind == inspect.Parameter.VAR_KEYWORD:
+            continue
+
+        # 获取类型注解
+        ann = param.annotation
+        ann_str = ann.__name__ if ann is not param.empty else "Any"
+
+        # 添加默认值信息
+        default = ""
+        if param.default is not param.empty:
+            default = f" (默认值: {repr(param.default)})"
+
+        # 添加参数类型标记
+        kind = ""
+        if param.kind == inspect.Parameter.KEYWORD_ONLY:
+            kind = " [keyword-only]"
+        elif param.kind == inspect.Parameter.POSITIONAL_ONLY:
+            kind = " [positional-only]"
+
+        lines.append(f"  - {name}: {ann_str}{default}{kind}")
+    return "\n".join(lines)
+
+
+def inject(func, **kwargs) -> Any:
+    sig = inspect.signature(func)
+    params = sig.parameters
+
+    model_fields = {}
+    for name, param in params.items():
+        if param.kind == inspect.Parameter.VAR_KEYWORD:
+            continue
+
+        annotation = param.annotation
+        if annotation is param.empty:
+            annotation = Any
+
+        default = PydanticUndefined
+        if param.default is not param.empty:
+            default = param.default
+
+        model_fields[name] = (annotation, default)
+
+    func_name = to_str(func)
+
+    model = create_model(
+        f"{func_name}_Params",
+        __config__=ConfigDict(
+            extra="allow",
+            arbitrary_types_allowed=True,
+            coerce_numbers_to_str=True
+        ),
+        **model_fields
+    )
+
+    try:
+        validated = model(**kwargs)
+    except ValidationError as e:
+        errors = []
+        for error in e.errors():
+            loc = ".".join(map(str, error["loc"]))
+            expected_type = " | ".join(error.get("ctx", {}).get("expected", ["未知类型"]))
+            actual_type = type(kwargs.get(loc, "<missing>")).__name__
+            msg = f"无法将类型 {actual_type} 转换为函数定义的类型 {expected_type}"
+            input_value = error.get("input", "<missing>")
+
+            errors.append(f"  - {loc}: {msg} (输入值: {input_value})")
+
+        arg_types = "\n".join([
+            f"  - {k}: {format_arg_type(v)}"
+            for k, v in kwargs.items()
+        ])
+
+        raise TypeError(
+            f"🚫 参数类型与可用参数不兼容，且强制转换失败，请检查 {func_name} 的定义:\n"
+            f"📋 定义的参数:\n{format_annotations(params)}\n"
+            f"📤 可用的全部参数(正确标准):\n{arg_types}\n"
+            f"❌ 参数类型不匹配且转换失败:\n{"\n".join(errors)}\n"
+            f"📍 函数定义位置: {get_function_location(func)}\n"
+        )
+
+    validated_data = validated.model_dump()
+
+    if any((name for name, param in params.items() if param.kind == inspect.Parameter.VAR_KEYWORD)):
+        return func(**validated_data)
+
+    return func(**{p.name: validated_data[p.name] for p in params.values()})
+
+
+__all__ = ["inject"]

quantification/default/__init__.py

@@ -0,0 +1,5 @@
+from .use import *
+from .stage import *
+from .trader import *
+from .trigger import *
+from .strategy import *

quantification/default/stage/__init__.py

@@ -0,0 +1 @@
+from .cn_stock import StockStageCN

quantification/default/stage/cn_stock.py

@@ -0,0 +1,23 @@
+from enum import auto
+from datetime import time
+
+from quantification import BaseStage
+
+
+class StockStageCN(BaseStage):
+    盘前 = auto()
+    开盘 = auto()
+    收盘 = auto()
+    盘后 = auto()
+
+    @property
+    def time(self) -> time:
+        return {
+            StockStageCN.盘前: time(0, 0),
+            StockStageCN.开盘: time(9, 30),
+            StockStageCN.收盘: time(15, 0),
+            StockStageCN.盘后: time(23, 59),
+        }[self]
+
+
+__all__ = ['StockStageCN']

quantification/default/strategy/__init__.py

@@ -0,0 +1 @@
+from .simple import *

quantification/default/strategy/simple/__init__.py

@@ -0,0 +1 @@
+from .strategy import SimpleStrategy

quantification/default/strategy/simple/strategy.py

@@ -0,0 +1,8 @@
+from quantification import BaseStrategy
+
+
+class SimpleStrategy(BaseStrategy):
+    ...
+
+
+__all__ = ['SimpleStrategy']

quantification/default/trader/__init__.py

@@ -0,0 +1,2 @@
+from .simple import *
+from .a_factor import *

quantification/default/trader/a_factor/__init__.py

@@ -0,0 +1 @@
+from .trader import AFactorTrader

quantification/default/trader/a_factor/trader.py

@@ -0,0 +1,27 @@
+from quantification import (
+    RMB,
+    Stock,
+    Portfolio,
+    BaseTrader,
+    StockBrokerCN
+)
+
+
+class AFactorTrader(BaseTrader):
+    def __init__(
+            self,
+            api,
+            start_date,
+            end_date,
+            stage,
+            strategy,
+            stocks: list[type[Stock]],
+            init_cash: float = 100_000,
+            padding: int = 0
+    ):
+        super().__init__(api, Portfolio(RMB(init_cash)), start_date, end_date, padding, stage, strategy,
+                         [StockBrokerCN])
+        self.stocks = stocks
+
+
+__all__ = ["AFactorTrader"]

quantification/default/trader/simple/__init__.py

@@ -0,0 +1 @@
+from .trader import SimpleTrader