pretty-mod 0.2.0__tar.gz → 0.2.1__tar.gz

{pretty_mod-0.2.0 → pretty_mod-0.2.1}/CLAUDE.md

@@ -2,30 +2,33 @@
 
 `pretty-mod` is a python package built on pyo3 to explore python packages for LLMs
 
-# Getting oriented
+## getting oriented
 
 - read @RELEASE_NOTES.md, @README.md, @pyproject.toml, and @justfile
 
-# run the tests
+## run the tests
 
 ```
 just test
 ```
 
-if for some reason you need to only build (just test does this automatically)
+if you only need to build (`just test` runs `just build` automatically)
 
 ```
 just build
 ```
 
-# run the local python package
+## run the local python package
 
 ```
 uv run pretty-mod tree fastapi.routing
 ```
 
-# run the remote python package
+## run the remote python package
 
 ```
 uvx pretty-mod tree fastapi.routing
-```
+```
+
+# IMPORTANT
+- avoid breaking changes to the public api defined by type stubs in @python/pretty_mod/_pretty_mod.pyi

{pretty_mod-0.2.0 → pretty_mod-0.2.1}/Cargo.lock

@@ -1017,7 +1017,7 @@ dependencies = [
 
 [[package]]
 name = "pretty-mod"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "flate2",
  "pyo3",

{pretty_mod-0.2.0 → pretty_mod-0.2.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pretty-mod"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2021"
 
 [lib]

{pretty_mod-0.2.0 → pretty_mod-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pretty-mod
-Version: 0.2.0
+Version: 0.2.1
 License-File: LICENSE
 Summary: A python module tree explorer for LLMs (and humans)
 Author-email: zzstoatzz <thrast36@gmail.com>
@@ -12,11 +12,9 @@ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 
 a python module tree explorer for LLMs (and humans)
 
-> [!IMPORTANT]
-> for all versions `>=0.1.0`, wheels for different operating systems are built via `maturin` and published to pypi, install `<0.1.0` for a pure python version
-
 > [!NOTE]
-> Starting from v0.2.0, output includes colors by default. Use `PRETTY_MOD_NO_COLOR=1` to disable.
+> - For all versions `>=0.1.0`, wheels for different operating systems are built via `maturin` and published to PyPI. Install `<0.1.0` for a pure Python version.
+> - Starting from v0.2.0, output includes colors by default. Use `PRETTY_MOD_NO_COLOR=1` to disable.
 
 ```bash
 # Explore module structure
@@ -89,6 +87,10 @@ pretty-mod tree requests --depth 3
 
 # Display function signatures  
 pretty-mod sig json:loads
+
+# Get JSON output for programmatic use
+pretty-mod tree json -o json | jq '.tree.submodules | keys'
+pretty-mod sig json:dumps -o json | jq '.parameters'
 pretty-mod sig os.path:join
 
 # Explore packages even without having them installed

{pretty_mod-0.2.0 → pretty_mod-0.2.1}/README.md

@@ -2,11 +2,9 @@
 
 a python module tree explorer for LLMs (and humans)
 
-> [!IMPORTANT]
-> for all versions `>=0.1.0`, wheels for different operating systems are built via `maturin` and published to pypi, install `<0.1.0` for a pure python version
-
 > [!NOTE]
