akshare-cli 0.2.0__py3-none-any.whl

akshare_cli/core/__init__.py

@@ -0,0 +1 @@
+"""Core package for AKShare CLI harness."""

akshare_cli/core/cache.py

@@ -0,0 +1,127 @@
+"""
+In-memory TTL result cache for akshare API calls.
+
+Caches function results to avoid redundant network requests.
+Each entry has a configurable time-to-live (TTL) in seconds.
+"""
+
+import hashlib
+import json
+import time
+from typing import Any, Dict, Optional
+
+# ---------------------------------------------------------------------------
+# TTL Configuration
+# ---------------------------------------------------------------------------
+
+# Functions that should NEVER be cached (real-time data)
+NO_CACHE: set = {
+    "stock_zh_a_spot_em",
+    "stock_sh_a_spot_em",
+    "stock_sz_a_spot_em",
+    "stock_bj_a_spot_em",
+    "stock_hk_spot_em",
+    "stock_us_spot_em",
+    "stock_bid_ask_em",
+    "stock_intraday_em",
+    "forex_spot_em",
+    "fund_etf_spot_em",
+    "index_global_spot_em",
+    "stock_zh_index_spot_em",
+}
+
+# Per-function TTL overrides (seconds)
+CACHE_TTL: Dict[str, int] = {
+    # Contract / instrument lists — rarely change
+    "futures_hist_table_em": 86400,         # 24h
+    "futures_contract_info_gfex": 86400,    # 24h
+    "futures_fees_info": 86400,             # 24h
+    "option_contract_info_ctp": 86400,      # 24h
+    # Macro — updated monthly at most
+    "macro_china_gdp_yearly": 86400,        # 24h
+    "macro_china_cpi_yearly": 86400,
+    "macro_china_cpi_monthly": 86400,
+    "macro_china_ppi_yearly": 86400,
+    "macro_china_pmi_yearly": 86400,
+    "macro_china_m2_yearly": 86400,
+    # Bond yield curves — updated daily
+    "bond_china_yield": 3600,               # 1h
+    "bond_zh_us_rate": 3600,
+}
+
+DEFAULT_TTL: int = 1800  # 30 minutes
+
+
+def get_ttl(func_name: str) -> int:
+    """Return the cache TTL for a function. 0 means do not cache."""
+    if func_name in NO_CACHE:
+        return 0
+    return CACHE_TTL.get(func_name, DEFAULT_TTL)
+
+
+# ---------------------------------------------------------------------------
+# ResultCache
+# ---------------------------------------------------------------------------
+
+class ResultCache:
+    """Simple in-memory cache with per-entry TTL."""
+
+    def __init__(self) -> None:
+        self._store: Dict[str, tuple] = {}  # key → (data, expire_timestamp)
+        self.enabled: bool = True
+        self.hits: int = 0
+        self.misses: int = 0
+
+    # -- key helpers --
+
+    @staticmethod
+    def _make_key(func_name: str, kwargs: dict) -> str:
+        raw = json.dumps({"f": func_name, "k": kwargs}, sort_keys=True, default=str)
+        return hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+    # -- public API --
+
+    def get(self, func_name: str, kwargs: dict) -> Optional[Any]:
+        """Retrieve a cached result.  Returns None on miss or expiry."""
+        if not self.enabled:
+            return None
+        key = self._make_key(func_name, kwargs)
+        entry = self._store.get(key)
+        if entry is None:
+            self.misses += 1
+            return None
+        data, expires = entry
+        if time.time() > expires:
+            del self._store[key]
+            self.misses += 1
+            return None
+        self.hits += 1
+        return data
+
+    def put(self, func_name: str, kwargs: dict, data: Any, ttl: int) -> None:
+        """Store a result with TTL (seconds)."""
+        if not self.enabled or ttl <= 0:
+            return
+        key = self._make_key(func_name, kwargs)
+        self._store[key] = (data, time.time() + ttl)
+
+    def clear(self) -> None:
+        """Remove all entries and reset counters."""
+        self._store.clear()
+        self.hits = 0
+        self.misses = 0
+
+    def stats(self) -> dict:
+        total = self.hits + self.misses
+        rate = f"{self.hits / total * 100:.1f}%" if total > 0 else "N/A"
+        return {
+            "enabled": self.enabled,
+            "entries": len(self._store),
+            "hits": self.hits,
+            "misses": self.misses,
+            "hit_rate": rate,
+        }
+
+
+# Global singleton
+_result_cache = ResultCache()

