Plugin extensibility: format registration mechanism.

[AuraMindNest]

Close #118.

Summary by CodeRabbit

Release Notes

• Documentation
  • Updated README with the new registry-based workflow for adding Weblate format adapters.
  • Updated deployment/runbook guidance for how plugin format overrides are merged into Weblate settings.
• Refactor
  • Introduced a declarative format registry and migrated the QuickBook adapter to register through it.
  • Updated settings override logic to include all registry-provided format adapters (not just QuickBook).
• Tests
  • Added comprehensive unit tests covering registry registration, lookups, and filename/extension matching.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d634973c-fbcb-4000-9894-a4e2cc291d5b

📥 Commits

Reviewing files that changed from the base of the PR and between 2bcf727 and ab3b32d.

📒 Files selected for processing (2)

• src/boost_weblate/formats/registry.py
• tests/test_settings_override.py

🚧 Files skipped from review as they are similar to previous changes (2)

• tests/test_settings_override.py
• src/boost_weblate/formats/registry.py

---

📝 Walkthrough

Walkthrough

Introduces FormatRegistry and RegisteredFormat in a new registry.py module to replace hardcoded QuickBook-specific format handling. QuickBookFormat is refactored to use the @registry.register decorator and inherit RegisteredFormat. settings_override.py now collects plugin format paths from the registry instead of a hardcoded class path. Tests and docs are updated accordingly.

Changes

Format Registry System

Layer / File(s)	Summary
RegisteredFormat contract and FormatRegistry core src/boost_weblate/formats/registry.py	New RegisteredFormat ABC defines format_id, file_patterns, weblate_class fields. FormatRegistry implements register, register_entry, weblate_class_paths, get_by_id, match_filename, extension_map, validation, and a module-level registry singleton.
QuickBookFormat registered via decorator and package init wiring src/boost_weblate/formats/quickbook.py, src/boost_weblate/formats/__init__.py	QuickBookFormat gains @registry.register decorator, RegisteredFormat base class, file_patterns/autoload metadata split, and weblate_class. formats/__init__.py calls registry.register_entry for bootstrap, expands __all__, and adds a lazy __getattr__ for QuickBookFormat.
settings_override migrated to registry-driven WEBLATE_FORMATS src/boost_weblate/settings_override.py	Removes weblate_formats_with_quickbook(); adds weblate_formats_with_plugin_formats() that merges AST-parsed upstream paths with registry.weblate_class_paths(), de-duplicating before returning the combined tuple.
Registry behavior tests tests/formats/test_registry.py	Adds isolated_registry fixture, MockFormatSpec/DuplicateMockFormatSpec test doubles, and 14 tests covering decorator registration, filename matching, extension map, idempotency, first-wins deduplication, missing id, ValueError on empty format_id, register_entry bootstrapping and class replacement, and module-level registry state.
Settings override tests updated and docs revised tests/test_settings_override.py, README.md, docs/deployment-runbook.md	Settings tests replace QuickBook-specific assertions with plugin-driven assertions via _plugin_weblate_paths(). README "Adding another format" section and deployment-runbook WEBLATE_FORMATS description updated for registry-based workflow.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested reviewers

• henry0816191
• wpak-ai

Poem

🐇 Hop hop, the registry's here,
No more hardcoded paths to fear!
@registry.register — what a treat,
New formats join with just one beat.
The rabbit stamps each format right,
QuickBook glows in registry light! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 42.11% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Plugin extensibility: format registration mechanism' directly and clearly summarizes the primary change—implementing a format registration mechanism to enable plugin extensibility.
Linked Issues check	✅ Passed	The PR fully implements all four acceptance criteria: FormatRegistry with @registry.register and register_entry() [#118], settings_override.py integration with registry.weblate_class_paths() [#118], QuickBookFormat implements RegisteredFormat and is discoverable [#118], and validation with duplicate/first-wins logic [#118].
Out of Scope Changes check	✅ Passed	All changes directly support the format registration mechanism objectives: registry implementation, format adapter refactoring, settings integration, documentation updates, and comprehensive tests are all within scope.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

tests/formats/test_registry.py (1)

100-110: ⚡ Quick win

Add negative tests for malformed file_patterns validation.

Given the registry contract is central to plugin extensibility, please add tests for invalid file_patterns (e.g., bare string and empty tuple) so bad specs fail fast and this behavior stays protected.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/formats/test_registry.py` around lines 100 - 110, Add new test
functions to validate that the FormatRegistry properly rejects malformed
file_patterns in RegisteredFormat subclasses. Create at least two additional
test functions following the same pattern as
test_register_validation_missing_format_id: one test where file_patterns is a
bare string instead of a tuple, and another where file_patterns is an empty
tuple. For each test, instantiate a BadSpec class with the invalid file_patterns
value, call reg.register(BadSpec), and assert that it raises a ValueError with
an appropriate error message mentioning file_patterns. This ensures the registry
validation protects against these common misconfiguration patterns.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/boost_weblate/formats/registry.py`:
- Around line 55-57: The current validation in the file_patterns check only
ensures it's non-empty but doesn't prevent a bare string from being passed,
which causes incorrect behavior since strings are iterable and the
match_filename() method will iterate over individual characters. In the
_validate() method, add explicit validation to ensure file_patterns is a
sequence type (list or tuple) and not a string, raising a ValueError with a
descriptive message if a string is passed. Apply the same validation logic in
the register_entry() method to catch this issue at the entry point where plugins
register their file patterns.

In `@tests/test_settings_override.py`:
- Line 67: The assertion on line 67 uses a hardcoded threshold value of 40 which
creates brittle coupling to a specific Weblate release. Replace this hardcoded
number with a computed expectation derived from the upstream FormatsConf.FORMATS
data that is already being parsed elsewhere in this test file. Calculate the
expected baseline count from the actual formats data and use that computed value
in the assertion instead of the magic number 40.

---

Nitpick comments:
In `@tests/formats/test_registry.py`:
- Around line 100-110: Add new test functions to validate that the
FormatRegistry properly rejects malformed file_patterns in RegisteredFormat
subclasses. Create at least two additional test functions following the same
pattern as test_register_validation_missing_format_id: one test where
file_patterns is a bare string instead of a tuple, and another where
file_patterns is an empty tuple. For each test, instantiate a BadSpec class with
the invalid file_patterns value, call reg.register(BadSpec), and assert that it
raises a ValueError with an appropriate error message mentioning file_patterns.
This ensures the registry validation protects against these common
misconfiguration patterns.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0507ea3b-157a-49d5-a826-1aab5f049796

📥 Commits

Reviewing files that changed from the base of the PR and between 7026f96 and 2bcf727.

📒 Files selected for processing (8)

• README.md
• docs/deployment-runbook.md
• src/boost_weblate/formats/__init__.py
• src/boost_weblate/formats/quickbook.py
• src/boost_weblate/formats/registry.py
• src/boost_weblate/settings_override.py
• tests/formats/test_registry.py
• tests/test_settings_override.py