-> Starting from v0.2.0, output includes colors by default. Use `PRETTY_MOD_NO_COLOR=1` to disable.
+> - For all versions `>=0.1.0`, wheels for different operating systems are built via `maturin` and published to PyPI. Install `<0.1.0` for a pure Python version.
+> - Starting from v0.2.0, output includes colors by default. Use `PRETTY_MOD_NO_COLOR=1` to disable.
 
 ```bash
 # Explore module structure
@@ -79,6 +77,10 @@ pretty-mod tree requests --depth 3
 
 # Display function signatures  
 pretty-mod sig json:loads
+
+# Get JSON output for programmatic use
+pretty-mod tree json -o json | jq '.tree.submodules | keys'
+pretty-mod sig json:dumps -o json | jq '.parameters'
 pretty-mod sig os.path:join
 
 # Explore packages even without having them installed

{pretty_mod-0.2.0 → pretty_mod-0.2.1}/RELEASE_NOTES.md

@@ -1,3 +1,28 @@
+# Release Notes - v0.2.1
+
+## 📊 JSON Output Support & Better Type Annotation Handling
+
+This release adds machine-readable JSON output and fixes a critical bug with complex type annotations.
+
+### ✨ New Features
+
+- **📊 JSON Output Support**: Export tree and signature data as JSON for programmatic use
+  - `pretty-mod tree json -o json` - Get module structure as JSON
+  - `pretty-mod sig json:dumps -o json` - Get function signature as JSON
+  - Perfect for piping to `jq` or other JSON processors
+  - Follows the Kubernetes pattern of `-o <format>` for output selection
+  - Example: `pretty-mod tree json -o json | jq '.tree.submodules | keys'`
+
+### 🏗️ Technical Improvements
+
+- **Visitor Pattern**: Implemented output formatters using the Visitor pattern for extensibility
+  - Clean separation between data structure and formatting
+  - Easy to add new output formats in the future
+  - Type-safe implementation using Rust traits
+
+
+---
+
 # Release Notes - v0.2.0
 
 ## 🎨 Customizable Display & Colors + Enhanced Signature Support
@@ -64,6 +89,10 @@ This release introduces customizable display characters, color output, full type
 
 ### 🐛 Bug Fixes
 
+- **Complex type annotations**: Fixed parameter splitting for nested generics
+  - Previously: `Callable[[Any], str]` would split incorrectly on the comma
+  - Now: Properly handles all nested brackets and quotes in type annotations
+  - Affects all complex types like `Dict[str, List[int]]`, `Literal['a', 'b']`, etc.
 - **Stdlib module handling**: Built-in modules no longer trigger PyPI download attempts
 - **Signature discovery**: Improved recursive search for symbols exported in `__all__`
 - **Download messages**: Colored warning messages for better visibility

pretty_mod-0.2.1/python/pretty_mod/__main__.py

@@ -0,0 +1,6 @@
+"""Enable running pretty-mod as a module: python -m pretty_mod"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

{pretty_mod-0.2.0 → pretty_mod-0.2.1}/python/pretty_mod/_pretty_mod.pyi

@@ -14,7 +14,12 @@ class ModuleTreeExplorer:
     def get_tree_string(self) -> str: ...
 
 def display_tree(
-    root_module_path: str, max_depth: int = 2, quiet: bool = False
+    root_module_path: str,
+    max_depth: int = 2,
+    quiet: bool = False,
+    format: str = "pretty",
 ) -> None: ...
-def display_signature(import_path: str, quiet: bool = False) -> str: ...
+def display_signature(
+    import_path: str, quiet: bool = False, format: str = "pretty"
+) -> str: ...
 def import_object(import_path: str) -> Any: ...

{pretty_mod-0.2.0 → pretty_mod-0.2.1}/python/pretty_mod/cli.py

@@ -26,6 +26,14 @@ def main():
         action="store_true",
         help="Suppress warnings and informational messages",
     )
+    tree_parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        choices=["pretty", "json"],
+        default="pretty",
+        help="Output format (default: pretty)",
+    )
 
     sig_parser = subparsers.add_parser("sig", help="Display function signature")
     sig_parser.add_argument(
@@ -36,14 +44,25 @@ def main():
         action="store_true",
         help="Suppress download messages",
     )
+    sig_parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        choices=["pretty", "json"],
+        default="pretty",
+        help="Output format (default: pretty)",
+    )
 
     args = parser.parse_args()
 
     try:
         if args.command == "tree":
-            display_tree(args.module, args.depth, args.quiet)
+            # Call display_tree with format parameter
+            display_tree(args.module, args.depth, args.quiet, args.output)
         elif args.command == "sig":
-            print(display_signature(args.import_path, args.quiet))
+            # Call display_signature with format parameter
+            result = display_signature(args.import_path, args.quiet, args.output)
+            print(result)
         else:
             parser.print_help()
             sys.exit(1)

{pretty_mod-0.2.0 → pretty_mod-0.2.1}/src/explorer.rs

@@ -1,4 +1,5 @@
 use crate::module_info::ModuleInfo;
+use crate::tree_formatter::format_tree_display;
 use pyo3::prelude::*;
 use std::fs;
 use std::path::{Path, PathBuf};
@@ -116,7 +117,7 @@ impl ModuleTreeExplorer {
         };
 
         // Use the display_tree formatting logic, which expects the wrapped format
-        crate::format_tree_display(py, &tree_obj, &self.root_module_path)
+        format_tree_display(py, &tree_obj, &self.root_module_path)
     }
 }
 

{pretty_mod-0.2.0 → pretty_mod-0.2.1}/src/lib.rs

@@ -1,6 +1,7 @@
 mod config;
 mod explorer;
 mod module_info;
+mod output_format;
 mod package_downloader;
 mod signature;
 mod stdlib;
@@ -8,15 +9,15 @@ mod tree_formatter;
 mod utils;
 
 use crate::explorer::ModuleTreeExplorer;
-use crate::signature::display_signature as display_signature_impl;
-use crate::tree_formatter::format_tree_display;
+use crate::output_format::create_formatter;
 use crate::utils::{extract_base_package, try_download_and_import, import_object_impl};
 use pyo3::prelude::*;
 
 /// Display a module tree
 #[pyfunction]
-#[pyo3(signature = (root_module_path, max_depth = 2, quiet = false))]
-fn display_tree(py: Python, root_module_path: &str, max_depth: usize, quiet: bool) -> PyResult<()> {
+#[pyo3(signature = (root_module_path, max_depth = 2, quiet = false, format = "pretty"))]
+fn display_tree(py: Python, root_module_path: &str, max_depth: usize, quiet: bool, format: &str) -> PyResult<()> {
+    let formatter = create_formatter(format);
     // Check for invalid single colon (but allow double colon)
     if root_module_path.contains(':') && !root_module_path.contains("::") {
         return Err(PyErr::new::<pyo3::exceptions::PyValueError, _>(
@@ -38,8 +39,8 @@ fn display_tree(py: Python, root_module_path: &str, max_depth: usize, quiet: boo
     let explorer = ModuleTreeExplorer::new(module_name.to_string(), max_depth);
     match explorer.explore(py) {
         Ok(tree) => {
-            // Display tree using the wrapped format
-            let tree_str = format_tree_display(py, &tree, module_name)?;
+            // Display tree using the formatter
+            let tree_str = formatter.format_tree(py, &tree, module_name)?;
             println!("{}", tree_str);
             Ok(())
         }
@@ -69,7 +70,7 @@ fn display_tree(py: Python, root_module_path: &str, max_depth: usize, quiet: boo
                     let explorer = ModuleTreeExplorer::new(module_name.to_string(), max_depth);
                     match explorer.explore(py) {
                         Ok(tree) => {
-                            let tree_str = format_tree_display(py, &tree, module_name)?;
+                            let tree_str = formatter.format_tree(py, &tree, module_name)?;
                             println!("{}", tree_str);
                             Ok(())
                         }
@@ -109,9 +110,26 @@ fn display_tree(py: Python, root_module_path: &str, max_depth: usize, quiet: boo
 
 /// Display a function signature
 #[pyfunction]
-#[pyo3(signature = (import_path, quiet = false))]
-fn display_signature(py: Python, import_path: &str, quiet: bool) -> PyResult<String> {
-    display_signature_impl(py, import_path, quiet)
+#[pyo3(signature = (import_path, quiet = false, format = "pretty"))]
+fn display_signature(py: Python, import_path: &str, quiet: bool, format: &str) -> PyResult<String> {
+    use crate::signature::try_ast_signature;
+    let formatter = create_formatter(format);
+    
+    // First try to get signature from AST
+    if let Some(result) = try_ast_signature(py, import_path, quiet) {
+        if let Some(ref sig) = result.signature {
+            return Ok(formatter.format_signature(sig));
+        }
+    }
+    
+    // If AST parsing didn't find it, return a simple message
+    let object_name = if import_path.contains(':') {
+        import_path.split(':').last().unwrap_or(import_path)
+    } else {
+        import_path.split('.').last().unwrap_or(import_path)
+    };
+    
+    Ok(formatter.format_signature_not_available(object_name))
 }
 
 /// Import an object from a module path (public API, no auto-download)

pretty_mod-0.2.1/src/output_format.rs

@@ -0,0 +1,121 @@
+use crate::module_info::FunctionSignature;
+use pyo3::prelude::*;
+use std::collections::HashMap;
+
+/// Trait for different output format visitors
+pub trait OutputFormatter {
+    /// Format a module tree
+    fn format_tree(&self, py: Python, tree: &PyObject, module_name: &str) -> PyResult<String>;
+
+    /// Format a function signature
+    fn format_signature(&self, signature: &FunctionSignature) -> String;
+
+    /// Format a signature not available message
+    fn format_signature_not_available(&self, object_name: &str) -> String;
+}
+
+/// Pretty print formatter (current default behavior)
+pub struct PrettyPrintFormatter;
+
+impl OutputFormatter for PrettyPrintFormatter {
+    fn format_tree(&self, py: Python, tree: &PyObject, module_name: &str) -> PyResult<String> {
+        // Use existing tree formatter
+        crate::tree_formatter::format_tree_display(py, tree, module_name)
+    }
+
+    fn format_signature(&self, signature: &FunctionSignature) -> String {
+        // Use existing signature formatter
+        crate::signature::format_signature_display(signature)
+    }
+
+    fn format_signature_not_available(&self, object_name: &str) -> String {
+        let config = crate::config::DisplayConfig::get();
+        format!(
+            "{} {} (signature not available)",
+            crate::config::colorize(
+                &config.signature_icon,
+                &config.color_scheme.signature_color,
+                config
+            ),
+            crate::config::colorize(object_name, &config.color_scheme.signature_color, config)
+        )
+    }
+}
+
+/// JSON formatter for machine-readable output
+pub struct JsonFormatter;
+
+impl OutputFormatter for JsonFormatter {
+    fn format_tree(&self, py: Python, tree: &PyObject, module_name: &str) -> PyResult<String> {
+        // Convert PyObject tree to a serializable structure
+        let mut result = HashMap::new();
+        result.insert(
+            "module".to_string(),
+            serde_json::Value::String(module_name.to_string()),
+        );
+
+        // Convert the tree structure to JSON
+        if let Ok(tree_value) = pyobject_to_json_value(py, tree) {
+            result.insert("tree".to_string(), tree_value);
+        }
+
+        serde_json::to_string_pretty(&result)
+            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(e.to_string()))
+    }
+
+    fn format_signature(&self, signature: &FunctionSignature) -> String {
+        // Serialize signature to JSON
+        serde_json::to_string_pretty(signature).unwrap_or_else(|_| "{}".to_string())
+    }
+
+    fn format_signature_not_available(&self, object_name: &str) -> String {
+        let result = serde_json::json!({
+            "name": object_name,
+            "available": false,
+            "reason": "signature not available"
+        });
+        serde_json::to_string_pretty(&result).unwrap_or_else(|_| "{}".to_string())
+    }
+}
+
+/// Convert PyObject to serde_json::Value
+fn pyobject_to_json_value(py: Python, obj: &PyObject) -> PyResult<serde_json::Value> {
+    // Try to extract as different Python types
+    if let Ok(dict) = obj.extract::<HashMap<String, PyObject>>(py) {
+        let mut map = serde_json::Map::new();
+        for (key, value) in dict {
+            if let Ok(json_value) = pyobject_to_json_value(py, &value) {
+                map.insert(key, json_value);
+            }
+        }
+        Ok(serde_json::Value::Object(map))
+    } else if let Ok(list) = obj.extract::<Vec<PyObject>>(py) {
+        let vec: Vec<serde_json::Value> = list
+            .iter()
+            .filter_map(|item| pyobject_to_json_value(py, item).ok())
+            .collect();
+        Ok(serde_json::Value::Array(vec))
+    } else if let Ok(s) = obj.extract::<String>(py) {
+        Ok(serde_json::Value::String(s))
+    } else if let Ok(b) = obj.extract::<bool>(py) {
+        Ok(serde_json::Value::Bool(b))
+    } else if let Ok(i) = obj.extract::<i64>(py) {
+        Ok(serde_json::Value::Number(serde_json::Number::from(i)))
+    } else if let Ok(f) = obj.extract::<f64>(py) {
+        if let Some(num) = serde_json::Number::from_f64(f) {
+            Ok(serde_json::Value::Number(num))
+        } else {
+            Ok(serde_json::Value::Null)
+        }
+    } else {
+        Ok(serde_json::Value::Null)
+    }
+}
+
+/// Factory function to create formatter based on format string
+pub fn create_formatter(format: &str) -> Box<dyn OutputFormatter> {
+    match format.to_lowercase().as_str() {
+        "json" => Box::new(JsonFormatter),
+        _ => Box::new(PrettyPrintFormatter),
+    }
+}

{pretty_mod-0.2.0 → pretty_mod-0.2.1}/src/signature.rs

@@ -187,7 +187,7 @@ fn find_signature_recursive<'a>(
 }
 
 /// Format a signature for display
-fn format_signature_display(sig: &FunctionSignature) -> String {
+pub fn format_signature_display(sig: &FunctionSignature) -> String {
     let config = DisplayConfig::get();
     let mut result = format!(
         "{} {}\n",
@@ -243,8 +243,15 @@ fn format_signature_display(sig: &FunctionSignature) -> String {
     result
 }
 
+/// Result of signature discovery
+pub struct SignatureResult {
+    pub signature: Option<FunctionSignature>,
+    #[allow(dead_code)]
+    pub formatted_output: String,
+}
+
 /// Try to get signature from AST parsing
-fn try_ast_signature(py: Python, import_path: &str, quiet: bool) -> Option<String> {
+pub fn try_ast_signature(py: Python, import_path: &str, quiet: bool) -> Option<SignatureResult> {
     // Parse the full specification first
     let (package_override, path_without_package, version) =
         crate::utils::parse_full_spec(import_path);
@@ -266,7 +273,7 @@ fn try_ast_signature(py: Python, import_path: &str, quiet: bool) -> Option<Strin
     };
 
     // Helper function to try exploration and get signature
-    let try_get_signature = |py: Python| -> Option<String> {
+    let try_get_signature = |py: Python| -> Option<FunctionSignature> {
         // For builtin modules (implemented in C), we can't extract signatures from filesystem
         if crate::stdlib::is_builtin_module(module_path) {
             return None;
@@ -276,7 +283,7 @@ fn try_ast_signature(py: Python, import_path: &str, quiet: bool) -> Option<Strin
         let explorer = crate::explorer::ModuleTreeExplorer::new(module_path.to_string(), 2);
         if let Ok(module_info) = explorer.explore_module_pure_filesystem(py, module_path) {
             if let Some(sig) = module_info.signatures.get(object_name) {
-                return Some(format_signature_display(sig));
+                return Some(sig.clone());
             }
 
             // Check if it's in __all__ and search recursively
@@ -284,7 +291,7 @@ fn try_ast_signature(py: Python, import_path: &str, quiet: bool) -> Option<Strin
                 if all_exports.contains(&object_name.to_string()) {
                     // Use the recursive search function to find it anywhere in the tree
                     if let Some(sig) = find_signature_recursive(&module_info, object_name) {
-                        return Some(format_signature_display(sig));
+                        return Some(sig.clone());
                     }
                 }
             }
@@ -298,7 +305,7 @@ fn try_ast_signature(py: Python, import_path: &str, quiet: bool) -> Option<Strin
             if let Ok(root_info) = explorer.explore_module_pure_filesystem(py, root_package) {
                 // Search recursively for the object
                 if let Some(sig) = find_signature_recursive(&root_info, object_name) {
-                    return Some(format_signature_display(sig));
+                    return Some(sig.clone());
                 }
             }
         }
@@ -308,7 +315,10 @@ fn try_ast_signature(py: Python, import_path: &str, quiet: bool) -> Option<Strin
 
     // First try direct filesystem exploration
     if let Some(sig) = try_get_signature(py) {
-        return Some(sig);
+        return Some(SignatureResult {
+            signature: Some(sig.clone()),
+            formatted_output: format_signature_display(&sig),
+        });
     }
 
     // Check if this is a stdlib module - if so, don't try to download
@@ -336,17 +346,23 @@ fn try_ast_signature(py: Python, import_path: &str, quiet: bool) -> Option<Strin
         download_result = try_get_signature(py);
         Ok(())
     }) {
-        return download_result;
+        if let Some(sig) = download_result {
+            return Some(SignatureResult {
+                signature: Some(sig.clone()),
+                formatted_output: format_signature_display(&sig),
+            });
+        }
     }
 
     None
 }
 
 /// Display a function signature
+#[allow(dead_code)]
 pub fn display_signature(py: Python, import_path: &str, quiet: bool) -> PyResult<String> {
     // First try to get signature from AST
-    if let Some(ast_sig) = try_ast_signature(py, import_path, quiet) {
-        return Ok(ast_sig);
+    if let Some(result) = try_ast_signature(py, import_path, quiet) {
+        return Ok(result.formatted_output);
     }
 
     // If AST parsing didn't find it, return a simple message

pretty_mod-0.2.1/tests/test_json_output.py

@@ -0,0 +1,103 @@
+"""Test JSON output format functionality."""
+
+import json
+import os
+import subprocess
+import sys
+
+
+def test_tree_json_output():
+    """Test tree command with JSON output."""
+    result = subprocess.run(
+        [sys.executable, "-m", "pretty_mod", "tree", "json", "-o", "json"],
+        capture_output=True,
+        text=True,
+    )
+
+    assert result.returncode == 0
+
+    # Parse JSON output
+    data = json.loads(result.stdout)
+
+    # Check structure
+    assert "module" in data
+    assert data["module"] == "json"
+    assert "tree" in data
+    assert "api" in data["tree"]
+    assert "submodules" in data["tree"]
+
+    # Check some expected content
+    api = data["tree"]["api"]
+    assert "dump" in api["functions"]
+    assert "loads" in api["functions"]
+    assert "JSONEncoder" in api["all"]
+
+
+def test_signature_json_output():
+    """Test signature command with JSON output."""
+    result = subprocess.run(
+        [sys.executable, "-m", "pretty_mod", "sig", "json:dumps", "-o", "json"],
+        capture_output=True,
+        text=True,
+    )
+
+    assert result.returncode == 0
+
+    # Parse JSON output
+    data = json.loads(result.stdout)
+
+    # Check structure
+    assert "name" in data
+    assert data["name"] == "dumps"
+    assert "parameters" in data
+    assert "obj" in data["parameters"]
+    assert "skipkeys=False" in data["parameters"]
+    assert "return_type" in data
+
+
+def test_signature_not_available_json():
+    """Test signature not available in JSON format."""
+    result = subprocess.run(
+        [sys.executable, "-m", "pretty_mod", "sig", "sys:maxsize", "-o", "json"],
+        capture_output=True,
+        text=True,
+    )
+
+    assert result.returncode == 0
+
+    # Parse JSON output
+    data = json.loads(result.stdout)
+
+    # Check structure
+    assert "name" in data
+    assert data["name"] == "maxsize"
+    assert "available" in data
+    assert data["available"] is False
+    assert "reason" in data
+
+
+def test_default_output_unchanged():
+    """Test that default output (without -o flag) remains unchanged."""
+    # Test tree
+    result_tree = subprocess.run(
+        [sys.executable, "-m", "pretty_mod", "tree", "json"],
+        capture_output=True,
+        text=True,
+        env={**os.environ, "PRETTY_MOD_NO_COLOR": "1"},
+    )
+
+    assert result_tree.returncode == 0
+    assert "📦 json" in result_tree.stdout
+    assert "├── ⚡ functions:" in result_tree.stdout
+
+    # Test signature
+    result_sig = subprocess.run(
+        [sys.executable, "-m", "pretty_mod", "sig", "json:dumps"],
+        capture_output=True,
+        text=True,
+        env={**os.environ, "PRETTY_MOD_NO_COLOR": "1"},
+    )
+
+    assert result_sig.returncode == 0
+    assert "📎 dumps" in result_sig.stdout
+    assert "├──  Parameters:" in result_sig.stdout