pytreebuilder 0.1.12
A module to create project structures from a tree description text file
Requires Python: >=3.6

# pytreebuilder

## Table of Contents
- [pytreebuilder](#pytreebuilder)
  - [Table of Contents](#table-of-contents)
  - [Module Structure Description](#module-structure-description)
    - [Description of Directories and Files](#description-of-directories-and-files)
  - [Description of the `pytreebuilder` Project](#description-of-the-pytreebuilder-project)
    - [Objective](#objective)
    - [Key Features](#key-features)
    - [Detailed Description of Functionalities](#detailed-description-of-functionalities)
      - [1. Automatic Creation of Project Structures](#1-automatic-creation-of-project-structures)
      - [2. Update Mode](#2-update-mode)
      - [3. Logging Configuration](#3-logging-configuration)
      - [4. Error Handling](#4-error-handling)
      - [5. Command Line Arguments](#5-command-line-arguments)
      - [6. Creation of Files and Directories](#6-creation-of-files-and-directories)
      - [7. Example Project Structure](#7-example-project-structure)
        - [Any Project Structure](#any-project-structure)
      - [8. Installation and Usage](#8-installation-and-usage)
      - [9. Unit Testing](#9-unit-testing)
      - [10. Documentation and Support](#10-documentation-and-support)
    - [Installation](#installation)
      - [Cloning the Repository](#cloning-the-repository)
      - [Local Installation](#local-installation)
      - [Installation via Internet](#installation-via-internet)
    - [Usage](#usage)
      - [Running the Script](#running-the-script)
      - [Command Line Arguments](#command-line-arguments)
    - [How to Test the `pytreebuilder` Module](#how-to-test-the-pytreebuilder-module)
      - [Prerequisites](#prerequisites)
      - [Step-by-Step Guide](#step-by-step-guide)
      - [Example Output](#example-output)
      - [Troubleshooting](#troubleshooting)
    - [Example: Using the `pytreebuilder` Module](#example-using-the-pytreebuilder-module)
      - [Step 1: Create a Description File](#step-1-create-a-description-file)
      - [Step 2: Install the `pytreebuilder` Module](#step-2-install-the-pytreebuilder-module)
      - [Step 3: Create a Python Script to Use the Module](#step-3-create-a-python-script-to-use-the-module)
      - [Step 4: Run the Script](#step-4-run-the-script)
      - [Step 5: Verify the Project Structure](#step-5-verify-the-project-structure)
    - [Running Examples from the Project Root](#running-examples-from-the-project-root)
      - [Example 1: Simple Project Structure](#example-1-simple-project-structure)
      - [Example 2: Complex Project Structure](#example-2-complex-project-structure)
    - [Summary](#summary)
    - [Contributing to the Project](#contributing-to-the-project)
      - [Fork the Repository](#fork-the-repository)
      - [Create a Branch](#create-a-branch)
      - [Submit Changes](#submit-changes)
    - [Support and Assistance](#support-and-assistance)
    - [Copyright](#copyright)

## Module Structure Description

### Description of Directories and Files
- **examples/** : Contains example scripts demonstrating how to use the `pytreebuilder` module.
  - **any_project_tree.py** : Script to create a simple project structure based on `trees/any_project_tree.txt`.
  - **complex_tree.py** : Script to create a complex project structure based on `trees/complex_tree.txt`.

- **logs/** : Directory for log files generated by the `pytreebuilder` module.
  - **pytreebuilder.log** : Log file recording the actions performed by the `pytreebuilder` module.

- **tests/** : Contains unit tests for the `pytreebuilder` module.
  - **__init__.py** : Initialization file for the tests package.
  - **test_pytreebuilder.py** : Unit tests for the `pytreebuilder` module.

- **pytreebuilder/** : Core module directory containing the main functionality.
  - **__init__.py** : Initialization file for the `pytreebuilder` package.
  - **pytreebuilder.py** : Main script containing the `PyTreeBuilder` class and its methods.
  - **version.py** : Contains the name and version of the `pytreebuilder` project.

- **trees/** : Directory containing project structure description files.
  - **any_project_tree.txt** : Description file for a simple project structure.
  - **complex_tree.txt** : Description file for a complex project structure.

- **.gitignore** : Specifies files and directories to be ignored by Git.

- **DISCRIPTION.md** : Provides a detailed description of the module's directory structure and their functions.

- **LICENSE** : Contains the license information for the project.

- **README.md** : Provides an overview and instructions for the project.

- **setup.py** : Script for setting up the `pytreebuilder` module, including installation and dependencies.

- **TREE** : Contains the detailed description of the module's directory structure.

## Description of the `pytreebuilder` Project

### Objective
The `pytreebuilder` project aims to simplify the creation of project structures using a text-based structure description file. It allows developers to quickly and easily generate consistent and well-organized project structures.

### Key Features
- Automatic creation of directories and files from a structure description file.
- Logging configuration to track actions performed by the module.
- Error handling to ensure smooth and uninterrupted execution.
- Update mode to create only new files and directories without overwriting existing ones.

### Detailed Description of Functionalities

#### 1. Automatic Creation of Project Structures
The `pytreebuilder` module allows for the automatic creation of project structures from a structure description file. This enables developers to quickly and easily generate consistent and well-organized project structures.

#### 2. Update Mode
The module includes an update mode (`update_mode`) that allows for the creation of only new files and directories without overwriting existing ones. This ensures that existing files and directories are not modified unless the user provides consent.

#### 3. Logging Configuration
The module configures a logging system to track the actions performed. Logs are recorded in a `pytreebuilder.log` file located in the `logs` directory. This helps keep track of the actions performed by the module and facilitates debugging in case of issues.

#### 4. Error Handling
The module handles errors to ensure smooth and uninterrupted execution. For example, it handles file not found errors and general exceptions, logging error messages in the log file.

#### 5. Command Line Arguments
The module accepts several command line arguments to customize its behavior:
- `-t` or `--tree-file-path` : Path to the structure description file (required).
- `-u` or `--update` : Run in update mode to create only new files and directories without overwriting existing ones.
- `-v` or `--version` : Show the program's version number and exit.

#### 6. Creation of Files and Directories
The module creates files and directories based on the description provided in the structure file. It checks if files and directories already exist and asks for user validation before overwriting them, unless the update mode is enabled.

#### 7. Example Project Structure
The module can create complex project structures from description files. For example, the file `trees/any_project_tree.txt` can contain the following structure:

##### Any Project Structure
The structure description file `trees/any_project_tree.txt` contains the following structure:

<pre><code class="language-plaintext">
anyproject/
&#x251C;&#x2500;&#x2500; anyproject/
&#x2502;   &#x251C;&#x2500;&#x2500; __init__.py
&#x2502;   &#x2514;&#x2500;&#x2500; anyproject.py
&#x251C;&#x2500;&#x2500; tests/
&#x2502;   &#x251C;&#x2500;&#x2500; __init__.py
&#x2502;   &#x2514;&#x2500;&#x2500; test_anyproject.py
&#x251C;&#x2500;&#x2500; setup.py
&#x251C;&#x2500;&#x2500; README.md
&#x2514;&#x2500;&#x2500; LICENSE
</code></pre>

#### 8. Installation and Usage
The module can be installed locally or via the internet. Once installed, it can be used to generate project structures by running Python scripts that utilize the `PyTreeBuilder` class.

#### 9. Unit Testing
The module includes unit tests to verify its functionality. Tests can be run using the following command:
```bash
python -m unittest discover tests/
```

#### 10. Documentation and Support
The module is accompanied by detailed documentation and a README file to help users understand its functionality and use it effectively. For questions or assistance, users can contact the project author via GitHub.

### Installation

#### Cloning the Repository
To get started, you need to clone the repository from GitHub. Follow these steps:
1. Open your terminal or command prompt.
2. Navigate to the directory where you want to clone the repository.
3. Run the following command to clone the repository:
   ```bash
   git clone https://github.com/eis-x/pytreebuilder.git
   ```
4. Navigate into the cloned repository:
   ```bash
   cd pytreebuilder
   ```

#### Local Installation
To install the `pytreebuilder` module locally, use the following command:
```bash
python -m pip install -e .
```

#### Installation via Internet
To install the `pytreebuilder` module from PyPI, use the following command:
```bash
pip install pytreebuilder
```

Sure! Let's continue with the help file for your `pytreebuilder` project from the "Usage" section:

### Usage

#### Running the Script
To run the script and generate the project structure, use the following command:
```bash
python examples/any_project_tree.py
```

#### Command Line Arguments
The `pytreebuilder` module accepts the following command line arguments:
- `-t` or `--tree-file-path` : Path to the structure description file (required).
- `-u` or `--update` : Run in update mode to create only new files and directories without overwriting existing ones.
- `-v` or `--version` : Show the program's version number and exit.

### How to Test the `pytreebuilder` Module

#### Prerequisites
- Python 3.6 or higher
- `unittest` for unit testing

#### Step-by-Step Guide
1. Ensure all necessary files are in place.
2. Run the unit tests with the following command:
   ```bash
   python -m unittest discover tests/
   ```

#### Example Output
The unit tests should display a result indicating that all tests have passed.
If the test passes, you should see something like this:
```plaintext
Directory created: anyproject/
Directory created: anyproject/anyproject/
File created: anyproject/anyproject/__init__.py
File created: anyproject/anyproject/anyproject.py
Directory created: anyproject/tests/
File created: anyproject/tests/__init__.py
File created: anyproject/tests/test_anyproject.py
File created: anyproject/setup.py
File created: anyproject/README.md
File created: anyproject/LICENSE
.
----------------------------------------------------------------------
Ran 1 test in 0.014s

OK
```

If there is a failure, you will see an output indicating what went wrong, similar to this:
```plaintext
F
======================================================================
FAIL: test_create_project_structure (tests.test_treebuilder.TestTreeBuilder)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "tests/test_treebuilder.py", line 27, in test_create_project_structure
    self.assertTrue(os.path.isdir('anyproject'))
AssertionError: False is not true

----------------------------------------------------------------------
Ran 1 test in 0.004s

FAILED (failures=1)
```

#### Troubleshooting
- **File Not Found**: Ensure that the `trees/any_project_tree.txt` file exists in the root directory of your project.
- **Import Errors**: Make sure the `pytreebuilder` module is installed and the import paths are correct.
- **Directory and File Checks**: Verify that the paths and names in the test script match the actual structure and names in your project.

By following these steps, you can effectively test the `pytreebuilder` module and ensure that it works as expected. If you have any questions or need further assistance, feel free to reach out! ðŸ˜Š

### Example: Using the `pytreebuilder` Module

#### Step 1: Create a Description File
Create a structure description file, for example `trees/any_project_tree.txt`.

#### Step 2: Install the `pytreebuilder` Module
Install the module using one of the installation methods described above.

#### Step 3: Create a Python Script to Use the Module
Create a Python script to generate the project structure, for example `examples/any_project_tree.py`.

#### Step 4: Run the Script
Run the script to generate the project structure:
```bash
python examples/any_project_tree.py
```

#### Step 5: Verify the Project Structure
Verify that the project structure has been created correctly by checking the generated directories and files.

### Running Examples from the Project Root

#### Example 1: Simple Project Structure
Use the file `trees/any_project_tree.txt` to generate a simple project structure.

#### Example 2: Complex Project Structure
Use the file `trees/complex_tree.txt` to generate a complex project structure.

### Summary
The `pytreebuilder` module simplifies the creation of project structures using text-based structure description files. It allows developers to quickly and easily generate consistent and well-organized project structures.

### Contributing to the Project

#### Fork the Repository
- Go to the GitHub repository page and click "Fork" to create a copy of the repository in your account.

#### Create a Branch
- Create a branch for your changes:
  ```bash
  git checkout -b branch-name
  ```

#### Submit Changes
- Commit your changes and push them to your forked repository:
  ```bash
  git add .
  git commit -m "Description of changes"
  git push origin branch-name
  ```
- Create a Pull Request to submit your changes to the main repository.

### Support and Assistance
For any questions or assistance, please contact the project author via GitHub.

### Copyright
This project is licensed under the MIT License. See the `LICENSE` file for more details.