Upgrade to Python 3.11

[olmos-keepsafe]

Key changes

• Migrates packaging from setup.py/setup.cfg to pyproject.toml with Python 3.11 metadata.
• Sets .python-version to 3.11.13 and bumps ks-email-parser from 0.3.2 to 1.0.0.
• Updates runtime/dev pins for Python 3.11 compatibility, including the pystache use_2to3 build blocker.
• Uses the latest observed compatible releases as of 2026-07-21, with the downstream-compatible lxml correction: beautifulsoup4 4.15.0, Markdown 3.10.2, inlinestyler 0.2.5, lxml 6.0.2, parse 1.22.1, pystache 0.6.8, and coverage 7.15.2.
• Retains cssutils 2.11.1 as the latest safe cssutils pin after proving cssutils 2.13.0, 2.14.0, and 2.15.0 import-fail locally through the missing encutils module.
• Confirms the latest pin updates do not break this project: upstream changes are compatible with the APIs used here, dependency/import checks pass, and all golden render and CLI behavior remains stable.
• Aligns lxml==6.0.2 with libks==1.0.5, which is the source of truth for shared downstream dependency versions.
• Modernizes Markdown extension hooks for Markdown 3, keeps no-tracking links/base-url images compatible, and preserves golden fixture rendering output.
• Adds a narrow inlinestyler/lxml compatibility shim for CSSSelector.evaluate with lxml 6 while preserving fixture output normalization.
• Confirms msgpack is not a direct dependency, source/test import, or installed transitive dependency; check-msgpack remains in make lint.
• Adds CircleCI package CI following the python311-service-upgrade-stack sample intent with valid CircleCI 2.1 executors/commands: cimg/python:3.11.13, prepare_cache, lint/test jobs, v3-pip-/v3-venv- fallback cache keys, coverage artifact storage, and non-fatal Codecov upload.
• Switches local test workflow from nosetests to pynose and keeps flake8 config in pyproject.toml.
• Uses pyupgrade only for the completed migration ladder and removes it from retained project extras afterward.
• Modernizes the CLI asyncio execution path and version lookup for Python 3.11.
• Fixes empty render handling both at the top-level render set and empty worker-batch level so missing/wrong input trees fail instead of silently succeeding.
• Adds docs/python311-migration-contract.md, CLI golden fixture smoke, empty-input CLI regression coverage, and refreshed task mapping/proof notes.

Proof run

• Baseline Python 3.11 install failed on pystache==0.5.4 because it uses removed use_2to3 metadata.
• make dev: pass with the latest selected dependency pins
• Fresh make dev after uninstalling pyupgrade: pass; pyupgrade was not reinstalled
• make lint: pass, including flake8 7.3.0, flake8-pyproject 1.2.4, and check-msgpack
• make test: pass, 86 tests, 79% coverage; includes golden fixture comparisons, CLI smoke, and empty-render failure regression
• venv/bin/python -m compileall email_parser tests: pass
• Updated dependency import/version smoke: pass for beautifulsoup4 4.15.0, lxml 6.0.2, parse 1.22.1, coverage 7.15.2, and email_parser.Parser
• venv/bin/ks-email-parser --version: pass, returned 1.0.0
• venv/bin/pip check: pass, no broken requirements found
• Downstream email-service editable integration on CPython 3.11.13: pass with libks==1.0.5, all four internal Python 3.11 worktrees, and lxml==6.0.2; pip check and pipdeptree --warn fail both pass
• Remote CircleCI on f77970f: prepare_cache, lint, and test passed
• venv/bin/python -m build: pass; built sdist and wheel with the updated metadata
• venv/bin/twine check dist/*: pass for both artifacts
• Wheel and sdist metadata inspection: pass; contains the updated exact pins and Python >=3.11,<3.12 requirement
• One-time venv/bin/pyupgrade ladder from --py36-plus through --py311-plus: pass/no-op on current files before removing the tool from project dependencies
• circleci config validate .circleci/config.yml: pass; remote jobs will run on the next branch push
• Dependency break proof: cssutils 2.13.0, 2.14.0, and 2.15.0 install but fail import cssutils with ModuleNotFoundError for encutils, so cssutils remains pinned to 2.11.1

Known gaps / follow-up work

• TODO: complete the skill's final two-consecutive-clean-review cycle after remote CircleCI reports on the next push.
• Email-service editable downstream validation is complete; package publication, the emails rendering workflow, and Ansible packaging/deployment remain follow-up work.
• Package artifacts were built and validated locally but were not published.
• make test still prints legacy warnings from intentionally malformed XML fallback fixtures; those warnings are covered by existing passing tests.
• Service-only python311-service-upgrade-stack tasks are intentionally skipped because this repo is library/CLI-shaped: no Gunicorn, PasteDeploy, service INI, workers, Docker runtime, health endpoints, local E2E stack, or egress guard.

Linear

• BE-93: Upgrade ks-email-parser to Python 3.11

Fixes BE-93