pretty-mod 0.0.1__tar.gz

pretty_mod-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    
+jobs:
+  publish-pypi-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - run: python3 -m pip install --upgrade build && python3 -m build
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          verbose: true

pretty_mod-0.0.1/.github/workflows/static-analysis.yml

@@ -0,0 +1,26 @@
+name: Run static analysis
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  static_analysis:
+    timeout-minutes: 1
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.10"
+      - uses: extractions/setup-just@v3
+      - name: Run pre-commit
+        run: uv run pre-commit run --all-files

pretty_mod-0.0.1/.github/workflows/tests.yml

@@ -0,0 +1,41 @@
+name: Run tests
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**/*.py"
+      - "tests/**/*.py"
+
+  pull_request:
+    paths:
+      - "src/**/*.py"
+      - "tests/**/*.py"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  run_tests:
+    # Skip the entire job for fork PRs
+    if: ${{ !(github.event.pull_request.head.repo.fork) }}
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10"]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run --frozen pytest

pretty_mod-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment variables
+.env

pretty_mod-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.9.1
+    hooks:
+      # Run the linter.
+      - id: ruff
+        args: [--fix]
+      # Run the formatter.
+      - id: ruff-format
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.7.3
+    hooks:
+      - id: uv-lock
+  - repo: local
+    hooks:
+      - id: ty-check
+        name: Typecheck
+        entry: just typecheck
+        language: system
+        pass_filenames: false

pretty_mod-0.0.1/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: pretty-mod
+Version: 0.0.1
+Summary: A module tree explorer for humans and LLMs
+Author-email: zzstoatzz <thrast36@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pretty-mod
+
+A module tree explorer for humans and LLMs.
+
+## Installation
+
+```bash
+uv add pretty-mod
+```
+
+## Usage
+
+```python
+from pretty_mod.explorer import ModuleTreeExplorer
+
+# Explore a module structure
+explorer = ModuleTreeExplorer("json", max_depth=2)
+explorer.explore()
+print(explorer.get_tree_string())
+```
+
+<details>
+<summary>Example output</summary>
+
+```text
+📦 json
+└── 📜 __all__: dump, dumps, load, loads, JSONDecoder, JSONDecodeError, JSONEncoder
+├── ⚡ functions: dump, dumps, load, loads
+├── 📦 decoder
+    ├── 📜 __all__: JSONDecoder, JSONDecodeError
+    ├── 🔷 classes: JSONDecodeError, JSONDecoder
+├── 📦 encoder
+    ├── 🔷 classes: JSONEncoder
+    ├── ⚡ functions: py_encode_basestring, py_encode_basestring_ascii
+├── 📦 scanner
+    ├── 📜 __all__: make_scanner
+└── 📦 tool
+    └── ⚡ functions: main
+```
+</details>
+
+
+
+```python
+from pretty_mod.explorer import display_signature
+
+# Display function signatures
+print(display_signature("json:loads"))
+```
+
+<details>
+<summary>Example output</summary>
+
+```text
+📎 loads
+├── Parameters:
+├── s
+├── cls = None (keyword-only)
+├── object_hook = None (keyword-only)
+├── parse_float = None (keyword-only)
+├── parse_int = None (keyword-only)
+├── parse_constant = None (keyword-only)
+├── object_pairs_hook = None (keyword-only)
+└── kw (**kwargs)
+```
+</details>
+
+## Examples
+
+See the [`examples/`](examples/) directory for more detailed usage patterns and advanced features.
+
+## Development
+
+```bash
+git clone https://github.com/zzstoatzz/pretty-mod.git
+cd pretty-mod
+uv sync
+uv run pytest
+```

pretty_mod-0.0.1/README.md

