powerquant-cli 0.2.6__tar.gz

powerquant_cli-0.2.6/.env.example

@@ -0,0 +1,7 @@
+# CLI uses HTTP endpoints and local workspace; no database credentials.
+PQ_QUANT_URL=http://localhost:8001/api/v1
+PQ_QUANT_TOKEN=
+# 默认 ~/.powerquant/workspace.duckdb；需要覆盖时设置 PQ_LOCAL_DATABASE
+# PQ_LOCAL_DATABASE=/path/to/workspace.duckdb
+MARKET_BASE_URL=http://localhost:8002/api/v1
+MARKET_API_TOKEN=

powerquant_cli-0.2.6/.gitignore

@@ -0,0 +1,22 @@
+# 运行时日志与文件锁（应用启动时自动创建 logs/ 目录）
+logs/
+
+# 本地环境配置（含数据库连接串、密钥等），只提交 .env.example
+.env
+.env.*
+!.env.example
+
+# Python 运行时产物
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.cache/
+.venv/
+dist/
+build/
+tasks/draft/TASK-20260906-1704-akshare-minute-ingestion/samples/
+tasks/approved/TASK-20260906-2119-real-market-integration-review-fixes/samples/
+
+node_modules/
+apps/quant_frontend/public/data-dictionary.md

powerquant_cli-0.2.6/LICENSE

@@ -0,0 +1,36 @@
+Power Quant Proprietary License
+Copyright (c) 2026 Power Quant contributors. All rights reserved.
+
+1. Permission to use
+You may install and use this software, inspect its source code, and make
+local copies and modifications for your own use. Permitted uses include
+connecting to Power Quant services and performing research and backtesting.
+Commercial use of the software is permitted under these same conditions.
+
+2. Redistribution and resale
+Unless you have prior written authorization from the copyright holders,
+you may not redistribute, sublicense, publish, or resell this software or
+its modified versions, including as part of another software product.
+The copyright holders may distribute the software through their designated
+release channels, including PyPI. This does not authorize recipients to
+redistribute it.
+
+3. Service access and results
+This license does not grant access to Power Quant services or market data.
+Service access requires a valid access token and remains subject to the
+applicable service and data terms. These redistribution restrictions apply
+to the software, not to your own research code or results; rights in market
+data remain governed by the applicable data terms.
+
+4. Third-party components
+Third-party components retain their own licenses and copyright notices.
+The restrictions above do not override rights granted by those licenses.
+In particular, components identified as derived from vn.py remain subject
+to the accompanying MIT license. Separately installed dependencies are
+subject to their own licenses.
+
+5. Disclaimer
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+AND NON-INFRINGEMENT. TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE
+COPYRIGHT HOLDERS ARE NOT LIABLE FOR DAMAGES ARISING FROM ITS USE.

powerquant_cli-0.2.6/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: powerquant-cli
+Version: 0.2.6
+Summary: Power Quant local research CLI
+Project-URL: Repository, https://github.com/Kepler452Byte/power-quant
+License-Expression: LicenseRef-PowerQuant-Proprietary AND MIT
+License-File: LICENSE
+License-File: licenses/LICENSE.vnpy
+Requires-Python: >=3.12
+Requires-Dist: duckdb<2,>=1.4
+Requires-Dist: filelock<4,>=3.20
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: numpy<3,>=2
+Requires-Dist: pandas<4,>=3
+Requires-Dist: polars<2,>=1.36
+Requires-Dist: pydantic<3,>=2.5
+Requires-Dist: scipy<2,>=1.17
+Requires-Dist: typer>=0.27.2
+Requires-Dist: tzdata>=2026.3
+Description-Content-Type: text/markdown
+
+# Power Quant CLI
+
+本地行情准备、因子计算、选股、研究及策略回测；结果保存在本地 DuckDB 和文件。
+
+## 安装
+
+推荐通过 uv 安装独立工具环境：
+
+```sh
+uv tool install --python 3.12 powerquant-cli
+pq --help
+uv tool upgrade powerquant-cli
+```
+
+也支持在 Python 3.12+ 环境通过 `pip install powerquant-cli` 安装。
+
+## 接入行情
+
+向管理员获取行情读取密钥，无需注册账户。服务当前仅在 LAN/WireGuard 内可达。
+
+```sh
+export MARKET_BASE_URL='http://服务器地址/market/api/v1'
+export MARKET_API_TOKEN='管理员提供的行情密钥'
+pq examples --directory powerquant-examples
+cd powerquant-examples/selection
+pq data prepare --config prepare.json
+```
+
+PowerShell 使用 `$env:MARKET_BASE_URL="..."` 与 `$env:MARKET_API_TOKEN="..."`。
+
+按实际覆盖调整 prepare.json 的股票和日期，将返回 manifest_path 写入 compute.json、select.json；按示例 README 执行 compute、select 和 backtest。不同使用目的的快照须分别通过完整性检查。
+
+密钥到期或撤销后在线准备会失败，已下载快照仍可离线使用。行情密钥不用于定义发布；发布定义另使用 PQ_QUANT_URL/PQ_QUANT_TOKEN。默认本地目录为 ~/.powerquant。
+
+## Python
+
+公开请求模型与调用入口位于 quant_cli.api，与 CLI 使用同一应用服务。
+
+## 使用许可
+
+自有代码采用随包附带的专有许可证：允许安装、查看源码、为自用进行修改，以及商业使用；未经书面授权不得再分发或转售本软件及其修改版本。第三方组件保留各自许可证。行情访问仍需要有效 Token；本许可证不授予行情数据的使用或再分发权。

