athena-kit 1.0.0__tar.gz

athena_kit-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wangmu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

athena_kit-1.0.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: athena-kit
+Version: 1.0.0
+Summary: A modular Python toolkit for Athena projects.
+Keywords: athena,toolkit,utilities,temporal,pydantic
+Author: wangmu
+Author-email: wangmu <wangmu8889@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: httpx>=0.28.1 ; extra == 'all'
+Requires-Dist: matplotlib>=3.10.9 ; extra == 'all'
+Requires-Dist: pandas>=2.3.3 ; extra == 'all'
+Requires-Dist: pandas>=2.3.3 ; extra == 'dataframe'
+Requires-Dist: httpx>=0.28.1 ; extra == 'http'
+Requires-Dist: httpx>=0.28.1 ; extra == 'lark'
+Requires-Dist: matplotlib>=3.10.9 ; extra == 'matplotlib'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/wangmu0115/Athena
+Project-URL: Repository, https://github.com/wangmu0115/Athena
+Project-URL: Issues, https://github.com/wangmu0115/Athena/issues
+Provides-Extra: all
+Provides-Extra: dataframe
+Provides-Extra: http
+Provides-Extra: lark
+Provides-Extra: matplotlib
+Description-Content-Type: text/markdown
+
+# Athena Kit
+
+Athena Kit 是 Athena 项目使用的模块化 Python 工具包。
+
+它发布为一个 Python 包：`athena-kit`，并提供统一的 Python 命名空间：`athena_kit`。
+
+## 安装
+
+```shell
+uv add athena-kit
+uv add "athena-kit[http]"
+uv add "athena-kit[lark]"
+uv add "athena-kit[matplotlib]"
+uv add "athena-kit[dataframe]"
+uv add "athena-kit[all]"
+```
+
+## Usage
+
+### athena http
+
+`athena_kit.http` 基于 HTTPX 做薄封装，提供同步/异步客户端、常用 event hooks、JSON 响应提取和简单重试工具。
+
+同步请求：
+
+```python
+from athena_kit.http import HttpClient
+
+with HttpClient(base_url="https://api.example.test", request_id=True) as client:
+    response = client.get("/items")
+    response.raise_for_status()
+```
+
+异步请求：
+
+```python
+from athena_kit.http import AsyncHttpClient
+
+async with AsyncHttpClient(base_url="https://api.example.test", request_id=True) as client:
+    response = await client.get("/items")
+    response.raise_for_status()
+```
+
+启用请求 ID、日志和响应状态检查：
+
+```python
+from athena_kit.http import HttpClient
+
+with HttpClient(
+    base_url="https://api.example.test",
+    request_id=True,
+    logging=True,
+    response_status=True,
+) as client:
+    response = client.get("/items")
+```
+
+提取 JSON 响应中的业务数据：
+
+```python
+from athena_kit.http import create_biz_code_validator, extract_response_json_value
+
+data = extract_response_json_value(
+    response,
+    "data.items[0]",
+    validator=create_biz_code_validator(code_key="code", success_codes=(0,)),
+)
+```
+
+为请求增加简单重试：
+
+```python
+import httpx
+from athena_kit.http import RetryOptions, retry
+
+response = retry(
+    request=lambda: client.get("/items"),
+    options=RetryOptions(attempts=3, initial_delay=0.2, multiplier=2.0, jitter=0.1, logger=True),
+    should_retry_result=lambda response: response.status_code in {429, 500, 502, 503, 504},
+    should_retry_exception=lambda exc: isinstance(exc, httpx.TimeoutException),
+)
+```
+
+更多 HTTP 使用案例见 [docs/athena_http.md](docs/athena_http.md)。
+
+### athena tabular
+
+`athena_kit.core.tabular` 提供二维表格模型、单元格序列化、pandas DataFrame 转换，以及同步/异步表格后端和仓储抽象。
+
+定义一行表格模型：
+
+```python
+from datetime import date
+
+from athena_kit.core.tabular import TableCell, TableRow
+
+
+class TradeRow(TableRow):
+    trade_date: date = TableCell(title="日期", order=1)
+    symbol: str = TableCell(title="代码", order=2)
+    amount: int = TableCell(title="成交额", order=3)
+```
+
+模型和二维表格行互相转换：
+
+```python
+row = TradeRow(trade_date=date(2026, 6, 11), symbol="000001", amount=1200)
+
+assert TradeRow.table_headers() == ["日期", "代码", "成交额"]
+assert row.to_table_row() == ["2026-06-11", "000001", 1200]
+```
+
+使用 repository 接入具体二维表格后端：
+
+```python
+from athena_kit.core.tabular import TableRepository
+
+repository = TableRepository(backend, locator, TradeRow)
+rows = repository.list_all()
+```
+
+更多 Tabular 使用案例见 [docs/athena_tabular.md](docs/athena_tabular.md)。
+
+### athena lark
+
+`athena_kit.lark` 提供飞书开放平台异步客户端。当前重点支持 Sheets，包括创建电子表格、批量新增工作表、读写单个工作表范围，以及接入 `core.tabular` 的异步表格后端。
+
+创建飞书客户端并新增电子表格：
+
+```python
+from athena_kit.lark import AsyncLarkClient
+
+
+async with AsyncLarkClient(app_id="cli_xxx", app_secret="xxx", response_status=True) as client:
+    spreadsheet_token, url = await client.sheets.create_spreadsheet(
+        folder_token="fldcn_xxx",
+        title="交易汇总",
+    )
+```
+
+写入飞书工作表：
+
+```python
+revision, updated_rows, updated_columns = await client.sheets.overwrite_values(
+    spreadsheet_token=spreadsheet_token,
+    sheet_id="sheet_xxx",
+    headers=["日期", "代码", "成交额"],
+    rows_values=[["2026-06-11", "000001", 1200]],
+    start_row=1,
+)
+```
+
+接入异步表格仓储：
+
+```python
+from athena_kit.core.tabular import AsyncTableRepository
+from athena_kit.lark.sheets import AsyncLarkSheetsBackend, LarkSheetsLocator
+
+backend = AsyncLarkSheetsBackend(client.sheets)
+locator = LarkSheetsLocator(spreadsheet_token=spreadsheet_token, sheet_id="sheet_xxx")
+repository = AsyncTableRepository(backend, locator, TradeRow)
+
+rows = await repository.list_all()
+```
+
+更多 Lark Sheets 使用案例见 [docs/athena_lark.md](docs/athena_lark.md)。
+
+## 模块结构
+
+- `athena_kit.core`：基础模型、时间编解码、表格和通用值处理工具。
+- `athena_kit.http`：基于 HTTPX 的同步/异步 HTTP 工具。
+- `athena_kit.lark`：飞书开放平台异步客户端和 Sheets 工具。
+- `athena_kit.matplotlib`：声明式图表渲染工具。
+- `athena_kit.bosun`：Bosun 表达式解析和 OpenTSDB 查询工具。
+
+## 开发
+
+```shell
+uv sync --extra all
+uv run ruff check src tests examples
+uv run ruff format --check src tests examples
+uv run pytest tests
+```
+
+## 发布到 PyPI
+
+发布前确认版本号已经更新，并且 `pyproject.toml` 和 `src/athena_kit/__init__.py` 中的版本一致。
+
+```shell
+uv sync --extra all
+uv run ruff check src tests examples
+uv run ruff format --check src tests examples
+uv run pytest tests
+rm -rf dist
+uv build
+uv publish
+```
+
+如果是第一次发布，先在 PyPI 创建 API Token，然后按 `uv publish` 的提示输入 token；也可以提前设置环境变量：
+
+```shell
+export UV_PUBLISH_TOKEN="pypi-..."
+uv publish
+```
+
+发布完成后，在其他项目中安装：
+
+```shell
+uv add athena-kit
+```