@@ -0,0 +1,79 @@
+# pretty-mod
+
+A module tree explorer for humans and LLMs.
+
+## Installation
+
+```bash
+uv add pretty-mod
+```
+
+## Usage
+
+```python
+from pretty_mod.explorer import ModuleTreeExplorer
+
+# Explore a module structure
+explorer = ModuleTreeExplorer("json", max_depth=2)
+explorer.explore()
+print(explorer.get_tree_string())
+```
+
+<details>
+<summary>Example output</summary>
+
+```text
+📦 json
+└── 📜 __all__: dump, dumps, load, loads, JSONDecoder, JSONDecodeError, JSONEncoder
+├── ⚡ functions: dump, dumps, load, loads
+├── 📦 decoder
+    ├── 📜 __all__: JSONDecoder, JSONDecodeError
+    ├── 🔷 classes: JSONDecodeError, JSONDecoder
+├── 📦 encoder
+    ├── 🔷 classes: JSONEncoder
+    ├── ⚡ functions: py_encode_basestring, py_encode_basestring_ascii
+├── 📦 scanner
+    ├── 📜 __all__: make_scanner
+└── 📦 tool
+    └── ⚡ functions: main
+```
+</details>
+
+
+
+```python
+from pretty_mod.explorer import display_signature
+
+# Display function signatures
+print(display_signature("json:loads"))
+```
+
+<details>
+<summary>Example output</summary>
+
+```text
+📎 loads
+├── Parameters:
+├── s
+├── cls = None (keyword-only)
+├── object_hook = None (keyword-only)
+├── parse_float = None (keyword-only)
+├── parse_int = None (keyword-only)
+├── parse_constant = None (keyword-only)
+├── object_pairs_hook = None (keyword-only)
+└── kw (**kwargs)
+```
+</details>
+
+## Examples
+
+See the [`examples/`](examples/) directory for more detailed usage patterns and advanced features.
+
+## Development
+
+```bash
+git clone https://github.com/zzstoatzz/pretty-mod.git
+cd pretty-mod
+uv sync
+uv run pytest
+```

pretty_mod-0.0.1/examples/README.md

@@ -0,0 +1,44 @@
+# Pretty-Mod Examples
+
+This directory contains practical examples demonstrating how to use `pretty-mod` for module exploration and code understanding.
+
+## Examples
+
+### 📚 `basic_usage.py`
+Demonstrates core functionality:
+- Exploring module structures with `ModuleTreeExplorer`
+- Displaying function signatures with `display_signature`
+- Dynamic imports with `import_object`
+- Working with different exploration depths
+
+**Run it:**
+```bash
+uv run python examples/basic_usage.py
+```
+
+### 🚀 `advanced_exploration.py`
+Shows practical use cases:
+- Comparing APIs across related modules
+- Generating module summaries
+- Finding similar functions across codebases
+- Interactive exploration patterns for unfamiliar code
+
+**Run it:**
+```bash
+uv run python examples/advanced_exploration.py
+```
+
+## Key Use Cases
+
+- **Code Discovery**: Quickly understand the structure of unfamiliar modules
+- **API Comparison**: Compare similar libraries to understand differences
+- **Documentation**: Generate overviews of module capabilities
+- **LLM Integration**: Perfect for AI assistants exploring codebases
+- **Interactive Development**: Dynamically explore and test code
+
+## Tips
+
+- Start with shallow exploration (`max_depth=1`) for quick overviews
+- Use deeper exploration for detailed analysis
+- Combine signature display with dynamic imports for testing
+- Great for exploring both built-in and third-party modules 

pretty_mod-0.0.1/examples/advanced_exploration.py