akshare_cli/core/export.py

@@ -0,0 +1,115 @@
+"""
+Export functionality for AKShare CLI harness.
+
+Supports exporting DataFrames to CSV, JSON, Excel, and Markdown.
+"""
+
+import json
+import os
+from typing import Optional
+
+import pandas as pd
+
+
+def export_csv(df: pd.DataFrame, filepath: str, index: bool = False) -> str:
+    """Export DataFrame to CSV file."""
+    os.makedirs(os.path.dirname(os.path.abspath(filepath)), exist_ok=True)
+    df.to_csv(filepath, index=index, encoding="utf-8-sig")
+    return os.path.abspath(filepath)
+
+
+def export_json(df: pd.DataFrame, filepath: str, orient: str = "records") -> str:
+    """Export DataFrame to JSON file."""
+    os.makedirs(os.path.dirname(os.path.abspath(filepath)), exist_ok=True)
+    df.to_json(filepath, orient=orient, force_ascii=False, indent=2)
+    return os.path.abspath(filepath)
+
+
+def export_excel(df: pd.DataFrame, filepath: str, sheet_name: str = "Sheet1") -> str:
+    """Export DataFrame to Excel file."""
+    os.makedirs(os.path.dirname(os.path.abspath(filepath)), exist_ok=True)
+    df.to_excel(filepath, index=False, sheet_name=sheet_name)
+    return os.path.abspath(filepath)
+
+
+def export_markdown(df: pd.DataFrame, filepath: str) -> str:
+    """Export DataFrame to Markdown table file."""
+    os.makedirs(os.path.dirname(os.path.abspath(filepath)), exist_ok=True)
+    with open(filepath, "w", encoding="utf-8") as f:
+        f.write(df.to_markdown(index=False))
+        f.write("\n")
+    return os.path.abspath(filepath)
+
+
+def format_table(
+    df: pd.DataFrame,
+    max_rows: Optional[int] = None,
+    show_index: bool = False,
+    max_col_width: int = 30,
+) -> str:
+    """Format DataFrame as a text table for terminal display."""
+    if max_rows is not None and len(df) > max_rows:
+        display_df = pd.concat([df.head(max_rows // 2), df.tail(max_rows // 2)])
+        truncated = True
+        total_rows = len(df)
+    else:
+        display_df = df
+        truncated = False
+        total_rows = len(df)
+
+    # Truncate wide columns for display
+    display_df = display_df.copy()
+    for col in display_df.columns:
+        if display_df[col].dtype == object:
+            display_df[col] = display_df[col].astype(str).str[:max_col_width]
+
+    table = display_df.to_string(index=show_index)
+
+    if truncated:
+        table += f"\n\n... [{total_rows} rows total, showing {max_rows}]"
+
+    return table
+
+
+def format_json(df: pd.DataFrame, max_rows: Optional[int] = None) -> str:
+    """Format DataFrame as JSON string."""
+    if max_rows is not None:
+        df = df.head(max_rows)
+
+    records = json.loads(df.to_json(orient="records", force_ascii=False))
+    result = {
+        "total_rows": len(df),
+        "columns": list(df.columns),
+        "data": records,
+    }
+    return json.dumps(result, indent=2, ensure_ascii=False, default=str)
+
+
+def format_csv(df: pd.DataFrame, max_rows: Optional[int] = None) -> str:
+    """Format DataFrame as CSV string."""
+    if max_rows is not None:
+        df = df.head(max_rows)
+    return df.to_csv(index=False)
+
+
+def auto_export(
+    df: pd.DataFrame,
+    filepath: str,
+    **kwargs,
+) -> str:
+    """Export DataFrame based on file extension."""
+    ext = os.path.splitext(filepath)[1].lower()
+    exporters = {
+        ".csv": export_csv,
+        ".json": export_json,
+        ".xlsx": export_excel,
+        ".xls": export_excel,
+        ".md": export_markdown,
+    }
+    exporter = exporters.get(ext)
+    if exporter is None:
+        raise ValueError(
+            f"Unsupported file format: {ext}. "
+            f"Supported: {', '.join(exporters.keys())}"
+        )
+    return exporter(df, filepath, **kwargs)

akshare_cli/core/registry.py

@@ -0,0 +1,236 @@
+"""
+Function registry and dynamic dispatch for akshare functions.
+
+Provides discovery, introspection, and invocation of all akshare public functions.
+"""
+
+import importlib
+import inspect
+import re
+import sys
+from datetime import date as _date
+from functools import lru_cache
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from akshare_cli.core.cache import _result_cache, get_ttl
+
+# Matches YYYYMMDD date strings
+_DATE_DEFAULT_RE = re.compile(r"^\d{8}$")
+
+# Functions disabled due to broken upstream API
+DISABLED_FUNCTIONS: set = {
+    "index_news_sentiment_scope",
+}
+
+
+@lru_cache(maxsize=1)
+def _get_akshare_module():
+    """Lazily import the real akshare library (not the local namespace package).
+
+    Uses importlib to ensure we get the pip-installed akshare,
+    even when running inside the akshare_cli namespace.
+    """
+    ak = importlib.import_module("akshare")
+    # Verify we got the real library, not the local namespace sub-package
+    if not hasattr(ak, "__version__"):
+        raise ImportError(
+            "Imported 'akshare' does not appear to be the real akshare library. "
+            "Ensure akshare is installed: pip install akshare"
+        )
+    return ak
+
+
+@lru_cache(maxsize=1)
+def get_all_functions() -> Dict[str, Callable]:
+    """Return a dict of all public akshare functions keyed by name."""
+    ak = _get_akshare_module()
+    funcs = {}
+    for name in dir(ak):
+        if name.startswith("_"):
+            continue
+        if name in DISABLED_FUNCTIONS:
+            continue
+        obj = getattr(ak, name)
+        if callable(obj) and not isinstance(obj, type):
+            funcs[name] = obj
+    return funcs
+
+
+def get_function(name: str) -> Optional[Callable]:
+    """Get a single akshare function by exact name."""
+    return get_all_functions().get(name)
+
+
+def search_functions(keyword: str) -> List[str]:
+    """Search function names containing the keyword (case-insensitive)."""
+    keyword_lower = keyword.lower()
+    return sorted(
+        name for name in get_all_functions()
+        if keyword_lower in name.lower()
+    )
+
+
+def list_functions_by_domain(domain: str) -> List[str]:
+    """List functions whose name starts with a given domain prefix."""
+    prefix = domain.lower() + "_"
+    return sorted(
+        name for name in get_all_functions()
+        if name.lower().startswith(prefix)
+    )
+
+
+def get_function_info(name: str) -> Optional[Dict[str, Any]]:
+    """Get detailed info about a function: signature, parameters, docstring."""
+    func = get_function(name)
+    if func is None:
+        return None
+
+    sig = inspect.signature(func)
+    params = []
+    for pname, param in sig.parameters.items():
+        p_info = {
+            "name": pname,
+            "kind": str(param.kind),
+            "has_default": param.default is not inspect.Parameter.empty,
+        }
+        if p_info["has_default"]:
+            p_info["default"] = param.default
+        if param.annotation is not inspect.Parameter.empty:
+            p_info["type"] = str(param.annotation)
+        params.append(p_info)
+
+    doc = inspect.getdoc(func) or ""
+    return {
+        "name": name,
+        "params": params,
+        "docstring": doc,
+        "module": getattr(func, "__module__", "unknown"),
+    }
+
+
+def parse_param_value(value_str: str, param_info: Dict) -> Any:
+    """Parse a string parameter value into the appropriate Python type.
+
+    Respects the function's type annotation: if a parameter is typed as str,
+    the value is kept as-is (preserving leading zeros like "000001").
+    """
+    # If the parameter is annotated as str, keep it as a string
+    param_type = param_info.get("type", "")
+    if "str" in param_type:
+        return value_str
+
+    if value_str.lower() in ("none", "null"):
+        return None
+    if value_str.lower() in ("true", "yes"):
+        return True
+    if value_str.lower() in ("false", "no"):
+        return False
+
+    # Try int (but not if it has leading zeros — likely a code like "000001")
+    if not (len(value_str) > 1 and value_str.startswith("0") and value_str != "0"):
+        try:
+            return int(value_str)
+        except ValueError:
+            pass
+
+    # Try float
+    try:
+        return float(value_str)
+    except ValueError:
+        pass
+
+    return value_str
+
+
+def call_function(name: str, kwargs: Dict[str, str]) -> Any:
+    """
+    Call an akshare function by name with string kwargs.
+
+    Parameters are automatically converted from strings based on type hints
+    and defaults in the function signature.
+
+    Returns the function result (typically a pd.DataFrame).
+    Raises ValueError if the function is not found.
+    Raises any exception from the underlying akshare function.
+    """
+    func = get_function(name)
+    if func is None:
+        raise ValueError(f"Function '{name}' not found in akshare")
+
+    info = get_function_info(name)
+    param_map = {p["name"]: p for p in info["params"]}
+
+    converted_kwargs = {}
+    for key, val in kwargs.items():
+        if key in param_map:
+            converted_kwargs[key] = parse_param_value(val, param_map[key])
+        else:
+            converted_kwargs[key] = val
+
+    # Auto-fill date-like params that have stale YYYYMMDD defaults
+    _auto_fill_date_params(info["params"], converted_kwargs)
+
+    # Check cache
+    cached = _result_cache.get(name, converted_kwargs)
+    if cached is not None:
+        print(f"(cached) {name}", file=sys.stderr)
+        return cached
+
+    result = func(**converted_kwargs)
+
+    # Store in cache
+    ttl = get_ttl(name)
+    if ttl > 0:
+        _result_cache.put(name, converted_kwargs, result, ttl)
+
+    return result
+
+
+def _auto_fill_date_params(params: List[Dict], kwargs: Dict[str, Any]) -> None:
+    """Auto-fill date-like parameters with today's date when not provided by user.
+
+    A parameter is considered date-like if:
+    1. Its name contains 'date' (case-insensitive)
+    2. It has a default value matching YYYYMMDD (8-digit string)
+    3. The user did not explicitly provide it
+    """
+    today_str = _date.today().strftime("%Y%m%d")
+
+    for pinfo in params:
+        pname = pinfo["name"]
+
+        # Skip if user explicitly provided this param
+        if pname in kwargs:
+            continue
+
+        # Must have a default value
+        if not pinfo.get("has_default"):
+            continue
+        default = pinfo.get("default")
+        if default is None or not isinstance(default, str):
+            continue
+
+        # Parameter name must contain 'date'
+        if "date" not in pname.lower():
+            continue
+
+        # Default must look like YYYYMMDD
+        if not _DATE_DEFAULT_RE.match(default):
+            continue
+
+        # Auto-fill with today's date
+        kwargs[pname] = today_str
+        print(
+            f"Note: --{pname} not specified, using today: {today_str}",
+            file=sys.stderr,
+        )
+
+
+def get_domains() -> List[str]:
+    """Get all unique domain prefixes from function names."""
+    domains = set()
+    for name in get_all_functions():
+        parts = name.split("_")
+        if parts:
+            domains.add(parts[0])
+    return sorted(domains)

akshare_cli/core/session.py

@@ -0,0 +1,115 @@
+"""
+Session management for the AKShare CLI harness.
+
+Tracks state across commands in REPL mode: last result, history, preferences.
+"""
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+
+
+class Session:
+    """Manages CLI session state including result history and preferences."""
+
+    def __init__(self, session_dir: Optional[str] = None):
+        self._history: List[Dict[str, Any]] = []
+        self._last_result: Optional[pd.DataFrame] = None
+        self._last_function: Optional[str] = None
+        self._preferences: Dict[str, Any] = {
+            "output_format": "table",
+            "max_rows": 50,
+            "show_index": False,
+        }
+        self._session_dir = session_dir or os.path.join(
+            os.path.expanduser("~"), ".akshare-cli"
+        )
+        self._start_time = datetime.now()
+
+    @property
+    def last_result(self) -> Optional[pd.DataFrame]:
+        """Get the last query result."""
+        return self._last_result
+
+    @property
+    def last_function(self) -> Optional[str]:
+        """Get the name of the last function called."""
+        return self._last_function
+
+    @property
+    def history(self) -> List[Dict[str, Any]]:
+        """Get command history."""
+        return list(self._history)
+
+    @property
+    def preferences(self) -> Dict[str, Any]:
+        """Get current session preferences."""
+        return dict(self._preferences)
+
+    def record_call(self, func_name: str, kwargs: Dict, result: Any) -> None:
+        """Record a function call in the session history."""
+        entry = {
+            "timestamp": datetime.now().isoformat(),
+            "function": func_name,
+            "kwargs": kwargs,
+            "rows": len(result) if isinstance(result, pd.DataFrame) else None,
+            "columns": list(result.columns) if isinstance(result, pd.DataFrame) else None,
+        }
+        self._history.append(entry)
+
+        if isinstance(result, pd.DataFrame):
+            self._last_result = result
+        self._last_function = func_name
+
+    def set_preference(self, key: str, value: Any) -> None:
+        """Set a session preference."""
+        self._preferences[key] = value
+
+    def get_preference(self, key: str, default: Any = None) -> Any:
+        """Get a session preference."""
+        return self._preferences.get(key, default)
+
+    def save_history(self, filepath: Optional[str] = None) -> str:
+        """Save session history to a JSON file."""
+        if filepath is None:
+            os.makedirs(self._session_dir, exist_ok=True)
+            filepath = os.path.join(
+                self._session_dir,
+                f"session_{self._start_time.strftime('%Y%m%d_%H%M%S')}.json",
+            )
+
+        data = {
+            "start_time": self._start_time.isoformat(),
+            "end_time": datetime.now().isoformat(),
+            "preferences": self._preferences,
+            "history": self._history,
+        }
+
+        with open(filepath, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False, default=str)
+
+        return filepath
+
+    def clear(self) -> None:
+        """Clear session state."""
+        self._history.clear()
+        self._last_result = None
+        self._last_function = None
+
+    def summary(self) -> Dict[str, Any]:
+        """Get a summary of the current session."""
+        return {
+            "start_time": self._start_time.isoformat(),
+            "total_calls": len(self._history),
+            "last_function": self._last_function,
+            "last_result_shape": (
+                f"{self._last_result.shape[0]}x{self._last_result.shape[1]}"
+                if self._last_result is not None
+                else None
+            ),
+            "preferences": self._preferences,
+        }

akshare_cli/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests package for AKShare CLI harness."""

akshare_cli/tests/conftest.py

@@ -0,0 +1,37 @@
+"""
+Conftest for akshare CLI harness tests.
+
+Ensures the real akshare library is importable even when running
+inside the akshare_cli package.
+"""
+
+import importlib
+import sys
+
+
+def pytest_configure(config):
+    """Ensure 'akshare' resolves to the pip-installed library, not the local namespace."""
+    # If 'akshare' in sys.modules points to our local package, remove it
+    if "akshare" in sys.modules:
+        mod = sys.modules["akshare"]
+        mod_file = getattr(mod, "__file__", "") or ""
+        if "akshare_cli" in mod_file or "agent-harness" in mod_file:
+            del sys.modules["akshare"]
+
+    # Force import of the real akshare
+    # First, temporarily remove CWD and agent-harness paths from sys.path
+    original_path = sys.path[:]
+    sys.path = [
+        p for p in sys.path
+        if "agent-harness" not in p
+        or "site-packages" in p
+    ]
+
+    try:
+        real_ak = importlib.import_module("akshare")
+        if hasattr(real_ak, "__version__"):
+            sys.modules["akshare"] = real_ak
+    except ImportError:
+        pass
+    finally:
+        sys.path = original_path