Metadata-Version: 2.4
Name: jexpand
Version: 1.0.3
Summary: Enhanced file expansion using Jinja2 templates
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: jinja2>=3.0.0
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# JExpand - Jinja2 Template File Expander

Enhanced file expansion using Jinja2 templates with flexible functionality for including files, conditional content, and more.

## Installation

```bash
pip install jexpand
```

## Usage

### Command Line Interface

JExpand now uses a modern argparse-based CLI with explicit input/output handling:

```bash
# Print to stdout
jexpand template.md

# Write to file
jexpand template.md -o expanded.md
jexpand template.md --output expanded.md

# Non-strict mode (don't fail on missing files)
jexpand template.md --no-strict

# Specify template directory
jexpand template.md --template-dir /path/to/templates

# Show help
jexpand --help
```

### Python Module

```bash
# Run as module
python -m jexpand template.md -o expanded.md
```

### Python API

```python
from jexpand import JinjaFileExpander

# Create expander
expander = JinjaFileExpander(strict_mode=True)

# Expand to file
expander.expand_file(
    template_path="template.md",
    output_path="output.md"
)

# Expand to string
result = expander.expand_file("template.md")

# Simple expansion with {file} syntax
result = expander.simple_expand("simple_template.md")
```

### Template Features

JExpand supports powerful Jinja2 templates with custom functions and filters:

#### Custom Functions

- `include_file(path)` - Include the contents of a file
- `file_exists(path)` - Check if a file exists
- `file_size(path)` - Get file size in bytes
- `file_extension(path)` - Get file extension
- `basename(path)` - Get basename of file
- `dirname(path)` - Get directory name of file

#### Custom Filters

- `code_block(language)` - Wrap content in markdown code block
- `indent(spaces)` - Indent each line with specified spaces
- `comment_out(comment_char)` - Comment out each line

#### Example Template

```jinja2
# My Project Documentation

## Source Implementation
{{ include_file('src/main.py') | code_block('python') }}

## Configuration
{% if file_exists('config.yaml') %}
{{ include_file('config.yaml') | code_block('yaml') }}
{% else %}
No configuration file found.
{% endif %}

## Multiple Files
{% for file_path in ['file1.py', 'file2.py'] %}
### {{ basename(file_path) }}
{{ include_file(file_path) | indent(4) }}
{% endfor %}

## File Information
{% for file in ['app.py', 'utils.py'] %}
{% if file_exists(file) %}
- **{{ file }}**: {{ file_size(file) }} bytes
{% endif %}
{% endfor %}
```

### Simple Syntax (Backward Compatibility)

JExpand also supports a simpler `{file_path}` syntax that gets converted to Jinja2:

```python
from jexpand import JinjaFileExpander

expander = JinjaFileExpander()
# Converts {/path/to/file} to {{ include_file('/path/to/file') }}
expander.simple_expand("simple_template.md")
```

## Advanced Usage

### Programmatic Generation

You can use jexpand programmatically to generate documentation:

```python
#!/usr/bin/env python3
from jexpand import JinjaFileExpander
from pathlib import Path

def generate_docs(source_dir, output_dir):
    """Generate documentation for all source files."""
    expander = JinjaFileExpander(strict_mode=True)
    
    for source_file in Path(source_dir).glob("*.py"):
        template_content = f"""
# {source_file.name} Documentation

## Source Code
{{{{ include_file('{source_file}') | code_block('python') }}}}

## Analysis
**File:** {source_file.name}
**Size:** {{{{ file_size('{source_file}') }}}} bytes
"""
        
        # Expand template
        result = expander.expand_string(template_content)
        
        # Write to output
        output_file = Path(output_dir) / f"{source_file.stem}_docs.md"
        with open(output_file, 'w') as f:
            f.write(result)

# Usage
generate_docs("src/", "docs/")
```

## Recent Improvements (v1.0.2)

### Enhanced CLI Interface
- **Modern argparse-based CLI** replacing the previous fire-based interface
- **Explicit input/output handling** with `-o`/`--output` flags
- **Better error messages** and help text
- **Proper exit codes** for scripting

### Bug Fixes
- **Fixed double printing issue** that caused duplicated output
- **Improved absolute path handling** for template files
- **Fixed Template constructor** compatibility issues
- **Removed subprocess overhead** in programmatic usage

### Performance Improvements
- **Direct import support** - no subprocess calls needed
- **Cleaner output handling** - no extra newlines or duplication
- **Reduced dependencies** - removed fire dependency

### Backward Compatibility
- **Simple expansion syntax** still supported via `simple_expand()`
- **Legacy `expand_file()` function** remains available
- **All existing templates** continue to work

## Development

### Local Installation

```bash
# Install in development mode
pip install -e .

# Test the command
jexpand --help
```

### Package Structure

```
jexpand/
├── jexpand/
│   ├── __init__.py      # Package exports and main entry point
│   ├── __main__.py      # Module entry point for python -m jexpand
│   └── main.py          # Core functionality and CLI
├── setup.py             # Package configuration
├── README.md            # This file
└── .gitignore          # Git ignore rules
```

## Examples

See the `examples/` directory (if present) or check the GitHub repository for real-world usage examples.

## License

MIT License 

## Links

- **PyPI**: https://pypi.org/project/jexpand/
- **GitHub**: https://github.com/OhadRubin/jexpand
- **Issues**: https://github.com/OhadRubin/jexpand/issues 
