reposnap 0.3.1__tar.gz → 0.4.0__tar.gz

reposnap-0.4.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.3
+Name: reposnap
+Version: 0.4.0
+Summary: Generate a Markdown file with all contents of your project
+Author: agoloborodko
+License-File: LICENSE
+Requires-Python: >=3.8
+Requires-Dist: gitpython>=3.1.43
+Requires-Dist: pathlib>=1.0.1
+Requires-Dist: pathspec>=0.12.1
+Requires-Dist: urwid>=2.6.15
+Description-Content-Type: text/markdown
+
+# RepoSnap
+
+## Overview
+
+`reposnap` is a Python tool designed to generate a Markdown file that documents the structure and contents of a Git project. It provides both a command-line interface (CLI) and a graphical user interface (GUI) for ease of use. This tool is particularly useful for creating a quick overview of a project's file hierarchy, including optional syntax-highlighted code snippets.
+
+## Features
+
+- **Command-Line Interface (CLI)**: Quickly generate documentation from the terminal.
+- **Graphical User Interface (GUI)**: A user-friendly GUI if you want to select files and directories interactively.
+- **Syntax Highlighting**: Includes syntax highlighting for known file types in the generated Markdown file.
+- **Structure Only Option**: The `--structure-only` flag can be used to generate the Markdown file with just the directory structure, omitting the contents of the files.
+- **Gitignore Support**: Automatically respects `.gitignore` patterns to exclude files and directories.
+
+## Installation
+
+You can install `reposnap` using pip:
+
+```bash
+pip install reposnap
+```
+
+Alternatively, you can clone the repository and install the required dependencies:
+
+```bash
+git clone https://github.com/username/reposnap.git
+cd reposnap
+pip install -r requirements.txt
+```
+
+## Usage
+
+### Command-Line Interface
+
+To use `reposnap` from the command line, run it with the following options:
+
+```bash
+reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] path
+```
+
+- `path`: Path to the Git repository or subdirectory.
+- `-h, --help`: Show help message and exit.
+- `-o, --output`: The name of the output Markdown file. Defaults to `output.md`.
+- `--structure-only`: Generate a Markdown file that includes only the project structure, without file contents.
+- `--debug`: Enable debug-level logging.
+
+#### Examples
+
+1. **Generate a full project structure with file contents**:
+
+    ```bash
+    reposnap .
+    ```
+
+2. **Generate a project structure only**:
+
+    ```bash
+    reposnap my_project/ --structure-only
+    ```
+
+3. **Generate a Markdown file excluding certain files and directories**:
+
+    ```bash
+    reposnap my_project/ -o output.md
+    ```
+
+### Graphical User Interface
+
+`reposnap` also provides a GUI for users who prefer an interactive interface.
+
+To launch the GUI, simply run:
+
+```bash
+reposnap-gui
+```
+
+#### Using the GUI
+
+1. **Select Root Directory**: When the GUI opens, you can specify the root directory of your Git project. By default, it uses the current directory.
+
+2. **Scan the Project**: Click the "Scan" button to analyze the project. The GUI will display the file tree of your project.
+
+3. **Select Files and Directories**: Use the checkboxes to select which files and directories you want to include in the Markdown documentation. Toggling a directory checkbox will toggle all its child files and directories.
+
+4. **Generate Markdown**: After selecting the desired files, click the "Render" button. The Markdown file will be generated and saved as `output.md` in the current directory.
+
+5. **Exit**: Click the "Exit" button to close the GUI.
+
+## Testing
+
+To run the tests, use the following command:
+
+```bash
+pytest tests/
+```
+
+Ensure that you have the `pytest` library installed:
+
+```bash
+pip install pytest
+```
+
+## License
+
+This project is licensed under the MIT License.
+
+## Acknowledgments
+
+- [GitPython](https://gitpython.readthedocs.io/) - Used for interacting with Git repositories.
+- [pathspec](https://pathspec.readthedocs.io/) - Used for pattern matching file paths.
+- [Urwid](https://urwid.org/) - Used for creating the GUI interface.

reposnap-0.4.0/README.md

@@ -0,0 +1,111 @@
+# RepoSnap
+
+## Overview
+
+`reposnap` is a Python tool designed to generate a Markdown file that documents the structure and contents of a Git project. It provides both a command-line interface (CLI) and a graphical user interface (GUI) for ease of use. This tool is particularly useful for creating a quick overview of a project's file hierarchy, including optional syntax-highlighted code snippets.
+
+## Features
+
+- **Command-Line Interface (CLI)**: Quickly generate documentation from the terminal.
+- **Graphical User Interface (GUI)**: A user-friendly GUI if you want to select files and directories interactively.
+- **Syntax Highlighting**: Includes syntax highlighting for known file types in the generated Markdown file.
+- **Structure Only Option**: The `--structure-only` flag can be used to generate the Markdown file with just the directory structure, omitting the contents of the files.
+- **Gitignore Support**: Automatically respects `.gitignore` patterns to exclude files and directories.
+
+## Installation
+
+You can install `reposnap` using pip:
+
+```bash
+pip install reposnap
+```
+
+Alternatively, you can clone the repository and install the required dependencies:
+
+```bash
+git clone https://github.com/username/reposnap.git
+cd reposnap
+pip install -r requirements.txt
+```
+
+## Usage
+
+### Command-Line Interface
+
+To use `reposnap` from the command line, run it with the following options:
+
+```bash
+reposnap [-h] [-o OUTPUT] [--structure-only] [--debug] path
+```
+
+- `path`: Path to the Git repository or subdirectory.
+- `-h, --help`: Show help message and exit.
+- `-o, --output`: The name of the output Markdown file. Defaults to `output.md`.
+- `--structure-only`: Generate a Markdown file that includes only the project structure, without file contents.
+- `--debug`: Enable debug-level logging.
+
+#### Examples
+
+1. **Generate a full project structure with file contents**:
+
+    ```bash
+    reposnap .
+    ```
+
+2. **Generate a project structure only**:
+
+    ```bash
+    reposnap my_project/ --structure-only
+    ```
+
+3. **Generate a Markdown file excluding certain files and directories**:
+
+    ```bash
+    reposnap my_project/ -o output.md
+    ```
+
+### Graphical User Interface
+
+`reposnap` also provides a GUI for users who prefer an interactive interface.
+
+To launch the GUI, simply run:
+
+```bash
+reposnap-gui
+```
+
+#### Using the GUI
+
+1. **Select Root Directory**: When the GUI opens, you can specify the root directory of your Git project. By default, it uses the current directory.
+
+2. **Scan the Project**: Click the "Scan" button to analyze the project. The GUI will display the file tree of your project.
+
+3. **Select Files and Directories**: Use the checkboxes to select which files and directories you want to include in the Markdown documentation. Toggling a directory checkbox will toggle all its child files and directories.
+
+4. **Generate Markdown**: After selecting the desired files, click the "Render" button. The Markdown file will be generated and saved as `output.md` in the current directory.
+
+5. **Exit**: Click the "Exit" button to close the GUI.
+
+## Testing
+
+To run the tests, use the following command:
+
+```bash
+pytest tests/
+```
+
+Ensure that you have the `pytest` library installed:
+
+```bash
+pip install pytest
+```
+
+## License
+
+This project is licensed under the MIT License.
+
+## Acknowledgments
+
+- [GitPython](https://gitpython.readthedocs.io/) - Used for interacting with Git repositories.
+- [pathspec](https://pathspec.readthedocs.io/) - Used for pattern matching file paths.
+- [Urwid](https://urwid.org/) - Used for creating the GUI interface.

{reposnap-0.3.1 → reposnap-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "reposnap"
-version = "0.3.1"
+version = "0.4.0"
 description = "Generate a Markdown file with all contents of your project"
 authors = [
     { name = "agoloborodko" }
@@ -9,6 +9,7 @@ dependencies = [
     "pathlib>=1.0.1",
     "pathspec>=0.12.1",
     "gitpython>=3.1.43",
+    "urwid>=2.6.15",
 ]
 readme = "README.md"
 requires-python = ">= 3.8"
@@ -30,4 +31,5 @@ allow-direct-references = true
 packages = ["src/reposnap"]
 
 [project.scripts]
-reposnap = "reposnap:main"
+reposnap = "reposnap.interfaces.cli:main"
+reposnap-gui = "reposnap.interfaces.gui:main"

{reposnap-0.3.1 → reposnap-0.4.0}/requirements-dev.lock

@@ -27,3 +27,9 @@ pluggy==1.5.0
 pytest==8.3.2
 smmap==5.0.1
     # via gitdb
+typing-extensions==4.12.2
+    # via urwid
+urwid==2.6.15
+    # via reposnap
+wcwidth==0.2.13
+    # via urwid

{reposnap-0.3.1 → reposnap-0.4.0}/requirements.lock

@@ -20,3 +20,9 @@ pathspec==0.12.1
     # via reposnap
 smmap==5.0.1
     # via gitdb
+typing-extensions==4.12.2
+    # via urwid
+urwid==2.6.15
+    # via reposnap
+wcwidth==0.2.13
+    # via urwid

reposnap-0.4.0/src/reposnap/controllers/project_controller.py

@@ -0,0 +1,96 @@
+# src/reposnap/controllers/project_controller.py
+
+import logging
+from pathlib import Path
+from reposnap.core.git_repo import GitRepo
+from reposnap.core.file_system import FileSystem
+from reposnap.core.markdown_generator import MarkdownGenerator
+from reposnap.models.file_tree import FileTree
+import pathspec
+from typing import List, Optional
+
+
+class ProjectController:
+    def __init__(self, args: Optional[object] = None):
+        self.logger = logging.getLogger(__name__)
+        self.root_dir: Path = Path(args.path).resolve() if args else Path('.').resolve()
+        self.output_file: Path = Path(args.output).resolve() if args else Path('output.md').resolve()
+        self.structure_only: bool = args.structure_only if args else False
+        self.args: object = args
+        self.file_tree: Optional[FileTree] = None
+        self.gitignore_patterns: List[str] = []
+        if self.root_dir:
+            self.gitignore_patterns = self._load_gitignore_patterns()
+
+    def set_root_dir(self, root_dir: Path) -> None:
+        self.root_dir = root_dir
+        self.gitignore_patterns = self._load_gitignore_patterns()
+
+    def get_file_tree(self) -> Optional[FileTree]:
+        return self.file_tree
+
+    def run(self) -> None:
+        self.collect_file_tree()
+        self.apply_filters()
+        self.generate_output()
+
+    def collect_file_tree(self) -> None:
+        self.logger.info("Collecting git files.")
+        git_repo: GitRepo = GitRepo(self.root_dir)
+        git_files: List[Path] = git_repo.get_git_files()
+        self.logger.debug(f"Git files before filtering: {git_files}")
+
+        self.logger.info("Building tree structure.")
+        file_system: FileSystem = FileSystem(self.root_dir)
+        tree_structure: dict = file_system.build_tree_structure(git_files)
+
+        self.file_tree = FileTree(tree_structure)
+        self.logger.debug(f"Tree structure: {self.file_tree.structure}")
+
+    def apply_filters(self) -> None:
+        self.logger.info("Applying filters to the file tree.")
+        spec: pathspec.PathSpec = pathspec.PathSpec.from_lines(pathspec.patterns.GitWildMatchPattern, self.gitignore_patterns)
+        self.logger.debug(f"Filter patterns: {self.gitignore_patterns}")
+        self.file_tree.filter_files(spec)
+
+    def generate_output(self) -> None:
+        self.logger.info("Starting markdown generation.")
+        markdown_generator: MarkdownGenerator = MarkdownGenerator(
+            root_dir=self.root_dir,
+            output_file=self.output_file,
+            structure_only=self.structure_only
+        )
+        markdown_generator.generate_markdown(self.file_tree.structure, self.file_tree.get_all_files())
+        self.logger.info(f"Markdown generated at {self.output_file}.")
+
+    def generate_output_from_selected(self, selected_files: set) -> None:
+        self.logger.info("Generating markdown from selected files.")
+        # Build a pruned tree structure based on selected files
+        pruned_tree = self.file_tree.prune_tree(selected_files)
+        markdown_generator: MarkdownGenerator = MarkdownGenerator(
+            root_dir=self.root_dir,
+            output_file=self.output_file,
+            structure_only=False,
+            hide_untoggled=True
+        )
+        markdown_generator.generate_markdown(pruned_tree, [Path(f) for f in selected_files])
+        self.logger.info(f"Markdown generated at {self.output_file}.")
+
+    def _load_gitignore_patterns(self) -> List[str]:
+        gitignore_path: Path = self.root_dir / '.gitignore'
+        if not gitignore_path.exists():
+            for parent in self.root_dir.parents:
+                gitignore_path = parent / '.gitignore'
+                if gitignore_path.exists():
+                    break
+            else:
+                gitignore_path = None
+
+        if gitignore_path and gitignore_path.exists():
+            with gitignore_path.open('r') as gitignore:
+                patterns: List[str] = gitignore.readlines()
+            self.logger.debug(f"Patterns from .gitignore in {gitignore_path.parent}: {patterns}")
+            return patterns
+        else:
+            self.logger.debug(f"No .gitignore found starting from {self.root_dir}. Proceeding without patterns.")
+            return []

{reposnap-0.3.1 → reposnap-0.4.0}/src/reposnap/core/file_system.py

@@ -2,29 +2,31 @@
 
 import logging
 from pathlib import Path
+from typing import List, Dict, Any
+
 
 class FileSystem:
     def __init__(self, root_dir: Path):
-        self.root_dir = root_dir.resolve()
+        self.root_dir: Path = root_dir.resolve()
         self.logger = logging.getLogger(__name__)
 
-    def build_tree_structure(self, files):
+    def build_tree_structure(self, files: List[Path]) -> Dict[str, Any]:
         """
         Builds a hierarchical tree structure from the list of files.
 
         Args:
-            files (list of Path): List of file paths relative to root_dir.
+            files (List[Path]): List of file paths relative to root_dir.
 
         Returns:
-            dict: Nested dictionary representing the directory structure.
+            Dict[str, Any]: Nested dictionary representing the directory structure.
         """
-        tree = {}
+        tree: Dict[str, Any] = {}
         self.logger.debug("Building tree structure.")
         for relative_path in files:
             parts = relative_path.parts
             current_level = tree
             for part in parts[:-1]:
                 current_level = current_level.setdefault(part, {})
-            current_level[parts[-1]] = relative_path.as_posix()
+            current_level[parts[-1]] = None  # Indicate a file node
         self.logger.debug(f"Tree structure built: {tree}")
         return tree

{reposnap-0.3.1 → reposnap-0.4.0}/src/reposnap/core/git_repo.py

@@ -3,23 +3,25 @@
 import logging
 from pathlib import Path
 from git import Repo, InvalidGitRepositoryError
+from typing import List
+
 
 class GitRepo:
     def __init__(self, repo_path: Path):
-        self.repo_path = repo_path.resolve()
+        self.repo_path: Path = repo_path.resolve()
         self.logger = logging.getLogger(__name__)
 
-    def get_git_files(self):
+    def get_git_files(self) -> List[Path]:
         try:
-            repo = Repo(self.repo_path, search_parent_directories=True)
-            repo_root = Path(repo.working_tree_dir).resolve()
-            git_files = repo.git.ls_files().splitlines()
+            repo: Repo = Repo(self.repo_path, search_parent_directories=True)
+            repo_root: Path = Path(repo.working_tree_dir).resolve()
+            git_files: List[str] = repo.git.ls_files().splitlines()
             self.logger.debug(f"Git files from {repo_root}: {git_files}")
-            git_files_relative = []
+            git_files_relative: List[Path] = []
             for f in git_files:
-                absolute_path = (repo_root / f).resolve()
+                absolute_path: Path = (repo_root / f).resolve()
                 try:
-                    relative_path = absolute_path.relative_to(self.repo_path)
+                    relative_path: Path = absolute_path.relative_to(self.repo_path)
                     git_files_relative.append(relative_path)
                 except ValueError:
                     # Skip files not under root_dir
@@ -28,3 +30,4 @@ class GitRepo:
         except InvalidGitRepositoryError:
             self.logger.error(f"Invalid Git repository at: {self.repo_path}")
             return []
+

{reposnap-0.3.1 → reposnap-0.4.0}/src/reposnap/core/markdown_generator.py

@@ -2,28 +2,31 @@
 
 import logging
 from pathlib import Path
-from ..utils.path_utils import format_tree
+from reposnap.utils.path_utils import format_tree
+from typing import List, Dict, Any
+
 
 class MarkdownGenerator:
-    def __init__(self, root_dir: Path, output_file: Path, structure_only: bool = False):
-        self.root_dir = root_dir.resolve()
-        self.output_file = output_file.resolve()
-        self.structure_only = structure_only
+    def __init__(self, root_dir: Path, output_file: Path, structure_only: bool = False, hide_untoggled: bool = False):
+        self.root_dir: Path = root_dir.resolve()
+        self.output_file: Path = output_file.resolve()
+        self.structure_only: bool = structure_only
+        self.hide_untoggled: bool = hide_untoggled
         self.logger = logging.getLogger(__name__)
 
-    def generate_markdown(self, tree_structure: dict, files: list):
+    def generate_markdown(self, tree_structure: Dict[str, Any], files: List[Path]) -> None:
         """
         Generates the Markdown file based on the provided tree structure and files.
 
         Args:
-            tree_structure (dict): The hierarchical structure of the project files.
-            files (list of Path): List of file paths to include in the markdown.
+            tree_structure (Dict[str, Any]): The hierarchical structure of the project files.
+            files (List[Path]): List of file paths to include in the markdown.
         """
         self._write_header(tree_structure)
         if not self.structure_only:
             self._write_file_contents(files)
 
-    def _write_header(self, tree_structure: dict):
+    def _write_header(self, tree_structure: Dict[str, Any]) -> None:
         """
         Writes the header and project structure to the Markdown file.
         """
@@ -32,7 +35,7 @@ class MarkdownGenerator:
             with self.output_file.open('w', encoding='utf-8') as f:
                 f.write("# Project Structure\n\n")
                 f.write("```\n")
-                for line in format_tree(tree_structure):
+                for line in format_tree(tree_structure, hide_untoggled=self.hide_untoggled):
                     f.write(line)
                 f.write("```\n\n")
             self.logger.debug("Header and project structure written successfully.")
@@ -40,16 +43,16 @@ class MarkdownGenerator:
             self.logger.error(f"Failed to write header to {self.output_file}: {e}")
             raise
 
-    def _write_file_contents(self, files: list):
+    def _write_file_contents(self, files: List[Path]) -> None:
         """
         Writes the contents of each file to the Markdown file.
 
         Args:
-            files (list of Path): List of file paths relative to root_dir.
+            files (List[Path]): List of file paths relative to root_dir.
         """
         self.logger.debug("Writing file contents to Markdown.")
         for relative_path in files:
-            file_path = self.root_dir / relative_path
+            file_path: Path = self.root_dir / relative_path
 
             if not file_path.exists():
                 self.logger.debug(f"File not found: {file_path}. Skipping.")
@@ -57,13 +60,13 @@ class MarkdownGenerator:
 
             self._write_file_content(file_path, relative_path.as_posix())
 
-    def _write_file_content(self, file_path: Path, relative_path: str):
+    def _write_file_content(self, file_path: Path, relative_path: str) -> None:
         """
         Writes the content of a single file to the Markdown file with syntax highlighting.
         """
         try:
             with file_path.open('r', encoding='utf-8') as f:
-                content = f.read()
+                content: str = f.read()
             with self.output_file.open('a', encoding='utf-8') as f:
                 f.write(f"## {relative_path}\n\n")
                 f.write("```python\n" if file_path.suffix == '.py' else "```\n")

reposnap-0.4.0/src/reposnap/interfaces/cli.py

@@ -0,0 +1,25 @@
+# src/reposnap/interfaces/cli.py
+
+import argparse
+import logging
+from reposnap.controllers.project_controller import ProjectController
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Generate a Markdown representation of a Git repository.')
+    parser.add_argument('path', nargs='?', default='.', help='Path to the Git repository or subdirectory.')
+    parser.add_argument('-o', '--output', help='Output Markdown file', default='output.md')
+    parser.add_argument('--structure-only', action='store_true',
+                        help='Only include the file structure without content.')
+    parser.add_argument('--debug', action='store_true', help='Enable debug-level logging.')
+
+    args = parser.parse_args()
+
+    log_level = logging.DEBUG if args.debug else logging.INFO
+    logging.basicConfig(level=log_level, format='%(asctime)s - %(levelname)s - %(message)s')
+
+    controller = ProjectController(args)
+    controller.run()
+
+if __name__ == "__main__":
+    main()