dirshot 0.1.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,194 @@
1
+ Metadata-Version: 2.4
2
+ Name: dirshot
3
+ Version: 0.2.0
4
+ Summary: A flexible, high-performance utility for creating project snapshots and searching files with a rich terminal UI.
5
+ Author-email: init-helpful <init.helpful@gmail.com>
6
+ Project-URL: Homepage, https://github.com/init-helpful/dirshot
7
+ Project-URL: Bug Tracker, https://github.com/init-helpful/dirshot/issues
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: License :: OSI Approved :: MIT License
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Topic :: Terminals
12
+ Classifier: Topic :: Utilities
13
+ Requires-Python: >=3.7
14
+ Description-Content-Type: text/markdown
15
+ Provides-Extra: rich
16
+ Requires-Dist: rich>=13.0.0; extra == "rich"
17
+
18
+
19
+ # dirshot 📸
20
+
21
+ [![PyPI version](https://badge.fury.io/py/dirshot.svg)](https://badge.fury.io/py/dirshot)
22
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
23
+ ![Python Version](https://img.shields.io/pypi/pyversions/dirshot)
24
+
25
+ A flexible, high-performance utility for creating project snapshots and searching files, complete with rich visual feedback in your terminal.
26
+
27
+ `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.
28
+
29
+ ---
30
+
31
+ ## ✨ Key Features
32
+
33
+ - **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.
34
+ - **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.).
35
+ - **Dual Modes**:
36
+ - **Snapshot Mode**: Collate all project files matching your criteria into a single, easy-to-share output file.
37
+ - **Search Mode**: Hunt for specific keywords in filenames or, optionally, within file contents.
38
+ - **Highly Customizable**: Fine-tune scans by combining presets with manual lists of file extensions, ignore paths, and specific file names to include or exclude.
39
+ - **Concurrent & Fast**: Uses a `ThreadPoolExecutor` for high-performance file discovery and processing, making scans quick and efficient.
40
+ - **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.
41
+
42
+ ## 📦 Installation
43
+
44
+ You can install `dirshot` directly from PyPI.
45
+
46
+ **Basic Installation (no visual dependencies):**
47
+
48
+ ```bash
49
+ pip install dirshot
50
+ ```
51
+
52
+ **Installation with Enhanced Terminal Visuals:**
53
+
54
+ To get the full rich terminal experience, install the `rich` extra, which adds support for `rich`.
55
+
56
+ ```bash
57
+ pip install dirshot[rich]
58
+ ```
59
+
60
+ ## 🚀 How to Use
61
+
62
+ `dirshot` is used by importing the `generate_snapshot` function into a Python script.
63
+
64
+ Here is a basic example of creating a snapshot of a Python project:
65
+
66
+ ```python
67
+ # snapshot_script.py
68
+ from src.dirshot import generate_snapshot, LanguagePreset, IgnorePreset
69
+ # or
70
+ # from src.dirshot import *
71
+
72
+ generate_snapshot(
73
+ root_directory=".", # optional
74
+ output_file_name="my_python_project.txt",
75
+ language_presets=[LanguagePreset.PYTHON, LanguagePreset.MARKUP],
76
+ ignore_presets=[
77
+ IgnorePreset.VERSION_CONTROL, # Ignore .git
78
+ IgnorePreset.PYTHON, # Ignore __pycache__, venv, etc.
79
+ IgnorePreset.IDE_METADATA # Ignore .vscode, .idea
80
+ ],
81
+ generate_tree=True,
82
+ show_token_count=True
83
+ )
84
+ ```
85
+
86
+ To run this, save the code as a Python file (e.g., `snapshot_script.py`) and execute it from your terminal:
87
+
88
+ ```bash
89
+ python snapshot_script.py
90
+ ```
91
+
92
+ ## 📋 Examples
93
+
94
+ The `examples.py` file in the repository contains many more use cases. Here are a few common ones:
95
+
96
+ #### 1. Full-Stack Web App (React + Node.js)
97
+
98
+ This example combines multiple presets to capture a full-stack JavaScript project while ignoring common clutter like `node_modules`.
99
+
100
+ ```python
101
+ generate_snapshot(
102
+ root_directory=".",
103
+ output_file_name="fullstack_js_snapshot.txt",
104
+ language_presets=[
105
+ LanguagePreset.REACT, # Handles all frontend JS/TS/JSX files
106
+ LanguagePreset.WEB_FRONTEND # Includes HTML and CSS files
107
+ ],
108
+ ignore_presets=[
109
+ IgnorePreset.NODE_JS, # Crucial for ignoring node_modules
110
+ IgnorePreset.IDE_METADATA,
111
+ IgnorePreset.BUILD_ARTIFACTS,
112
+ IgnorePreset.VERSION_CONTROL
113
+ ],
114
+ generate_tree=True,
115
+ show_tree_stats=True
116
+ )
117
+ ```
118
+
119
+ #### 2. Data Science Project (Python, Notebooks & SQL)
120
+
121
+ Collate all relevant files from a data analysis or machine learning project.
122
+
123
+ ```python
124
+ generate_snapshot(
125
+ root_directory="./data_science_project",
126
+ output_file_name="data_science_snapshot.txt",
127
+ language_presets=[
128
+ LanguagePreset.PYTHON,
129
+ LanguagePreset.DATA_SCIENCE_NOTEBOOKS, # .ipynb
130
+ LanguagePreset.SQL,
131
+ LanguagePreset.MARKUP # Include READMEs
132
+ ],
133
+ ignore_presets=[
134
+ IgnorePreset.PYTHON, # Ignores venv, __pycache__, etc.
135
+ IgnorePreset.JUPYTER_NOTEBOOKS, # Ignores .ipynb_checkpoints
136
+ IgnorePreset.IDE_METADATA,
137
+ IgnorePreset.VERSION_CONTROL
138
+ ]
139
+ )
140
+ ```
141
+
142
+ #### 3. Search for Secrets or API Keys
143
+
144
+ Use "Search Mode" to perform a security audit. This example intentionally omits the `SECRET_FILES` ignore preset to ensure `.env` files are searched.
145
+
146
+ ```python
147
+ generate_snapshot(
148
+ root_directory=".",
149
+ output_file_name="secrets_audit_results.txt",
150
+ search_keywords=["password", "secret_key", "api_key", "token"],
151
+ language_presets=[LanguagePreset.CONFIGURATION],
152
+ search_file_contents=True,
153
+ ignore_presets=[
154
+ IgnorePreset.VERSION_CONTROL,
155
+ IgnorePreset.NODE_JS,
156
+ IgnorePreset.BUILD_ARTIFACTS
157
+ # Deliberately not ignoring SECRET_FILES
158
+ ]
159
+ )
160
+ ```
161
+
162
+ ## ⚙️ API Reference
163
+
164
+ The `generate_snapshot()` function accepts the following parameters:
165
+
166
+ | Parameter | Type | Default | Description |
167
+ | ------------------------------------- | ---------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
168
+ | `root_directory` | `str` | `"."` | The starting directory for the scan. |
169
+ | `output_file_name` | `str` | `"project_snapshot.txt"` | The name of the file to save the results to. |
170
+ | `search_keywords` | `Optional[List[str]]` | `None` | If provided, switches to **Search Mode**. Otherwise, runs in **Snapshot Mode**. |
171
+ | `language_presets` | `Optional[List[LanguagePreset]]` | `None` | A list of `LanguagePreset` enums for common file types (e.g., `LanguagePreset.PYTHON`). |
172
+ | `ignore_presets` | `Optional[List[IgnorePreset]]` | `None` | A list of `IgnorePreset` enums for common ignore patterns (e.g., `IgnorePreset.NODE_JS`). |
173
+ | `file_extensions` | `Optional[List[str]]` | `None` | A manual list of file extensions to include (e.g., `[".py", ".md"]`). |
174
+ | `ignore_if_in_path` | `Optional[List[str]]` | `None` | A manual list of directory or file names to exclude. |
175
+ | `ignore_extensions` | `Optional[List[str]]` | `None` | A manual list of file extensions to explicitly ignore (e.g., `[".log", ".tmp"]`). |
176
+ | `search_file_contents` | `bool` | `True` | In Search Mode, search for keywords within file contents. |
177
+ | `generate_tree` | `bool` | `True` | Include a file tree of the matched files at the top of the output. |
178
+ | `show_tree_stats` | `bool` | `False` | Display file and directory counts in the generated tree. |
179
+ | `show_token_count` | `bool` | `False` | Display an approximated token/character count in the summary and output file. |
180
+ | `exclude_whitespace_in_token_count` | `bool` | `False` | If `True`, removes whitespace before counting tokens for a more compact count. |
181
+ | `max_workers` | `Optional[int]` | `CPU count + 4` | The maximum number of worker threads for concurrent processing. |
182
+ | `read_binary_files` | `bool` | `False` | If `True`, the content search will attempt to read and search through binary files. |
183
+
184
+ ## 🤝 Contributing
185
+
186
+ Contributions are welcome! Please feel free to submit a pull request or open an issue.
187
+
188
+ 1. Fork the repository.
189
+ 2. Create a new branch (`git checkout -b feature/your-feature-name`).
190
+ 3. Make your changes.
191
+ 4. Commit your changes (`git commit -m 'Add some feature'`).
192
+ 5. Push to the branch (`git push origin feature/your-feature-name`).
193
+ 6. Open a pull request.
194
+
@@ -0,0 +1,6 @@
1
+ dirshot/__init__.py,sha256=OpzEFnxp6FpjdapuhBF5UTEc-rpR-Z9r0B2wa9gTSwo,476
2
+ dirshot/dirshot.py,sha256=ScuXzqd3GKxR_sEwnPXCE-6Bh4h34NehfQo8u-oZGNk,38031
3
+ dirshot-0.2.0.dist-info/METADATA,sha256=IEiMd97Wsa8CTJJBEW78DqsYluu7G3_zTxm9ClpSFT8,10394
4
+ dirshot-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
5
+ dirshot-0.2.0.dist-info/top_level.txt,sha256=ROGW8gTcmwJ2jJ1Fp7TV1REZLRUGbL3L-Lfoy8tPxOA,8
6
+ dirshot-0.2.0.dist-info/RECORD,,
dirshot/examples.py DELETED
@@ -1,65 +0,0 @@
1
- from src.dirshot.dirshot import *
2
-
3
- if __name__ == "__main__":
4
- # To run a specific example, make sure it is NOT commented out,
5
- # and the other examples ARE commented out.
6
-
7
- # --- Example 1: Search with NO Presets (Custom Filters) ---
8
- # Goal: Find the words "API" or "Controller" inside any .java or .js file,
9
- # while manually ignoring common dependency/build folders.
10
- # print("\n--- Example 1: Running a custom search with NO presets ---")
11
- # find_in_project(
12
- # root_dir_param="example_project",
13
- # output_file_name="search_custom_results.txt",
14
- # search_keywords=["API", "Controller"],
15
-
16
- # # --- NO language_presets ---
17
- # # Manually define which file types to scan
18
- # file_extensions_to_check=[".java", ".js"],
19
-
20
- # # --- NO ignore_presets ---
21
- # # Manually define which directories to skip
22
- # ignore_dirs_in_path=["node_modules", "build", "venv"],
23
-
24
- # search_file_contents=True,
25
- # show_tree_stats=True,
26
- # show_token_count=True,
27
- # )
28
-
29
-
30
- # # --- Example 2: Search with Python Presets ---
31
- # # Goal: Find the word "Flask" inside any Python-related file.
32
- # # The presets will automatically handle file types and ignore folders like 'venv'.
33
- # print("\n--- Example 2: Running a search with Python presets ---")
34
- # find_in_project(
35
- # root_dir_param=".",
36
- # output_file_name="search_python_preset_results.txt",
37
- # search_keywords=[""],
38
-
39
- # # Use presets for convenience
40
- # language_presets=[LanguagePreset.PYTHON],
41
- # ignore_presets=[IgnorePreset.PYTHON_ENV],
42
-
43
- # search_file_contents=True,
44
- # show_tree_stats=True,
45
- # show_token_count=True,
46
- # )
47
-
48
-
49
- filter_project(
50
- root_dir_param=".",
51
- output_file_name="snapshot.txt",
52
- file_types=[".py"],
53
- # Use presets to define the scope of the snapshot
54
- # language_presets=[LanguagePreset.PYTHON],
55
-
56
- ignore_dirs_in_path=[".git"],
57
- ignore_presets=[
58
- IgnorePreset.PYTHON_ENV,
59
- IgnorePreset.NODE_MODULES,
60
- IgnorePreset.BUILD_ARTIFACTS,
61
- ],
62
-
63
- show_tree_stats=False,
64
- show_token_count=True,
65
- )
@@ -1,110 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: dirshot
3
- Version: 0.1.3
4
- Summary: A flexible utility for creating project snapshots and searching for files.
5
- Author-email: init-helpful <init.helpful@gmail.com>
6
- Project-URL: Homepage, https://github.com/init-helpful/dirshot
7
- Project-URL: Bug Tracker, https://github.com/init-helpful/dirshot/issues
8
- Classifier: Programming Language :: Python :: 3
9
- Classifier: License :: OSI Approved :: MIT License
10
- Classifier: Operating System :: OS Independent
11
- Requires-Python: >=3.7
12
- Description-Content-Type: text/markdown
13
- Requires-Dist: tqdm
14
-
15
- # Dirshot: A Flexible Project Snapshot and Search Tool
16
-
17
- Dirshot is a Python utility that creates snapshots of a project's directory structure and file contents. It can operate in two modes: filtering files based on their type and path, or searching for files based on keywords in their name or content.
18
-
19
- The script generates a single output file containing a directory tree and the concatenated text of the selected files. This is useful for quickly gathering project context for code analysis, sharing with collaborators, or providing to a Large Language Model (LLM).
20
-
21
- ## Key Features
22
-
23
- * **Two Operating Modes**:
24
- * **Filter Mode**: Create a snapshot of your project by filtering files based on extensions, filenames, and directory paths.
25
- * **Search Mode**: Search for files containing specific keywords in their name, path, or content.
26
- * **Customizable Filtering**:
27
- * Use language presets for popular languages (Python, JavaScript, Java, etc.).
28
- * Use ignore presets to exclude common files and directories (e.g., `.git`, `node_modules`, `__pycache__`).
29
- * Define custom file types, and whitelist/blacklist substrings in filenames and paths.
30
- * **Flexible Tree Generation**:
31
- * Display a directory tree in various styles (Unicode, ASCII, Compact).
32
- * Show statistics for included/matched files and directories in the tree.
33
- * **Content Collation**:
34
- * Concatenates the content of all selected files into a single output file.
35
- * Optionally display an approximated token/character count.
36
- * **Snapshot Deconstruction**:
37
- * A utility function to parse a generated snapshot file and extract the directory tree and file paths.
38
-
39
- ## Installation
40
-
41
- You can install Dirshot from PyPI:
42
-
43
- ```bash
44
- pip install dirshot
45
- ```
46
-
47
-
48
-
49
- ## Usage
50
-
51
- Here are some examples of how to use Dirshot in your own Python scripts.
52
-
53
- #### Example 1: Creating a Snapshot with Presets (Filter Mode)
54
-
55
- This example creates a snapshot of a Python project, ignoring common virtual environment and build directories.
56
-
57
- ```python
58
- from dirshot import filter_project, LanguagePreset, IgnorePreset
59
-
60
- filter_project(
61
- root_dir_param=".",
62
- output_file_name="project_snapshot.txt",
63
- language_presets=[LanguagePreset.PYTHON],
64
- ignore_presets=[
65
- IgnorePreset.PYTHON_ENV,
66
- IgnorePreset.NODE_MODULES,
67
- IgnorePreset.BUILD_ARTIFACTS,
68
- ],
69
- show_token_count=True,
70
- )
71
- ```
72
-
73
- #### Example 2: Searching for Keywords in a Project (Search Mode)
74
-
75
- This example searches for the keywords "API" or "Controller" within `.java` and `.js` files.
76
-
77
- ```python
78
- from dirshot import find_in_project
79
-
80
- find_in_project(
81
- root_dir_param="example_project",
82
- output_file_name="search_results.txt",
83
- search_keywords=["API", "Controller"],
84
- file_extensions_to_check=[".java", ".js"],
85
- ignore_dirs_in_path=["node_modules", "build"],
86
- search_file_contents=True,
87
- show_tree_stats=True,
88
- )
89
- ```
90
-
91
- ### Deconstructing a Snapshot
92
-
93
- You can also parse a previously generated snapshot file to extract the directory structure and the list of included files.
94
-
95
- ```python
96
- from dirshot import deconstruct_snapshot
97
-
98
- snapshot_data = deconstruct_snapshot("project_snapshot.txt")
99
- print("Directory Tree:")
100
- for line in snapshot_data["tree_lines"]:
101
- print(line)
102
-
103
- print("\nIncluded Files:")
104
- for file_path in snapshot_data["file_paths"]:
105
- print(file_path)
106
- ```
107
-
108
- ## Contributing
109
-
110
- Contributions are welcome! Please feel free to submit a pull request or open an issue on the project's GitHub repository.
@@ -1,7 +0,0 @@
1
- dirshot/__init__.py,sha256=ss4HC5VTyD9j6GFGCLMU6VxPlXy0qaGFzXlZB3_d2WM,403
2
- dirshot/dirshot.py,sha256=2zx4ghzYi5Rsh-C0maHATapF2ArremgRLFWJlWlRu34,40365
3
- dirshot/examples.py,sha256=q--iNqxmA4xX8nyXYdOP-HPsqzpLHBFo1PTseQ9ki7M,2344
4
- dirshot-0.1.3.dist-info/METADATA,sha256=9mdpQmEFer0rY-kineW0bSU2OZHHYo7FNw1eDCZ_M4I,4172
5
- dirshot-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
6
- dirshot-0.1.3.dist-info/top_level.txt,sha256=ROGW8gTcmwJ2jJ1Fp7TV1REZLRUGbL3L-Lfoy8tPxOA,8
7
- dirshot-0.1.3.dist-info/RECORD,,