扩展指标
This commit is contained in:
@@ -0,0 +1,300 @@
|
||||
"""
|
||||
ferro_ta.api_info — API discovery helpers.
|
||||
|
||||
Provides :func:`indicators`, :func:`methods`, :func:`about`, and :func:`info`
|
||||
for exploring the ferro_ta public API without reading source code.
|
||||
|
||||
Usage
|
||||
-----
|
||||
>>> import ferro_ta
|
||||
>>> ferro_ta.indicators() # all indicators, sorted
|
||||
>>> ferro_ta.indicators(category="momentum") # filter by category
|
||||
>>> ferro_ta.methods() # public callables across modules
|
||||
>>> ferro_ta.about()["version"] # package metadata summary
|
||||
>>> ferro_ta.info(ferro_ta.SMA) # parameter docs for SMA
|
||||
|
||||
API
|
||||
---
|
||||
indicators(category=None) — Return list of dicts describing every indicator.
|
||||
methods(category=None) — Return list of public callables across modules.
|
||||
about() — Return package/version/module summary metadata.
|
||||
info(func_or_name) — Return a dict with full signature/docstring info.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib
|
||||
import inspect
|
||||
from typing import Any
|
||||
|
||||
__all__ = ["indicators", "methods", "about", "info"]
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Category → module mapping used by indicators()
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
_CATEGORY_MODULES: dict[str, str] = {
|
||||
"overlap": "ferro_ta.indicators.overlap",
|
||||
"momentum": "ferro_ta.indicators.momentum",
|
||||
"volume": "ferro_ta.indicators.volume",
|
||||
"volatility": "ferro_ta.indicators.volatility",
|
||||
"statistic": "ferro_ta.indicators.statistic",
|
||||
"price_transform": "ferro_ta.indicators.price_transform",
|
||||
"pattern": "ferro_ta.indicators.pattern",
|
||||
"cycle": "ferro_ta.indicators.cycle",
|
||||
"math_ops": "ferro_ta.indicators.math_ops",
|
||||
"extended": "ferro_ta.indicators.extended",
|
||||
"batch": "ferro_ta.data.batch",
|
||||
"streaming": "ferro_ta.data.streaming",
|
||||
"resampling": "ferro_ta.data.resampling",
|
||||
"aggregation": "ferro_ta.data.aggregation",
|
||||
"signals": "ferro_ta.analysis.signals",
|
||||
"portfolio": "ferro_ta.analysis.portfolio",
|
||||
"features": "ferro_ta.analysis.features",
|
||||
"alerts": "ferro_ta.tools.alerts",
|
||||
"crypto": "ferro_ta.analysis.crypto",
|
||||
"regime": "ferro_ta.analysis.regime",
|
||||
}
|
||||
|
||||
_METHOD_MODULES: dict[str, str] = {
|
||||
"top_level": "ferro_ta",
|
||||
**_CATEGORY_MODULES,
|
||||
"options": "ferro_ta.analysis.options",
|
||||
"futures": "ferro_ta.analysis.futures",
|
||||
"backtest": "ferro_ta.analysis.backtest",
|
||||
"options_strategy": "ferro_ta.analysis.options_strategy",
|
||||
"derivatives_payoff": "ferro_ta.analysis.derivatives_payoff",
|
||||
"attribution": "ferro_ta.analysis.attribution",
|
||||
"cross_asset": "ferro_ta.analysis.cross_asset",
|
||||
"tools": "ferro_ta.tools.tools",
|
||||
"viz": "ferro_ta.tools.viz",
|
||||
}
|
||||
|
||||
|
||||
def _iter_module_callables(
|
||||
module_name: str,
|
||||
) -> list[tuple[str, Any]]:
|
||||
"""Import *module_name* and return its ``__all__`` callables."""
|
||||
try:
|
||||
mod = importlib.import_module(module_name)
|
||||
except Exception:
|
||||
return []
|
||||
|
||||
names = getattr(mod, "__all__", [])
|
||||
result = []
|
||||
for name in names:
|
||||
obj = getattr(mod, name, None)
|
||||
if callable(obj):
|
||||
result.append((name, obj))
|
||||
return result
|
||||
|
||||
|
||||
def indicators(category: str | None = None) -> list[dict[str, Any]]:
|
||||
"""Return a list of all ferro_ta indicators with metadata.
|
||||
|
||||
Each entry is a dict with the following keys:
|
||||
|
||||
- ``"name"`` (str): The indicator name, e.g. ``"SMA"``.
|
||||
- ``"category"`` (str): The category / sub-module, e.g. ``"overlap"``.
|
||||
- ``"module"`` (str): The fully qualified module name.
|
||||
- ``"doc"`` (str): First line of the docstring, or ``""`` if absent.
|
||||
- ``"params"`` (list[str]): Names of the function's parameters.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
category : str | None
|
||||
If given, only return indicators from that category. Must be one of
|
||||
the keys in :data:`ferro_ta.api_info._CATEGORY_MODULES`.
|
||||
|
||||
Returns
|
||||
-------
|
||||
list[dict[str, Any]]
|
||||
Sorted alphabetically by ``"name"``.
|
||||
|
||||
Examples
|
||||
--------
|
||||
>>> import ferro_ta
|
||||
>>> all_inds = ferro_ta.indicators()
|
||||
>>> len(all_inds) > 50
|
||||
True
|
||||
>>> overlap_inds = ferro_ta.indicators(category="overlap")
|
||||
>>> any(d["name"] == "SMA" for d in overlap_inds)
|
||||
True
|
||||
"""
|
||||
cats: dict[str, str] = (
|
||||
{category: _CATEGORY_MODULES[category]}
|
||||
if category is not None
|
||||
else _CATEGORY_MODULES
|
||||
)
|
||||
result: list[dict[str, Any]] = []
|
||||
seen: set[str] = set()
|
||||
|
||||
for cat, mod_name in cats.items():
|
||||
for name, func in _iter_module_callables(mod_name):
|
||||
if name in seen:
|
||||
continue
|
||||
seen.add(name)
|
||||
doc = inspect.getdoc(func) or ""
|
||||
first_line = doc.splitlines()[0] if doc else ""
|
||||
try:
|
||||
sig = inspect.signature(func)
|
||||
params = list(sig.parameters.keys())
|
||||
except (ValueError, TypeError):
|
||||
params = []
|
||||
result.append(
|
||||
{
|
||||
"name": name,
|
||||
"category": cat,
|
||||
"module": mod_name,
|
||||
"doc": first_line,
|
||||
"params": params,
|
||||
}
|
||||
)
|
||||
|
||||
result.sort(key=lambda d: d["name"])
|
||||
return result
|
||||
|
||||
|
||||
def methods(category: str | None = None) -> list[dict[str, Any]]:
|
||||
"""Return public callables across ferro_ta modules.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
category : str | None
|
||||
Optional key from :data:`_METHOD_MODULES`, such as ``"top_level"``,
|
||||
``"options"``, ``"futures"``, or ``"batch"``.
|
||||
"""
|
||||
cats: dict[str, str] = (
|
||||
{category: _METHOD_MODULES[category]}
|
||||
if category is not None
|
||||
else _METHOD_MODULES
|
||||
)
|
||||
|
||||
result: list[dict[str, Any]] = []
|
||||
seen: set[tuple[str, str]] = set()
|
||||
for cat, mod_name in cats.items():
|
||||
for name, func in _iter_module_callables(mod_name):
|
||||
key = (mod_name, name)
|
||||
if key in seen:
|
||||
continue
|
||||
seen.add(key)
|
||||
doc = inspect.getdoc(func) or ""
|
||||
first_line = doc.splitlines()[0] if doc else ""
|
||||
try:
|
||||
sig = inspect.signature(func)
|
||||
params = list(sig.parameters.keys())
|
||||
except (ValueError, TypeError):
|
||||
params = []
|
||||
result.append(
|
||||
{
|
||||
"name": name,
|
||||
"category": cat,
|
||||
"module": mod_name,
|
||||
"doc": first_line,
|
||||
"params": params,
|
||||
}
|
||||
)
|
||||
|
||||
result.sort(key=lambda d: (d["category"], d["name"]))
|
||||
return result
|
||||
|
||||
|
||||
def about() -> dict[str, Any]:
|
||||
"""Return a small metadata summary for the installed ferro_ta package."""
|
||||
import ferro_ta # noqa: PLC0415
|
||||
|
||||
top_level_exports = sorted(getattr(ferro_ta, "__all__", []))
|
||||
return {
|
||||
"name": "ferro-ta",
|
||||
"version": getattr(ferro_ta, "__version__", "0+unknown"),
|
||||
"top_level_export_count": len(top_level_exports),
|
||||
"indicator_count": len(indicators()),
|
||||
"method_count": len(methods()),
|
||||
"categories": sorted(_METHOD_MODULES.keys()),
|
||||
"top_level_exports": top_level_exports,
|
||||
}
|
||||
|
||||
|
||||
def info(func_or_name: Any) -> dict[str, Any]:
|
||||
"""Return detailed information about an indicator function.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
func_or_name : callable | str
|
||||
The indicator function (e.g. ``ferro_ta.SMA``) or its name as a
|
||||
string (e.g. ``"SMA"``).
|
||||
|
||||
Returns
|
||||
-------
|
||||
dict[str, Any]
|
||||
Dictionary with the following keys:
|
||||
|
||||
- ``"name"`` (str)
|
||||
- ``"module"`` (str)
|
||||
- ``"signature"`` (str): Full ``inspect.signature`` string.
|
||||
- ``"doc"`` (str): Full docstring.
|
||||
- ``"params"`` (dict[str, dict]): Mapping of parameter name →
|
||||
``{"default": ..., "kind": str}`` for each parameter.
|
||||
|
||||
Raises
|
||||
------
|
||||
ValueError
|
||||
If *func_or_name* is a string that does not match any indicator.
|
||||
|
||||
Examples
|
||||
--------
|
||||
>>> import ferro_ta
|
||||
>>> d = ferro_ta.info(ferro_ta.SMA)
|
||||
>>> d["name"]
|
||||
'SMA'
|
||||
>>> "close" in d["params"]
|
||||
True
|
||||
"""
|
||||
if isinstance(func_or_name, str):
|
||||
import ferro_ta # noqa: PLC0415
|
||||
|
||||
func = getattr(ferro_ta, func_or_name, None)
|
||||
if func is None:
|
||||
raise ValueError(
|
||||
f"No indicator named {func_or_name!r} found in ferro_ta. "
|
||||
"Use ferro_ta.indicators() to list all available indicators."
|
||||
)
|
||||
else:
|
||||
func = func_or_name
|
||||
|
||||
name = getattr(func, "__name__", repr(func))
|
||||
module = getattr(func, "__module__", "")
|
||||
doc = inspect.getdoc(func) or ""
|
||||
|
||||
try:
|
||||
sig = inspect.signature(func)
|
||||
sig_str = str(sig)
|
||||
params = {}
|
||||
for pname, param in sig.parameters.items():
|
||||
kind_map = {
|
||||
inspect.Parameter.POSITIONAL_ONLY: "positional_only",
|
||||
inspect.Parameter.POSITIONAL_OR_KEYWORD: "positional_or_keyword",
|
||||
inspect.Parameter.VAR_POSITIONAL: "var_positional",
|
||||
inspect.Parameter.KEYWORD_ONLY: "keyword_only",
|
||||
inspect.Parameter.VAR_KEYWORD: "var_keyword",
|
||||
}
|
||||
params[pname] = {
|
||||
"default": (
|
||||
param.default
|
||||
if param.default is not inspect.Parameter.empty
|
||||
else None
|
||||
),
|
||||
"has_default": param.default is not inspect.Parameter.empty,
|
||||
"kind": kind_map.get(param.kind, "unknown"),
|
||||
}
|
||||
except (ValueError, TypeError):
|
||||
sig_str = "()"
|
||||
params = {}
|
||||
|
||||
return {
|
||||
"name": name,
|
||||
"module": module,
|
||||
"signature": sig_str,
|
||||
"doc": doc,
|
||||
"params": params,
|
||||
}
|
||||
Reference in New Issue
Block a user