@@ -0,0 +1,200 @@
+"""
+Advanced exploration examples for pretty-mod.
+
+This example shows practical use cases for exploring and understanding codebases,
+particularly useful for LLMs and developers working with unfamiliar modules.
+"""
+
+from pretty_mod.explorer import ModuleTreeExplorer, display_signature
+
+
+def compare_module_apis():
+    """Compare APIs of related modules to understand their differences."""
+    print("🔄 Comparing related module APIs:")
+    print("=" * 60)
+
+    modules = ["json", "pickle", "csv"]
+
+    for module_name in modules:
+        print(f"\n📦 {module_name.upper()} module API:")
+        print("-" * 30)
+
+        explorer = ModuleTreeExplorer(module_name, max_depth=1)
+        tree = explorer.explore()
+
+        api = tree.get("api", {})
+
+        if api.get("functions"):
+            print(f"Functions: {', '.join(sorted(api['functions']))}")
+        if api.get("classes"):
+            print(f"Classes: {', '.join(sorted(api['classes']))}")
+        if api.get("constants"):
+            print(f"Constants: {', '.join(sorted(api['constants']))}")
+
+
+def explore_third_party_module():
+    """Example of exploring a third-party module (if available)."""
+    print("\n🌐 Exploring third-party modules:")
+    print("=" * 60)
+
+    # Try to explore common third-party modules
+    modules_to_try = ["requests", "numpy", "pandas", "pathlib"]
+
+    for module_name in modules_to_try:
+        try:
+            explorer = ModuleTreeExplorer(module_name, max_depth=1)
+            tree = explorer.explore()
+
+            if tree.get("api"):
+                print(f"\n✅ Found {module_name}:")
+                print(explorer.get_tree_string())
+                break
+        except Exception:
+            continue
+    else:
+        print("\n⚠️  No common third-party modules found.")
+        print("Try installing requests or another package to see this in action!")
+
+
+def function_signature_analysis():
+    """Analyze function signatures to understand usage patterns."""
+    print("\n🔍 Function Signature Analysis:")
+    print("=" * 60)
+
+    # Functions with different signature patterns
+    functions = [
+        ("builtins:print", "Built-in with *args"),
+        ("json:dumps", "Serialization function"),
+        ("os.path:join", "Path manipulation"),
+        ("re:match", "Pattern matching"),
+    ]
+
+    for func_path, description in functions:
+        try:
+            print(f"\n{description}:")
+            print(display_signature(func_path))
+        except Exception as e:
+            print(f"❌ Could not analyze {func_path}: {e}")
+
+
+def find_similar_functions():
+    """Find functions with similar names across different modules."""
+    print("\n🎯 Finding similar functions across modules:")
+    print("=" * 60)
+
+    target_functions = ["loads", "dumps", "open"]
+    modules = ["json", "pickle", "os"]
+
+    for func_name in target_functions:
+        print(f"\nLooking for '{func_name}' functions:")
+
+        for module_name in modules:
+            try:
+                explorer = ModuleTreeExplorer(module_name, max_depth=1)
+                tree = explorer.explore()
+                functions = tree.get("api", {}).get("functions", [])
+
+                matching = [f for f in functions if func_name in f.lower()]
+                if matching:
+                    print(f"  📦 {module_name}: {', '.join(matching)}")
+            except Exception:
+                continue
+
+
+def generate_module_summary():
+    """Generate a comprehensive summary of a module."""
+    print("\n📊 Module Summary Generator:")
+    print("=" * 60)
+
+    module_name = "datetime"
+    explorer = ModuleTreeExplorer(module_name, max_depth=2)
+    tree = explorer.explore()
+
+    print(f"Summary for '{module_name}' module:")
+    print("-" * 40)
+
+    api = tree.get("api", {})
+    submodules = tree.get("submodules", {})
+
+    # Main module stats
+    print(f"Classes: {len(api.get('classes', []))}")
+    print(f"Functions: {len(api.get('functions', []))}")
+    print(f"Constants: {len(api.get('constants', []))}")
+    print(f"Submodules: {len(submodules)}")
+
+    if api.get("all"):
+        print(f"Public API (__all__): {len(api['all'])} items")
+
+    # Show class details
+    if api.get("classes"):
+        print(f"\nMain classes: {', '.join(api['classes'][:5])}")
+        if len(api["classes"]) > 5:
+            print(f"... and {len(api['classes']) - 5} more")
+
+    # Show submodule details
+    if submodules:
+        print("\nSubmodules:")
+        for sub_name, sub_tree in list(submodules.items())[:3]:
+            sub_api = sub_tree.get("api", {})
+            total_items = (
+                len(sub_api.get("classes", []))
+                + len(sub_api.get("functions", []))
+                + len(sub_api.get("constants", []))
+            )
+            print(f"  📦 {sub_name}: {total_items} public items")
+
+
+def interactive_exploration():
+    """Show how to use pretty-mod for interactive exploration."""
+    print("\n🎮 Interactive Exploration Pattern:")
+    print("=" * 60)
+
+    print("Here's how you might explore an unfamiliar module step by step:")
+    print()
+
+    # Step 1: High-level overview
+    print("1. Get a high-level overview:")
+    print("   explorer = ModuleTreeExplorer('os', max_depth=1)")
+    print("   print(explorer.get_tree_string())")
+    print()
+
+    # Step 2: Deep dive
+    print("2. Deep dive into interesting submodules:")
+    print("   explorer = ModuleTreeExplorer('os.path', max_depth=2)")
+    print("   print(explorer.get_tree_string())")
+    print()
+
+    # Step 3: Function analysis
+    print("3. Analyze specific functions:")
+    print("   print(display_signature('os.path:join'))")
+    print("   print(display_signature('os:getcwd'))")
+    print()
+
+    # Step 4: Dynamic testing
+    print("4. Dynamically import and test:")
+    print("   join_func = import_object('os.path:join')")
+    print("   result = join_func('home', 'user', 'documents')")
+    print()
+
+    # Demonstrate this pattern
+    print("Let's run this pattern on the 'pathlib' module:")
+    try:
+        explorer = ModuleTreeExplorer("pathlib", max_depth=1)
+        explorer.explore()
+        print(explorer.get_tree_string())
+    except Exception as e:
+        print(f"Could not explore pathlib: {e}")
+
+
+if __name__ == "__main__":
+    print("🚀 Advanced pretty-mod exploration examples")
+    print("=" * 70)
+
+    compare_module_apis()
+    explore_third_party_module()
+    function_signature_analysis()
+    find_similar_functions()
+    generate_module_summary()
+    interactive_exploration()
+
+    print("\n🎯 These patterns help you quickly understand any Python codebase!")

