Initial commit

.gitignore

@@ -0,0 +1,6 @@
+.idea
+.git
+.pypirc
+/*.egg-info
+/dist
+*/__pycache__/

LICENSE.rst

@@ -0,0 +1,28 @@
+Copyright 2024 Armen-Jean Andreasian
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1.  Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+3.  Neither the name of the copyright holder nor the names of its
+    contributors may be used to endorse or promote products derived from
+    this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,58 @@
+## The Directory Scanner
+
+The Directory Scanner is a Python library designed to simplify the process of scanning directory structures and generating a comprehensive list of files and folders. It provides a convenient way to recursively traverse directories, ignoring specific files and folders specified by the user.
+
+![](.github/cover.jpg)
+### Features:
+- Recursively scan directories and subdirectories to generate a structured list of files and folders.
+- Exclude specific files and folders from the scan using an ignore list.
+- Supports customization of the output format to suit different needs.
+
+### Usage:
+1. Install the library using pip:
+    ```
+    pip install the-directory-scanner
+    ```
+
+2. Import the `scan_directory` function from the library and use it to scan a directory:
+    ```python
+   from the_directory_scanner import scan_directory
+
+   scan_result = scan_directory(directory=".", output_file_name="directory_structure.txt",
+                                ignored_items=('.git', '.idea', 'venv', '__pycache__',))
+    ```
+3. Access the generated directory structure in the output file (`directory_structure.txt` in this example) to view the results.
+
+4. If you wish to modify the structure, import `prettify_structure` function and provide the path to generated file:
+   ```python
+   from the_directory_scanner import scan_directory, prettify_structure
+
+   scan_result = scan_directory(directory=".", output_file_name="directory_structure.txt",
+                                ignored_items=('.git', '.idea', 'venv', '__pycache__',))
+
+   prettify_structure(output_file=scan_result, spaces_to_trim=4, lines_to_trim=1)
+   ```
+
+---
+Output example `directory_structure.txt`:
+```
+directory_structure.txt
+LICENSE.rst
+README.md
+setup.py
+usage.py
+directory_scanner/
+    directory_structure.txt
+    main.py
+    __init__.py
+```
+---
+
+### About:
+The Directory Scanner library aims to simplify directory scanning tasks by providing a flexible and easy-to-use interface. Whether you need to generate a directory structure for documentation, analysis, or any other purpose, this library offers a convenient solution.
+
+### Links:
+- [GitHub Repository](https://github.com/Armen-Jean-Andreasian/the-directory-scanner)
+- [PyPI Package](https://pypi.org/project/the-directory-scanner/)
+
+---

directory_structure.txt

@@ -0,0 +1,14 @@
+cover.jpg
+directory_structure.txt
+LICENSE.rst
+README.md
+setup.py
+usage.py
+the_directory_scanner/
+    main.py
+    __init__.py
+the_directory_scanner.egg-info/
+    dependency_links.txt
+    PKG-INFO
+    SOURCES.txt
+    top_level.txt

setup.py

@@ -0,0 +1,39 @@
+from setuptools import setup
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name='the-directory-scanner',
+    packages=['the_directory_scanner'],
+    version='1.0',
+    license='BSD',
+
+    description='The Directory Scanner is a Python library designed to simplify the process of scanning directory structures and generating a comprehensive list of files and folders. It provides a convenient way to recursively traverse directories, ignoring specific files and folders specified by the user.',
+
+    author='Armen-Jean Andreasian',
+    author_email='[email protected]',
+
+    url='https://github.com/Armen-Jean-Andreasian',
+    keywords=['directory structure', 'python'],
+    # Keywords users can search on PyPI
+
+    classifiers=[
+        'Development Status :: 3 - Alpha',
+        'Intended Audience :: Developers',
+        'Topic :: Software Development :: Libraries :: Python Modules',
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: BSD License",
+        "Operating System :: OS Independent",
+    ],
+
+    install_requires=[
+        # List any dependencies your library may have
+    ],
+
+    python_requires='>=3.8',
+
+    long_description=long_description
+    ,
+    long_description_content_type='text/markdown',
+)

the_directory_scanner/__init__.py

@@ -0,0 +1 @@
+from .main import scan_directory, prettify_structure

the_directory_scanner/main.py

@@ -0,0 +1,56 @@
+import os
+
+def scan_directory(directory: str = None, output_file_name: str = None, ignored_items: tuple = None) -> str:
+    """
+    Scans the specified directory and writes its structure to a file.
+
+    :param directory: Path to the directory to be scanned. If not specified, the current directory is used.
+    :param output_file_name: Name of the file where the structure will be written. Default is 'directory_structure.txt'.
+    :param ignored_items: List of files and directories to ignore during scanning.
+                        Default is ('.git', '.idea', 'venv', '__pycache__').
+    :return: Name of the file where the structure is written.
+    """
+    if output_file_name is None:
+        output_file_name = 'directory_structure.txt'
+
+    if ignored_items is None:
+        ignored_items = ('.git', '.idea', 'venv', '__pycache__',)
+
+    if directory is None:
+        directory = "."
+
+    with open(output_file_name, 'w') as f:
+        for root, dirs, files in os.walk(directory):
+            level = root.replace(directory, '').count(os.sep)
+            indent = ' ' * 4 * level
+
+            if any(ignore_item in root for ignore_item in ignored_items):
+                continue
+
+            basename = os.path.basename(root)
+            f.write('{}{}/\n'.format(indent, basename))
+
+            sub_indent = ' ' * 4 * (level + 1)
+            for file in files:
+                if any(ignore_item in file for ignore_item in ignored_items):
+                    continue
+
+                f.write('{}{}\n'.format(sub_indent, file))
+    print("Directory structure was captured in file:", output_file_name)
+    return output_file_name
+
+def prettify_structure(output_file: str, spaces_to_trim: int, lines_to_trim: int):
+    """
+    Trims specified number of spaces and lines from the beginning of the file.
+
+    :param output_file: The file to prettify.
+    :param spaces_to_trim: Number of spaces to trim from the beginning of each line.
+    :param lines_to_trim: Number of lines to trim from the beginning of the file.
+    :return: None
+    """
+    with open(output_file, 'r') as f:
+        lines = f.readlines()
+
+    with open(output_file, 'w') as f:
+        for line in lines[lines_to_trim:]:
+            f.write(line[spaces_to_trim:])

usage.py

@@ -0,0 +1,8 @@
+from the_directory_scanner import scan_directory
+from the_directory_scanner import prettify_structure
+
+scan_result = scan_directory(directory=".",
+                             output_file_name="directory_structure.txt",
+                             ignored_items=('.git', '.idea', 'venv', '__pycache__', 'whatever'))
+
+prettify_structure(output_file=scan_result, spaces_to_trim=4, lines_to_trim=1)