From b0e7ab07f0c1cb081de94a38926c97f3d99d051a Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 18 Apr 2026 21:15:39 +0800 Subject: [PATCH 1/2] feat: organize query templates by subdirectory with dynamic category discovery Move query template YAML files into category subdirectories (basic/, business/, statistical/) and replace the hardcoded category field + enum list with automatic discovery from the directory structure. This allows new categories and templates to be added by simply placing YAML files in the appropriate subdirectory, with no code changes needed. All CLI parameters (--list, --category, --template-info, --template-use) remain unchanged in their interface and behavior. Fixes #43 --- src/pt_snap_cli/cli.py | 11 ++-- src/pt_snap_cli/completion.py | 6 ++- src/pt_snap_cli/query/config.py | 12 +++-- src/pt_snap_cli/query/registry.py | 54 ++++++++++++++++++- .../templates/{ => basic}/active_blocks.yaml | 1 - .../templates/{ => basic}/blocks_by_size.yaml | 1 - .../{ => basic}/events_by_action.yaml | 1 - .../{ => basic}/memory_timeline.yaml | 1 - .../{ => business}/leak_detection.yaml | 1 - .../{ => statistical}/callstack_analysis.yaml | 1 - .../{ => statistical}/memory_peak.yaml | 1 - tests/test_completion.py | 6 ++- 12 files changed, 72 insertions(+), 24 deletions(-) rename src/pt_snap_cli/query/templates/{ => basic}/active_blocks.yaml (97%) rename src/pt_snap_cli/query/templates/{ => basic}/blocks_by_size.yaml (97%) rename src/pt_snap_cli/query/templates/{ => basic}/events_by_action.yaml (97%) rename src/pt_snap_cli/query/templates/{ => basic}/memory_timeline.yaml (98%) rename src/pt_snap_cli/query/templates/{ => business}/leak_detection.yaml (97%) rename src/pt_snap_cli/query/templates/{ => statistical}/callstack_analysis.yaml (97%) rename src/pt_snap_cli/query/templates/{ => statistical}/memory_peak.yaml (99%) diff --git a/src/pt_snap_cli/cli.py b/src/pt_snap_cli/cli.py index 7884ec8..72d8f9b 100644 --- a/src/pt_snap_cli/cli.py +++ b/src/pt_snap_cli/cli.py @@ -198,7 +198,7 @@ def query_database( str | None, typer.Option( "--category", - help="Filter templates by category (basic, statistical, business)", + help="Filter templates by category", autocompletion=complete_categories, ), ] = None, @@ -232,6 +232,7 @@ def query_database( """ from pt_snap_cli.query import QueryExecutor from pt_snap_cli.query.registry import ( + discover_categories, get_template_info, list_by_category_with_details, ) @@ -241,12 +242,8 @@ def query_database( list_templates = True if list_templates: - categories = ["basic", "statistical", "business"] - category_labels = { - "basic": "Basic Queries", - "statistical": "Statistical Queries", - "business": "Business Queries", - } + categories = discover_categories() + category_labels = {cat: cat.replace("_", " ").title() + " Queries" for cat in categories} if category is not None and category not in categories: typer.secho( diff --git a/src/pt_snap_cli/completion.py b/src/pt_snap_cli/completion.py index 89557d1..16a90c8 100644 --- a/src/pt_snap_cli/completion.py +++ b/src/pt_snap_cli/completion.py @@ -17,8 +17,10 @@ def complete_template_names() -> list[str]: def complete_categories() -> list[str]: - """Return valid category names for shell completion.""" - return ["basic", "statistical", "business"] + """Return valid category names from template directory structure for shell completion.""" + from pt_snap_cli.query.registry import discover_categories + + return discover_categories() def _resolve_db_for_completion() -> Path | None: diff --git a/src/pt_snap_cli/query/config.py b/src/pt_snap_cli/query/config.py index d2fdfde..7ba56c3 100644 --- a/src/pt_snap_cli/query/config.py +++ b/src/pt_snap_cli/query/config.py @@ -90,11 +90,13 @@ def validate_params(self, params: dict[str, Any]) -> dict[str, Any]: return validated @classmethod - def from_dict(cls, data: dict[str, Any]) -> QueryTemplate: + def from_dict(cls, data: dict[str, Any], default_category: str | None = None) -> QueryTemplate: """Create QueryTemplate from dictionary. Args: data: Dictionary with template data. + default_category: Category inferred from directory structure when + not explicitly declared in the YAML. Returns: QueryTemplate instance. @@ -116,7 +118,7 @@ def from_dict(cls, data: dict[str, Any]) -> QueryTemplate: parameters=parameters, query=data.get("query", ""), output_schema=data.get("output_schema", []), - category=data.get("category", "basic"), + category=data.get("category") or default_category or "basic", ) @@ -147,11 +149,13 @@ def list_queries(self) -> list[str]: return list(self.queries.keys()) @classmethod - def load_yaml(cls, path: str | Path) -> QueryConfig: + def load_yaml(cls, path: str | Path, default_category: str | None = None) -> QueryConfig: """Load configuration from YAML file. Args: path: Path to YAML file. + default_category: Category inferred from directory structure when + not explicitly declared in the YAML. Returns: QueryConfig instance. @@ -170,7 +174,7 @@ def load_yaml(cls, path: str | Path) -> QueryConfig: queries = {} for name, query_data in data.get("queries", {}).items(): query_data["name"] = name - queries[name] = QueryTemplate.from_dict(query_data) + queries[name] = QueryTemplate.from_dict(query_data, default_category=default_category) return cls( version=data.get("version", "1.0"), diff --git a/src/pt_snap_cli/query/registry.py b/src/pt_snap_cli/query/registry.py index cd93231..81a7893 100644 --- a/src/pt_snap_cli/query/registry.py +++ b/src/pt_snap_cli/query/registry.py @@ -248,9 +248,58 @@ def list_by_category_with_details(category: str) -> list[dict[str, str]]: return _registry.list_by_category_with_details(category) +def get_template_dir() -> Path: + """Return the path to the template directory.""" + return Path(__file__).parent / "templates" + + +def discover_categories(template_dir: Path | str | None = None) -> list[str]: + """Discover category names from subdirectory structure. + + Args: + template_dir: Path to template directory. Defaults to package templates dir. + + Returns: + Sorted list of category names (subdirectory names). + """ + if template_dir is None: + template_dir = get_template_dir() + else: + template_dir = Path(template_dir) + + if not template_dir.exists(): + return [] + + return sorted( + d.name for d in template_dir.iterdir() + if d.is_dir() and not d.name.startswith("_") and not d.name.startswith(".") + ) + + +def _infer_category(yaml_file: Path, template_dir: Path) -> str | None: + """Infer category from the parent directory of a YAML file. + + Returns None when the file is directly under the template root + (not in a subdirectory), letting YAML's own category field or + default take precedence. + """ + try: + parent = yaml_file.resolve().parent.name + template_root = template_dir.resolve().name + if parent != template_root: + return parent + except OSError: + pass + return None + + def _load_yaml_templates(template_dir: Path | str | None = None) -> None: """Load all YAML templates from the template directory. + Scans recursively (``**/*.yaml``) so that each subdirectory + acts as a category. The subdirectory name is used as the + template's category when the YAML does not declare one. + Args: template_dir: Path to template directory. Defaults to package templates dir. """ @@ -262,9 +311,10 @@ def _load_yaml_templates(template_dir: Path | str | None = None) -> None: if not template_dir.exists(): return - for yaml_file in template_dir.glob("*.yaml"): + for yaml_file in sorted(template_dir.glob("**/*.yaml")): try: - config = QueryConfig.load_yaml(yaml_file) + default_cat = _infer_category(yaml_file, template_dir) + config = QueryConfig.load_yaml(yaml_file, default_category=default_cat) for _query_name, template in config.queries.items(): _registry.register(template) except Exception as e: diff --git a/src/pt_snap_cli/query/templates/active_blocks.yaml b/src/pt_snap_cli/query/templates/basic/active_blocks.yaml similarity index 97% rename from src/pt_snap_cli/query/templates/active_blocks.yaml rename to src/pt_snap_cli/query/templates/basic/active_blocks.yaml index b21339a..f66ef57 100644 --- a/src/pt_snap_cli/query/templates/active_blocks.yaml +++ b/src/pt_snap_cli/query/templates/basic/active_blocks.yaml @@ -1,7 +1,6 @@ version: "1.0" queries: active_blocks: - category: basic description: Get active memory blocks (active=1) devices: - all diff --git a/src/pt_snap_cli/query/templates/blocks_by_size.yaml b/src/pt_snap_cli/query/templates/basic/blocks_by_size.yaml similarity index 97% rename from src/pt_snap_cli/query/templates/blocks_by_size.yaml rename to src/pt_snap_cli/query/templates/basic/blocks_by_size.yaml index e72969e..5020f7a 100644 --- a/src/pt_snap_cli/query/templates/blocks_by_size.yaml +++ b/src/pt_snap_cli/query/templates/basic/blocks_by_size.yaml @@ -1,7 +1,6 @@ version: "1.0" queries: blocks_by_size: - category: basic description: Get blocks filtered by size range devices: - all diff --git a/src/pt_snap_cli/query/templates/events_by_action.yaml b/src/pt_snap_cli/query/templates/basic/events_by_action.yaml similarity index 97% rename from src/pt_snap_cli/query/templates/events_by_action.yaml rename to src/pt_snap_cli/query/templates/basic/events_by_action.yaml index 37ec323..0cc71fc 100644 --- a/src/pt_snap_cli/query/templates/events_by_action.yaml +++ b/src/pt_snap_cli/query/templates/basic/events_by_action.yaml @@ -1,7 +1,6 @@ version: "1.0" queries: events_by_action: - category: basic description: Get events filtered by action type devices: - all diff --git a/src/pt_snap_cli/query/templates/memory_timeline.yaml b/src/pt_snap_cli/query/templates/basic/memory_timeline.yaml similarity index 98% rename from src/pt_snap_cli/query/templates/memory_timeline.yaml rename to src/pt_snap_cli/query/templates/basic/memory_timeline.yaml index 2e7381e..f926d4a 100644 --- a/src/pt_snap_cli/query/templates/memory_timeline.yaml +++ b/src/pt_snap_cli/query/templates/basic/memory_timeline.yaml @@ -1,7 +1,6 @@ version: "1.0" queries: memory_timeline: - category: basic description: Get memory allocation timeline for analysis devices: - all diff --git a/src/pt_snap_cli/query/templates/leak_detection.yaml b/src/pt_snap_cli/query/templates/business/leak_detection.yaml similarity index 97% rename from src/pt_snap_cli/query/templates/leak_detection.yaml rename to src/pt_snap_cli/query/templates/business/leak_detection.yaml index af7fa73..bb33987 100644 --- a/src/pt_snap_cli/query/templates/leak_detection.yaml +++ b/src/pt_snap_cli/query/templates/business/leak_detection.yaml @@ -1,7 +1,6 @@ version: "1.0" queries: leak_detection: - category: business description: Detect memory leaks by finding allocations without free events devices: - all diff --git a/src/pt_snap_cli/query/templates/callstack_analysis.yaml b/src/pt_snap_cli/query/templates/statistical/callstack_analysis.yaml similarity index 97% rename from src/pt_snap_cli/query/templates/callstack_analysis.yaml rename to src/pt_snap_cli/query/templates/statistical/callstack_analysis.yaml index 01ef2e9..f4fb399 100644 --- a/src/pt_snap_cli/query/templates/callstack_analysis.yaml +++ b/src/pt_snap_cli/query/templates/statistical/callstack_analysis.yaml @@ -1,7 +1,6 @@ version: "1.0" queries: callstack_analysis: - category: statistical description: Analyze memory allocation by callstack devices: - all diff --git a/src/pt_snap_cli/query/templates/memory_peak.yaml b/src/pt_snap_cli/query/templates/statistical/memory_peak.yaml similarity index 99% rename from src/pt_snap_cli/query/templates/memory_peak.yaml rename to src/pt_snap_cli/query/templates/statistical/memory_peak.yaml index 6f17a89..10a203a 100644 --- a/src/pt_snap_cli/query/templates/memory_peak.yaml +++ b/src/pt_snap_cli/query/templates/statistical/memory_peak.yaml @@ -1,7 +1,6 @@ version: "1.0" queries: memory_peak: - category: statistical description: Get peak memory metrics from trace events with corresponding event IDs devices: - all diff --git a/tests/test_completion.py b/tests/test_completion.py index 18ac456..32970db 100644 --- a/tests/test_completion.py +++ b/tests/test_completion.py @@ -72,10 +72,12 @@ def test_returns_sorted(self): class TestCompleteCategories: def test_returns_three_categories(self): result = complete_categories() - assert result == ["basic", "statistical", "business"] + assert len(result) == 3 + assert set(result) == {"basic", "statistical", "business"} def test_order_is_fixed(self): - assert complete_categories() == ["basic", "statistical", "business"] + result = complete_categories() + assert result == sorted(result) class TestCompleteDeviceIds: From 834af64ae14b5e1ea4b71947def8f445486a2d6b Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 18 Apr 2026 21:19:10 +0800 Subject: [PATCH 2/2] style: apply black formatting to registry.py Fixes formatting from dynamic category discovery changes. --- src/pt_snap_cli/query/registry.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/pt_snap_cli/query/registry.py b/src/pt_snap_cli/query/registry.py index 81a7893..7671d64 100644 --- a/src/pt_snap_cli/query/registry.py +++ b/src/pt_snap_cli/query/registry.py @@ -271,7 +271,8 @@ def discover_categories(template_dir: Path | str | None = None) -> list[str]: return [] return sorted( - d.name for d in template_dir.iterdir() + d.name + for d in template_dir.iterdir() if d.is_dir() and not d.name.startswith("_") and not d.name.startswith(".") )