dirshot 0.1.3__tar.gz → 0.3.0__tar.gz

dirshot-0.3.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: dirshot
+Version: 0.3.0
+Summary: A flexible, high-performance utility for creating project snapshots and searching files with a rich terminal UI.
+Author-email: init-helpful <init.helpful@gmail.com>
+Project-URL: Homepage, https://github.com/init-helpful/dirshot
+Project-URL: Bug Tracker, https://github.com/init-helpful/dirshot/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Provides-Extra: rich
+Requires-Dist: rich>=13.0.0; extra == "rich"
+
+
+# dirshot 📸
+
+[![PyPI version](https://badge.fury.io/py/dirshot.svg)](https://badge.fury.io/py/dirshot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![Python Version](https://img.shields.io/pypi/pyversions/dirshot)
+
+A flexible, high-performance utility for creating project snapshots and searching files, complete with rich visual feedback in your terminal.
+
+`dirshot` scans your project directories to either create a single, comprehensive text file "snapshot" of your codebase or to search for specific keywords within your files. It's perfect for feeding project context to Large Language Models (LLMs), archiving codebases, conducting security audits, or simply navigating complex projects.
+
+---
+
+## ✨ Key Features
+
+-   **Rich Terminal Visuals**: Powered by `rich`, `dirshot` provides a beautiful and informative live view of its progress, including spinners, progress bars, summary tables, and thread activity. It falls back to a simple text-based progress indicator if `rich` is not installed.
+-   **Powerful Presets**: Comes with an extensive list of `LanguagePreset` and `IgnorePreset` enums to instantly configure scans for dozens of languages, frameworks, and tools (Python, JavaScript, Go, Rust, Terraform, Docker, etc.).
+-   **Dual Modes**:
+    -   **Snapshot Mode**: Collate all project files matching your criteria into a single, easy-to-share output file.
+    -   **Search Mode**: Hunt for specific keywords in filenames or, optionally, within file contents.
+-   **Highly Customizable**: Fine-tune scans by combining presets with manual lists of file extensions, ignore paths, and specific file names to include or exclude.
+-   **Concurrent & Fast**: Uses a `ThreadPoolExecutor` for high-performance file discovery and processing, making scans quick and efficient.
+-   **Detailed Output**: Generates an optional file tree, shows detailed scan summaries, and can even approximate token/character counts, which is useful for LLM context limits.
+
+## 📦 Installation
+
+You can install `dirshot` directly from PyPI.
+
+**Basic Installation (no visual dependencies):**
+
+```bash
+pip install dirshot
+```
+
+**Installation with Enhanced Terminal Visuals:**
+
+To get the full rich terminal experience, install the `rich` extra, which adds support for `rich`.
+
+```bash
+pip install dirshot[rich]
+```
+
+## 🚀 How to Use
+
+`dirshot` is used by importing the `generate_snapshot` function into a Python script.
+
+Here is a basic example of creating a snapshot of a Python project:
+
+```python
+# snapshot_script.py
+from src.dirshot import generate_snapshot, LanguagePreset, IgnorePreset
+# or 
+# from src.dirshot import *
+
+generate_snapshot(
+    root_directory=".", # optional
+    output_file_name="my_python_project.txt",
+    language_presets=[LanguagePreset.PYTHON, LanguagePreset.MARKUP],
+    ignore_presets=[
+        IgnorePreset.VERSION_CONTROL, # Ignore .git
+        IgnorePreset.PYTHON,          # Ignore __pycache__, venv, etc.
+        IgnorePreset.IDE_METADATA     # Ignore .vscode, .idea
+    ],
+    generate_tree=True,
+    show_token_count=True
+)
+```
+
+To run this, save the code as a Python file (e.g., `snapshot_script.py`) and execute it from your terminal:
+
+```bash
+python snapshot_script.py
+```
+
+## 📋 Examples
+
+The `examples.py` file in the repository contains many more use cases. Here are a few common ones:
+
+#### 1. Full-Stack Web App (React + Node.js)
+
+This example combines multiple presets to capture a full-stack JavaScript project while ignoring common clutter like `node_modules`.
+
+```python
+generate_snapshot(
+    root_directory=".",
+    output_file_name="fullstack_js_snapshot.txt",
+    language_presets=[
+        LanguagePreset.REACT,      # Handles all frontend JS/TS/JSX files
+        LanguagePreset.WEB_FRONTEND  # Includes HTML and CSS files
+    ],
+    ignore_presets=[
+        IgnorePreset.NODE_JS,      # Crucial for ignoring node_modules
+        IgnorePreset.IDE_METADATA,
+        IgnorePreset.BUILD_ARTIFACTS,
+        IgnorePreset.VERSION_CONTROL
+    ],
+    generate_tree=True,
+    show_tree_stats=True
+)
+```
+
+#### 2. Data Science Project (Python, Notebooks & SQL)
+
+Collate all relevant files from a data analysis or machine learning project.
+
+```python
+generate_snapshot(
+    root_directory="./data_science_project",
+    output_file_name="data_science_snapshot.txt",
+    language_presets=[
+        LanguagePreset.PYTHON,
+        LanguagePreset.DATA_SCIENCE_NOTEBOOKS, # .ipynb
+        LanguagePreset.SQL,
+        LanguagePreset.MARKUP # Include READMEs
+    ],
+    ignore_presets=[
+        IgnorePreset.PYTHON,             # Ignores venv, __pycache__, etc.
+        IgnorePreset.JUPYTER_NOTEBOOKS,  # Ignores .ipynb_checkpoints
+        IgnorePreset.IDE_METADATA,
+        IgnorePreset.VERSION_CONTROL
+    ]
+)
+```
+
+#### 3. Search for Secrets or API Keys
+
+Use "Search Mode" to perform a security audit. This example intentionally omits the `SECRET_FILES` ignore preset to ensure `.env` files are searched.
+
+```python
+generate_snapshot(
+    root_directory=".",
+    output_file_name="secrets_audit_results.txt",
+    search_keywords=["password", "secret_key", "api_key", "token"],
+    language_presets=[LanguagePreset.CONFIGURATION],
+    search_file_contents=True,
+    ignore_presets=[
+        IgnorePreset.VERSION_CONTROL,
+        IgnorePreset.NODE_JS,
+        IgnorePreset.BUILD_ARTIFACTS
+        # Deliberately not ignoring SECRET_FILES
+    ]
+)
+```
+
+## ⚙️ API Reference
+
+The `generate_snapshot()` function accepts the following parameters:
+
+| Parameter                             | Type                         | Default                      | Description                                                                                             |
+| ------------------------------------- | ---------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `root_directory`                      | `str`                        | `"."`                        | The starting directory for the scan.                                                                    |
+| `output_file_name`                    | `str`                        | `"project_snapshot.txt"`     | The name of the file to save the results to.                                                            |
+| `search_keywords`                     | `Optional[List[str]]`        | `None`                       | If provided, switches to **Search Mode**. Otherwise, runs in **Snapshot Mode**.                         |
+| `files`                               | `Optional[List[str]]`        | `None`                       | A list of specific filenames to include. If provided, checks this list first before extensions.         |
+| `language_presets`                    | `Optional[List[LanguagePreset]]` | `None`                       | A list of `LanguagePreset` enums for common file types (e.g., `LanguagePreset.PYTHON`).                 |
+| `ignore_presets`                      | `Optional[List[IgnorePreset]]`   | `None`                       | A list of `IgnorePreset` enums for common ignore patterns (e.g., `IgnorePreset.NODE_JS`).             |
+| `file_extensions`                     | `Optional[List[str]]`        | `None`                       | A manual list of file extensions to include (e.g., `[".py", ".md"]`).                                   |
+| `ignore_if_in_path`                   | `Optional[List[str]]`        | `None`                       | A list of directory or file substring names to exclude (e.g., `["temp"]` excludes `src/temp/file.py`).  |
+| `ignore_extensions`                   | `Optional[List[str]]`        | `None`                       | A manual list of file extensions to explicitly ignore (e.g., `[".log", ".tmp"]`).                       |
+| `search_file_contents`                | `bool`                       | `True`                       | In Search Mode, search for keywords within file contents.                                               |
+| `generate_tree`                       | `bool`                       | `True`                       | Include a file tree of the matched files at the top of the output.                                      |
+| `show_tree_stats`                     | `bool`                       | `False`                      | Display file and directory counts in the generated tree.                                                |
+| `show_token_count`                    | `bool`                       | `False`                      | Display an approximated token/character count in the summary and output file.                           |
+| `exclude_whitespace_in_token_count`   | `bool`                       | `False`                      | If `True`, removes whitespace before counting tokens for a more compact count.                          |
+| `max_workers`                         | `Optional[int]`              | `CPU count + 4`              | The maximum number of worker threads for concurrent processing.                                         |
+| `read_binary_files`                   | `bool`                       | `False`                      | If `True`, the content search will attempt to read and search through binary files.                     |
+| `only_show_tree`                      | `bool`                       | `False`                      | If `True`, the output file will contain only the file tree (and stats), omitting file content.          |
+| `case_sensitive_filter`               | `bool`                       | `False`                      | If `True`, file filtering (extensions, ignore paths) is case-sensitive.                                 |
+| `case_sensitive_search`               | `bool`                       | `False`                      | If `True`, keyword searching is case-sensitive.                                                         |
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a pull request or open an issue.
+
+1.  Fork the repository.
+2.  Create a new branch (`git checkout -b feature/your-feature-name`).
+3.  Make your changes.
+4.  Commit your changes (`git commit -m 'Add some feature'`).
+5.  Push to the branch (`git push origin feature/your-feature-name`).
+6.  Open a pull request.

dirshot-0.3.0/README.md

@@ -0,0 +1,180 @@
+
+# dirshot 📸
+
+[![PyPI version](https://badge.fury.io/py/dirshot.svg)](https://badge.fury.io/py/dirshot)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![Python Version](https://img.shields.io/pypi/pyversions/dirshot)
+
+A flexible, high-performance utility for creating project snapshots and searching files, complete with rich visual feedback in your terminal.
+
+`dirshot` scans your project directories to either create a single, comprehensive text file "snapshot" of your codebase or to search for specific keywords within your files. It's perfect for feeding project context to Large Language Models (LLMs), archiving codebases, conducting security audits, or simply navigating complex projects.
+
+---
+
+## ✨ Key Features
+
+-   **Rich Terminal Visuals**: Powered by `rich`, `dirshot` provides a beautiful and informative live view of its progress, including spinners, progress bars, summary tables, and thread activity. It falls back to a simple text-based progress indicator if `rich` is not installed.
+-   **Powerful Presets**: Comes with an extensive list of `LanguagePreset` and `IgnorePreset` enums to instantly configure scans for dozens of languages, frameworks, and tools (Python, JavaScript, Go, Rust, Terraform, Docker, etc.).
+-   **Dual Modes**:
+    -   **Snapshot Mode**: Collate all project files matching your criteria into a single, easy-to-share output file.
+    -   **Search Mode**: Hunt for specific keywords in filenames or, optionally, within file contents.
+-   **Highly Customizable**: Fine-tune scans by combining presets with manual lists of file extensions, ignore paths, and specific file names to include or exclude.
+-   **Concurrent & Fast**: Uses a `ThreadPoolExecutor` for high-performance file discovery and processing, making scans quick and efficient.
+-   **Detailed Output**: Generates an optional file tree, shows detailed scan summaries, and can even approximate token/character counts, which is useful for LLM context limits.
+
+## 📦 Installation
+
+You can install `dirshot` directly from PyPI.
+
+**Basic Installation (no visual dependencies):**
+
+```bash
+pip install dirshot
+```
+
+**Installation with Enhanced Terminal Visuals:**
+
+To get the full rich terminal experience, install the `rich` extra, which adds support for `rich`.
+
+```bash
+pip install dirshot[rich]
+```
+
+## 🚀 How to Use
+
+`dirshot` is used by importing the `generate_snapshot` function into a Python script.
+
+Here is a basic example of creating a snapshot of a Python project:
+
+```python
+# snapshot_script.py
+from src.dirshot import generate_snapshot, LanguagePreset, IgnorePreset
+# or 
+# from src.dirshot import *
+
+generate_snapshot(
+    root_directory=".", # optional
+    output_file_name="my_python_project.txt",
+    language_presets=[LanguagePreset.PYTHON, LanguagePreset.MARKUP],
+    ignore_presets=[
+        IgnorePreset.VERSION_CONTROL, # Ignore .git
+        IgnorePreset.PYTHON,          # Ignore __pycache__, venv, etc.
+        IgnorePreset.IDE_METADATA     # Ignore .vscode, .idea
+    ],
+    generate_tree=True,
+    show_token_count=True
+)
+```
+
+To run this, save the code as a Python file (e.g., `snapshot_script.py`) and execute it from your terminal:
+
+```bash
+python snapshot_script.py
+```
+
+## 📋 Examples
+
+The `examples.py` file in the repository contains many more use cases. Here are a few common ones:
+
+#### 1. Full-Stack Web App (React + Node.js)
+
+This example combines multiple presets to capture a full-stack JavaScript project while ignoring common clutter like `node_modules`.
+
+```python
+generate_snapshot(
+    root_directory=".",
+    output_file_name="fullstack_js_snapshot.txt",
+    language_presets=[
+        LanguagePreset.REACT,      # Handles all frontend JS/TS/JSX files
+        LanguagePreset.WEB_FRONTEND  # Includes HTML and CSS files
+    ],
+    ignore_presets=[
+        IgnorePreset.NODE_JS,      # Crucial for ignoring node_modules
+        IgnorePreset.IDE_METADATA,
+        IgnorePreset.BUILD_ARTIFACTS,
+        IgnorePreset.VERSION_CONTROL
+    ],
+    generate_tree=True,
+    show_tree_stats=True
+)
+```
+
+#### 2. Data Science Project (Python, Notebooks & SQL)
+
+Collate all relevant files from a data analysis or machine learning project.
+
+```python
+generate_snapshot(
+    root_directory="./data_science_project",
+    output_file_name="data_science_snapshot.txt",
+    language_presets=[
+        LanguagePreset.PYTHON,
+        LanguagePreset.DATA_SCIENCE_NOTEBOOKS, # .ipynb
+        LanguagePreset.SQL,
+        LanguagePreset.MARKUP # Include READMEs
+    ],
+    ignore_presets=[
+        IgnorePreset.PYTHON,             # Ignores venv, __pycache__, etc.
+        IgnorePreset.JUPYTER_NOTEBOOKS,  # Ignores .ipynb_checkpoints
+        IgnorePreset.IDE_METADATA,
+        IgnorePreset.VERSION_CONTROL
+    ]
+)
+```
+
+#### 3. Search for Secrets or API Keys
+
+Use "Search Mode" to perform a security audit. This example intentionally omits the `SECRET_FILES` ignore preset to ensure `.env` files are searched.
+
+```python
+generate_snapshot(
+    root_directory=".",
+    output_file_name="secrets_audit_results.txt",
+    search_keywords=["password", "secret_key", "api_key", "token"],
+    language_presets=[LanguagePreset.CONFIGURATION],
+    search_file_contents=True,
+    ignore_presets=[
+        IgnorePreset.VERSION_CONTROL,
+        IgnorePreset.NODE_JS,
+        IgnorePreset.BUILD_ARTIFACTS
+        # Deliberately not ignoring SECRET_FILES
+    ]
+)
+```
+
+## ⚙️ API Reference
+
+The `generate_snapshot()` function accepts the following parameters:
+
+| Parameter                             | Type                         | Default                      | Description                                                                                             |
+| ------------------------------------- | ---------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `root_directory`                      | `str`                        | `"."`                        | The starting directory for the scan.                                                                    |
+| `output_file_name`                    | `str`                        | `"project_snapshot.txt"`     | The name of the file to save the results to.                                                            |
+| `search_keywords`                     | `Optional[List[str]]`        | `None`                       | If provided, switches to **Search Mode**. Otherwise, runs in **Snapshot Mode**.                         |
+| `files`                               | `Optional[List[str]]`        | `None`                       | A list of specific filenames to include. If provided, checks this list first before extensions.         |
+| `language_presets`                    | `Optional[List[LanguagePreset]]` | `None`                       | A list of `LanguagePreset` enums for common file types (e.g., `LanguagePreset.PYTHON`).                 |
+| `ignore_presets`                      | `Optional[List[IgnorePreset]]`   | `None`                       | A list of `IgnorePreset` enums for common ignore patterns (e.g., `IgnorePreset.NODE_JS`).             |
+| `file_extensions`                     | `Optional[List[str]]`        | `None`                       | A manual list of file extensions to include (e.g., `[".py", ".md"]`).                                   |
+| `ignore_if_in_path`                   | `Optional[List[str]]`        | `None`                       | A list of directory or file substring names to exclude (e.g., `["temp"]` excludes `src/temp/file.py`).  |
+| `ignore_extensions`                   | `Optional[List[str]]`        | `None`                       | A manual list of file extensions to explicitly ignore (e.g., `[".log", ".tmp"]`).                       |
+| `search_file_contents`                | `bool`                       | `True`                       | In Search Mode, search for keywords within file contents.                                               |
+| `generate_tree`                       | `bool`                       | `True`                       | Include a file tree of the matched files at the top of the output.                                      |
+| `show_tree_stats`                     | `bool`                       | `False`                      | Display file and directory counts in the generated tree.                                                |
+| `show_token_count`                    | `bool`                       | `False`                      | Display an approximated token/character count in the summary and output file.                           |
+| `exclude_whitespace_in_token_count`   | `bool`                       | `False`                      | If `True`, removes whitespace before counting tokens for a more compact count.                          |
+| `max_workers`                         | `Optional[int]`              | `CPU count + 4`              | The maximum number of worker threads for concurrent processing.                                         |
+| `read_binary_files`                   | `bool`                       | `False`                      | If `True`, the content search will attempt to read and search through binary files.                     |
+| `only_show_tree`                      | `bool`                       | `False`                      | If `True`, the output file will contain only the file tree (and stats), omitting file content.          |
+| `case_sensitive_filter`               | `bool`                       | `False`                      | If `True`, file filtering (extensions, ignore paths) is case-sensitive.                                 |
+| `case_sensitive_search`               | `bool`                       | `False`                      | If `True`, keyword searching is case-sensitive.                                                         |
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a pull request or open an issue.
+
+1.  Fork the repository.
+2.  Create a new branch (`git checkout -b feature/your-feature-name`).
+3.  Make your changes.
+4.  Commit your changes (`git commit -m 'Add some feature'`).
+5.  Push to the branch (`git push origin feature/your-feature-name`).
+6.  Open a pull request.

{dirshot-0.1.3 → dirshot-0.3.0}/pyproject.toml

@@ -4,22 +4,30 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dirshot"
-version = "0.1.3"
+version = "0.3.0"
 authors = [
   { name="init-helpful", email="init.helpful@gmail.com" },
 ]
-description = "A flexible utility for creating project snapshots and searching for files."
+description = "A flexible, high-performance utility for creating project snapshots and searching files with a rich terminal UI."
 readme = "README.md"
 requires-python = ">=3.7"
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
+    "Topic :: Terminals",
+    "Topic :: Utilities",
 ]
-dependencies = [
-    "tqdm",
-]
+
+
+dependencies = []
 
 [project.urls]
 "Homepage" = "https://github.com/init-helpful/dirshot"
-"Bug Tracker" = "https://github.com/init-helpful/dirshot/issues"
+"Bug Tracker" = "https://github.com/init-helpful/dirshot/issues"
+
+# Install with: pip install dirshot[rich]
+[project.optional-dependencies]
+rich = [
+    "rich>=13.0.0",
+]

dirshot-0.3.0/src/dirshot/__init__.py

@@ -0,0 +1,22 @@
+
+"""
+dirshot - A flexible, high-performance utility for creating project snapshots 
+and searching files with a rich terminal UI.
+"""
+
+from .dirshot import (
+    generate_snapshot,
+    LanguagePreset,
+    IgnorePreset,
+)
+
+__all__ = [
+    # The primary function for all scanning and snapshot operations.
+    "generate_snapshot",
+    
+    # Enums for easy configuration of scanning criteria.
+    "LanguagePreset",
+    "IgnorePreset",
+]
+
+__version__ = "0.2.0"