xsl

xsl - Universal File Editor

PyPI version Python Support License: MIT Tests

🛠️ Powerful CLI tool and Python library for editing XML, SVG, and HTML files using XPath and CSS selectors.

✨ Features

🚀 Quick Start

Installation

# Basic installation
pip install xsl

# Full installation with all features  
pip install xsl[full]

# Specific feature sets
pip install xsl[xpath]     # XPath support only
pip install xsl[css]       # CSS selectors only  
pip install xsl[remote]    # Remote file support only
pip install xsl[server]    # HTTP server support only

CLI Usage

# Load and query files
xsl load example.svg
xsl query "//svg:text[@id='title']"
xsl set "//svg:text[@id='title']" "New Title"

# Extract embedded data
xsl extract "//svg:image/@xlink:href" --output document.pdf
xsl extract "//svg:image/@xlink:href" --info

# Interactive shell
xsl shell

# HTTP Server
xsl server --port 8082

Python API

from xsl import FileEditor

# Load and edit file
editor = FileEditor('example.svg')
editor.set_element_text("//svg:text[@id='title']", "New Title")
editor.save('modified.svg')

# Extract Data URI
result = editor.extract_data_uri("//svg:image/@xlink:href")
if 'error' not in result:
    print(f"Found {result['mime_type']} ({result['size']} bytes)")

# Work with remote files
remote_editor = FileEditor('https://example.com/diagram.svg')
elements = remote_editor.list_elements("//svg:*[@id]")

📖 Documentation

🎯 Use Cases

📊 Extract Data from SVG Diagrams

# Extract embedded PDF from technical diagram
xsl extract "//svg:image/@xlink:href" --output manual.pdf

# Get chart data from SVG
xsl query "//svg:foreignObject//script[@type='application/json']"

🔧 Batch Update XML Configurations

# Update database connections across config files
for config in configs/*.xml; do
  xsl set "//database/host" "new-server.com" "$config"
  xsl save "$config"
done

🌐 Parse Web Pages for Data

# Extract structured data from HTML
xsl query "//table[@id='data']//tr[@data-status='active']" page.html
xsl extract "//script[@type='application/json']" --output data.json

🔄 Document Format Conversion

# Convert XML structure using XPath
from xsl import FileEditor

source = FileEditor('legacy.xml')
data = source.list_elements("//record")

target = FileEditor('template.xml')
for item in data:
    target.add_element("//records", "entry", item['text'], item['attributes'])
target.save('migrated.xml')

🔍 XPath Examples

SVG Files

# Get all text elements
//svg:text

# Find elements by ID
//svg:*[@id='title']

# Extract Data URIs
//svg:image/@xlink:href[starts-with(., 'data:')]

# Get metadata
//svg:metadata

XML Files

# Find by attribute
//user[@type='admin']

# Text content search
//*[contains(text(), 'error')]

# Nested elements
//config//database//host

HTML Files

# CSS class targeting
//div[@class='content']

# Form elements
//input[@type='checkbox'][@checked]

# JSON script tags
//script[@type='application/json']

🌐 HTTP Server API

Start the server:

xsl server --port 8082

Direct Data URI Extraction

# Extract from remote file
curl "http://localhost:8082/api/extract?url=https://example.com/diagram.svg&xpath=//svg:image/@href"

Full API Workflow

# Load file
curl -X POST http://localhost:8082/api/load \
  -H "Content-Type: application/json" \
  -d '{"file_path": "example.svg"}'

# Query elements  
curl -X POST http://localhost:8082/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "//svg:text", "type": "xpath"}'

# Update content
curl -X POST http://localhost:8082/api/update \
  -H "Content-Type: application/json" \
  -d '{"xpath": "//svg:text[@id=\"title\"]", "type": "text", "value": "Updated"}'

# Save changes
curl -X POST http://localhost:8082/api/save \
  -H "Content-Type: application/json" \
  -d '{"output_path": "modified.svg"}'

Web Interface

Open http://localhost:8082 in your browser for a full-featured web interface with:

🧪 Examples and Testing

Generate example files:

xsl examples --dir ./test_files

This creates:

⚙️ Configuration

Optional Dependencies

xsl works with basic XML support out of the box, but optional dependencies unlock additional features:

Install all features:

pip install xsl[full]

Environment Variables

# Default server settings
export xsl_DEFAULT_PORT=8082
export xsl_DEFAULT_HOST=localhost

# Debug mode
export xsl_DEBUG=1

🔧 Development

Setup Development Environment

git clone https://github.com/veridock/xsl.git
cd xsl

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install --extras "full"

# Run tests
poetry run pytest

# Format code
poetry run black xsl/
poetry run isort xsl/

Running Tests

# All tests
poetry run pytest

# With coverage
poetry run pytest --cov=xsl --cov-report=html

# Specific test categories
poetry run pytest -m "not slow"  # Skip slow tests
poetry run pytest -m "integration"  # Only integration tests

Code Quality

# Format and lint
poetry run black xsl/ tests/
poetry run isort xsl/ tests/
poetry run flake8 xsl/ tests/
poetry run mypy xsl/

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Workflow

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and add tests
  4. Run tests: poetry run pytest
  5. Format code: poetry run black xsl/
  6. Commit: git commit -m 'Add amazing feature'
  7. Push: git push origin feature/amazing-feature
  8. Open a Pull Request

📋 Requirements

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

📞 Support

Made with ❤️ by the xsl team

This site is open source. Improve this page.