Upgrade to Python 3.11

[olmos-keepsafe]

Summary

Upgrades html-structure-diff to Python 3.11 and establishes the Python-3.11-only sdiff==2.0.0 line on Mistune 3.3.4 while preserving the package’s public parsing, rendering, and structural-diff behavior.

Changes

• Standardize local development, packaging, and CI on Python 3.11.13.
• Replace setup.py and setup.cfg with pyproject.toml.
• Establish version 2.0.0 as the Python-3.11-only release line.
• Apply and verify the complete pyupgrade ladder through --py311-plus.
• Add native CircleCI 2.1 configuration.
• Add reproducible runtime and development requirements generated with pip-compile.
• Add package-oriented Makefile targets for setup, linting, tests, dependency checks, requirements generation, package builds, and Mistune compatibility proof.
• Upgrade Mistune from 0.8.4 to 3.3.4 behind a repository-owned compatibility parser.
• Add Golden Mistune 0.8.4 Fixtures, curated compatibility cases, deterministic fuzzing, exhaustive link/image matrices, and focused parity regressions.
• Add an all-in-one make mistune-compat workflow that creates a fresh Mistune 0.8.4 oracle under /tmp, runs the comparison, and removes it afterward.
• Include compatibility helpers and Markdown/JSON fixtures in the source distribution.
• Add import, fixture, wheel-install, package metadata, and extracted-source-distribution smoke coverage.

This repository is a library/tool rather than a service, so service-only migration work such as Docker Compose, Gunicorn, backing services, and runtime health checks is intentionally excluded.

Compatibility

The Mistune 3.3.4 adapter preserves the documented sdiff parser, renderer, model, structural-diff, link-diff, HTML, list, link/image, and Zendesk behavior previously produced with Mistune 0.8.4.

Compatibility is protected by:

• 13 compact golden parser/renderer/diff scenarios.
• Existing Markdown fixture pairs.
• 1,000 deterministic structured fuzz cases.
• 1,086 named Mistune 0.8.4-versus-3.3.4 comparisons with zero mismatches.
• Two exhaustive matrices covering another 98,334 link/image inputs.
• Golden Mistune 0.8.4 Fixtures checked by every normal make test run.
• Focused malformed-input and bounded-time regressions.

One intentional improvement fixes a Mistune 0.8-era bug where constructing a Zendesk parser mutated shared MdParser rules and could break later plain-parser instances. Private Mistune 0.8 implementation classes and attributes are not part of the supported sdiff public API.

Downstream impact

sdiff==2.x requires Python 3.11. Downstream consumers should adopt this release only as part of their own Python 3.11 migrations and rerun their service-level compatibility and integration proof.

Known consumers:

• content-validator directly imports sdiff APIs and currently references the pre-Mistune-upgrade immutable revision. Its Python 3.11 migration should move to the final 2.x tag or immutable revision. Its local suite passed against this branch with 65 tests passing and one expected skip.
• email-service consumes sdiff transitively through content-validator. It should update after migrating to Python 3.11 and adopting a compatible content-validator release.
• translation-real-time-validaton also consumes sdiff transitively through content-validator and will need the same dependency refresh and service-level verification.

Consumers that have not migrated to Python 3.11 should remain on the legacy sdiff release line.

This pull request makes the Python 3.11/Mistune 3-compatible library available but does not modify or deploy downstream repositories.

Validation

• 77 tests passed on Python 3.11.13.
• 99% total branch-aware coverage.
• sdiff/parser.py reached 100% statement and 99% branch coverage.
• Mistune 0.8.4 versus 3.3.4: 1,086 named cases, zero mismatches.
• Exhaustive matrices covered another 98,334 link/image inputs.
• Flake8 and the direct-msgpack guard passed.
• Public API/import and fixture smoke passed.
• pip check reported no broken requirements.
• Python compile smoke passed.
• Generated requirements were stable across consecutive runs.
• Source distribution and wheel built successfully.
• twine check passed for both package artifacts.
• The complete extracted-source-distribution suite passed: 77 tests and 1,120 subtests.
• Isolated wheel installation and structural-diff smoke passed.
• CircleCI configuration passed standard, --next, and processed-config validation.
• Downstream content-validator proof passed: 65 tests and one expected skip.
• git diff --check passed.

Linear

BE-96: Upgrade html-structure to Python 3.11

Fixes BE-96