athena_kit-1.0.0/README.md

@@ -0,0 +1,210 @@
+# Athena Kit
+
+Athena Kit 是 Athena 项目使用的模块化 Python 工具包。
+
+它发布为一个 Python 包：`athena-kit`，并提供统一的 Python 命名空间：`athena_kit`。
+
+## 安装
+
+```shell
+uv add athena-kit
+uv add "athena-kit[http]"
+uv add "athena-kit[lark]"
+uv add "athena-kit[matplotlib]"
+uv add "athena-kit[dataframe]"
+uv add "athena-kit[all]"
+```
+
+## Usage
+
+### athena http
+
+`athena_kit.http` 基于 HTTPX 做薄封装，提供同步/异步客户端、常用 event hooks、JSON 响应提取和简单重试工具。
+
+同步请求：
+
+```python
+from athena_kit.http import HttpClient
+
+with HttpClient(base_url="https://api.example.test", request_id=True) as client:
+    response = client.get("/items")
+    response.raise_for_status()
+```
+
+异步请求：
+
+```python
+from athena_kit.http import AsyncHttpClient
+
+async with AsyncHttpClient(base_url="https://api.example.test", request_id=True) as client:
+    response = await client.get("/items")
+    response.raise_for_status()
+```
+
+启用请求 ID、日志和响应状态检查：
+
+```python
+from athena_kit.http import HttpClient
+
+with HttpClient(
+    base_url="https://api.example.test",
+    request_id=True,
+    logging=True,
+    response_status=True,
+) as client:
+    response = client.get("/items")
+```
+
+提取 JSON 响应中的业务数据：
+
+```python
+from athena_kit.http import create_biz_code_validator, extract_response_json_value
+
+data = extract_response_json_value(
+    response,
+    "data.items[0]",
+    validator=create_biz_code_validator(code_key="code", success_codes=(0,)),
+)
+```
+
+为请求增加简单重试：
+
+```python
+import httpx
+from athena_kit.http import RetryOptions, retry
+
+response = retry(
+    request=lambda: client.get("/items"),
+    options=RetryOptions(attempts=3, initial_delay=0.2, multiplier=2.0, jitter=0.1, logger=True),
+    should_retry_result=lambda response: response.status_code in {429, 500, 502, 503, 504},
+    should_retry_exception=lambda exc: isinstance(exc, httpx.TimeoutException),
+)
+```
+
+更多 HTTP 使用案例见 [docs/athena_http.md](docs/athena_http.md)。
+
+### athena tabular
+
+`athena_kit.core.tabular` 提供二维表格模型、单元格序列化、pandas DataFrame 转换，以及同步/异步表格后端和仓储抽象。
+
+定义一行表格模型：
+
+```python
+from datetime import date
+
+from athena_kit.core.tabular import TableCell, TableRow
+
+
+class TradeRow(TableRow):
+    trade_date: date = TableCell(title="日期", order=1)
+    symbol: str = TableCell(title="代码", order=2)
+    amount: int = TableCell(title="成交额", order=3)
+```
+
+模型和二维表格行互相转换：
+
+```python
+row = TradeRow(trade_date=date(2026, 6, 11), symbol="000001", amount=1200)
+
+assert TradeRow.table_headers() == ["日期", "代码", "成交额"]
+assert row.to_table_row() == ["2026-06-11", "000001", 1200]
+```
+
+使用 repository 接入具体二维表格后端：
+
+```python
+from athena_kit.core.tabular import TableRepository
+
+repository = TableRepository(backend, locator, TradeRow)
+rows = repository.list_all()
+```
+
+更多 Tabular 使用案例见 [docs/athena_tabular.md](docs/athena_tabular.md)。
+
+### athena lark
+
+`athena_kit.lark` 提供飞书开放平台异步客户端。当前重点支持 Sheets，包括创建电子表格、批量新增工作表、读写单个工作表范围，以及接入 `core.tabular` 的异步表格后端。
+
+创建飞书客户端并新增电子表格：
+
+```python
+from athena_kit.lark import AsyncLarkClient
+
+
+async with AsyncLarkClient(app_id="cli_xxx", app_secret="xxx", response_status=True) as client:
+    spreadsheet_token, url = await client.sheets.create_spreadsheet(
+        folder_token="fldcn_xxx",
+        title="交易汇总",
+    )
+```
+
+写入飞书工作表：
+
+```python
+revision, updated_rows, updated_columns = await client.sheets.overwrite_values(
+    spreadsheet_token=spreadsheet_token,
+    sheet_id="sheet_xxx",
+    headers=["日期", "代码", "成交额"],
+    rows_values=[["2026-06-11", "000001", 1200]],
+    start_row=1,
+)
+```
+
+接入异步表格仓储：
+
+```python
+from athena_kit.core.tabular import AsyncTableRepository
+from athena_kit.lark.sheets import AsyncLarkSheetsBackend, LarkSheetsLocator
+
+backend = AsyncLarkSheetsBackend(client.sheets)
+locator = LarkSheetsLocator(spreadsheet_token=spreadsheet_token, sheet_id="sheet_xxx")
+repository = AsyncTableRepository(backend, locator, TradeRow)
+
+rows = await repository.list_all()
+```
+
+更多 Lark Sheets 使用案例见 [docs/athena_lark.md](docs/athena_lark.md)。
+
+## 模块结构
+
+- `athena_kit.core`：基础模型、时间编解码、表格和通用值处理工具。
+- `athena_kit.http`：基于 HTTPX 的同步/异步 HTTP 工具。
+- `athena_kit.lark`：飞书开放平台异步客户端和 Sheets 工具。
+- `athena_kit.matplotlib`：声明式图表渲染工具。
+- `athena_kit.bosun`：Bosun 表达式解析和 OpenTSDB 查询工具。
+
+## 开发
+
+```shell
+uv sync --extra all
+uv run ruff check src tests examples
+uv run ruff format --check src tests examples
+uv run pytest tests
+```
+
+## 发布到 PyPI
+
+发布前确认版本号已经更新，并且 `pyproject.toml` 和 `src/athena_kit/__init__.py` 中的版本一致。
+
+```shell
+uv sync --extra all
+uv run ruff check src tests examples
+uv run ruff format --check src tests examples
+uv run pytest tests
+rm -rf dist
+uv build
+uv publish
+```
+
+如果是第一次发布，先在 PyPI 创建 API Token，然后按 `uv publish` 的提示输入 token；也可以提前设置环境变量：
+
+```shell
+export UV_PUBLISH_TOKEN="pypi-..."
+uv publish
+```
+
+发布完成后，在其他项目中安装：
+
+```shell
+uv add athena-kit
+```

athena_kit-1.0.0/pyproject.toml

@@ -0,0 +1,90 @@
+[project]
+name = "athena-kit"
+version = "1.0.0"
+description = "A modular Python toolkit for Athena projects."
+readme = "README.md"
+authors = [
+    { name = "wangmu", email = "wangmu8889@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.13.4",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["athena", "toolkit", "utilities", "temporal", "pydantic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/wangmu0115/Athena"
+Repository = "https://github.com/wangmu0115/Athena"
+Issues = "https://github.com/wangmu0115/Athena/issues"
+
+[project.optional-dependencies]
+dataframe = [
+    "pandas>=2.3.3",
+]
+http = [
+    "httpx>=0.28.1",
+]
+lark = [
+    "httpx>=0.28.1",
+]
+matplotlib = [
+    "matplotlib>=3.10.9",
+]
+all = [
+    "httpx>=0.28.1",
+    "matplotlib>=3.10.9",
+    "pandas>=2.3.3",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.25,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "ruff>=0.15.12",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+src = [
+    "src",
+    "tests",
+    "examples",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle error
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+]
+ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+docstring-code-format = true
+preview = true
+
+[tool.ruff.lint.isort]
+known-first-party = [
+    "athena_kit",
+]

athena_kit-1.0.0/src/athena_kit/__init__.py

@@ -0,0 +1,5 @@
+"""Athena Kit public namespace."""
+
+__all__ = ("__version__",)
+
+__version__ = "1.0.0"

athena_kit-1.0.0/src/athena_kit/_import_utils.py

@@ -0,0 +1,41 @@
+from importlib import import_module
+
+
+def import_attr(
+    attr_name: str,
+    module_name: str | None,
+    package: str | None,
+) -> object:
+    """Import an attribute from a module located in a package.
+
+    This utility function is used in custom `__getattr__` methods within `__init__.py`
+    files to dynamically import attributes.
+
+    Args:
+        attr_name: The name of the attribute to import.
+        module_name: The name of the module to import from.
+
+            If `None`, the attribute is imported from the package itself.
+        package: The name of the package where the module is located.
+
+    Returns:
+        The imported attribute.
+
+    Raises:
+        ImportError: If the module cannot be found.
+        AttributeError: If the attribute does not exist in the module or package.
+    """
+    if module_name == "__module__" or module_name is None:
+        try:
+            result = import_module(f".{attr_name}", package=package)
+        except ModuleNotFoundError:
+            msg = f"module '{package!r}' has no attribute {attr_name!r}"
+            raise AttributeError(msg) from None
+    else:
+        try:
+            module = import_module(f".{module_name}", package=package)
+        except ModuleNotFoundError as err:
+            msg = f"module '{package!r}.{module_name!r}' not found ({err})"
+            raise ImportError(msg) from None
+        result = getattr(module, attr_name)
+    return result

athena_kit-1.0.0/src/athena_kit/bosun/__init__.py

@@ -0,0 +1,32 @@
+from typing import TYPE_CHECKING
+
+from athena_kit._import_utils import import_attr
+
+if TYPE_CHECKING:
+    from athena_kit.bosun.parser import Lexer, Parser
+    from athena_kit.bosun.parser.preprocess import preprocess
+
+__all__ = (
+    "Lexer",
+    "Parser",
+    "preprocess",
+)
+
+_dynamic_imports = {
+    "Lexer": "parser",
+    "Parser": "parser",
+    "preprocess": "parser.preprocess",
+}
+
+
+def __getattr__(attr_name: str) -> object:
+    module_name = _dynamic_imports.get(attr_name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {attr_name!r}")
+    result = import_attr(attr_name, module_name, __spec__.parent)
+    globals()[attr_name] = result
+    return result
+
+
+def __dir__() -> list[str]:
+    return list(__all__)