Skip to content

Remove misleading reference doc type alias renames#687

Draft
danielporterda wants to merge 1 commit into
mainfrom
python-type-alias-cleanup
Draft

Remove misleading reference doc type alias renames#687
danielporterda wants to merge 1 commit into
mainfrom
python-type-alias-cleanup

Conversation

@danielporterda
Copy link
Copy Markdown
Contributor

@danielporterda danielporterda commented Jun 2, 2026

Summary

  • Remove plain NewType = OldType aliases left from PR Tighten Python reference doc types #684 in the Python reference-doc typing surface.
  • Inline generic JSON object/list types where a separate name was only a rename.
  • Replace semantic aliases for Daml JSON modules, TypeDoc documents/exports, OpenRPC params/results, and protobuf metadata overlays with concrete TypedDict shapes.
  • Add shared parsed-JSON and Mintlify navigation validators so JSON/YAML boundary code earns JsonValue, object, array, and nav item types instead of relying on cast(...).
  • Add shape-specific loaders for Daml JSON modules, TypeDoc documents, AsyncAPI/OpenRPC documents, and protobuf metadata overlays.
  • Keep only recursive structural aliases that are not simple renames: JsonValue, MintlifyNavItem, and MintlifyNavItems.

Validation

  • direnv exec . python3 -m compileall -q scripts/generated_reference_nav.py scripts/reference_nav.py src/x2mdx/asyncapi/lifecycle.py src/x2mdx/asyncapi/models.py src/x2mdx/asyncapi/snapshots.py src/x2mdx/daml_json/models.py src/x2mdx/daml_json/snapshots.py src/x2mdx/jvm_docs/snapshots.py src/x2mdx/mintlify.py src/x2mdx/openrpc/lifecycle.py src/x2mdx/openrpc/models.py src/x2mdx/openrpc/snapshots.py src/x2mdx/protobuf/models.py src/x2mdx/protobuf/snapshots.py src/x2mdx/typedoc/models.py src/x2mdx/typedoc/snapshots.py src/x2mdx/types.py
  • direnv exec . ruff check scripts/generated_reference_nav.py scripts/reference_nav.py src/x2mdx/asyncapi/lifecycle.py src/x2mdx/asyncapi/models.py src/x2mdx/asyncapi/snapshots.py src/x2mdx/daml_json/models.py src/x2mdx/daml_json/snapshots.py src/x2mdx/jvm_docs/snapshots.py src/x2mdx/mintlify.py src/x2mdx/openrpc/lifecycle.py src/x2mdx/openrpc/models.py src/x2mdx/openrpc/snapshots.py src/x2mdx/protobuf/models.py src/x2mdx/protobuf/snapshots.py src/x2mdx/typedoc/models.py src/x2mdx/typedoc/snapshots.py src/x2mdx/types.py
  • direnv exec . mypy scripts/generated_reference_nav.py scripts/reference_nav.py src/x2mdx/asyncapi/lifecycle.py src/x2mdx/asyncapi/models.py src/x2mdx/asyncapi/snapshots.py src/x2mdx/daml_json/models.py src/x2mdx/daml_json/snapshots.py src/x2mdx/jvm_docs/snapshots.py src/x2mdx/mintlify.py src/x2mdx/openrpc/lifecycle.py src/x2mdx/openrpc/models.py src/x2mdx/openrpc/snapshots.py src/x2mdx/protobuf/models.py src/x2mdx/protobuf/snapshots.py src/x2mdx/typedoc/models.py src/x2mdx/typedoc/snapshots.py src/x2mdx/types.py
  • Cast scan over src/x2mdx, scripts/generated_reference_nav.py, and scripts/reference_nav.py finds no cast(...) usage.
  • Alias scan over the PR-touched files finds no plain rename aliases; only recursive structural aliases remain.
  • PYTHONDONTWRITEBYTECODE=1 direnv exec . python3 -m pytest tests/test_api_reference_navigation.py tests/test_asyncapi.py tests/test_openrpc.py tests/test_daml_json.py tests/test_jvm_docs.py tests/test_protobuf.py tests/test_protobuf_nav.py tests/test_typedoc.py tests/test_typescript_bindings_reference.py -k 'not test_build_report_requires_status_for_non_deprecated_types and not test_build_report_tracks_lifecycle_from_local_jars and not test_cli_builds_pages_and_updates_docs_json and not test_cli_builds_overview_and_package_pages' passed: 31 passed, 4 deselected.
  • git diff --check

Known base failures

The full focused pytest command currently has 4 failures that reproduce outside this branch:

  • Three tests/test_jvm_docs.py cases fail while building fixture jars under Python 3.14 with struct.error: 'H' format requires 0 <= number <= 65535.
  • tests/test_protobuf.py::ProtobufTests::test_cli_builds_overview_and_package_pages expects href="packages/com-example-v1", while the renderer emits href="./packages/com-example-v1".

@danielporterda danielporterda force-pushed the python-type-alias-cleanup branch from c8747ee to dcdb3ff Compare June 2, 2026 16:50
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.

1 participant