BasicTree

A Python package for converting text with hierarchy markers to visual tree structures.

Style 1	Style 2
Style 3	Style 4
Style 5	Style 6

Features

• Parse text with # hierarchy markers into tree structures
• Multiple visualization styles (Unicode, ASCII, compact, box, etc.)
• Colored output with hierarchy-based coloring
• PDF export capabilities (optional)
• Command-line interface and Python API
• Tree statistics and analysis

Installation

Default Installation (includes PDF support)

git clone <repository-url>
cd basictree
pip install .

Test Installation

basictree --test

Development Installation

git clone <repository-url>
cd basictree
pip install -e .[dev]

Dependencies

Core Dependencies

• Python 3.8+
• reportlab>=3.5.0 (for PDF export - included by default)

Optional

• Install with basictree[minimal] to exclude PDF support

Development

• pytest
• black
• flake8
• mypy

Quick Start

Command Line Usage

# Basic usage
basictree document.txt

# Different styles
basictree document.txt --style compact
basictree document.txt --style colored

# Save to file
basictree document.txt --output tree_output.txt

# Export to PDF
basictree document.txt --pdf tree.pdf --style colored

# Include statistics
basictree document.txt --stats

Python API Usage

from tree_parser import parse_text_to_tree, draw_tree_unicode

# Sample text with hierarchy markers
text = '''
# Project Root
## Source Code
### Python Files
#### main.py
#### utils.py
### Documentation
#### README.md
#### API.md
## Tests
### Unit Tests
### Integration Tests
'''

# Parse text into tree structure
tree = parse_text_to_tree(text)

# Generate tree visualization
tree_output = draw_tree_unicode(tree)
print(tree_output)

Input Format

The parser recognizes text with # hierarchy markers:

# Level 1
## Level 2
### Level 3
#### Level 4

Example input:

# mdp option
## Preprocessing
### include: directories to include in your topology file
### define: defines to pass to the preprocessor
#### -DFLEXIBLE (flexible water)
#### -DPOSRES (position restraints, requires posre.itp)
## Run Control
### integrator: algorithm that include integration algorithm
#### md: (leap-frog)
#### md-vv: (velocity-verlet)

Visualization Styles

Available Styles

1. unicode (default) - Unicode tree characters
2. ascii - ASCII tree characters
3. compact - Compact representation
4. box - Boxed nodes
5. simple - Simple indentation
6. colored - Colored Unicode output
7. colored_ascii - Colored ASCII output
8. colored_compact - Colored compact output
9. outline - Outline format

Style Examples

Unicode Style:

├── mdp option
│   ├── Preprocessing
│   │   ├── include: directories to include
│   │   └── define: defines to pass
│   └── Run Control
│       └── integrator: algorithm

Colored Style:

• Uses different colors for each hierarchy level
• Highlights key terms before colons
• Provides visual hierarchy distinction

Python API

Core Functions

from tree_parser import (
    parse_text_to_tree,
    draw_tree_unicode,
    draw_tree_ascii,
    draw_tree_colored,
    export_tree_to_pdf,
    get_tree_statistics
)

# Parse text to tree
tree = parse_text_to_tree(text)

# Different drawing styles
unicode_output = draw_tree_unicode(tree)
ascii_output = draw_tree_ascii(tree)
colored_output = draw_tree_colored(tree)

# Export to PDF (requires reportlab)
export_tree_to_pdf(tree, "output.pdf", style="colored")

# Get tree statistics
stats = get_tree_statistics(tree)
print(f"Total nodes: {stats['total_nodes']}")
print(f"Max depth: {stats['max_depth']}")

TreeNode Class

from tree_parser import TreeNode

# Access tree structure
for child in tree.children:
    print(f"Node: {child.content}, Level: {child.level}")
    
# Convert to dictionary
tree_dict = tree.to_dict()

# Find nodes by content
from tree_parser import find_nodes_by_content
matches = find_nodes_by_content(tree, "Run Control")

Command Line Options

basictree input_file [options]

Options:
  --style STYLE         Tree drawing style (default: unicode)
  --output OUTPUT       Output file path
  --pdf PDF_FILE        Export to PDF file  
  --stats               Include tree statistics
  --keep-colors         Keep ANSI colors in file output
  --version             Show version
  --help                Show help message

Examples

Basic Tree Parsing

import tree_parser

text = '''
# Configuration
## Database
### Connection Settings
#### Host: localhost
#### Port: 5432
### Authentication
#### Username: admin
#### Password: secret
## API
### Endpoints
#### /users
#### /posts
### Rate Limiting
#### Requests per minute: 100
'''

tree = tree_parser.parse_text_to_tree(text)
print(tree_parser.draw_tree_colored(tree))

Tree Analysis

# Get detailed statistics
stats = tree_parser.get_tree_statistics(tree)
print(tree_parser.format_tree_statistics(stats))

# Find specific nodes
db_nodes = tree_parser.find_nodes_by_content(tree, "Database", exact_match=False)
for node in db_nodes:
    path = tree_parser.get_path_to_node(node)
    print(" -> ".join(path))

Export Options

# Export to different formats
tree_parser.export_tree_to_pdf(tree, "tree.pdf", style="colored")

