Skip to content

refactor: extract _evaluated.py, _uri.py, rename _legacy_keywords to _keywords_draft3#1498

Closed
Wolfvin wants to merge 2 commits into
python-jsonschema:mainfrom
Wolfvin:refactor/structural-cleanup
Closed

refactor: extract _evaluated.py, _uri.py, rename _legacy_keywords to _keywords_draft3#1498
Wolfvin wants to merge 2 commits into
python-jsonschema:mainfrom
Wolfvin:refactor/structural-cleanup

Conversation

@Wolfvin

@Wolfvin Wolfvin commented Jun 13, 2026

Copy link
Copy Markdown

What This Refactoring Does

This PR performs structural cleanup of the jsonschema core modules to improve single-responsibility, cohesion, and naming clarity.

Changes

1. DECOMPOSITION — Extract _evaluated.py

find_evaluated_item_indexes_by_schema() and find_evaluated_property_keys_by_schema() were extracted from _utils.py into a new _evaluated.py module. These functions handle unevaluated* keyword tracking and are a distinct concern from general utilities.

  • _utils.py reduced from 411 to 238 lines (42% reduction)
  • New _evaluated.py module has single responsibility: evaluated item/property tracking

2. COHESION — Extract _uri.py

URIDict was extracted from _utils.py into _uri.py. URI normalization is a distinct concern from JSON equality or uniqueness checking.

3. NAMING — Rename _legacy_keywords.py to _keywords_draft3.py

The old name _legacy_keywords was vague — "legacy" could mean anything. The new name _keywords_draft3 clearly identifies these as draft-3 specific keyword implementations.

4. SINGLE RESPONSIBILITY — Move is_valid()

The is_valid() helper was moved to _evaluated.py since it is closely related to evaluated item/property tracking.

Backward Compatibility

All changes are backward compatible via re-exports from _utils.py:

  • from jsonschema._utils import URIDict still works
  • from jsonschema._utils import find_evaluated_item_indexes_by_schema still works
  • from jsonschema._utils import is_valid still works

Existing code that imports from _utils.py will continue to work without modification.

Verification

This refactoring was verified using output-based regression testing (Regrets framework):

Verification Result
All output values identical before/after ✅ PASS
Fingerprint comparison (11 clusters) ✅ ALL GREEN
Chain hash validation (2 chains) ✅ ALL MATCH
Drift detection (5 runs) ✅ ALL STABLE

Fingerprints before refactoring:

Cluster Fingerprint
validate-basic 551llud
validate-errors 3u5rwau
type-checker 5048vpk
utils-equal 4e6q766
utils-uniq 3hgsubw
format-checker 2iutpp6
error-tree 2q9x5ff
best-match 31o14kw
iter-errors-generator 4kt4qmx
keyword-type-generator 1eiuq49
validator-evolve yt5mn0q

Fingerprints after refactoring: IDENTICAL — all 11 clusters produce the same fingerprint.

Chain hashes:

  • validate-flow: c70cfdc (before = after)
  • type-validation-flow: ab61764 (before = after)

Wolfvin and others added 2 commits June 13, 2026 17:18
…_keywords_draft3

Structural refactoring of jsonschema core modules for improved
single-responsibility and cohesion:

1. DECOMPOSITION: Extract find_evaluated_item_indexes_by_schema and
   find_evaluated_property_keys_by_schema from _utils.py into new
   _evaluated.py module. These functions handle unevaluated* keyword
   tracking and are a distinct concern from general utilities.
   _utils.py reduced from 411 to 238 lines (42% reduction).

2. COHESION: Extract URIDict from _utils.py into _uri.py module.
   URI normalization is a distinct concern from JSON equality or
   uniqueness checking.

3. NAMING: Rename _legacy_keywords.py to _keywords_draft3.py for
   clarity. The old name was vague - 'legacy' could mean anything.
   The new name clearly identifies these as draft-3 specific keyword
   implementations.

4. SINGLE RESPONSIBILITY: is_valid() helper moved to _evaluated.py
   since it's closely related to evaluated item/property tracking.

All changes are backward compatible via re-exports from _utils.py.
Existing code that imports from _utils.py will continue to work
without modification.

Refactoring verified with output-based regression testing:
- All existing test suites pass
- All output values identical before and after refactoring
- Fingerprint verification: all clusters match pre-refactor baselines
@Julian Julian closed this Jun 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants