akshare-cli 0.2.2__tar.gz → 0.2.4__tar.gz

{akshare_cli-0.2.2 → akshare_cli-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akshare-cli
-Version: 0.2.2
+Version: 0.2.4
 Summary: CLI harness for the AKShare financial data library
 Author: cli-anything
 License: MIT

{akshare_cli-0.2.2 → akshare_cli-0.2.4}/akshare_cli/__init__.py

@@ -1,3 +1,3 @@
 """AKShare CLI Harness - Sub-package"""
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"

{akshare_cli-0.2.2 → akshare_cli-0.2.4}/akshare_cli/cli.py

@@ -25,6 +25,12 @@ import click
 import pandas as pd
 
 from akshare_cli.core.cache import _result_cache
+from akshare_cli.core.catalog import (
+    get_direct_functions,
+    get_function_path,
+    get_functions,
+    list_categories,
+)
 from akshare_cli.core.registry import (
     call_function,
     get_all_functions,
@@ -57,9 +63,8 @@ class OutputConfig:
         self.max_rows = None
         self.show_index = False
         self.no_header = False
-        self.sort_order = "desc"
 
-    def apply(self, use_json=False, use_csv=False, output_file=None, limit=None, no_header=False, sort=None):
+    def apply(self, use_json=False, use_csv=False, output_file=None, limit=None, no_header=False):
         """Apply output options, only overriding if explicitly set."""
         if use_json:
             self.format = "json"
@@ -71,24 +76,21 @@ class OutputConfig:
             self.max_rows = limit
         if no_header:
             self.no_header = no_header
-        if sort is not None:
-            self.sort_order = sort
 
 
 _output_config = OutputConfig()
 
 
 def output_options(func):
-    """Decorator that adds --json/--csv/--output/--limit/--no-header/--sort to any command."""
+    """Decorator that adds --json/--csv/--output/--limit/--no-header to any command."""
     @click.option("--json", "use_json", is_flag=True, help="Output as JSON.")
     @click.option("--csv", "use_csv", is_flag=True, help="Output as CSV.")
     @click.option("--output", "-o", "output_file", default=None, help="Save output to file.")
     @click.option("--limit", "-n", "limit", type=int, default=None, help="Limit number of rows.")
     @click.option("--no-header", "no_header", is_flag=True, help="Suppress table headers.")
-    @click.option("--sort", "sort", type=click.Choice(["asc", "desc"]), default=None, help="Sort order: desc (newest first, default) or asc (oldest first).")
     @functools.wraps(func)
-    def wrapper(*args, use_json=False, use_csv=False, output_file=None, limit=None, no_header=False, sort=None, **kwargs):
-        _output_config.apply(use_json, use_csv, output_file, limit, no_header, sort)
+    def wrapper(*args, use_json=False, use_csv=False, output_file=None, limit=None, no_header=False, **kwargs):
+        _output_config.apply(use_json, use_csv, output_file, limit, no_header)
         return func(*args, **kwargs)
     return wrapper
 
@@ -107,10 +109,6 @@ def _handle_result(result, func_name: str = "", kwargs: dict = None):
                 click.echo("No data returned (empty DataFrame).")
             return
 
-        # Apply sort order before display/limit
-        if _output_config.sort_order == "desc":
-            result = result.iloc[::-1].reset_index(drop=True)
-
         output = display_result(
             result,
             output_format=_output_config.format,
@@ -138,16 +136,15 @@ def _handle_result(result, func_name: str = "", kwargs: dict = None):
 @click.option("--output", "-o", "output_file", help="Save output to file.")
 @click.option("--limit", "-n", type=int, help="Limit number of rows.")
 @click.option("--no-header", is_flag=True, help="Suppress table headers.")
-@click.option("--sort", type=click.Choice(["asc", "desc"]), default=None, help="Sort order: desc (newest first, default) or asc (oldest first).")
 @click.option("--no-cache", is_flag=True, help="禁用结果缓存，强制从 API 获取最新数据。")
 @click.option("--retry", type=int, default=0, help="网络失败时自动重试次数 (指数退避，默认 0 不重试)")
 @click.version_option(version="0.1.0", prog_name="akshare-cli")
 @click.pass_context
-def cli(ctx, use_json, use_csv, output_file, limit, no_header, sort, no_cache, retry):
+def cli(ctx, use_json, use_csv, output_file, limit, no_header, no_cache, retry):
     """AKShare CLI - 命令行金融数据工具
 
     支持调用 akshare 库的 1090+ 个函数，获取股票、基金、期货、债券、外汇、宏观等金融数据。
-    输出选项 (--json, --csv, --output, --limit, --sort) 可以放在子命令的前面或后面。
+    输出选项 (--json, --csv, --output, --limit) 可以放在子命令的前面或后面。
 
     \b
     基本用法:
@@ -168,7 +165,7 @@ def cli(ctx, use_json, use_csv, output_file, limit, no_header, sort, no_cache, r
     """
     ctx.ensure_object(dict)
 
-    _output_config.apply(use_json, use_csv, output_file, limit, no_header, sort)
+    _output_config.apply(use_json, use_csv, output_file, limit, no_header)
 
     if no_cache:
         _result_cache.enabled = False
@@ -227,7 +224,6 @@ def cmd_call(ctx, params):
     call_output_csv = False
     call_output_file = None
     call_limit = None
-    call_sort = None
     full_help = False
 
     filtered = []
@@ -252,10 +248,6 @@ def cmd_call(ctx, params):
             except ValueError:
                 pass
             i += 2
-        elif p == "--sort" and i + 1 < len(remaining):
-            if remaining[i + 1] in ("asc", "desc"):
-                call_sort = remaining[i + 1]
-            i += 2
         elif p == "--no-header":
             _output_config.no_header = True
             i += 1
@@ -269,7 +261,7 @@ def cmd_call(ctx, params):
             filtered.append(p)
             i += 1
 
-    _output_config.apply(call_output_json, call_output_csv, call_output_file, call_limit, sort=call_sort)
+    _output_config.apply(call_output_json, call_output_csv, call_output_file, call_limit)
 
     # Second pass: the first non-flag token is the function name
     func_name = None
@@ -282,7 +274,22 @@ def cmd_call(ctx, params):
 
     # Handle --full-help
     if full_help:
-        _print_full_help(func_name)
+        # 支持批量查询：多个函数名用空格或逗号分隔
+        func_names = []
+        if func_name:
+            # 处理逗号分隔：call --full-help fn1,fn2,fn3
+            for tok in [func_name] + [t for t in func_params if not t.startswith("--")]:
+                for part in tok.split(","):
+                    part = part.strip()
+                    if part:
+                        func_names.append(part)
+        if len(func_names) <= 1:
+            _print_full_help(func_names[0] if func_names else None)
+        else:
+            for i, fn in enumerate(func_names):
+                if i > 0:
+                    click.echo("\n" + "─" * 60 + "\n")
+                _print_full_help(fn, exit_on_error=False)
         return
 
     if not func_name:
@@ -333,7 +340,7 @@ def _clean_docstring(docstring: str) -> str:
     return "\n".join(lines) if lines else ""
 
 
-def _print_full_help(func_name: Optional[str] = None) -> None:
+def _print_full_help(func_name: Optional[str] = None, exit_on_error: bool = True) -> None:
     """Print detailed usage help for one function or list popular examples."""
     if func_name:
         info = get_function_info(func_name)
@@ -344,7 +351,9 @@ def _print_full_help(func_name: Optional[str] = None) -> None:
                 click.echo("\n你是不是想找:")
                 for s in suggestions[:5]:
                     click.echo(f"  {s}")
-            sys.exit(1)
+            if exit_on_error:
+                sys.exit(1)
+            return
 
         source = get_function_source(info["name"])
         clean_desc = _clean_docstring(info["docstring"])
@@ -591,10 +600,17 @@ def cmd_info(func_name):
         sys.exit(1)
 
     if _output_config.format == "json":
+        # 注入分类路径到 JSON 输出
+        cat_path = get_function_path(func_name)
+        if cat_path:
+            info["category"] = " > ".join(cat_path)
         click.echo(json.dumps(info, indent=2, ensure_ascii=False, default=str))
     else:
         click.echo(f"Function: {info['name']}")
         click.echo(f"Module:   {info['module']}")
+        cat_path = get_function_path(func_name)
+        if cat_path:
+            click.echo(f"分类:     {' > '.join(cat_path)}")
         click.echo()
         if info["params"]:
             click.echo("Parameters:")
@@ -610,6 +626,107 @@ def cmd_info(func_name):
             click.echo(f"  {info['docstring']}")
 
 
+# ─── BROWSE COMMAND ─────────────────────────────────────────────────────────
+
+
+@cli.command("browse")
+@click.argument("path", default="", required=False)
+@click.option("--func", "func_name", default=None, help="查询某函数所属分类路径。")
+@output_options
+def cmd_browse(path, func_name):
+    """按目录浏览 akshare 函数分类
+
+    基于 akshare 官方文档的层级结构，逐级浏览函数分类。
+    使用 '/' 分隔路径层级。
+
+    \b
+    示例:
+        akshare-cli browse                           # 顶级分类
+        akshare-cli browse 股票数据                    # 子分类
+        akshare-cli browse 股票数据/A股/历史行情数据     # 函数列表
+        akshare-cli browse --func stock_zh_a_hist    # 查函数归属
+        akshare-cli browse --json                    # JSON 输出
+    """
+    if func_name:
+        _browse_func(func_name)
+        return
+    _browse_path(path)
+
+
+def _browse_func(func_name):
+    """查询函数所属分类路径。"""
+    cat_path = get_function_path(func_name)
+    if cat_path is None:
+        if _output_config.format == "json":
+            click.echo(json.dumps({"error": f"Function '{func_name}' not found in catalog"}, indent=2))
+        else:
+            print_error(f"Function '{func_name}' not found in catalog.")
+        sys.exit(1)
+
+    if _output_config.format == "json":
+        click.echo(json.dumps({"function": func_name, "path": cat_path, "display": " > ".join(cat_path)}, indent=2, ensure_ascii=False))
+    else:
+        click.echo(f"{func_name}")
+        click.echo(f"  分类: {' > '.join(cat_path)}")
+
+
+def _browse_path(path):
+    """浏览目录路径。"""
+    categories = list_categories(path)
+    direct_funcs = get_direct_functions(path) if path else []
+
+    if not categories and not direct_funcs:
+        # 路径不存在
+        if _output_config.format == "json":
+            click.echo(json.dumps({"error": f"Path '{path}' not found"}, indent=2))
+        else:
+            print_error(f"Path '{path}' not found.")
+        sys.exit(1)
+
+    if _output_config.format == "json":
+        data = {}
+        if path:
+            data["path"] = path
+        if categories:
+            data["categories"] = [{"name": name, "count": count} for name, count in categories]
+        if direct_funcs:
+            data["functions"] = direct_funcs
+        click.echo(json.dumps(data, indent=2, ensure_ascii=False))
+        return
+
+    # Table output
+    if path:
+        click.echo(path.replace("/", " > "))
+        click.echo()
+
+    if categories:
+        if path:
+            click.echo("子分类:")
+        # 计算对齐宽度
+        max_width = max(_display_width(name) for name, _ in categories)
+        for name, count in categories:
+            padding = " " * (max_width - _display_width(name) + 2)
+            click.echo(f"  {name}{padding}({count} 个函数)")
+
+    if direct_funcs:
+        if categories:
+            click.echo()
+        click.echo("函数:")
+        for fn in direct_funcs:
+            click.echo(f"  {fn}")
+
+
+def _display_width(s):
+    """计算字符串显示宽度（中文字符宽度为 2）。"""
+    width = 0
+    for ch in s:
+        if '\u4e00' <= ch <= '\u9fff' or '\u3000' <= ch <= '\u303f' or '\uff00' <= ch <= '\uffef':
+            width += 2
+        else:
+            width += 1
+    return width
+
+
 # ─── DOMAIN SHORTCUTS ────────────────────────────────────────────────────────
 
 

akshare_cli-0.2.4/akshare_cli/core/catalog.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""目录查询模块 — 基于 catalog.json 提供函数分类浏览。"""
+
+import json
+import os
+from typing import Dict, List, Optional, Tuple
+
+_catalog = None
+
+
+def load_catalog() -> dict:
+    """加载 catalog.json（模块级缓存）。"""
+    global _catalog
+    if _catalog is not None:
+        return _catalog
+    catalog_path = os.path.join(os.path.dirname(__file__), "..", "data", "catalog.json")
+    catalog_path = os.path.normpath(catalog_path)
+    with open(catalog_path, encoding="utf-8") as f:
+        _catalog = json.load(f)
+    return _catalog
+
+
+def _resolve_node(path: str) -> Optional[dict]:
+    """根据 '/' 分隔路径定位目录节点，返回 None 表示路径不存在。"""
+    catalog = load_catalog()
+    node = {"children": catalog["categories"]}
+    if not path:
+        return node
+    parts = [p.strip() for p in path.split("/") if p.strip()]
+    for part in parts:
+        children = node.get("children", {})
+        if part not in children:
+            return None
+        node = children[part]
+    return node
+
+
+def list_categories(path: str = "") -> List[Tuple[str, int]]:
+    """列出子目录及其函数数量。
+
+    返回 [(name, func_count), ...]，按名称排序。
+    """
+    node = _resolve_node(path)
+    if node is None:
+        return []
+    children = node.get("children", {})
+    result = []
+    for name, child in children.items():
+        count = _count_functions(child)
+        result.append((name, count))
+    return sorted(result, key=lambda x: x[0])
+
+
+def _count_functions(node: dict) -> int:
+    """递归统计节点下的函数总数。"""
+    count = len(node.get("functions", []))
+    for child in node.get("children", {}).values():
+        count += _count_functions(child)
+    return count
+
+
+def get_functions(path: str) -> List[str]:
+    """返回某目录下所有函数（含子目录递归），排序。"""
+    node = _resolve_node(path)
+    if node is None:
+        return []
+    funcs = []
+    _collect_functions(node, funcs)
+    return sorted(funcs)
+
+
+def _collect_functions(node: dict, result: list):
+    """递归收集函数名。"""
+    result.extend(node.get("functions", []))
+    for child in node.get("children", {}).values():
+        _collect_functions(child, result)
+
+
+def get_function_path(func_name: str) -> Optional[List[str]]:
+    """查函数所属目录路径，返回 None 表示未找到。"""
+    catalog = load_catalog()
+    return catalog["func_to_path"].get(func_name)
+
+
+def get_direct_functions(path: str) -> List[str]:
+    """返回某目录直接包含的函数（不递归子目录）。"""
+    node = _resolve_node(path)
+    if node is None:
+        return []
+    return sorted(node.get("functions", []))

{akshare_cli-0.2.2 → akshare_cli-0.2.4}/akshare_cli/core/registry.py

@@ -84,13 +84,51 @@ def get_function(name: str) -> Optional[Callable]:
 
 
 def search_functions(keyword: str) -> List[str]:
-    """Search function names containing the keyword (case-insensitive)."""
+    """Search functions by name, docstring, or catalog category path.
+
+    Matches against:
+    1. Function name (case-insensitive)
+    2. First line of docstring (supports Chinese)
+    3. Catalog category path (Chinese category names)
+    """
     keyword_lower = keyword.lower()
-    return sorted(
-        name for name in get_all_functions()
+    all_funcs = get_all_functions()
+
+    # Phase 1: name match (always fast)
+    name_matches = set(
+        name for name in all_funcs
         if keyword_lower in name.lower()
     )
 
+    # Phase 2: docstring match (for Chinese keywords or broader search)
+    doc_matches = set()
+    for name in all_funcs:
+        if name in name_matches:
+            continue
+        func = get_function(name)
+        if func and func.__doc__:
+            first_line = func.__doc__.strip().split("\n")[0]
+            if keyword_lower in first_line.lower():
+                doc_matches.add(name)
+
+    # Phase 3: catalog category path match
+    cat_matches = set()
+    try:
+        from akshare_cli.core.catalog import load_catalog
+        catalog = load_catalog()
+        func_to_path = catalog.get("func_to_path", {})
+        for fname, path_list in func_to_path.items():
+            if fname in name_matches or fname in doc_matches:
+                continue
+            path_str = "/".join(path_list).lower()
+            if keyword_lower in path_str:
+                if fname in all_funcs:
+                    cat_matches.add(fname)
+    except Exception:
+        pass
+
+    return sorted(name_matches | doc_matches | cat_matches)
+
 
 def list_functions_by_domain(domain: str) -> List[str]:
     """List functions whose name starts with a given domain prefix."""

{akshare_cli-0.2.2 → akshare_cli-0.2.4}/akshare_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akshare-cli
-Version: 0.2.2
+Version: 0.2.4
 Summary: CLI harness for the AKShare financial data library
 Author: cli-anything
 License: MIT

{akshare_cli-0.2.2 → akshare_cli-0.2.4}/akshare_cli.egg-info/SOURCES.txt

@@ -10,11 +10,13 @@ akshare_cli.egg-info/requires.txt
 akshare_cli.egg-info/top_level.txt
 akshare_cli/core/__init__.py
 akshare_cli/core/cache.py
+akshare_cli/core/catalog.py
 akshare_cli/core/docsource.py
 akshare_cli/core/export.py
 akshare_cli/core/fallback.py
 akshare_cli/core/registry.py
 akshare_cli/core/session.py
+akshare_cli/data/__init__.py
 akshare_cli/tests/__init__.py
 akshare_cli/tests/conftest.py
 akshare_cli/tests/test_cache.py

{akshare_cli-0.2.2 → akshare_cli-0.2.4}/setup.py

@@ -4,7 +4,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="akshare-cli",
-    version="0.2.2",
+    version="0.2.4",
     description="CLI harness for the AKShare financial data library",
     long_description=open("README.md", encoding="utf-8").read(),
     long_description_content_type="text/markdown",