# Save colored output to text file
output = tree_parser.draw_tree_colored(tree)
tree_parser.save_tree_output(output, "tree.txt", keep_colors=True)

Complete Command Reference

Basic Commands

# Display tree with default Unicode style
basictree input.txt

# Short alias
btree input.txt

# Display help
basictree --help
btree --help

# Show version
basictree --version

Style Options

# Unicode characters (default)
basictree input.txt --style unicode

# ASCII characters for compatibility
basictree input.txt --style ascii

# Compact representation
basictree input.txt --style compact

# Box-style with borders
basictree input.txt --style box

# Simple indentation only
basictree input.txt --style simple

# Colored Unicode (requires color terminal)
basictree input.txt --style colored

# Colored ASCII
basictree input.txt --style colored_ascii

# Colored compact
basictree input.txt --style colored_compact

# Colored simple
basictree input.txt --style colored_simple

# Outline format (markdown-like)
basictree input.txt --style outline

Output Options

# Save to text file
basictree input.txt --output result.txt

# Save with ANSI color codes preserved
basictree input.txt --style colored --output colored_result.txt --keep-colors

# Export to PDF (included by default)
basictree input.txt --pdf output.pdf

# Export colored PDF
basictree input.txt --pdf colored_output.pdf --style colored

# Multiple outputs
basictree input.txt --output text_result.txt --pdf pdf_result.pdf --style colored

Analysis and Statistics

# Include tree statistics
basictree input.txt --stats

# Statistics with specific style
basictree input.txt --stats --style compact

# Save statistics to file
basictree input.txt --stats --output analysis.txt

# Combine all analysis options
basictree input.txt --stats --style colored --output full_analysis.txt --keep-colors

Complex Examples

# Professional report generation
basictree project_structure.txt \
  --style colored \
  --stats \
  --output project_tree.txt \
  --pdf project_tree.pdf \
  --keep-colors

# Quick ASCII preview for documentation
basictree config.txt --style ascii --output docs/tree_structure.txt

# Compact analysis for large files
basictree large_file.txt --style compact --stats

# Box style for presentations
basictree presentation_outline.txt --style box --pdf presentation_tree.pdf

File Processing Examples

# Process configuration files
basictree config.md --style colored --output config_tree.txt

# Analyze documentation structure
basictree docs_outline.txt --style unicode --stats --pdf docs_structure.pdf

# Convert markdown headings to tree
basictree README_headings.txt --style outline --output structured_readme.txt

# Process multiple formats
basictree project.txt --style colored --output project.txt --pdf project.pdf --stats

Integration Examples

# Pipe input processing
cat structure.txt | basictree /dev/stdin --style compact

# Use in scripts
#!/bin/bash
for file in *.txt; do
    basictree "$file" --style ascii --output "${file%.txt}_tree.txt"
done

# Quick preview in terminal
basictree quick_notes.txt --style simple

# Generate documentation
basictree api_structure.txt --style box --pdf api_documentation.pdf --stats

Error Handling and Debugging

# Test with empty file (will show warning)
touch empty.txt
basictree empty.txt

# Test with non-existent file (will show error)
basictree nonexistent.txt

# Test invalid style (will show available options)
basictree input.txt --style invalid_style

# Verbose output for debugging
basictree input.txt --stats --style colored 2>&1 | tee debug.log

Advanced Usage Patterns

# Batch processing with different styles
basictree outline.txt --style unicode --output unicode_version.txt
basictree outline.txt --style ascii --output ascii_version.txt
basictree outline.txt --style colored --pdf colored_version.pdf

# Analysis workflow
basictree large_project.txt --stats > project_stats.txt
basictree large_project.txt --style compact --output compact_view.txt
basictree large_project.txt --style colored --pdf presentation.pdf

# Documentation generation
basictree api_endpoints.txt --style box --output api_tree.txt
basictree database_schema.txt --style unicode --pdf schema_diagram.pdf
basictree user_manual.txt --style simple --output manual_structure.txt

# Quality assurance
basictree test_structure.txt --stats --style colored --output qa_report.txt --keep-colors

Automation and Scripting

# Makefile integration
generate-docs:
	basictree src/structure.txt --style colored --pdf docs/architecture.pdf --stats

# Git hooks
#!/bin/bash
# pre-commit hook
if [ -f project_structure.txt ]; then
    basictree project_structure.txt --style compact --output .git/project_tree.txt
fi

# CI/CD pipeline
- name: Generate project structure
  run: |
    basictree project_outline.txt --style unicode --output project_structure.txt
    basictree project_outline.txt --pdf project_structure.pdf --style colored

# Monitoring and logging
basictree system_config.txt --stats --output "logs/config_$(date +%Y%m%d).txt"

Performance and Optimization

# Large file processing
basictree large_structure.txt --style simple  # Fastest rendering
basictree large_structure.txt --style compact # Memory efficient

# Network sharing
basictree shared_config.txt --style ascii --output shared_tree.txt  # Best compatibility

# Mobile/small screen
basictree mobile_layout.txt --style compact --output mobile_view.txt

License

MIT License

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request

Changelog

1.0.0

• Initial release
• Core tree parsing functionality
• Multiple visualization styles
• PDF export support
• Command-line interface
• Python API