musicalform 0.3.0

A Python library for representing and validating musical form annotation labels.

musicalform

A Python library and infrastructure for modelling musical form.

---

Installation

pip install musicalform

Requirements: Python 3.11+, DHParser 1.8.3+

---

CLI

The package ships a validate command that tests LCMA form-annotation labels against the current grammar:

# Validate a single expression
musicalform validate -e "bi"

# Validate a text file
musicalform validate -f my_label.txt

# Validate all expressions in a CSV (column: 'expression')
musicalform validate -c annotations.csv

# Extract and validate from a JSON timeline file
musicalform validate -j piece.json -o reports/

# Recursively process a directory of JSON files
musicalform validate -d data/ -o all_results.csv

# Verbose mode (show parse trees and skipped files)
musicalform validate -e "bi" -v

---

Development

Getting Started

git clone <repo-url>
cd musicalform

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests and Checks

# Run tests for all supported Python versions
tox

# Run tests for a specific Python version
tox -e py311
tox -e py312

# Or use pytest directly
pytest

# Run linters
tox -e lint

# Run type checking
tox -e typecheck

Workflow

All pull requests should target the development branch. Commits follow conventional commit format, which enables semantic versioning:

Commit Message	Version Bump	Emoji
feat: add new feature	Minor (0.x.0)	✨
fix: resolve issue	Patch (0.0.x)	🐛
BREAKING CHANGE: description	Major (x.0.0)	⚠️
docs: update documentation	No release	📚
refactor: reorganize code	No release	♻️
test: add tests	No release	✅
perf: improve performance	No release	⚡
chore: maintenance tasks	No release	🔧

Release Process

When commits are pushed to development, Release Please automatically:

1. Analyzes conventional commit messages
2. Creates a PR with bumped version in pyproject.toml and updated CHANGELOG.md
3. When merged, creates a GitHub Release

To publish to PyPI after a release is created:

# Build the package
tox -e build

# Publish to PyPI (requires TWINE_API_TOKEN in environment)
tox -e publish

Check your version at any time with:

musicalform --version

---

License

This project is released into the public domain under the Unlicense. See LICENSE for details.