| Name | treedir-py JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | None |
| Summary | A Python library for parsing directory structures from text files and implementing them in target folders |
| upload_time | 2025-08-30 21:47:08 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | None |
| keywords |
directory
structure
tree
filesystem
automation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# TreeDir - Directory Structure Parser and Manager
[](https://badge.fury.io/py/treedir)
[](https://pypi.org/project/treedir/)
[](https://opensource.org/licenses/MIT)
A Python library for parsing directory structures from text files and implementing them in target folders with various operation modes.
## Features
- **Multiple Input Formats**: Support for tree format, dictionary format, and simple path format
- **Flexible Operations**: Additive and strict enforcement modes
- **Visualization**: Tree-style visualization of directory structures
- **Sandbox Mode**: Preview changes before applying them
- **Search Functions**: Find files and folders with absolute or relative paths
- **Backup Creation**: Automatic backups before destructive operations
- **Cross-Platform**: Works on Windows, macOS, and Linux
## Installation
```bash
pip install treedir-py
```
## Quick Start
```python
import treedir
# Create directory structure from file (additive mode)
treedir.run('structure.txt', 'my_project')
# Strictly enforce structure (removes extra files)
treedir.urun('structure.txt', 'my_project')
# Visualize current directory
print(treedir.vis('my_project'))
# Find a file
path = treedir.find('main.py', 'my_project')
# Preview changes before applying
preview = treedir.sandbox(treedir.run, 'structure.txt', 'my_project')
print(preview)
```
## Supported Input Formats
### Tree Format
```
project/
├── src/
│ ├── main.py
│ └── utils.py
├── tests/
│ └── test_main.py
└── README.md
```
### Dictionary Format
```json
{
"src": {
"main.py": null,
"utils.py": null
},
"tests": {
"test_main.py": null
},
"README.md": null
}
```
### Path Format
```
src/main.py
src/utils.py
tests/test_main.py
README.md
```
## API Reference
### Core Functions
#### `run(structure_file, target="current")`
Additive file system execution. Only adds new files/directories, preserves existing ones.
**Parameters:**
- `structure_file` (str): Path to structure definition file
- `target` (str): Target directory path or "current" for current directory
**Returns:** `bool` - True if successful
#### `urun(structure_file, target="current")`
Unconditional run - strictly enforce structure. Keeps common files intact but removes files not in the structure.
**Parameters:**
- `structure_file` (str): Path to structure definition file
- `target` (str): Target directory path or "current" for current directory
**Returns:** `bool` - True if successful
#### `reset(target="current")`
Reset target folder (remove all contents).
**Parameters:**
- `target` (str): Target directory path or "current" for current directory
**Returns:** `bool` - True if successful
#### `vis(target="current")`
Visualize directory structure in tree format.
**Parameters:**
- `target` (str): Target directory path or "current" for current directory
**Returns:** `str` - Tree representation of directory structure
#### `find(filename, target="current")`
Find file/folder and return absolute path.
**Parameters:**
- `filename` (str): Name of file/folder to find
- `target` (str): Target directory path or "current" for current directory
**Returns:** `str` or `None` - Absolute path if found, None otherwise
#### `findr(filename, target="current")`
Find file/folder and return relative path.
**Parameters:**
- `filename` (str): Name of file/folder to find
- `target` (str): Target directory path or "current" for current directory
**Returns:** `str` or `None` - Relative path if found, None otherwise
#### `sandbox(operation_func, *args, **kwargs)`
Visualize how directory will look after changes without actually executing them.
**Parameters:**
- `operation_func`: Function to simulate (run, urun, etc.)
- `*args`: Arguments for the operation function
- `**kwargs`: Keyword arguments for the operation function
**Returns:** `str` - Preview of resulting directory tree
## Advanced Usage
### Using Classes Directly
```python
from treedir import TreeDir, TreeParser, TreeVisualizer
# Initialize components
td = TreeDir()
parser = TreeParser()
visualizer = TreeVisualizer()
# Parse structure file
structure = parser.parse_file('my_structure.txt')
# Create structure
td._create_structure(structure, '/path/to/target', mode='additive')
# Compare two directories
comparison = visualizer.compare_structures('dir1', 'dir2')
print(comparison)
```
### Generating Structure Files
```python
from treedir import TreeVisualizer
tv = TreeVisualizer()
# Generate tree format from existing directory
tree_content = tv.generate_structure_file('my_project', 'tree')
# Generate dictionary format
dict_content = tv.generate_structure_file('my_project', 'dict')
# Generate path format
path_content = tv.generate_structure_file('my_project', 'path')
```
### Error Handling
```python
import treedir
try:
result = treedir.run('structure.txt', 'target_folder')
if result:
print("Structure created successfully!")
else:
print("Failed to create structure")
except FileNotFoundError:
print("Structure file not found")
except ValueError as e:
print(f"Invalid structure format: {e}")
```
## Examples
### Example 1: Basic Project Setup
Create a `project_structure.txt`:
```
my_app/
├── src/
│ ├── __init__.py
│ ├── main.py
│ └── config.py
├── tests/
│ ├── __init__.py
│ └── test_main.py
├── docs/
│ └── README.md
├── requirements.txt
└── setup.py
```
Run:
```python
import treedir
# Create the structure
treedir.run('project_structure.txt', 'new_project')
# Visualize result
print(treedir.vis('new_project'))
```
### Example 2: Using Sandbox Mode
```python
import treedir
# Preview what will happen
preview = treedir.sandbox(treedir.run, 'structure.txt', 'test_folder')
print("Preview:")
print(preview)
# If satisfied, apply changes
treedir.run('structure.txt', 'test_folder')
```
### Example 3: Finding Files
```python
import treedir
# Find a specific file
main_py_path = treedir.find('main.py', 'my_project')
if main_py_path:
print(f"Found main.py at: {main_py_path}")
# Get relative path
rel_path = treedir.findr('main.py', 'my_project')
print(f"Relative path: {rel_path}")
```
## Safety Features
- **Automatic Backups**: `urun()` and `reset()` automatically create backups
- **Sandbox Mode**: Preview changes before applying them
- **Path Validation**: Validates file and directory names
- **Error Handling**: Comprehensive error handling and reporting
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Changelog
### Version 1.0.0
- Initial release
- Support for tree, dictionary, and path formats
- Core functionality: run, urun, reset, vis, find, findr, sandbox
- Automatic backup creation
- Cross-platform compatibility
Raw data
{
"_id": null,
"home_page": null,
"name": "treedir-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Parth Nuwal <parthnuwal7@gmail.com>",
"keywords": "directory, structure, tree, filesystem, automation",
"author": null,
"author_email": "Parth Nuwal <parthnuwal7@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/90/0d/c3f1f3a6a5fd9094fb915af8bbe28fa6b26fae31d4c2fa714ee9859dffaa/treedir_py-0.1.2.tar.gz",
"platform": null,
"description": "# TreeDir - Directory Structure Parser and Manager\r\n\r\n[](https://badge.fury.io/py/treedir)\r\n[](https://pypi.org/project/treedir/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\nA Python library for parsing directory structures from text files and implementing them in target folders with various operation modes.\r\n\r\n## Features\r\n\r\n- **Multiple Input Formats**: Support for tree format, dictionary format, and simple path format\r\n- **Flexible Operations**: Additive and strict enforcement modes\r\n- **Visualization**: Tree-style visualization of directory structures\r\n- **Sandbox Mode**: Preview changes before applying them\r\n- **Search Functions**: Find files and folders with absolute or relative paths\r\n- **Backup Creation**: Automatic backups before destructive operations\r\n- **Cross-Platform**: Works on Windows, macOS, and Linux\r\n\r\n## Installation\r\n\r\n```bash\r\npip install treedir-py\r\n```\r\n\r\n## Quick Start\r\n\r\n```python\r\nimport treedir\r\n\r\n# Create directory structure from file (additive mode)\r\ntreedir.run('structure.txt', 'my_project')\r\n\r\n# Strictly enforce structure (removes extra files)\r\ntreedir.urun('structure.txt', 'my_project')\r\n\r\n# Visualize current directory\r\nprint(treedir.vis('my_project'))\r\n\r\n# Find a file\r\npath = treedir.find('main.py', 'my_project')\r\n\r\n# Preview changes before applying\r\npreview = treedir.sandbox(treedir.run, 'structure.txt', 'my_project')\r\nprint(preview)\r\n```\r\n\r\n## Supported Input Formats\r\n\r\n### Tree Format\r\n```\r\nproject/\r\n\u251c\u2500\u2500 src/\r\n\u2502 \u251c\u2500\u2500 main.py\r\n\u2502 \u2514\u2500\u2500 utils.py\r\n\u251c\u2500\u2500 tests/\r\n\u2502 \u2514\u2500\u2500 test_main.py\r\n\u2514\u2500\u2500 README.md\r\n```\r\n\r\n### Dictionary Format\r\n```json\r\n{\r\n \"src\": {\r\n \"main.py\": null,\r\n \"utils.py\": null\r\n },\r\n \"tests\": {\r\n \"test_main.py\": null\r\n },\r\n \"README.md\": null\r\n}\r\n```\r\n\r\n### Path Format\r\n```\r\nsrc/main.py\r\nsrc/utils.py\r\ntests/test_main.py\r\nREADME.md\r\n```\r\n\r\n## API Reference\r\n\r\n### Core Functions\r\n\r\n#### `run(structure_file, target=\"current\")`\r\nAdditive file system execution. Only adds new files/directories, preserves existing ones.\r\n\r\n**Parameters:**\r\n- `structure_file` (str): Path to structure definition file\r\n- `target` (str): Target directory path or \"current\" for current directory\r\n\r\n**Returns:** `bool` - True if successful\r\n\r\n#### `urun(structure_file, target=\"current\")`\r\nUnconditional run - strictly enforce structure. Keeps common files intact but removes files not in the structure.\r\n\r\n**Parameters:**\r\n- `structure_file` (str): Path to structure definition file\r\n- `target` (str): Target directory path or \"current\" for current directory\r\n\r\n**Returns:** `bool` - True if successful\r\n\r\n#### `reset(target=\"current\")`\r\nReset target folder (remove all contents).\r\n\r\n**Parameters:**\r\n- `target` (str): Target directory path or \"current\" for current directory\r\n\r\n**Returns:** `bool` - True if successful\r\n\r\n#### `vis(target=\"current\")`\r\nVisualize directory structure in tree format.\r\n\r\n**Parameters:**\r\n- `target` (str): Target directory path or \"current\" for current directory\r\n\r\n**Returns:** `str` - Tree representation of directory structure\r\n\r\n#### `find(filename, target=\"current\")`\r\nFind file/folder and return absolute path.\r\n\r\n**Parameters:**\r\n- `filename` (str): Name of file/folder to find\r\n- `target` (str): Target directory path or \"current\" for current directory\r\n\r\n**Returns:** `str` or `None` - Absolute path if found, None otherwise\r\n\r\n#### `findr(filename, target=\"current\")`\r\nFind file/folder and return relative path.\r\n\r\n**Parameters:**\r\n- `filename` (str): Name of file/folder to find\r\n- `target` (str): Target directory path or \"current\" for current directory\r\n\r\n**Returns:** `str` or `None` - Relative path if found, None otherwise\r\n\r\n#### `sandbox(operation_func, *args, **kwargs)`\r\nVisualize how directory will look after changes without actually executing them.\r\n\r\n**Parameters:**\r\n- `operation_func`: Function to simulate (run, urun, etc.)\r\n- `*args`: Arguments for the operation function\r\n- `**kwargs`: Keyword arguments for the operation function\r\n\r\n**Returns:** `str` - Preview of resulting directory tree\r\n\r\n## Advanced Usage\r\n\r\n### Using Classes Directly\r\n\r\n```python\r\nfrom treedir import TreeDir, TreeParser, TreeVisualizer\r\n\r\n# Initialize components\r\ntd = TreeDir()\r\nparser = TreeParser()\r\nvisualizer = TreeVisualizer()\r\n\r\n# Parse structure file\r\nstructure = parser.parse_file('my_structure.txt')\r\n\r\n# Create structure\r\ntd._create_structure(structure, '/path/to/target', mode='additive')\r\n\r\n# Compare two directories\r\ncomparison = visualizer.compare_structures('dir1', 'dir2')\r\nprint(comparison)\r\n```\r\n\r\n### Generating Structure Files\r\n\r\n```python\r\nfrom treedir import TreeVisualizer\r\n\r\ntv = TreeVisualizer()\r\n\r\n# Generate tree format from existing directory\r\ntree_content = tv.generate_structure_file('my_project', 'tree')\r\n\r\n# Generate dictionary format\r\ndict_content = tv.generate_structure_file('my_project', 'dict')\r\n\r\n# Generate path format\r\npath_content = tv.generate_structure_file('my_project', 'path')\r\n```\r\n\r\n### Error Handling\r\n\r\n```python\r\nimport treedir\r\n\r\ntry:\r\n result = treedir.run('structure.txt', 'target_folder')\r\n if result:\r\n print(\"Structure created successfully!\")\r\n else:\r\n print(\"Failed to create structure\")\r\nexcept FileNotFoundError:\r\n print(\"Structure file not found\")\r\nexcept ValueError as e:\r\n print(f\"Invalid structure format: {e}\")\r\n```\r\n\r\n## Examples\r\n\r\n### Example 1: Basic Project Setup\r\n\r\nCreate a `project_structure.txt`:\r\n```\r\nmy_app/\r\n\u251c\u2500\u2500 src/\r\n\u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u251c\u2500\u2500 main.py\r\n\u2502 \u2514\u2500\u2500 config.py\r\n\u251c\u2500\u2500 tests/\r\n\u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u2514\u2500\u2500 test_main.py\r\n\u251c\u2500\u2500 docs/\r\n\u2502 \u2514\u2500\u2500 README.md\r\n\u251c\u2500\u2500 requirements.txt\r\n\u2514\u2500\u2500 setup.py\r\n```\r\n\r\nRun:\r\n```python\r\nimport treedir\r\n\r\n# Create the structure\r\ntreedir.run('project_structure.txt', 'new_project')\r\n\r\n# Visualize result\r\nprint(treedir.vis('new_project'))\r\n```\r\n\r\n### Example 2: Using Sandbox Mode\r\n\r\n```python\r\nimport treedir\r\n\r\n# Preview what will happen\r\npreview = treedir.sandbox(treedir.run, 'structure.txt', 'test_folder')\r\nprint(\"Preview:\")\r\nprint(preview)\r\n\r\n# If satisfied, apply changes\r\ntreedir.run('structure.txt', 'test_folder')\r\n```\r\n\r\n### Example 3: Finding Files\r\n\r\n```python\r\nimport treedir\r\n\r\n# Find a specific file\r\nmain_py_path = treedir.find('main.py', 'my_project')\r\nif main_py_path:\r\n print(f\"Found main.py at: {main_py_path}\")\r\n\r\n# Get relative path\r\nrel_path = treedir.findr('main.py', 'my_project')\r\nprint(f\"Relative path: {rel_path}\")\r\n```\r\n\r\n## Safety Features\r\n\r\n- **Automatic Backups**: `urun()` and `reset()` automatically create backups\r\n- **Sandbox Mode**: Preview changes before applying them\r\n- **Path Validation**: Validates file and directory names\r\n- **Error Handling**: Comprehensive error handling and reporting\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## Changelog\r\n\r\n### Version 1.0.0\r\n- Initial release\r\n- Support for tree, dictionary, and path formats\r\n- Core functionality: run, urun, reset, vis, find, findr, sandbox\r\n- Automatic backup creation\r\n- Cross-platform compatibility\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for parsing directory structures from text files and implementing them in target folders",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/Parthnuwal7/treedir",
"Documentation": "https://github.com/Parthnuwal7/treedir#readme",
"Homepage": "https://github.com/Parthnuwal7/treedir",
"Repository": "https://github.com/Parthnuwal7/treedir"
},
"split_keywords": [
"directory",
" structure",
" tree",
" filesystem",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d81c747f607a6a7bc2fa071e0d887fe0f8aecb5e16ab1253dc2e0979e24bb1ab",
"md5": "55401be530097f8ec92258454b1be6fd",
"sha256": "e9c70a7d113fc3a8ab990a0cc0911fad2b9f9353709e598f353ac8c5a91fcd08"
},
"downloads": -1,
"filename": "treedir_py-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "55401be530097f8ec92258454b1be6fd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 16077,
"upload_time": "2025-08-30T21:47:06",
"upload_time_iso_8601": "2025-08-30T21:47:06.724510Z",
"url": "https://files.pythonhosted.org/packages/d8/1c/747f607a6a7bc2fa071e0d887fe0f8aecb5e16ab1253dc2e0979e24bb1ab/treedir_py-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "900dc3f1f3a6a5fd9094fb915af8bbe28fa6b26fae31d4c2fa714ee9859dffaa",
"md5": "4912cd73b102bc512f3cff8f017f6c96",
"sha256": "69f08b8cbcfc951df3b9e342f2881a568d8b34d33e0020a89aea189c4cd3f530"
},
"downloads": -1,
"filename": "treedir_py-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "4912cd73b102bc512f3cff8f017f6c96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 19673,
"upload_time": "2025-08-30T21:47:08",
"upload_time_iso_8601": "2025-08-30T21:47:08.189992Z",
"url": "https://files.pythonhosted.org/packages/90/0d/c3f1f3a6a5fd9094fb915af8bbe28fa6b26fae31d4c2fa714ee9859dffaa/treedir_py-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 21:47:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Parthnuwal7",
"github_project": "treedir",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "treedir-py"
}