powerquant_cli-0.2.6/README.md

@@ -0,0 +1,41 @@
+# Power Quant CLI
+
+本地行情准备、因子计算、选股、研究及策略回测；结果保存在本地 DuckDB 和文件。
+
+## 安装
+
+推荐通过 uv 安装独立工具环境：
+
+```sh
+uv tool install --python 3.12 powerquant-cli
+pq --help
+uv tool upgrade powerquant-cli
+```
+
+也支持在 Python 3.12+ 环境通过 `pip install powerquant-cli` 安装。
+
+## 接入行情
+
+向管理员获取行情读取密钥，无需注册账户。服务当前仅在 LAN/WireGuard 内可达。
+
+```sh
+export MARKET_BASE_URL='http://服务器地址/market/api/v1'
+export MARKET_API_TOKEN='管理员提供的行情密钥'
+pq examples --directory powerquant-examples
+cd powerquant-examples/selection
+pq data prepare --config prepare.json
+```
+
+PowerShell 使用 `$env:MARKET_BASE_URL="..."` 与 `$env:MARKET_API_TOKEN="..."`。
+
+按实际覆盖调整 prepare.json 的股票和日期，将返回 manifest_path 写入 compute.json、select.json；按示例 README 执行 compute、select 和 backtest。不同使用目的的快照须分别通过完整性检查。
+
+密钥到期或撤销后在线准备会失败，已下载快照仍可离线使用。行情密钥不用于定义发布；发布定义另使用 PQ_QUANT_URL/PQ_QUANT_TOKEN。默认本地目录为 ~/.powerquant。
+
+## Python
+
+公开请求模型与调用入口位于 quant_cli.api，与 CLI 使用同一应用服务。
+
+## 使用许可
+
+自有代码采用随包附带的专有许可证：允许安装、查看源码、为自用进行修改，以及商业使用；未经书面授权不得再分发或转售本软件及其修改版本。第三方组件保留各自许可证。行情访问仍需要有效 Token；本许可证不授予行情数据的使用或再分发权。

powerquant_cli-0.2.6/bundled/pqdata/__init__.py

@@ -0,0 +1,6 @@
+"""Power Quant 行情服务的独立 Python 客户端。"""
+
+from pqdata.client import MarketClient
+from pqdata.exceptions import MarketAPIError, MarketProtocolError
+
+__all__ = ["MarketAPIError", "MarketClient", "MarketProtocolError"]

powerquant_cli-0.2.6/bundled/pqdata/client.py