pretty_mod-0.0.1/examples/basic_usage.py

@@ -0,0 +1,93 @@
+"""
+Basic usage examples for pretty-mod.
+
+This example demonstrates how to explore module structures and display function signatures.
+"""
+
+from pretty_mod.explorer import ModuleTreeExplorer, display_signature, import_object
+
+
+def explore_json_module():
+    """Example: Explore the built-in json module structure."""
+    print("🔍 Exploring the json module:")
+    print("=" * 50)
+
+    explorer = ModuleTreeExplorer("json", max_depth=2)
+    explorer.explore()
+
+    # Display the tree structure
+    tree_string = explorer.get_tree_string()
+    print(tree_string)
+    print()
+
+
+def explore_function_signature():
+    """Example: Display function signatures in a readable format."""
+    print("📋 Function Signature Examples:")
+    print("=" * 50)
+
+    # Example with a built-in function
+    print("Built-in function:")
+    print(display_signature("builtins:len"))
+    print()
+
+    # Example with a module function
+    print("Module function:")
+    print(display_signature("json:loads"))
+    print()
+
+
+def import_and_use_objects():
+    """Example: Import objects dynamically using import paths."""
+    print("📦 Dynamic Import Examples:")
+    print("=" * 50)
+
+    # Import using colon syntax
+    json_loads = import_object("json:loads")
+    print(f"Imported json.loads: {json_loads}")
+
+    # Test the imported function
+    test_data = '{"name": "pretty-mod", "type": "module"}'
+    parsed = json_loads(test_data)
+    print(f"Parsed JSON: {parsed}")
+    print()
+
+    # Import using dot syntax
+    sys_version = import_object("sys.version_info")
+    print(
+        f"Python version: {sys_version.major}.{sys_version.minor}.{sys_version.micro}"
+    )
+    print()
+
+
+def explore_custom_depth():
+    """Example: Explore modules with different depth limits."""
+    print("🏗️ Exploring with different depths:")
+    print("=" * 50)
+
+    # Shallow exploration
+    print("Shallow exploration (depth=1):")
+    explorer_shallow = ModuleTreeExplorer("urllib", max_depth=1)
+    explorer_shallow.explore()
+    print(explorer_shallow.get_tree_string())
+    print()
+
+    # Deeper exploration
+    print("Deeper exploration (depth=2):")
+    explorer_deep = ModuleTreeExplorer("urllib", max_depth=2)
+    explorer_deep.explore()
+    print(explorer_deep.get_tree_string())
+    print()
+
+
+if __name__ == "__main__":
+    print("🎉 Welcome to pretty-mod examples!")
+    print("=" * 60)
+    print()
+
+    explore_json_module()
+    explore_function_signature()
+    import_and_use_objects()
+    explore_custom_depth()
+
+    print("✨ That's pretty-mod in action! ✨")

pretty_mod-0.0.1/justfile

@@ -0,0 +1,36 @@
+# Check for uv installation
+check-uv:
+    #!/usr/bin/env sh
+    if ! command -v uv >/dev/null 2>&1; then
+        echo "uv is not installed or not found in expected locations."
+        case "$(uname)" in
+            "Darwin")
+                echo "To install uv on macOS, run one of:"
+                echo "• brew install uv"
+                echo "• curl -LsSf https://astral.sh/uv/install.sh | sh"
+                ;;
+            "Linux")
+                echo "To install uv, run:"
+                echo "• curl -LsSf https://astral.sh/uv/install.sh | sh"
+                ;;
+            *)
+                echo "To install uv, visit: https://github.com/astral-sh/uv"
+                ;;
+        esac
+        exit 1
+    fi
+
+# Install development dependencies
+install: check-uv
+    uv sync
+
+typecheck: check-uv
+    uv run ty check
+
+# Clean up environment
+clean: check-uv
+    deactivate || true
+    rm -rf .venv
+
+run-pre-commits: check-uv
+    uv run pre-commit run --all-files

pretty_mod-0.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "pretty-mod"
+description = "A module tree explorer for humans and LLMs"
+readme = "README.md"
+authors = [{ name = "zzstoatzz", email = "thrast36@gmail.com" }]
+requires-python = ">=3.10"
+dynamic = ["version"]
+dependencies = []
+
+[dependency-groups]
+dev = ["pytest-sugar", "ruff", "ty", "ipython", "pre-commit"]
+
+[build-system]
+requires = ["hatchling>=1.21.0", "hatch-vcs>=0.4.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pretty_mod"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.ruff.lint]
+extend-select = ["I", "UP"]
+
+[tool.ty.src]
+root = "./src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-v", "--strict-markers"]