Example-toml.md

Example Scenario: Updating Project Configuration Files

We'll process TOML files (like Python's pyproject.toml) to:

1. Update dependency versions
2. Add missing sections
3. Standardize formatting

Usage of alterx.toml

usage: python3 -m alterx.toml [-h] [--depth-first] [--follow-symlinks] [--exclude GLOB] [--include GLOB] [--sizes min..max]
                              [--depth min..max] [--paths-from FILE] [-m] [-d NAME=VALUE] [-x SCRIPT] [-o FILE] [--encoding USE_ENCODING]
                              [-n]
                              [PATH ...]

positional arguments:
  PATH

options:
  -h, --help            show this help message and exit
  -m                    Modify flag
  -d NAME=VALUE         Define some variable
  -x SCRIPT             Extension script
  -o FILE               Output to FILE
  --encoding USE_ENCODING
                        Encoding to use when saving
  -n                    No modifiaction will happend

Traversal:
  --depth-first         Process each directory's contents before the directory itself
  --follow-symlinks     Follow symbolic links
  --exclude GLOB        exclude matching GLOB
  --include GLOB        include matching GLOB
  --sizes min..max      Filter sizes: 1k.., 4g, ..2mb
  --depth min..max      Check for depth: 2.., 4, ..3
  --paths-from FILE     read list of source-file names from FILE

---

1. Create Sample TOML Files

mkdir -p projects
cat > projects/project_a.toml <<EOF
[build-system]
requires = ["setuptools>=61.0.0"]
build-backend = "setuptools.build_meta"

[tool.poetry]
name = "project-a"
version = "1.0.0"
EOF

cat > projects/project_b.toml <<EOF
[project]
name = "project-b"
dynamic = ["version"]
EOF

2. Create Processing Script (update_toml.py)

def init(app):
    # Define our standard versions
    app.defs.update({
        'SETUPTOOLS_VERSION': ">=68.0.0",
        'PYTHON_REQUIRES': ">=3.8"
    })

def process(doc, stat, app):
    # Update setuptools version
    if 'build-system' in doc and 'requires' in doc['build-system']:
        reqs = doc['build-system']['requires']
        for i, req in enumerate(reqs):
            if req.startswith('setuptools'):
                reqs[i] = f"setuptools{app.defs['SETUPTOOLS_VERSION']}"

    # Add python requires if missing
    if 'project' in doc and 'requires-python' not in doc['project']:
        doc['project']['requires-python'] = app.defs['PYTHON_REQUIRES']

    # Add description if missing
    if 'project' in doc and 'description' not in doc['project']:
        doc['project']['description'] = ""

def end(app):
    print(f"Updated {app.total.Altered}/{app.total.Files} TOML files")

3. Run the Processor

Using -mm flag to modify only if changed.

> python -m alterx.toml -mm -x update_toml.py projects

INFO: Module 'ext_e9cb3fe6' '/tmp/tmpxoe8wqsr/processor.py'
INFO: TOML [#1] /tmp/tmpxoe8wqsr/project_a.toml
WARN: Altered!
INFO: TOML [#2] /tmp/tmpxoe8wqsr/project_b.toml
WARN: Altered!
Updated 2/2 TOML files
INFO: Total Altered 2; Files 2;

If you run it agian, nothing is modified!

> python -m alterx.toml -mm -x update_toml.py projects
INFO: Module 'ext_e9cb3fe6' '/tmp/tmpxoe8wqsr/processor.py'
INFO: TOML [#1] /tmp/tmpxoe8wqsr/project_a.toml
INFO: TOML [#2] /tmp/tmpxoe8wqsr/project_b.toml
Updated 0/2 TOML files
INFO: Total Altered 0; Files 2;

4. Expected Output Files

project_a.toml:

[build-system]
requires = ["setuptools>=68.0.0"]
build-backend = "setuptools.build_meta"

[tool.poetry]
name = "project-a"
version = "1.0.0"

project_b.toml:

[project]
name = "project-b"
dynamic = ["version"]
requires-python = ">=3.8"
description = ""

Key Features Demonstrated:

• TOML-Specific Handling: Uses tomlkit for parsing/preserving formatting
• Conditional Modifications: Only makes changes when needed
• Variable Passing: Shares configuration through app.defs
• Change Detection: Only modifies files that need updates

This example shows how to use alterx for maintaining consistency across TOML configuration files in a project repository. The test case verifies both the transformation logic and the tool's change detection capabilities.