galaxy-tool-source 0.1.0__tar.gz

galaxy_tool_source-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Per-version xsdata models — generated at build time by hatch_build.py
+src/galaxy_tool_xml/models/v*/
+src/galaxy_tool_xml/models/any_tool.py
+
+# Dev-only corpus checkouts — public Galaxy tool repositories (and any
+# future toolshed snapshots) cloned by scripts/corpus_check.py for deep
+# testing and design decisions; never committed.
+corpus/
+
+# Local, per-developer Claude Code settings
+.claude/settings.local.json
+

galaxy_tool_source-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

galaxy_tool_source-0.1.0/CLAUDE.md

@@ -0,0 +1,140 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository.
+
+## Project
+
+`galaxy-tool-source` is a foundation library and CLI for parsing, profile-aware
+validation, and typed inspection of Galaxy tool definition XML. It is the
+foundation for a separate, `black`-like Galaxy tool linter/formatter — it has
+**no serializer**: it exposes the mutable lxml tree and callers serialize it
+themselves.
+
+## Commands
+
+Run these from the **workspace root** (`galaxy-tool-refactor/`):
+
+- `uv sync` — install dependencies; the build hook generates the per-version models.
+- `uv run --package galaxy-tool-source pytest galaxy-tool-source/tests/` — run this package's tests.
+- `uv run --package galaxy-tool-source pytest galaxy-tool-source/tests/test_binding.py::test_load_tool_returns_document` — run a single test.
+- `uv run --package galaxy-tool-source pytest -m slow galaxy-tool-source/tests/` — run the xsdata codegen sweep over every vendored XSD.
+- `uv run ruff check galaxy-tool-source/src` — lint.
+- `uv run mypy --config-file galaxy-tool-source/pyproject.toml galaxy-tool-source/src` — type-check (strict).
+- `uv run python -m scripts.fetch_schemas` — download release XSDs (`--force` re-downloads all).
+- `uv run python -m scripts.regenerate` — regenerate the per-version typed models from every vendored XSD.
+- `uv run python -m scripts.corpus_check validate` — sweep public Galaxy tool repositories for crashes (maintainer QA).
+- `uv run galaxy-tool-source validate <file>` / `suggest <file>` / `profiles` — the CLI.
+- `uv build --package galaxy-tool-source` — build the wheel (the build hook generates the per-version models).
+
+## Naming
+
+The repo directory, the distribution, and the CLI command are all
+`galaxy-tool-source`; the import package is `galaxy_tool_source`.
+
+## Architecture
+
+`ToolDocument` (`document.py`) wraps a mutable lxml tree — the **source of
+truth**, faithfully preserving CDATA, comments, and attribute order.
+`binding.py` parses (`load_tool`, `parse_tool`; `load_macros` for a `<macros>`
+file → `MacroDocument`), validates (`validate_tool`), and finds a tool's newest
+valid profile (`newest_valid_profile`). `MacroDocument` (`document.py`) is the
+macro-file counterpart to `ToolDocument` — a mutable tree with no profile/model
+and no standalone XSD validation. `profiles.py`
+resolves a tool's `profile` to one of the ~28 vendored per-release XSDs.
+`macros.py` handles Galaxy macros and is the sole `galaxy-util` adapter; it also
+exposes read-only macro-file resolution (`imported_macro_paths`) and
+token-definition lookup (`token_definitions` / `TokenDefinition`) over a tool and
+its imported macro files. `bundle.py` builds a `ToolBundle` (a tool + its
+transitively-imported macro documents) via `load_bundle` and renames a parameter
+across the whole bundle (`rename_param_in_bundle`) — the cross-file extension of
+`cheetah_rename` (decisions §21).
+`corrections.py` suggests near-miss typo fixes. `schema_content.py` derives
+the text-bearing element-tag set from the vendored XSDs (the fmt tier's
+payload-guard source of truth). `rst.py` / `rst_markdown.py` own
+the `<help>` reStructuredText subsystem: validity + surgical repair (the GTR089
+partition seam, decisions §23) and the render-equivalence-gated RST → Markdown
+conversion (GTR092's engine, §24; markdown-it-py rides the `[markdown]` extra). `models/` holds an
+xsdata-generated read-only typed model per vendored schema version, generated at
+build time by `_codegen.py` and reached via `ToolDocument.model()`;
+`models/registry.py` resolves a version to its model.
+
+The public API is the prose-declared list in `README.md`; everything else is
+private and may change. For the rationale behind each architectural choice
+(profile-aware validation, the lxml-as-source-of-truth contract, the macro
+expansion adapter, etc.) plus assumptions about the Galaxy ecosystem and
+testing-derived data, see `docs/decisions.md`.
+
+## Coding standards
+
+Hand-written code follows **dignified-python**, vendored at the workspace root
+`.claude/skills/dignified-python/`: LBYL over `try/except`; exceptions only at
+the click error boundary (chained `from e`); `pathlib` with explicit
+`encoding` for text I/O; no import-time side effects (`@cache` for module
+state); absolute imports, no re-exports, no `__all__`; keyword-only arguments
+after the first. `optimized-python` (`.claude/skills/optimized-python/`) is
+installed as a reference; **dignified-python governs on any conflict**. The
+generated per-version model packages (`models/v*/`, `models/any_tool.py`) are
+exempt — they are not hand-written; `models/__init__.py` and `models/registry.py`
+are hand-written and are not exempt.
+
+## Non-obvious conventions
+
+- The lxml tree is the source of truth; the typed model is a derived read-only
+  view, bound to the tool's own profile. The library does not emit XML.
+- Parsing uses `strip_cdata=False`: CDATA, comments, and attribute order are
+  preserved. XML is parsed from `bytes`, never a decoded `str`, so the
+  document's own encoding declaration is honoured.
+- The Galaxy XSD is a **post-macro-expansion** schema; `validate_tool`
+  transforms the tool per `macro_handling` (default `expand`) into a throwaway
+  copy and validates that — the `ToolDocument` tree is never mutated.
+- `galaxy.util` is Galaxy's *internal* API; all use of it is confined to
+  `macros.py`, and `galaxy-util` is pinned to a version range.
+- The per-version model packages (`models/v*/`, `models/any_tool.py`) are
+  generated — never hand-edit; they are gitignored, regenerated by the build
+  hook and by `scripts/regenerate.py`, and excluded from ruff and mypy. Each
+  generated `v*/__init__.py` re-exports its module — the one sanctioned
+  exception to the no-re-exports rule.
+- `schema/` holds vendored XSDs downloaded once by `scripts/fetch_schemas.py`;
+  re-running is additive, `--force` re-downloads. `manifest.json` and
+  `PROVENANCE.md` are committed alongside the XSDs.
+- `../docs/corpus_data/` (workspace root) holds the fine-grained per-tool data
+  (JSON + TSV) emitted alongside the aggregate `../docs/*_corpus_stats.md`
+  artifacts; both regenerate together on a full `corpus_check.py validate` sweep.
+  Toolshed row
+  versions come from `.local/corpus/galaxy-toolshed/manifest.json`, which
+  `fetch_toolshed.py` populates by capturing each clone's tip changeset
+  before `.hg/` is removed. The combined stats markdown also carries two
+  failure-reason tables (macro-expansion failures, no-valid-profile
+  reasons) categorising every tool whose validity vector is empty —
+  these answer the "are these our bugs?" question at a glance.
+- Both validation and binding are profile-aware: `validate_tool` uses the
+  per-release XSD, and `ToolDocument.model()` binds against the model for the
+  tool's resolved profile (overridable via `model(version=...)`).
+- Binding uses a lenient xsdata config: unknown elements/attributes are ignored,
+  and schema-required fields the tree omits (an element a macro would supply)
+  default to `None`, so binding an un-expanded tool never raises.
+- `corrections.py` is suggest-only and independent of `validate_tool`; its
+  vocabulary comes from introspecting the generated model for the tool's own
+  profile, with a macro skip-set so an un-expanded tool's macro constructs are
+  never flagged.
+- No-profile tools validate against `16.10` (our oldest vendored XSD), matching
+  Galaxy's `16.01` legacy default for a missing `profile` (`resolve_profile(None)`
+  → nearest vendored = 16.10). See `docs/decisions.md` §1.5.
+- Failure modes: syntax errors (`load_tool` raises, the others collect them),
+  macro-expansion errors, and XSD validation errors. The XSD has no
+  `targetNamespace`, so Galaxy tool XML is namespace-free.
+
+## Implementation workarounds
+
+Two deviations from a naive implementation, both forced by upstream bugs:
+
+- **xsdata codegen** (`_codegen.py`): xsdata 26.2's circular-reference detector
+  raises `KeyError` on the Galaxy 24.2+ schema when inner classes are nested, so
+  codegen sets `output.unnest_classes = True`. Each version is generated in its
+  own subprocess — xsdata caches its resolved output path process-wide.
+- **Schema compilation** (`profiles.py`): Galaxy releases 19.05 through 23.0
+  shipped an XSD whose `Output` type has a non-deterministic content model that
+  libxml2 refuses to compile. `compiled_schema` retries after applying Galaxy's
+  own release-23.1 fix (drop the redundant `Output` group) in memory — the
+  vendored XSD files on disk remain verbatim.