@@ -0,0 +1,389 @@
+"""有界、强类型行情客户端；不引入 ORM、供应商 SDK 或应用配置。"""
+
+import asyncio
+from collections.abc import AsyncIterator
+from datetime import date, datetime
+from hashlib import sha256
+from types import TracebackType
+from typing import Any, Self
+from urllib.parse import quote
+
+import httpx
+from pydantic import TypeAdapter, ValidationError
+
+from pqdata.exceptions import MarketAPIError, MarketProtocolError
+from pqdata.schema.adjustment_schema import AdjustedBarSeries, BarViewRequest
+from pqdata.schema.bar_content_schema import BarContent
+from pqdata.schema.bar_schema import BarFrequency, BarPage, BarQuery, BarResponse
+from pqdata.schema.history_schema import HistoryFacts, HistoryFactsQuery
+from pqdata.schema.pit_daily_window import PITDailyWindow
+from pqdata.schema.query_schema import (
+    BarWindowQuery,
+    DataHealthQuery,
+    InstrumentRangeQuery,
+    PITWindowQuery,
+)
+from pqdata.schema.quote_schema import DailyBasicResponse
+from pqdata.schema.reference_schema import (
+    InstrumentResponse,
+    TradingCalendarDayResponse,
+    TradingRuleResponse,
+)
+from pqdata.schema.reliability_schema import DatasetHealthResult
+
+
+class MarketClient:
+    """持有一个连接池；通过 async with 或 aclose 显式释放连接。"""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        token: str | None = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not 0 <= max_retries <= 5:
+            raise ValueError("max_retries must be between 0 and 5")
+        self._max_retries = max_retries
+        self._http = httpx.AsyncClient(
+            base_url=base_url.rstrip("/") + "/",
+            headers={"Authorization": f"Bearer {token}"} if token else {},
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=False,
+        )
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    @property
+    def source_id(self) -> str:
+        """服务地址的稳定摘要，用于隔离不同数据源的本地缓存。"""
+        return sha256(str(self._http.base_url).encode("utf-8")).hexdigest()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        response_type: Any,
+        *,
+        params: dict[str, Any] | None = None,
+        body: Any = None,
+    ) -> Any:
+        # 所有当前端点均为只读查询；未来写入端点不能复用此重试路径。
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._http.request(method, path, params=params, json=body)
+            except httpx.TransportError:
+                if attempt == self._max_retries:
+                    raise
+                await asyncio.sleep(min(0.25 * 2**attempt, 2.0))
+                continue
+            if response.status_code not in {429, 502, 503, 504} or attempt == self._max_retries:
+                break
+            delay = min(0.25 * 2**attempt, 2.0)
+            retry_after = response.headers.get("retry-after", "")
+            if retry_after.isdecimal():
+                delay = min(max(delay, int(retry_after)), 5.0)
+            await response.aclose()
+            await asyncio.sleep(delay)
+        if not response.is_success:
+            raise MarketAPIError(response.status_code, response.headers.get("x-request-id"))
+        try:
+            return TypeAdapter(response_type).validate_json(response.content)
+        except ValidationError as error:
+            raise MarketProtocolError("Invalid market response") from error
+
+    async def get_instrument(self, instrument_id: str) -> InstrumentResponse:
+        return await self._request(
+            "GET",
+            f"instruments/{quote(instrument_id, safe='')}",
+            InstrumentResponse,
+        )
+
+    async def get_history_facts(self, query: HistoryFactsQuery) -> HistoryFacts:
+        result = await self._request(
+            "POST", "history/facts", HistoryFacts, body=query.model_dump(mode="json")
+        )
+        if query.revision is not None and result.revision != query.revision:
+            raise MarketProtocolError("History facts revision changed")
+        if result.instrument.instrument_id != query.instrument_id:
+            raise MarketProtocolError("History facts instrument differs from query")
+        return result
+
+    async def get_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        limit: int = 1000,
+    ) -> list[BarResponse]:
+        query = BarWindowQuery(
+            instrument_id=instrument_id,
+            frequency=TypeAdapter(BarFrequency).validate_python(frequency),
+            start=start,
+            end=end,
+            limit=limit,
+        )
+        return await self._request(
+            "POST", "bars/window", list[BarResponse], body=query.model_dump(mode="json")
+        )
+
+    async def get_adjusted_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        view: BarViewRequest,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        limit: int = 1000,
+    ) -> AdjustedBarSeries:
+        query = BarWindowQuery(
+            instrument_id=instrument_id,
+            frequency=TypeAdapter(BarFrequency).validate_python(frequency),
+            start=start,
+            end=end,
+            limit=limit,
+            view=BarViewRequest.model_validate(view.model_dump(mode="json")),
+        )
+        return await self._request(
+            "POST", "bars/view", AdjustedBarSeries, body=query.model_dump(mode="json")
+        )
+
+    async def verify_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        start: datetime,
+        end: datetime,
+    ) -> DatasetHealthResult:
+        query = DataHealthQuery(
+            instrument_id=instrument_id,
+            frequency=TypeAdapter(BarFrequency).validate_python(frequency),
+            start=start,
+            end=end,
+        )
+        return await self._request(
+            "POST", "verify/bars", DatasetHealthResult, body=query.model_dump(mode="json")
+        )
+
+    async def verify_adjustment_factors(
+        self,
+        instrument_id: str,
+        frequency: str,
+        start: datetime,
+        end: datetime,
+    ) -> DatasetHealthResult:
+        query = DataHealthQuery(
+            instrument_id=instrument_id,
+            frequency=TypeAdapter(BarFrequency).validate_python(frequency),
+            start=start,
+            end=end,
+        )
+        return await self._request(
+            "POST",
+            "verify/adjustment-factors",
+            DatasetHealthResult,
+            body=query.model_dump(mode="json"),
+        )
+
+    async def verify_corporate_actions(
+        self,
+        instrument_id: str,
+        start: datetime,
+        end: datetime,
+    ) -> DatasetHealthResult:
+        query = DataHealthQuery(instrument_id=instrument_id, start=start, end=end)
+        return await self._request(
+            "POST",
+            "verify/corporate-actions",
+            DatasetHealthResult,
+            body=query.model_dump(mode="json"),
+        )
+
+    async def snapshot(self, start: date, end: date) -> dict[str, str]:
+        return await self._request(
+            "GET",
+            "revisions",
+            dict[str, str],
+            params={
+                "start": start.isoformat(),
+                "end": end.isoformat(),
+            },
+        )
+
+    async def search_instruments(
+        self,
+        keyword: str | None = None,
+        instrument_type: str | None = None,
+        exchange: str | None = None,
+        limit: int = 100,
+    ) -> list[InstrumentResponse]:
+        params = {
+            key: value
+            for key, value in {
+                "keyword": keyword,
+                "instrument_type": instrument_type,
+                "exchange": exchange,
+                "limit": limit,
+            }.items()
+            if value is not None
+        }
+        return await self._request("GET", "instruments", list[InstrumentResponse], params=params)
+
+    async def list_instruments_on(
+        self, on_date: date, limit: int = 10000
+    ) -> list[InstrumentResponse]:
+        return await self._request(
+            "GET",
+            "universe",
+            list[InstrumentResponse],
+            params={
+                "on_date": on_date.isoformat(),
+                "limit": limit,
+            },
+        )
+
+    async def list_trading_rules(
+        self,
+        instrument_ids: list[str],
+        start: date,
+        end: date,
+    ) -> list[TradingRuleResponse]:
+        query = InstrumentRangeQuery(instrument_ids=instrument_ids, start=start, end=end)
+        return await self._request(
+            "POST",
+            "trading-rules/query",
+            list[TradingRuleResponse],
+            body=query.model_dump(mode="json"),
+        )
+
+    async def list_trading_days(
+        self,
+        exchange: str,
+        start: date,
+        end: date,
+    ) -> list[TradingCalendarDayResponse]:
+        return await self._request(
+            "GET",
+            "calendar",
+            list[TradingCalendarDayResponse],
+            params={
+                "exchange": exchange,
+                "start": start.isoformat(),
+                "end": end.isoformat(),
+            },
+        )
+
+    async def is_trading_day(self, exchange: str, trade_date: date) -> bool:
+        return await self._request(
+            "GET",
+            "calendar/is-open",
+            bool,
+            params={
+                "exchange": exchange,
+                "trade_date": trade_date.isoformat(),
+            },
+        )
+
+    async def list_daily_basic_at(
+        self,
+        decision_time: datetime,
+        limit: int = 10000,
+    ) -> list[DailyBasicResponse]:
+        return await self._request(
+            "GET",
+            "daily-basic/visible",
+            list[DailyBasicResponse],
+            params={
+                "decision_time": decision_time.isoformat(),
+                "limit": limit,
+            },
+        )
+
+    async def get_pit_daily_windows(
+        self,
+        instrument_id: str,
+        days: list[date],
+        next_days: list[date],
+        lookback: int,
+    ) -> tuple[PITDailyWindow, ...]:
+        query = PITWindowQuery(
+            instrument_id=instrument_id,
+            days=days,
+            next_days=next_days,
+            lookback=lookback,
+        )
+        return await self._request(
+            "POST",
+            "bars/pit-windows",
+            tuple[PITDailyWindow, ...],
+            body=query.model_dump(mode="json"),
+        )
+
+    async def query_bars(self, query: BarQuery) -> BarPage:
+        """读取一页数据；错误内容不混入行情结果。"""
+        page = await self._request(
+            "POST", "bars/query", BarPage, body=query.model_dump(mode="json")
+        )
+        if query.revision is not None and page.revision != query.revision:
+            raise MarketProtocolError("Market revision changed during pagination")
+        if len(page.items) > query.page_size:
+            raise MarketProtocolError("Server exceeded requested page size")
+        previous: tuple | None = None
+        for bar in page.items:
+            key = (bar.timestamp, bar.instrument_id)
+            if (
+                bar.instrument_id not in query.instrument_ids
+                or bar.frequency != query.frequency
+                or not query.start <= bar.timestamp <= query.end
+                or (previous is not None and key <= previous)
+            ):
+                raise MarketProtocolError("Bar page violates query range or ordering")
+            previous = key
+        return page
+
+    async def describe_bars(self, query: BarQuery) -> BarContent:
+        """只传输范围摘要；服务端仍需扫描数据，不能视为常数成本的查询。"""
+        if query.cursor is not None:
+            raise ValueError("Content queries must start at the first page")
+        result = await self._request(
+            "POST", "bars/content", BarContent, body=query.model_dump(mode="json")
+        )
+        if query.revision is not None and result.revision != query.revision:
+            raise MarketProtocolError("Content revision differs from query")
+        return result
+
+    async def iter_bar_pages(self, query: BarQuery) -> AsyncIterator[BarPage]:
+        """逐页消费，固定 revision，检测重复游标与跨页重复数据。"""
+        seen: set[str] = {query.cursor} if query.cursor else set()
+        previous: tuple | None = None
+        while True:
+            page = await self.query_bars(query)
+            if previous is not None and page.items:
+                first = page.items[0]
+                if (first.timestamp, first.instrument_id) <= previous:
+                    raise MarketProtocolError("Bar pages overlap or are out of order")
+            if page.next_cursor and (page.next_cursor in seen or not page.items):
+                raise MarketProtocolError("Pagination did not advance")
+            yield page
+            if page.next_cursor is None:
+                return
+            last = page.items[-1]
+            previous = (last.timestamp, last.instrument_id)
+            seen.add(page.next_cursor)
+            query = query.model_copy(update={"cursor": page.next_cursor, "revision": page.revision})

powerquant_cli-0.2.6/bundled/pqdata/download.py

@@ -0,0 +1,60 @@
+"""流式落盘；完整下载后才替换目标文件，失败保留原文件。"""
+
+import hashlib
+import os
+import tempfile
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from pqdata.client import MarketClient
+from pqdata.schema.bar_schema import BarQuery
+
+
+class DownloadReceipt(BaseModel):
+    """供本地缓存记录查询条件、版本及内容校验和。"""
+
+    query: BarQuery
+    revision: str
+    row_count: int = Field(ge=0)
+    byte_count: int = Field(ge=0)
+    sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
+
+
+async def download_bars(
+    client: MarketClient, query: BarQuery, destination: Path
+) -> DownloadReceipt:
+    """完整范围以 JSON Lines 落盘；内存上限为一页数据。"""
+    if query.cursor is not None:
+        raise ValueError("Downloads must start at the first page")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temporary: Path | None = None
+    digest = hashlib.sha256()
+    row_count = byte_count = 0
+    revision = ""
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb", dir=destination.parent, prefix=".market-", suffix=".part", delete=False
+        ) as output:
+            temporary = Path(output.name)
+            async for page in client.iter_bar_pages(query):
+                revision = page.revision
+                for bar in page.items:
+                    line = (bar.model_dump_json() + "\n").encode("utf-8")
+                    output.write(line)
+                    digest.update(line)
+                    row_count += 1
+                    byte_count += len(line)
+            output.flush()
+            os.fsync(output.fileno())
+        os.replace(temporary, destination)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+    return DownloadReceipt(
+        query=query,
+        revision=revision,
+        row_count=row_count,
+        byte_count=byte_count,
+        sha256=digest.hexdigest(),
+    )

powerquant_cli-0.2.6/bundled/pqdata/exceptions.py

@@ -0,0 +1,14 @@
+"""客户端错误不依赖服务端异常实现。"""
+
+
+class MarketAPIError(Exception):
+    """服务拒绝请求；保留状态码和可追踪的请求 ID，不暴露凭据。"""
+
+    def __init__(self, status_code: int, request_id: str | None = None) -> None:
+        self.status_code = status_code
+        self.request_id = request_id
+        super().__init__(f"Market request failed (HTTP {status_code}, request_id={request_id})")
+
+
+class MarketProtocolError(Exception):
+    """响应不符合契约或下载内容不一致，禁止继续消费。"""

powerquant_cli-0.2.6/bundled/pqdata/schema/__init__.py

@@ -0,0 +1 @@
+"""客户端公开数据契约。"""