galaxy_tool_source-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Burhans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

galaxy_tool_source-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: galaxy-tool-source
+Version: 0.1.0
+Summary: Foundation library for parsing, profile-aware validation, and typed inspection of Galaxy tool XML
+Project-URL: Homepage, https://github.com/richard-burhans/galaxy-tool-refactor
+Project-URL: Repository, https://github.com/richard-burhans/galaxy-tool-refactor
+Project-URL: Issues, https://github.com/richard-burhans/galaxy-tool-refactor/issues
+Author-email: Richard Burhans <richard.burhans@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bioinformatics,cheetah,galaxy,tool-xml,validation,xsd
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8
+Requires-Dist: docutils>=0.21
+Requires-Dist: galaxy-util[template]<27,>=24
+Requires-Dist: lxml>=5
+Requires-Dist: packaging>=23
+Requires-Dist: xsdata[lxml]>=26.2
+Provides-Extra: markdown
+Requires-Dist: markdown-it-py>=4; extra == 'markdown'
+Provides-Extra: shell-oracle
+Requires-Dist: bashlex>=0.18; extra == 'shell-oracle'
+Description-Content-Type: text/markdown
+
+# galaxy-tool-source
+
+A Python library and small CLI for parsing, profile-aware validation, and typed
+inspection of [Galaxy](https://galaxyproject.org/) tool definition XML — the
+`<tool>` wrapper files that define Galaxy bioinformatics tools.
+
+This package is the **foundation** for a separate, `black`-like program for
+Galaxy tool XML (conformance checking, autofixing, reformatting). It provides
+only the foundation — no rules, no formatter, no serializer:
+
+1. **Parse** tool XML into a mutable representation that faithfully preserves
+   CDATA, comments, attribute data and order, and significant element text.
+2. A **typed read-only view** of a parsed tool — bound to the model for the
+   tool's own schema profile — for convenient rule-checking.
+3. **Profile-aware XSD validation**, with configurable macro handling so
+   validation is accurate on real-world tools that use Galaxy macros.
+4. **Near-miss typo suggestions** against the schema vocabulary (suggest only).
+
+## Install
+
+```sh
+uv sync
+```
+
+## Usage
+
+```python
+from galaxy_tool_source.binding import load_tool, validate_tool
+
+document = load_tool("my_tool.xml")
+print(document.profile)
+
+result = validate_tool("my_tool.xml")
+if not result.valid:
+    for error in result.errors:
+        print(error)
+```
+
+From the command line:
+
+```sh
+uv run galaxy-tool-source validate my_tool.xml
+uv run galaxy-tool-source suggest my_tool.xml
+uv run galaxy-tool-source profiles
+```
+
+## Public API
+
+The downstream formatter project may rely on exactly these symbols. Everything
+else is private and may change without notice.
+
+```python
+from galaxy_tool_source.binding import load_tool, parse_tool, validate_tool, newest_valid_profile
+from galaxy_tool_source.binding import load_macros
+from galaxy_tool_source.binding import ParseResult, ValidationResult, XmlError, ToolXmlSyntaxError
+from galaxy_tool_source.document import ToolDocument, MacroDocument
+from galaxy_tool_source.macros import MacroError, imported_macro_paths, token_definitions, TokenDefinition, expanded_detection_root
+from galaxy_tool_source.corrections import suggest_corrections, Correction
+from galaxy_tool_source.boolean_values import suggest_boolean_normalizations, normalize_boolean_token, BooleanNormalization
+from galaxy_tool_source.cheetah_refs import tool_cheetah_references, CheetahRef
+from galaxy_tool_source.cheetah_rename import rename_param, rename_param_plan, RenameOutcome, RenameEdit, RenamePlan
+from galaxy_tool_source.bundle import ToolBundle, load_bundle, rename_param_in_bundle, BundleRenameOutcome
+from galaxy_tool_source.profiles import available_profiles, latest_profile, UnknownProfileError
+from galaxy_tool_source.schema_content import text_bearing_tags
+from galaxy_tool_source.models.registry import model_module, tool_class
+from galaxy_tool_source.models.any_tool import AnyTool
+```
+
+## Architecture
+
+`ToolDocument` (`document.py`) wraps a mutable lxml tree — the source of truth,
+faithfully preserving CDATA, comments, and attribute order. `binding.py` parses
+and validates; `profiles.py` resolves the per-release vendored XSD; `macros.py`
+handles Galaxy macros (the sole `galaxy-util` adapter); `corrections.py` suggests
+near-miss typo fixes; `boolean_values.py` reports schema-boolean attribute value
+normalizations (`True` → `true`); `cheetah_refs.py` / `cheetah_rename.py` find and
+rename a parameter across a tool's Cheetah sections (the latter renders the rename
+either as a tree mutation, `rename_param`, or as minimal source offsets,
+`rename_param_plan`, for editor / LSP use); `bundle.py` extends the rename across a
+tool *and its imported macro files* (`ToolBundle` / `load_bundle` /
+`rename_param_in_bundle`); `rst.py` / `rst_markdown.py` own the `<help>`
+reStructuredText subsystem — validity + surgical repair (the GTR089 partition seam)
+and the render-equivalence-gated RST → Markdown conversion (GTR092; needs the
+`[markdown]` extra); `models/` holds an xsdata-generated
+read-only typed model for every vendored schema version, reached via
+`ToolDocument.model()`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).