generate using cargo-dist

## Summary

<!-- What's the purpose of the change? What does it do, and why? -->
This PR updates the metadata in the YAML frontmatter of the mkdocs
documentation to include the rule short code as a tag, so it can be
easily searched.
Ref: #13684

## Test Plan

<!-- How was it tested? -->
This has been tested locally using the documentation provided
[here](https://docs.astral.sh/ruff/contributing/#mkdocs) for generating
docs.

This generates docs that now have the tags section:
```markdown
---
description: Checks for abstract classes without abstract methods.
tags:
- B024
---

# abstract-base-class-without-abstract-method (B024)
... trimmed
```

I've also verified that this gives the ability to get straight to the
page via search when serving mkdocs locally.

---------

Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>

.github/CODEOWNERS

@@ -17,5 +17,5 @@
 /scripts/fuzz-parser/ @AlexWaygood
 
 # red-knot
-/crates/red_knot* @carljm @MichaReiser @AlexWaygood
-/crates/ruff_db/ @carljm @MichaReiser @AlexWaygood
+/crates/red_knot* @carljm @MichaReiser @AlexWaygood @sharkdp
+/crates/ruff_db/ @carljm @MichaReiser @AlexWaygood @sharkdp

.github/workflows/build-binaries.yml

@@ -63,7 +63,7 @@ jobs:
 
   macos-x86_64:
     if: ${{ !contains(github.event.pull_request.labels.*.name, 'no-build') }}
-    runs-on: macos-12
+    runs-on: macos-14
     steps:
       - uses: actions/checkout@v4
         with:

.github/workflows/build-docker.yml

@@ -17,12 +17,21 @@ on:
     paths:
       - .github/workflows/build-docker.yml
 
+env:
+  RUFF_BASE_IMG: ghcr.io/${{ github.repository_owner }}/ruff
+
 jobs:
-  docker-publish:
-    name: Build Docker image (ghcr.io/astral-sh/ruff)
+  docker-build:
+    name: Build Docker image (ghcr.io/astral-sh/ruff) for ${{ matrix.platform }}
     runs-on: ubuntu-latest
     environment:
       name: release
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - linux/amd64
+          - linux/arm64
     steps:
       - uses: actions/checkout@v4
         with:
@@ -36,12 +45,6 @@ jobs:
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Extract metadata (tags, labels) for Docker
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ghcr.io/astral-sh/ruff
-
       - name: Check tag consistency
         if: ${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
         run: |
@@ -55,14 +58,233 @@ jobs:
             echo "Releasing ${version}"
           fi
 
-      - name: "Build and push Docker image"
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.RUFF_BASE_IMG }}
+          # Defining this makes sure the org.opencontainers.image.version OCI label becomes the actual release version and not the branch name
+          tags: |
+            type=raw,value=dry-run,enable=${{ inputs.plan == '' || fromJson(inputs.plan).announcement_tag_is_implicit }}
+            type=pep440,pattern={{ version }},value=${{ inputs.plan != '' && fromJson(inputs.plan).announcement_tag || 'dry-run' }},enable=${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
+
+      - name: Normalize Platform Pair (replace / with -)
+        run: |
+          platform=${{ matrix.platform }}
+          echo "PLATFORM_TUPLE=${platform//\//-}" >> $GITHUB_ENV
+
+      # Adapted from https://docs.docker.com/build/ci/github-actions/multi-platform/
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: ${{ matrix.platform }}
+          cache-from: type=gha,scope=ruff-${{ env.PLATFORM_TUPLE }}
+          cache-to: type=gha,mode=min,scope=ruff-${{ env.PLATFORM_TUPLE }}
+          labels: ${{ steps.meta.outputs.labels }}
+          outputs: type=image,name=${{ env.RUFF_BASE_IMG }},push-by-digest=true,name-canonical=true,push=${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
+
+      - name: Export digests
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.build.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"
+
+      - name: Upload digests
+        uses: actions/upload-artifact@v4
+        with:
+          name: digests-${{ env.PLATFORM_TUPLE }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  docker-publish:
+    name: Publish Docker image (ghcr.io/astral-sh/ruff)
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+    needs:
+      - docker-build
+    if: ${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
+    steps:
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/digests
+          pattern: digests-*
+          merge-multiple: true
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.RUFF_BASE_IMG }}
+          # Order is on purpose such that the label org.opencontainers.image.version has the first pattern with the full version
+          tags: |
+            type=pep440,pattern={{ version }},value=${{ fromJson(inputs.plan).announcement_tag }}
+            type=pep440,pattern={{ major }}.{{ minor }},value=${{ fromJson(inputs.plan).announcement_tag }}
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Adapted from https://docs.docker.com/build/ci/github-actions/multi-platform/
+      - name: Create manifest list and push
+        working-directory: /tmp/digests
+        # The jq command expands the docker/metadata json "tags" array entry to `-t tag1 -t tag2 ...` for each tag in the array
+        # The printf will expand the base image with the `<RUFF_BASE_IMG>@sha256:<sha256> ...` for each sha256 in the directory
+        # The final command becomes `docker buildx imagetools create -t tag1 -t tag2 ... <RUFF_BASE_IMG>@sha256:<sha256_1> <RUFF_BASE_IMG>@sha256:<sha256_2> ...`
+        run: |
+          docker buildx imagetools create \
+            $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ env.RUFF_BASE_IMG }}@sha256:%s ' *)
+
+  docker-publish-extra:
+    name: Publish additional Docker image based on ${{ matrix.image-mapping }}
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+    needs:
+      - docker-publish
+    if: ${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Mapping of base image followed by a comma followed by one or more base tags (comma separated)
+        # Note, org.opencontainers.image.version label will use the first base tag (use the most specific tag first)
+        image-mapping:
+          - alpine:3.20,alpine3.20,alpine
+          - debian:bookworm-slim,bookworm-slim,debian-slim
+          - buildpack-deps:bookworm,bookworm,debian
+    steps:
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate Dynamic Dockerfile Tags
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          # Extract the image and tags from the matrix variable
+          IFS=',' read -r BASE_IMAGE BASE_TAGS <<< "${{ matrix.image-mapping }}"
+
+          # Generate Dockerfile content
+          cat <<EOF > Dockerfile
+          FROM ${BASE_IMAGE}
+          COPY --from=${{ env.RUFF_BASE_IMG }}:latest /ruff /usr/local/bin/ruff
+          ENTRYPOINT []
+          CMD ["/usr/local/bin/ruff"]
+          EOF
+
+          # Initialize a variable to store all tag docker metadata patterns
+          TAG_PATTERNS=""
+
+          # Loop through all base tags and append its docker metadata pattern to the list
+          # Order is on purpose such that the label org.opencontainers.image.version has the first pattern with the full version
+          IFS=','; for TAG in ${BASE_TAGS}; do
+            TAG_PATTERNS="${TAG_PATTERNS}type=pep440,pattern={{ version }},suffix=-${TAG},value=${{ fromJson(inputs.plan).announcement_tag }}\n"
+            TAG_PATTERNS="${TAG_PATTERNS}type=pep440,pattern={{ major }}.{{ minor }},suffix=-${TAG},value=${{ fromJson(inputs.plan).announcement_tag }}\n"
+            TAG_PATTERNS="${TAG_PATTERNS}type=raw,value=${TAG}\n"
+          done
+
+          # Remove the trailing newline from the pattern list
+          TAG_PATTERNS="${TAG_PATTERNS%\\n}"
+
+          # Export image cache name
+          echo "IMAGE_REF=${BASE_IMAGE//:/-}" >> $GITHUB_ENV
+
+          # Export tag patterns using the multiline env var syntax
+          {
+            echo "TAG_PATTERNS<<EOF"
+            echo -e "${TAG_PATTERNS}"
+            echo EOF
+          } >> $GITHUB_ENV
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        # ghcr.io prefers index level annotations
+        env:
+          DOCKER_METADATA_ANNOTATIONS_LEVELS: index
+        with:
+          images: ${{ env.RUFF_BASE_IMG }}
+          flavor: |
+            latest=false
+          tags: |
+            ${{ env.TAG_PATTERNS }}
+
+      - name: Build and push
         uses: docker/build-push-action@v6
         with:
           context: .
           platforms: linux/amd64,linux/arm64
-          # Reuse the builder
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-          push: ${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
-          tags: ghcr.io/astral-sh/ruff:latest,ghcr.io/astral-sh/ruff:${{ (inputs.plan != '' && fromJson(inputs.plan).announcement_tag) || 'dry-run' }}
+          # We do not really need to cache here as the Dockerfile is tiny
+          #cache-from: type=gha,scope=ruff-${{ env.IMAGE_REF }}
+          #cache-to: type=gha,mode=min,scope=ruff-${{ env.IMAGE_REF }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          annotations: ${{ steps.meta.outputs.annotations }}
+
+  # This is effectively a duplicate of `docker-publish` to make https://github.com/astral-sh/ruff/pkgs/container/ruff
+  # show the ruff base image first since GitHub always shows the last updated image digests
+  # This works by annotating the original digests (previously non-annotated) which triggers an update to ghcr.io
+  docker-republish:
+    name: Annotate Docker image (ghcr.io/astral-sh/ruff)
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+    needs:
+      - docker-publish-extra
+    if: ${{ inputs.plan != '' && !fromJson(inputs.plan).announcement_tag_is_implicit }}
+    steps:
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/digests
+          pattern: digests-*
+          merge-multiple: true
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        env:
+          DOCKER_METADATA_ANNOTATIONS_LEVELS: index
+        with:
+          images: ${{ env.RUFF_BASE_IMG }}
+          # Order is on purpose such that the label org.opencontainers.image.version has the first pattern with the full version
+          tags: |
+            type=pep440,pattern={{ version }},value=${{ fromJson(inputs.plan).announcement_tag }}
+            type=pep440,pattern={{ major }}.{{ minor }},value=${{ fromJson(inputs.plan).announcement_tag }}
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Adapted from https://docs.docker.com/build/ci/github-actions/multi-platform/
+      - name: Create manifest list and push
+        working-directory: /tmp/digests
+        # The readarray part is used to make sure the quoting and special characters are preserved on expansion (e.g. spaces)
+        # The jq command expands the docker/metadata json "tags" array entry to `-t tag1 -t tag2 ...` for each tag in the array
+        # The printf will expand the base image with the `<RUFF_BASE_IMG>@sha256:<sha256> ...` for each sha256 in the directory
+        # The final command becomes `docker buildx imagetools create -t tag1 -t tag2 ... <RUFF_BASE_IMG>@sha256:<sha256_1> <RUFF_BASE_IMG>@sha256:<sha256_2> ...`
+        run: |
+          readarray -t lines <<< "$DOCKER_METADATA_OUTPUT_ANNOTATIONS"; annotations=(); for line in "${lines[@]}"; do annotations+=(--annotation "$line"); done
+          docker buildx imagetools create \
+            "${annotations[@]}" \
+            $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ env.RUFF_BASE_IMG }}@sha256:%s ' *)

.github/workflows/ci.yaml

@@ -193,7 +193,7 @@ jobs:
         run: rustup target add wasm32-unknown-unknown
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           cache: "npm"
           cache-dependency-path: playground/package-lock.json
       - uses: jetli/wasm-pack-action@v0.4.0

.github/workflows/publish-playground.yml

@@ -29,7 +29,7 @@ jobs:
         run: rustup target add wasm32-unknown-unknown
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           cache: "npm"
           cache-dependency-path: playground/package-lock.json
       - uses: jetli/wasm-pack-action@v0.4.0
@@ -47,7 +47,7 @@ jobs:
         working-directory: playground
       - name: "Deploy to Cloudflare Pages"
         if: ${{ env.CF_API_TOKEN_EXISTS == 'true' }}
-        uses: cloudflare/wrangler-action@v3.7.0
+        uses: cloudflare/wrangler-action@v3.9.0
         with:
           apiToken: ${{ secrets.CF_API_TOKEN }}
           accountId: ${{ secrets.CF_ACCOUNT_ID }}

.github/workflows/publish-pypi.yml

@@ -21,14 +21,12 @@ jobs:
       # For PyPI's trusted publishing.
       id-token: write
     steps:
+      - name: "Install uv"
+        uses: astral-sh/setup-uv@v3
       - uses: actions/download-artifact@v4
         with:
           pattern: wheels-*
           path: wheels
           merge-multiple: true
       - name: Publish to PyPi
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          skip-existing: true
-          packages-dir: wheels
-          verbose: true
+        run: uv publish -v wheels/*

.github/workflows/publish-wasm.yml

@@ -43,7 +43,7 @@ jobs:
       - run: cp LICENSE crates/ruff_wasm/pkg # wasm-pack does not put the LICENSE file in the pkg
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           registry-url: "https://registry.npmjs.org"
       - name: "Publish (dry-run)"
         if: ${{ inputs.plan == '' || fromJson(inputs.plan).announcement_tag_is_implicit }}

.github/workflows/release.yml

@@ -202,46 +202,15 @@ jobs:
           name: artifacts-dist-manifest
           path: dist-manifest.json
 
-  custom-publish-pypi:
-    needs:
-      - plan
-      - host
-    if: ${{ !fromJson(needs.plan.outputs.val).announcement_is_prerelease || fromJson(needs.plan.outputs.val).publish_prereleases }}
-    uses: ./.github/workflows/publish-pypi.yml
-    with:
-      plan: ${{ needs.plan.outputs.val }}
-    secrets: inherit
-    # publish jobs get escalated permissions
-    permissions:
-      "id-token": "write"
-      "packages": "write"
-
-  custom-publish-wasm:
-    needs:
-      - plan
-      - host
-    if: ${{ !fromJson(needs.plan.outputs.val).announcement_is_prerelease || fromJson(needs.plan.outputs.val).publish_prereleases }}
-    uses: ./.github/workflows/publish-wasm.yml
-    with:
-      plan: ${{ needs.plan.outputs.val }}
-    secrets: inherit
-    # publish jobs get escalated permissions
-    permissions:
-      "contents": "read"
-      "id-token": "write"
-      "packages": "write"
-
   # Create a GitHub Release while uploading all files to it
   announce:
     needs:
       - plan
       - host
-      - custom-publish-pypi
-      - custom-publish-wasm
     # use "always() && ..." to allow us to wait for all publish jobs while
     # still allowing individual publish jobs to skip themselves (for prereleases).
     # "host" however must run to completion, no skipping allowed!
-    if: ${{ always() && needs.host.result == 'success' && (needs.custom-publish-pypi.result == 'skipped' || needs.custom-publish-pypi.result == 'success') && (needs.custom-publish-wasm.result == 'skipped' || needs.custom-publish-wasm.result == 'success') }}
+    if: ${{ always() && needs.host.result == 'success' }}
     runs-on: "ubuntu-20.04"
     env:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.pre-commit-config.yaml

@@ -1,4 +1,4 @@
-fail_fast: true
+fail_fast: false
 
 exclude: |
   (?x)^(
@@ -17,12 +17,12 @@ exclude: |
 
 repos:
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.20.2
+    rev: v0.21
     hooks:
       - id: validate-pyproject
 
   - repo: https://github.com/executablebooks/mdformat
-    rev: 0.7.17
+    rev: 0.7.18
     hooks:
       - id: mdformat
         additional_dependencies:
@@ -45,8 +45,17 @@ repos:
             | docs/\w+\.md
           )$
 
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.19.1
+    hooks:
+      - id: blacken-docs
+        args: ["--pyi", "--line-length", "130"]
+        files: '^crates/.*/resources/mdtest/.*\.md'
+        additional_dependencies:
+          - black==24.10.0
+
   - repo: https://github.com/crate-ci/typos
-    rev: v1.25.0
+    rev: v1.26.0
     hooks:
       - id: typos
 
@@ -60,7 +69,7 @@ repos:
         pass_filenames: false # This makes it a lot faster
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.9
+    rev: v0.7.0
     hooks:
       - id: ruff-format
       - id: ruff

BREAKING_CHANGES.md

@@ -1,5 +1,18 @@
 # Breaking Changes
 
+## 0.7.0
+
+- The pytest rules `PT001` and `PT023` now default to omitting the decorator parentheses when there are no arguments
+    ([#12838](https://github.com/astral-sh/ruff/pull/12838), [#13292](https://github.com/astral-sh/ruff/pull/13292)).
+    This was a change that we attempted to make in Ruff v0.6.0, but only partially made due to an error on our part.
+    See the [blog post](https://astral.sh/blog/ruff-v0.7.0) for more details.
+- The `useless-try-except` rule (in our `tryceratops` category) has been recoded from `TRY302` to
+    `TRY203` ([#13502](https://github.com/astral-sh/ruff/pull/13502)). This ensures Ruff's code is consistent with
+    the same rule in the [`tryceratops`](https://github.com/guilatrova/tryceratops) linter.
+- The `lint.allow-unused-imports` setting has been removed ([#13677](https://github.com/astral-sh/ruff/pull/13677)). Use
+    [`lint.pyflakes.allow-unused-imports`](https://docs.astral.sh/ruff/settings/#lint_pyflakes_allowed-unused-imports)
+    instead.
+
 ## 0.6.0
 
 - Detect imports in `src` layouts by default for `isort` rules ([#12848](https://github.com/astral-sh/ruff/pull/12848))

CHANGELOG.md

@@ -1,5 +1,103 @@
 # Changelog
 
+## 0.7.2
+
+### Preview features
+
+- Fix formatting of single with-item with trailing comment ([#14005](https://github.com/astral-sh/ruff/pull/14005))
+- \[`pyupgrade`\] Add PEP 646 `Unpack` conversion to `*` with fix (`UP044`) ([#13988](https://github.com/astral-sh/ruff/pull/13988))
+
+### Rule changes
+
+- Regenerate `known_stdlibs.rs` with stdlibs 2024.10.25 ([#13963](https://github.com/astral-sh/ruff/pull/13963))
+- \[`flake8-no-pep420`\] Skip namespace package enforcement for PEP 723 scripts (`INP001`) ([#13974](https://github.com/astral-sh/ruff/pull/13974))
+
+### Server
+
+- Fix server panic when undoing an edit ([#14010](https://github.com/astral-sh/ruff/pull/14010))
+
+### Bug fixes
+
+- Fix issues in discovering ruff in pip build environments ([#13881](https://github.com/astral-sh/ruff/pull/13881))
+- \[`flake8-type-checking`\] Fix false positive for `singledispatchmethod` (`TCH003`) ([#13941](https://github.com/astral-sh/ruff/pull/13941))
+- \[`flake8-type-checking`\] Treat return type of `singledispatch` as runtime-required (`TCH003`) ([#13957](https://github.com/astral-sh/ruff/pull/13957))
+
+### Documentation
+
+- \[`flake8-simplify`\] Include caveats of enabling `if-else-block-instead-of-if-exp` (`SIM108`) ([#14019](https://github.com/astral-sh/ruff/pull/14019))
+
+## 0.7.1
+
+### Preview features
+
+- Fix `E221` and `E222` to flag missing or extra whitespace around `==` operator ([#13890](https://github.com/astral-sh/ruff/pull/13890))
+- Formatter: Alternate quotes for strings inside f-strings in preview  ([#13860](https://github.com/astral-sh/ruff/pull/13860))
+- Formatter: Join implicit concatenated strings when they fit on a line ([#13663](https://github.com/astral-sh/ruff/pull/13663))
+- \[`pylint`\] Restrict `iteration-over-set` to only work on sets of literals (`PLC0208`) ([#13731](https://github.com/astral-sh/ruff/pull/13731))
+
+### Rule changes
+
+- \[`flake8-type-checking`\] Support auto-quoting when annotations contain quotes ([#11811](https://github.com/astral-sh/ruff/pull/11811))
+
+### Server
+
+- Avoid indexing the workspace for single-file mode ([#13770](https://github.com/astral-sh/ruff/pull/13770))
+
+### Bug fixes
+
+- Make `ARG002` compatible with `EM101` when raising `NotImplementedError` ([#13714](https://github.com/astral-sh/ruff/pull/13714))
+
+### Other changes
+
+- Introduce more Docker tags for Ruff (similar to uv) ([#13274](https://github.com/astral-sh/ruff/pull/13274))
+
+## 0.7.0
+
+Check out the [blog post](https://astral.sh/blog/ruff-v0.7.0) for a migration guide and overview of the changes!
+
+### Breaking changes
+
+- The pytest rules `PT001` and `PT023` now default to omitting the decorator parentheses when there are no arguments
+    ([#12838](https://github.com/astral-sh/ruff/pull/12838), [#13292](https://github.com/astral-sh/ruff/pull/13292)).
+    This was a change that we attempted to make in Ruff v0.6.0, but only partially made due to an error on our part.
+    See the [blog post](https://astral.sh/blog/ruff-v0.7.0) for more details.
+- The `useless-try-except` rule (in our `tryceratops` category) has been recoded from `TRY302` to
+    `TRY203` ([#13502](https://github.com/astral-sh/ruff/pull/13502)). This ensures Ruff's code is consistent with
+    the same rule in the [`tryceratops`](https://github.com/guilatrova/tryceratops) linter.
+- The `lint.allow-unused-imports` setting has been removed ([#13677](https://github.com/astral-sh/ruff/pull/13677)). Use
+    [`lint.pyflakes.allow-unused-imports`](https://docs.astral.sh/ruff/settings/#lint_pyflakes_allowed-unused-imports)
+    instead.
+
+### Formatter preview style
+
+- Normalize implicit concatenated f-string quotes per part ([#13539](https://github.com/astral-sh/ruff/pull/13539))
+
+### Preview linter features
+
+- \[`refurb`\] implement `hardcoded-string-charset` (FURB156) ([#13530](https://github.com/astral-sh/ruff/pull/13530))
+- \[`refurb`\] Count codepoints not bytes for `slice-to-remove-prefix-or-suffix (FURB188)` ([#13631](https://github.com/astral-sh/ruff/pull/13631))
+
+### Rule changes
+
+- \[`pylint`\] Mark `PLE1141` fix as unsafe ([#13629](https://github.com/astral-sh/ruff/pull/13629))
+- \[`flake8-async`\] Consider async generators to be "checkpoints" for `cancel-scope-no-checkpoint` (`ASYNC100`) ([#13639](https://github.com/astral-sh/ruff/pull/13639))
+- \[`flake8-bugbear`\] Do not suggest setting parameter `strict=` to `False` in `B905` diagnostic message ([#13656](https://github.com/astral-sh/ruff/pull/13656))
+- \[`flake8-todos`\] Only flag the word "TODO", not words starting with "todo" (`TD006`) ([#13640](https://github.com/astral-sh/ruff/pull/13640))
+- \[`pycodestyle`\] Fix whitespace-related false positives and false negatives inside type-parameter lists (`E231`, `E251`) ([#13704](https://github.com/astral-sh/ruff/pull/13704))
+- \[`flake8-simplify`\] Stabilize preview behavior for `SIM115` so that the rule can detect files
+    being opened from a wider range of standard-library functions ([#12959](https://github.com/astral-sh/ruff/pull/12959)).
+
+### CLI
+
+- Add explanation of fixable in `--statistics` command ([#13774](https://github.com/astral-sh/ruff/pull/13774))
+
+### Bug fixes
+
+- \[`pyflakes`\] Allow `ipytest` cell magic (`F401`) ([#13745](https://github.com/astral-sh/ruff/pull/13745))
+- \[`flake8-use-pathlib`\] Fix `PTH123` false positive when `open` is passed a file descriptor ([#13616](https://github.com/astral-sh/ruff/pull/13616))
+- \[`flake8-bandit`\] Detect patterns from multi line SQL statements (`S608`) ([#13574](https://github.com/astral-sh/ruff/pull/13574))
+- \[`flake8-pyi`\] - Fix dropped expressions in `PYI030` autofix ([#13727](https://github.com/astral-sh/ruff/pull/13727))
+
 ## 0.6.9
 
 ### Preview features

Cargo.lock

@@ -69,7 +69,7 @@ version = "0.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ccaf7e9dfbb6ab22c82e473cd1a8a7bd313c19a5b7e40970f3d89ef5a5c9e81e"
 dependencies = [
- "unicode-width",
+ "unicode-width 0.1.13",
  "yansi-term",
 ]
 
@@ -123,9 +123,9 @@ dependencies = [
 
 [[package]]
 name = "anyhow"
-version = "1.0.89"
+version = "1.0.91"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "86fdf8605db99b54d3cd748a44c6d04df638eb5dafb219b135d0149bd0db01f6"
+checksum = "c042108f3ed77fd83760a5fd79b53be043192bb3b9dba91d8c574c0ada7850c8"
 
 [[package]]
 name = "append-only-vec"
@@ -407,7 +407,7 @@ dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -491,7 +491,7 @@ dependencies = [
  "encode_unicode",
  "lazy_static",
  "libc",
- "unicode-width",
+ "unicode-width 0.1.13",
  "windows-sys 0.52.0",
 ]
 
@@ -687,7 +687,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "strsim 0.10.0",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -698,7 +698,7 @@ checksum = "a668eda54683121533a393014d8692171709ff57a7d61f187b6e782719f8933f"
 dependencies = [
  "darling_core",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -750,6 +750,27 @@ dependencies = [
  "crypto-common",
 ]
 
+[[package]]
+name = "dir-test"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c44bdf9319ad5223afb7eb15a7110452b0adf0373ea6756561b2c708eef0dd1"
+dependencies = [
+ "dir-test-macros",
+]
+
+[[package]]
+name = "dir-test-macros"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "644f96047137dfaa7a09e34d4623f9e52a1926ecc25ba32ad2ba3fc422536b25"
+dependencies = [
+ "glob",
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+]
+
 [[package]]
 name = "dirs"
 version = "4.0.0"
@@ -879,9 +900,9 @@ checksum = "e8c02a5121d4ea3eb16a80748c74f5549a5665e4c21333c6098f283870fbdea6"
 
 [[package]]
 name = "fern"
-version = "0.6.2"
+version = "0.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d9f0c14694cbd524c8720dd69b0e3179344f04ebb5f90f2e4a440c6ea3b2f1ee"
+checksum = "69ff9c9d5fb3e6da8ac2f77ab76fe7e8087d512ce095200f8f29ac5b656cf6dc"
 dependencies = [
  "log",
 ]
@@ -957,7 +978,7 @@ version = "0.2.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "14dbbfd5c71d70241ecf9e6f13737f7b5ce823821063188d7e46c41d371eebd5"
 dependencies = [
- "unicode-width",
+ "unicode-width 0.1.13",
 ]
 
 [[package]]
@@ -1160,7 +1181,7 @@ dependencies = [
  "instant",
  "number_prefix",
  "portable-atomic",
- "unicode-width",
+ "unicode-width 0.1.13",
  "vt100",
 ]
 
@@ -1192,9 +1213,9 @@ dependencies = [
 
 [[package]]
 name = "insta"
-version = "1.40.0"
+version = "1.41.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6593a41c7a73841868772495db7dc1e8ecab43bb5c0b6da2059246c4b506ab60"
+checksum = "a1f72d3e19488cf7d8ea52d2fc0f8754fc933398b337cd3cbdb28aaeb35159ef"
 dependencies = [
  "console",
  "globset",
@@ -1246,7 +1267,7 @@ dependencies = [
  "Inflector",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -1346,9 +1367,9 @@ checksum = "e2abad23fbc42b3700f2f279844dc832adb2b2eb069b2df918f455c4e18cc646"
 
 [[package]]
 name = "libc"
-version = "0.2.159"
+version = "0.2.161"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "561d97a539a36e26a9a5fad1ea11a3039a67714694aaa379433e580854bc3dc5"
+checksum = "8e9489c2807c139ffd9c1794f4af0ebe86a828db53ecdc7fea2111d0fed085d1"
 
 [[package]]
 name = "libcst"
@@ -1372,7 +1393,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a2ae40017ac09cd2c6a53504cb3c871c7f2b41466eac5bc66ba63f39073b467b"
 dependencies = [
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -1760,18 +1781,17 @@ dependencies = [
  "once_cell",
  "regex",
  "serde",
- "unicode-width",
+ "unicode-width 0.1.13",
 ]
 
 [[package]]
 name = "pep440_rs"
-version = "0.6.6"
+version = "0.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "466eada3179c2e069ca897b99006cbb33f816290eaeec62464eea907e22ae385"
+checksum = "7c8ee724d21f351f9d47276614ac9710975db827ba9fe2ca5a517ba648193307"
 dependencies = [
- "once_cell",
  "serde",
- "unicode-width",
+ "unicode-width 0.2.0",
  "unscanny",
 ]
 
@@ -1787,7 +1807,7 @@ dependencies = [
  "serde",
  "thiserror",
  "tracing",
- "unicode-width",
+ "unicode-width 0.1.13",
  "url",
 ]
 
@@ -1828,7 +1848,7 @@ dependencies = [
  "pest_meta",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -1943,9 +1963,9 @@ dependencies = [
 
 [[package]]
 name = "proc-macro2"
-version = "1.0.87"
+version = "1.0.89"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b3e4daa0dcf6feba26f985457cdf104d4b4256fc5a09547140f3631bb076b19a"
+checksum = "f139b0662de085916d1fb67d2b4169d1addddda1919e696f3252b740b629986e"
 dependencies = [
  "unicode-ident",
 ]
@@ -2080,13 +2100,14 @@ dependencies = [
  "camino",
  "compact_str",
  "countme",
+ "dir-test",
  "hashbrown 0.15.0",
  "insta",
  "itertools 0.13.0",
+ "memchr",
  "ordermap",
  "red_knot_test",
  "red_knot_vendored",
- "rstest",
  "ruff_db",
  "ruff_index",
  "ruff_python_ast",
@@ -2135,7 +2156,7 @@ version = "0.0.0"
 dependencies = [
  "anyhow",
  "colored",
- "once_cell",
+ "memchr",
  "red_knot_python_semantic",
  "red_knot_vendored",
  "regex",
@@ -2153,7 +2174,6 @@ dependencies = [
 name = "red_knot_vendored"
 version = "0.0.0"
 dependencies = [
- "once_cell",
  "path-slash",
  "ruff_db",
  "walkdir",
@@ -2227,9 +2247,9 @@ dependencies = [
 
 [[package]]
 name = "regex"
-version = "1.11.0"
+version = "1.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "38200e5ee88914975b69f657f0801b6f6dccafd44fd9326302a4aaeecfacb1d8"
+checksum = "b544ef1b4eac5dc2db33ea63606ae9ffcfac26c1416a2806ae0bf5f56b201191"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -2269,12 +2289,6 @@ version = "0.8.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2b15c43186be67a4fd63bee50d0303afffcef381492ebe2c5d87f324e1b8815c"
 
-[[package]]
-name = "relative-path"
-version = "1.9.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ba39f3699c378cd8970968dcbff9c43159ea4cfbd88d43c00b22f2ef10a435d2"
-
 [[package]]
 name = "ring"
 version = "0.17.8"
@@ -2290,36 +2304,9 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
-[[package]]
-name = "rstest"
-version = "0.22.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7b423f0e62bdd61734b67cd21ff50871dfaeb9cc74f869dcd6af974fbcb19936"
-dependencies = [
- "rstest_macros",
- "rustc_version",
-]
-
-[[package]]
-name = "rstest_macros"
-version = "0.22.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c5e1711e7d14f74b12a58411c542185ef7fb7f2e7f8ee6e2940a883628522b42"
-dependencies = [
- "cfg-if",
- "glob",
- "proc-macro2",
- "quote",
- "regex",
- "relative-path",
- "rustc_version",
- "syn",
- "unicode-ident",
-]
-
 [[package]]
 name = "ruff"
-version = "0.6.9"
+version = "0.7.2"
 dependencies = [
  "anyhow",
  "argfile",
@@ -2381,7 +2368,6 @@ dependencies = [
  "codspeed-criterion-compat",
  "criterion",
  "mimalloc",
- "once_cell",
  "rayon",
  "red_knot_python_semantic",
  "red_knot_workspace",
@@ -2505,7 +2491,7 @@ dependencies = [
  "serde",
  "static_assertions",
  "tracing",
- "unicode-width",
+ "unicode-width 0.1.13",
 ]
 
 [[package]]
@@ -2514,7 +2500,6 @@ version = "0.1.0"
 dependencies = [
  "anyhow",
  "clap",
- "once_cell",
  "red_knot_python_semantic",
  "ruff_cache",
  "ruff_db",
@@ -2538,7 +2523,7 @@ dependencies = [
 
 [[package]]
 name = "ruff_linter"
-version = "0.6.9"
+version = "0.7.2"
 dependencies = [
  "aho-corasick",
  "annotate-snippets 0.9.2",
@@ -2559,10 +2544,9 @@ dependencies = [
  "log",
  "memchr",
  "natord",
- "once_cell",
  "path-absolutize",
  "pathdiff",
- "pep440_rs 0.6.6",
+ "pep440_rs 0.7.1",
  "pyproject-toml",
  "quick-junit",
  "regex",
@@ -2593,7 +2577,7 @@ dependencies = [
  "toml",
  "typed-arena",
  "unicode-normalization",
- "unicode-width",
+ "unicode-width 0.1.13",
  "unicode_names2",
  "url",
 ]
@@ -2606,7 +2590,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "ruff_python_trivia",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -2615,7 +2599,6 @@ version = "0.0.0"
 dependencies = [
  "anyhow",
  "itertools 0.13.0",
- "once_cell",
  "rand",
  "ruff_diagnostics",
  "ruff_source_file",
@@ -2637,7 +2620,7 @@ dependencies = [
  "compact_str",
  "is-macro",
  "itertools 0.13.0",
- "once_cell",
+ "memchr",
  "ruff_cache",
  "ruff_macros",
  "ruff_python_trivia",
@@ -2663,7 +2646,6 @@ dependencies = [
 name = "ruff_python_codegen"
 version = "0.0.0"
 dependencies = [
- "once_cell",
  "ruff_python_ast",
  "ruff_python_literal",
  "ruff_python_parser",
@@ -2681,7 +2663,6 @@ dependencies = [
  "insta",
  "itertools 0.13.0",
  "memchr",
- "once_cell",
  "regex",
  "ruff_cache",
  "ruff_formatter",
@@ -2768,7 +2749,6 @@ dependencies = [
  "ruff_python_ast",
  "ruff_python_parser",
  "ruff_python_stdlib",
- "ruff_source_file",
  "ruff_text_size",
  "rustc-hash 2.0.0",
  "schemars",
@@ -2799,7 +2779,6 @@ dependencies = [
  "insta",
  "ruff_python_parser",
  "ruff_python_trivia",
- "ruff_source_file",
  "ruff_text_size",
 ]
 
@@ -2832,6 +2811,7 @@ dependencies = [
  "serde",
  "serde_json",
  "shellexpand",
+ "thiserror",
  "tracing",
  "tracing-subscriber",
 ]
@@ -2841,7 +2821,6 @@ name = "ruff_source_file"
 version = "0.0.0"
 dependencies = [
  "memchr",
- "once_cell",
  "ruff_text_size",
  "serde",
 ]
@@ -2858,7 +2837,7 @@ dependencies = [
 
 [[package]]
 name = "ruff_wasm"
-version = "0.6.9"
+version = "0.7.2"
 dependencies = [
  "console_error_panic_hook",
  "console_log",
@@ -2897,7 +2876,7 @@ dependencies = [
  "matchit",
  "path-absolutize",
  "path-slash",
- "pep440_rs 0.6.6",
+ "pep440_rs 0.7.1",
  "regex",
  "ruff_cache",
  "ruff_formatter",
@@ -2939,15 +2918,6 @@ version = "2.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "583034fd73374156e66797ed8e5b0d5690409c9226b22d87cb7f19821c05d152"
 
-[[package]]
-name = "rustc_version"
-version = "0.4.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92"
-dependencies = [
- "semver",
-]
-
 [[package]]
 name = "rustix"
 version = "0.38.37"
@@ -3008,7 +2978,7 @@ checksum = "e86697c916019a8588c99b5fac3cead74ec0b4b819707a682fd4d23fa0ce1ba1"
 [[package]]
 name = "salsa"
 version = "0.18.0"
-source = "git+https://github.com/salsa-rs/salsa.git?rev=4a7c955255e707e64e43f3ce5eabb771ae067768#4a7c955255e707e64e43f3ce5eabb771ae067768"
+source = "git+https://github.com/salsa-rs/salsa.git?rev=254c749b02cde2fd29852a7463a33e800b771758#254c749b02cde2fd29852a7463a33e800b771758"
 dependencies = [
  "append-only-vec",
  "arc-swap",
@@ -3028,17 +2998,17 @@ dependencies = [
 [[package]]
 name = "salsa-macro-rules"
 version = "0.1.0"
-source = "git+https://github.com/salsa-rs/salsa.git?rev=4a7c955255e707e64e43f3ce5eabb771ae067768#4a7c955255e707e64e43f3ce5eabb771ae067768"
+source = "git+https://github.com/salsa-rs/salsa.git?rev=254c749b02cde2fd29852a7463a33e800b771758#254c749b02cde2fd29852a7463a33e800b771758"
 
 [[package]]
 name = "salsa-macros"
 version = "0.18.0"
-source = "git+https://github.com/salsa-rs/salsa.git?rev=4a7c955255e707e64e43f3ce5eabb771ae067768#4a7c955255e707e64e43f3ce5eabb771ae067768"
+source = "git+https://github.com/salsa-rs/salsa.git?rev=254c749b02cde2fd29852a7463a33e800b771758#254c749b02cde2fd29852a7463a33e800b771758"
 dependencies = [
  "heck",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
  "synstructure",
 ]
 
@@ -3072,7 +3042,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "serde_derive_internals",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -3093,17 +3063,11 @@ version = "4.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1c107b6f4780854c8b126e228ea8869f4d7b71260f962fefb57b996b8959ba6b"
 
-[[package]]
-name = "semver"
-version = "1.0.23"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "61697e0a1c7e512e84a621326239844a24d8207b4669b41bc18b32ea5cbf988b"
-
 [[package]]
 name = "serde"
-version = "1.0.210"
+version = "1.0.213"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c8e3592472072e6e22e0a54d5904d9febf8508f65fb8552499a1abc7d1078c3a"
+checksum = "3ea7893ff5e2466df8d720bb615088341b295f849602c6956047f8f80f0e9bc1"
 dependencies = [
  "serde_derive",
 ]
@@ -3121,13 +3085,13 @@ dependencies = [
 
 [[package]]
 name = "serde_derive"
-version = "1.0.210"
+version = "1.0.213"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "243902eda00fad750862fc144cea25caca5e20d615af0a81bee94ca738f1df1f"
+checksum = "7e85ad2009c50b58e87caa8cd6dac16bdf511bbfb7af6c33df902396aa480fa5"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -3138,14 +3102,14 @@ checksum = "330f01ce65a3a5fe59a60c82f3c9a024b573b8a6e875bd233fe5f934e71d54e3"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
 name = "serde_json"
-version = "1.0.128"
+version = "1.0.132"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6ff5456707a1de34e7e37f2a6fd3d3f808c318259cbd01ab6377795054b483d8"
+checksum = "d726bfaff4b320266d395898905d0eba0345aae23b54aee3a737e260fd46db03"
 dependencies = [
  "itoa",
  "memchr",
@@ -3161,7 +3125,7 @@ checksum = "6c64451ba24fc7a6a2d60fc75dd9c83c90903b19028d4eff35e88fc1e86564e9"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -3202,7 +3166,7 @@ dependencies = [
  "darling",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -3304,7 +3268,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "rustversion",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -3315,9 +3279,20 @@ checksum = "81cdd64d312baedb58e21336b31bc043b77e01cc99033ce76ef539f78e965ebc"
 
 [[package]]
 name = "syn"
-version = "2.0.79"
+version = "1.0.109"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "89132cd0bf050864e1d38dc3bbc07a0eb8e7530af26344d3d2bbbef83499f590"
+checksum = "72b64191b275b66ffe2469e8af2c1cfe3bafa67b529ead792a6d0160888b4237"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.85"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5023162dfcd14ef8f32034d8bcd4cc5ddc61ef7a247c024a33e24e1f24d21b56"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -3332,7 +3307,7 @@ checksum = "c8af7666ab7b6390ab78131fb5b0fce11d6b7a6951602017c35fa82800708971"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -3395,7 +3370,7 @@ dependencies = [
  "cfg-if",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -3406,28 +3381,28 @@ checksum = "5c89e72a01ed4c579669add59014b9a524d609c0c88c6a585ce37485879f6ffb"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
  "test-case-core",
 ]
 
 [[package]]
 name = "thiserror"
-version = "1.0.64"
+version = "1.0.65"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d50af8abc119fb8bb6dbabcfa89656f46f84aa0ac7688088608076ad2b459a84"
+checksum = "5d11abd9594d9b38965ef50805c5e469ca9cc6f197f883f717e0269a3057b3d5"
 dependencies = [
  "thiserror-impl",
 ]
 
 [[package]]
 name = "thiserror-impl"
-version = "1.0.64"
+version = "1.0.65"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "08904e7672f5eb876eaaf87e0ce17857500934f4981c4a0ab2b4aa98baac7fc3"
+checksum = "ae71770322cbd277e69d762a16c444af02aa0575ac0d174f0b9562d3b37f8602"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -3539,7 +3514,7 @@ checksum = "34704c8d6ebcbc939824180af020566b01a7c01f80641264eba0999f6c2b6be7"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -3703,6 +3678,12 @@ version = "0.1.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0336d538f7abc86d282a4189614dfaa90810dfc2c6f6427eaf88e16311dd225d"
 
+[[package]]
+name = "unicode-width"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fc81956842c57dac11422a97c3b8195a1ff727f06e85c84ed2e8aa277c9a0fd"
+
 [[package]]
 name = "unicode_names2"
 version = "1.3.0"
@@ -3773,9 +3754,9 @@ checksum = "711b9620af191e0cdc7468a8d14e709c3dcdb115b36f838e601583af800a370a"
 
 [[package]]
 name = "uuid"
-version = "1.10.0"
+version = "1.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "81dfa00651efa65069b0b6b651f4aaa31ba9e3c3ce0137aaad053604ee7e0314"
+checksum = "f8c5f0a0af699448548ad1a2fbf920fb4bee257eae39953ba95cb84891a0446a"
 dependencies = [
  "getrandom",
  "rand",
@@ -3785,13 +3766,13 @@ dependencies = [
 
 [[package]]
 name = "uuid-macro-internal"
-version = "1.10.0"
+version = "1.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ee1cd046f83ea2c4e920d6ee9f7c3537ef928d75dce5d84a87c2c5d6b3999a3a"
+checksum = "6b91f57fe13a38d0ce9e28a03463d8d3c2468ed03d75375110ec71d93b449a08"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -3814,7 +3795,7 @@ checksum = "84cd863bf0db7e392ba3bd04994be3473491b31e66340672af5d11943c6274de"
 dependencies = [
  "itoa",
  "log",
- "unicode-width",
+ "unicode-width 0.1.13",
  "vte",
 ]
 
@@ -3877,7 +3858,7 @@ dependencies = [
  "once_cell",
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
  "wasm-bindgen-shared",
 ]
 
@@ -3911,7 +3892,7 @@ checksum = "26c6ab57572f7a24a4985830b120de1594465e5d500f24afe89e16b4e833ef68"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
  "wasm-bindgen-backend",
  "wasm-bindgen-shared",
 ]
@@ -3945,7 +3926,7 @@ checksum = "c97b2ef2c8d627381e51c071c2ab328eac606d3f69dd82bcbca20a9e389d95f0"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]
@@ -4233,7 +4214,7 @@ checksum = "9ce1b18ccd8e73a9321186f97e46f9f04b778851177567b1975109d26a08d2a6"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn",
+ "syn 2.0.85",
 ]
 
 [[package]]

Cargo.toml

@@ -4,7 +4,7 @@ resolver = "2"
 
 [workspace.package]
 edition = "2021"
-rust-version = "1.76"
+rust-version = "1.80"
 homepage = "https://docs.astral.sh/ruff"
 documentation = "https://docs.astral.sh/ruff"
 repository = "https://github.com/astral-sh/ruff"
@@ -65,10 +65,11 @@ compact_str = "0.8.0"
 criterion = { version = "0.5.1", default-features = false }
 crossbeam = { version = "0.8.4" }
 dashmap = { version = "6.0.1" }
+dir-test = { version = "0.3.0" }
 drop_bomb = { version = "0.1.5" }
 env_logger = { version = "0.11.0" }
 etcetera = { version = "0.8.0" }
-fern = { version = "0.6.1" }
+fern = { version = "0.7.0" }
 filetime = { version = "0.2.23" }
 glob = { version = "0.3.1" }
 globset = { version = "0.4.14" }
@@ -101,12 +102,11 @@ memchr = { version = "2.7.1" }
 mimalloc = { version = "0.1.39" }
 natord = { version = "1.0.9" }
 notify = { version = "6.1.1" }
-once_cell = { version = "1.19.0" }
 ordermap = { version = "0.5.0" }
 path-absolutize = { version = "3.1.1" }
 path-slash = { version = "0.2.1" }
 pathdiff = { version = "0.2.1" }
-pep440_rs = { version = "0.6.0", features = ["serde"] }
+pep440_rs = { version = "0.7.1" }
 pretty_assertions = "1.3.0"
 proc-macro2 = { version = "1.0.79" }
 pyproject-toml = { version = "0.9.0" }
@@ -115,9 +115,8 @@ quote = { version = "1.0.23" }
 rand = { version = "0.8.5" }
 rayon = { version = "1.10.0" }
 regex = { version = "1.10.2" }
-rstest = { version = "0.22.0", default-features = false }
 rustc-hash = { version = "2.0.0" }
-salsa = { git = "https://github.com/salsa-rs/salsa.git", rev = "4a7c955255e707e64e43f3ce5eabb771ae067768" }
+salsa = { git = "https://github.com/salsa-rs/salsa.git", rev = "254c749b02cde2fd29852a7463a33e800b771758" }
 schemars = { version = "0.8.16" }
 seahash = { version = "4.1.0" }
 serde = { version = "1.0.197", features = ["derive"] }
@@ -189,8 +188,9 @@ missing_panics_doc = "allow"
 module_name_repetitions = "allow"
 must_use_candidate = "allow"
 similar_names = "allow"
+single_match_else = "allow"
 too_many_lines = "allow"
-# To allow `#[allow(clippy::all)]` in `crates/ruff_python_parser/src/python.rs`.
+# Without the hashes we run into a `rustfmt` bug in some snapshot tests, see #13250
 needless_raw_string_hashes = "allow"
 # Disallowed restriction lints
 print_stdout = "warn"
@@ -203,6 +203,10 @@ get_unwrap = "warn"
 rc_buffer = "warn"
 rc_mutex = "warn"
 rest_pat_in_fully_bound_structs = "warn"
+# nursery rules
+redundant_clone = "warn"
+debug_assert_with_mut_call = "warn"
+unused_peekable = "warn"
 
 [profile.release]
 # Note that we set these explicitly, and these values
@@ -289,7 +293,7 @@ build-local-artifacts = false
 # Local artifacts jobs to run in CI
 local-artifacts-jobs = ["./build-binaries", "./build-docker"]
 # Publish jobs to run in CI
-publish-jobs = ["./publish-pypi", "./publish-wasm"]
+# publish-jobs = ["./publish-pypi", "./publish-wasm"]
 # Post-announce jobs to run in CI
 post-announce-jobs = [
     "./notify-dependents",

Dockerfile

@@ -1,4 +1,4 @@
-FROM --platform=$BUILDPLATFORM ubuntu as build
+FROM --platform=$BUILDPLATFORM ubuntu AS build
 ENV HOME="/root"
 WORKDIR $HOME
 

README.md

@@ -136,8 +136,8 @@ curl -LsSf https://astral.sh/ruff/install.sh | sh
 powershell -c "irm https://astral.sh/ruff/install.ps1 | iex"
 
 # For a specific version.
-curl -LsSf https://astral.sh/ruff/0.6.9/install.sh | sh
-powershell -c "irm https://astral.sh/ruff/0.6.9/install.ps1 | iex"
+curl -LsSf https://astral.sh/ruff/0.7.2/install.sh | sh
+powershell -c "irm https://astral.sh/ruff/0.7.2/install.ps1 | iex"
 ```
 
 You can also install Ruff via [Homebrew](https://formulae.brew.sh/formula/ruff), [Conda](https://anaconda.org/conda-forge/ruff),
@@ -170,7 +170,7 @@ Ruff can also be used as a [pre-commit](https://pre-commit.com/) hook via [`ruff
 ```yaml
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.6.9
+  rev: v0.7.2
   hooks:
     # Run the linter.
     - id: ruff
@@ -417,6 +417,7 @@ Ruff is used by a number of major open-source projects and companies, including:
 - [Babel](https://github.com/python-babel/babel)
 - Benchling ([Refac](https://github.com/benchling/refac))
 - [Bokeh](https://github.com/bokeh/bokeh)
+- CrowdCent ([NumerBlox](https://github.com/crowdcent/numerblox)) <!-- typos: ignore -->
 - [Cryptography (PyCA)](https://github.com/pyca/cryptography)
 - CERN ([Indico](https://getindico.io/))
 - [DVC](https://github.com/iterative/dvc)

_typos.toml

@@ -12,6 +12,7 @@ pn = "pn"  # `import panel as pn` is a thing
 poit = "poit"
 BA = "BA" # acronym for "Bad Allowed", used in testing.
 jod = "jod" # e.g., `jod-thread`
+Numer = "Numer" # Library name 'NumerBlox' in "Who's Using Ruff?"
 
 [default]
 extend-ignore-re = [

crates/red_knot/src/main.rs

@@ -144,7 +144,7 @@ pub fn main() -> ExitStatus {
 }
 
 fn run() -> anyhow::Result<ExitStatus> {
-    let args = Args::parse_from(std::env::args().collect::<Vec<_>>());
+    let args = Args::parse_from(std::env::args());
 
     if matches!(args.command, Some(Command::Server)) {
         return run_server().map(|()| ExitStatus::Success);

crates/red_knot/tests/file_watching.rs

@@ -501,7 +501,10 @@ fn directory_moved_to_workspace() -> anyhow::Result<()> {
         .with_context(|| "Failed to create __init__.py")?;
     std::fs::write(a_original_path.as_std_path(), "").with_context(|| "Failed to create a.py")?;
 
-    let sub_a_module = resolve_module(case.db().upcast(), ModuleName::new_static("sub.a").unwrap());
+    let sub_a_module = resolve_module(
+        case.db().upcast(),
+        &ModuleName::new_static("sub.a").unwrap(),
+    );
 
     assert_eq!(sub_a_module, None);
     assert_eq!(
@@ -525,7 +528,11 @@ fn directory_moved_to_workspace() -> anyhow::Result<()> {
         .expect("a.py to exist");
 
     // `import sub.a` should now resolve
-    assert!(resolve_module(case.db().upcast(), ModuleName::new_static("sub.a").unwrap()).is_some());
+    assert!(resolve_module(
+        case.db().upcast(),
+        &ModuleName::new_static("sub.a").unwrap()
+    )
+    .is_some());
 
     assert_eq!(
         case.collect_package_files(&case.workspace_path("bar.py")),
@@ -544,7 +551,11 @@ fn directory_moved_to_trash() -> anyhow::Result<()> {
     ])?;
     let bar = case.system_file(case.workspace_path("bar.py")).unwrap();
 
-    assert!(resolve_module(case.db().upcast(), ModuleName::new_static("sub.a").unwrap()).is_some());
+    assert!(resolve_module(
+        case.db().upcast(),
+        &ModuleName::new_static("sub.a").unwrap()
+    )
+    .is_some());
 
     let sub_path = case.workspace_path("sub");
     let init_file = case
@@ -569,7 +580,11 @@ fn directory_moved_to_trash() -> anyhow::Result<()> {
     case.apply_changes(changes);
 
     // `import sub.a` should no longer resolve
-    assert!(resolve_module(case.db().upcast(), ModuleName::new_static("sub.a").unwrap()).is_none());
+    assert!(resolve_module(
+        case.db().upcast(),
+        &ModuleName::new_static("sub.a").unwrap()
+    )
+    .is_none());
 
     assert!(!init_file.exists(case.db()));
     assert!(!a_file.exists(case.db()));
@@ -592,10 +607,14 @@ fn directory_renamed() -> anyhow::Result<()> {
 
     let bar = case.system_file(case.workspace_path("bar.py")).unwrap();
 
-    assert!(resolve_module(case.db().upcast(), ModuleName::new_static("sub.a").unwrap()).is_some());
     assert!(resolve_module(
         case.db().upcast(),
-        ModuleName::new_static("foo.baz").unwrap()
+        &ModuleName::new_static("sub.a").unwrap()
+    )
+    .is_some());
+    assert!(resolve_module(
+        case.db().upcast(),
+        &ModuleName::new_static("foo.baz").unwrap()
     )
     .is_none());
 
@@ -623,11 +642,15 @@ fn directory_renamed() -> anyhow::Result<()> {
     case.apply_changes(changes);
 
     // `import sub.a` should no longer resolve
-    assert!(resolve_module(case.db().upcast(), ModuleName::new_static("sub.a").unwrap()).is_none());
+    assert!(resolve_module(
+        case.db().upcast(),
+        &ModuleName::new_static("sub.a").unwrap()
+    )
+    .is_none());
     // `import foo.baz` should now resolve
     assert!(resolve_module(
         case.db().upcast(),
-        ModuleName::new_static("foo.baz").unwrap()
+        &ModuleName::new_static("foo.baz").unwrap()
     )
     .is_some());
 
@@ -665,7 +688,11 @@ fn directory_deleted() -> anyhow::Result<()> {
 
     let bar = case.system_file(case.workspace_path("bar.py")).unwrap();
 
-    assert!(resolve_module(case.db().upcast(), ModuleName::new_static("sub.a").unwrap()).is_some());
+    assert!(resolve_module(
+        case.db().upcast(),
+        &ModuleName::new_static("sub.a").unwrap()
+    )
+    .is_some());
 
     let sub_path = case.workspace_path("sub");
 
@@ -688,7 +715,11 @@ fn directory_deleted() -> anyhow::Result<()> {
     case.apply_changes(changes);
 
     // `import sub.a` should no longer resolve
-    assert!(resolve_module(case.db().upcast(), ModuleName::new_static("sub.a").unwrap()).is_none());
+    assert!(resolve_module(
+        case.db().upcast(),
+        &ModuleName::new_static("sub.a").unwrap()
+    )
+    .is_none());
 
     assert!(!init_file.exists(case.db()));
     assert!(!a_file.exists(case.db()));
@@ -710,7 +741,7 @@ fn search_path() -> anyhow::Result<()> {
     let site_packages = case.root_path().join("site_packages");
 
     assert_eq!(
-        resolve_module(case.db(), ModuleName::new("a").unwrap()),
+        resolve_module(case.db(), &ModuleName::new("a").unwrap()),
         None
     );
 
@@ -720,7 +751,7 @@ fn search_path() -> anyhow::Result<()> {
 
     case.apply_changes(changes);
 
-    assert!(resolve_module(case.db().upcast(), ModuleName::new_static("a").unwrap()).is_some());
+    assert!(resolve_module(case.db().upcast(), &ModuleName::new_static("a").unwrap()).is_some());
     assert_eq!(
         case.collect_package_files(&case.workspace_path("bar.py")),
         &[case.system_file(case.workspace_path("bar.py")).unwrap()]
@@ -736,7 +767,7 @@ fn add_search_path() -> anyhow::Result<()> {
     let site_packages = case.workspace_path("site_packages");
     std::fs::create_dir_all(site_packages.as_std_path())?;
 
-    assert!(resolve_module(case.db().upcast(), ModuleName::new_static("a").unwrap()).is_none());
+    assert!(resolve_module(case.db().upcast(), &ModuleName::new_static("a").unwrap()).is_none());
 
     // Register site-packages as a search path.
     case.update_search_path_settings(SearchPathConfiguration {
@@ -751,7 +782,7 @@ fn add_search_path() -> anyhow::Result<()> {
 
     case.apply_changes(changes);
 
-    assert!(resolve_module(case.db().upcast(), ModuleName::new_static("a").unwrap()).is_some());
+    assert!(resolve_module(case.db().upcast(), &ModuleName::new_static("a").unwrap()).is_some());
 
     Ok(())
 }
@@ -805,7 +836,7 @@ fn changed_versions_file() -> anyhow::Result<()> {
 
     // Unset the custom typeshed directory.
     assert_eq!(
-        resolve_module(case.db(), ModuleName::new("os").unwrap()),
+        resolve_module(case.db(), &ModuleName::new("os").unwrap()),
         None
     );
 
@@ -820,7 +851,7 @@ fn changed_versions_file() -> anyhow::Result<()> {
 
     case.apply_changes(changes);
 
-    assert!(resolve_module(case.db(), ModuleName::new("os").unwrap()).is_some());
+    assert!(resolve_module(case.db(), &ModuleName::new("os").unwrap()).is_some());
 
     Ok(())
 }
@@ -1044,7 +1075,7 @@ mod unix {
 
         let baz = resolve_module(
             case.db().upcast(),
-            ModuleName::new_static("bar.baz").unwrap(),
+            &ModuleName::new_static("bar.baz").unwrap(),
         )
         .expect("Expected bar.baz to exist in site-packages.");
         let baz_workspace = case.workspace_path("bar/baz.py");
@@ -1125,7 +1156,7 @@ mod unix {
 
         let baz = resolve_module(
             case.db().upcast(),
-            ModuleName::new_static("bar.baz").unwrap(),
+            &ModuleName::new_static("bar.baz").unwrap(),
         )
         .expect("Expected bar.baz to exist in site-packages.");
         let bar_baz = case.workspace_path("bar/baz.py");
@@ -1229,7 +1260,7 @@ mod unix {
 
         let baz = resolve_module(
             case.db().upcast(),
-            ModuleName::new_static("bar.baz").unwrap(),
+            &ModuleName::new_static("bar.baz").unwrap(),
         )
         .expect("Expected bar.baz to exist in site-packages.");
         let baz_site_packages_path =

crates/red_knot_python_semantic/Cargo.toml

@@ -34,6 +34,7 @@ hashbrown = { workspace = true }
 smallvec = { workspace = true }
 static_assertions = { workspace = true }
 test-case = { workspace = true }
+memchr = { workspace = true }
 
 [dev-dependencies]
 ruff_db = { workspace = true, features = ["os", "testing"] }
@@ -42,8 +43,8 @@ red_knot_test = { workspace = true }
 red_knot_vendored = { workspace = true }
 
 anyhow = { workspace = true }
+dir-test = {workspace = true}
 insta = { workspace = true }
-rstest = { workspace = true }
 tempfile = { workspace = true }
 
 [lints]

crates/red_knot_python_semantic/build.rs

@@ -1,4 +1,4 @@
 /// Rebuild the crate if a test file is added or removed from
 pub fn main() {
-    println!("cargo:rerun-if-changed=resources/mdtest");
+    println!("cargo::rerun-if-changed=resources/mdtest");
 }

crates/red_knot_python_semantic/resources/mdtest/.mdformat.toml

@@ -0,0 +1 @@
+wrap = 100

crates/red_knot_python_semantic/resources/mdtest/assignment/annotations.md

@@ -0,0 +1,112 @@
+# Assignment with annotations
+
+## Annotation only transparent to local inference
+
+```py
+x = 1
+x: int
+y = x
+
+reveal_type(y)  # revealed: Literal[1]
+```
+
+## Violates own annotation
+
+```py
+x: int = "foo"  # error: [invalid-assignment] "Object of type `Literal["foo"]` is not assignable to `int`"
+```
+
+## Violates previous annotation
+
+```py
+x: int
+x = "foo"  # error: [invalid-assignment] "Object of type `Literal["foo"]` is not assignable to `int`"
+```
+
+## Tuple annotations are understood
+
+```py path=module.py
+from typing_extensions import Unpack
+
+a: tuple[()] = ()
+b: tuple[int] = (42,)
+c: tuple[str, int] = ("42", 42)
+d: tuple[tuple[str, str], tuple[int, int]] = (("foo", "foo"), (42, 42))
+e: tuple[str, ...] = ()
+# TODO: we should not emit this error
+# error: [call-possibly-unbound-method] "Method `__class_getitem__` of type `Literal[tuple]` is possibly unbound"
+f: tuple[str, *tuple[int, ...], bytes] = ("42", b"42")
+g: tuple[str, Unpack[tuple[int, ...]], bytes] = ("42", b"42")
+h: tuple[list[int], list[int]] = ([], [])
+i: tuple[str | int, str | int] = (42, 42)
+j: tuple[str | int] = (42,)
+```
+
+```py path=script.py
+from module import a, b, c, d, e, f, g, h, i, j
+
+reveal_type(a)  # revealed: tuple[()]
+reveal_type(b)  # revealed: tuple[int]
+reveal_type(c)  # revealed: tuple[str, int]
+reveal_type(d)  # revealed: tuple[tuple[str, str], tuple[int, int]]
+
+# TODO: homogenous tuples, PEP-646 tuples
+reveal_type(e)  # revealed: @Todo
+reveal_type(f)  # revealed: @Todo
+reveal_type(g)  # revealed: @Todo
+
+# TODO: support more kinds of type expressions in annotations
+reveal_type(h)  # revealed: @Todo
+
+reveal_type(i)  # revealed: tuple[str | int, str | int]
+reveal_type(j)  # revealed: tuple[str | int]
+```
+
+## Incorrect tuple assignments are complained about
+
+```py
+# error: [invalid-assignment] "Object of type `tuple[Literal[1], Literal[2]]` is not assignable to `tuple[()]`"
+a: tuple[()] = (1, 2)
+
+# error: [invalid-assignment] "Object of type `tuple[Literal["foo"]]` is not assignable to `tuple[int]`"
+b: tuple[int] = ("foo",)
+
+# error: [invalid-assignment] "Object of type `tuple[list, Literal["foo"]]` is not assignable to `tuple[str | int, str]`"
+c: tuple[str | int, str] = ([], "foo")
+```
+
+## PEP-604 annotations are supported
+
+```py
+def foo() -> str | int | None:
+    return None
+
+reveal_type(foo())  # revealed: str | int | None
+
+def bar() -> str | str | None:
+    return None
+
+reveal_type(bar())  # revealed: str | None
+
+def baz() -> str | str:
+    return "Hello, world!"
+
+reveal_type(baz())  # revealed: str
+```
+
+## Attribute expressions in type annotations are understood
+
+```py
+import builtins
+
+int = "foo"
+a: builtins.int = 42
+
+# error: [invalid-assignment] "Object of type `Literal["bar"]` is not assignable to `int`"
+b: builtins.int = "bar"
+
+c: builtins.tuple[builtins.tuple[builtins.int, builtins.int], builtins.int] = ((42, 42), 42)
+
+# error: [invalid-assignment] "Object of type `Literal["foo"]` is not assignable to `tuple[tuple[int, int], int]`"
+c: builtins.tuple[builtins.tuple[builtins.int, builtins.int], builtins.int] = "foo"
+```

crates/red_knot_python_semantic/resources/mdtest/assignment/augmented.md

@@ -0,0 +1,154 @@
+# Augmented assignment
+
+## Basic
+
+```py
+x = 3
+x -= 1
+reveal_type(x)  # revealed: Literal[2]
+
+x = 1.0
+x /= 2
+reveal_type(x)  # revealed: float
+```
+
+## Dunder methods
+
+```py
+class C:
+    def __isub__(self, other: int) -> str:
+        return "Hello, world!"
+
+x = C()
+x -= 1
+reveal_type(x)  # revealed: str
+
+class C:
+    def __iadd__(self, other: str) -> float:
+        return 1.0
+
+x = C()
+x += "Hello"
+reveal_type(x)  # revealed: float
+```
+
+## Unsupported types
+
+```py
+class C:
+    def __isub__(self, other: str) -> int:
+        return 42
+
+x = C()
+x -= 1
+
+# TODO: should error, once operand type check is implemented
+reveal_type(x)  # revealed: int
+```
+
+## Method union
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+class Foo:
+    if bool_instance():
+        def __iadd__(self, other: int) -> str:
+            return "Hello, world!"
+    else:
+        def __iadd__(self, other: int) -> int:
+            return 42
+
+f = Foo()
+f += 12
+
+reveal_type(f)  # revealed: str | int
+```
+
+## Partially bound `__iadd__`
+
+```py
+def bool_instance() -> bool:
+    return True
+
+class Foo:
+    if bool_instance():
+        def __iadd__(self, other: str) -> int:
+            return 42
+
+f = Foo()
+
+# TODO: We should emit an `unsupported-operator` error here, possibly with the information
+# that `Foo.__iadd__` may be unbound as additional context.
+f += "Hello, world!"
+
+reveal_type(f)  # revealed: int
+```
+
+## Partially bound with `__add__`
+
+```py
+def bool_instance() -> bool:
+    return True
+
+class Foo:
+    def __add__(self, other: str) -> str:
+        return "Hello, world!"
+    if bool_instance():
+        def __iadd__(self, other: str) -> int:
+            return 42
+
+f = Foo()
+f += "Hello, world!"
+
+# TODO(charlie): This should be `int | str`, since `__iadd__` may be unbound.
+reveal_type(f)  # revealed: int
+```
+
+## Partially bound target union
+
+```py
+def bool_instance() -> bool:
+    return True
+
+class Foo:
+    def __add__(self, other: int) -> str:
+        return "Hello, world!"
+    if bool_instance():
+        def __iadd__(self, other: int) -> int:
+            return 42
+
+if bool_instance():
+    f = Foo()
+else:
+    f = 42.0
+f += 12
+
+# TODO(charlie): This should be `str | int | float`
+reveal_type(f)  # revealed: @Todo
+```
+
+## Target union
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+class Foo:
+    def __iadd__(self, other: int) -> str:
+        return "Hello, world!"
+
+if flag:
+    f = Foo()
+else:
+    f = 42.0
+f += 12
+
+# TODO(charlie): This should be `str | float`.
+reveal_type(f)  # revealed: @Todo
+```

crates/red_knot_python_semantic/resources/mdtest/assignment/multi_target.md

@@ -0,0 +1,9 @@
+# Multi-target assignment
+
+## Basic
+
+```py
+x = y = 1
+reveal_type(x)  # revealed: Literal[1]
+reveal_type(y)  # revealed: Literal[1]
+```

crates/red_knot_python_semantic/resources/mdtest/assignment/unbound.md

@@ -0,0 +1,59 @@
+# Unbound
+
+## Unbound
+
+```py
+x = foo  # error: [unresolved-reference] "Name `foo` used when not defined"
+foo = 1
+
+# No error `unresolved-reference` diagnostic is reported for `x`. This is
+# desirable because we would get a lot of cascading errors even though there
+# is only one root cause (the unbound variable `foo`).
+
+# revealed: Unknown
+reveal_type(x)
+```
+
+Note: in this particular example, one could argue that the most likely error would be a wrong order
+of the `x`/`foo` definitions, and so it could be desirable to infer `Literal[1]` for the type of
+`x`. On the other hand, there might be a variable `fob` a little higher up in this file, and the
+actual error might have been just a typo. Inferring `Unknown` thus seems like the safest option.
+
+## Unbound class variable
+
+Name lookups within a class scope fall back to globals, but lookups of class attributes don't.
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = 1
+
+class C:
+    y = x
+    if flag:
+        x = 2
+
+reveal_type(C.x)  # revealed: Literal[2]
+reveal_type(C.y)  # revealed: Literal[1]
+```
+
+## Possibly unbound in class and global scope
+
+```py
+def bool_instance() -> bool:
+    return True
+
+if bool_instance():
+    x = "abc"
+
+class C:
+    if bool_instance():
+        x = 1
+
+    # error: [possibly-unresolved-reference]
+    y = x
+
+reveal_type(C.y)  # revealed: Literal[1] | Literal["abc"]
+```

crates/red_knot_python_semantic/resources/mdtest/assignment/walrus.md

@@ -0,0 +1,17 @@
+# Walrus operator
+
+## Basic
+
+```py
+x = (y := 1) + 1
+reveal_type(x)  # revealed: Literal[2]
+reveal_type(y)  # revealed: Literal[1]
+```
+
+## Walrus self-addition
+
+```py
+x = 0
+(x := x + 1)
+reveal_type(x)  # revealed: Literal[1]
+```

crates/red_knot_python_semantic/resources/mdtest/attributes.md

@@ -0,0 +1,20 @@
+# Class attributes
+
+## Union of attributes
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+if flag:
+    class C:
+        x = 1
+
+else:
+    class C:
+        x = 2
+
+reveal_type(C.x)  # revealed: Literal[1, 2]
+```

crates/red_knot_python_semantic/resources/mdtest/binary/booleans.md

@@ -0,0 +1,48 @@
+## Binary operations on booleans
+
+## Basic Arithmetic
+
+We try to be precise and all operations except for division will result in Literal type.
+
+```py
+a = True
+b = False
+
+reveal_type(a + a)  # revealed: Literal[2]
+reveal_type(a + b)  # revealed: Literal[1]
+reveal_type(b + a)  # revealed: Literal[1]
+reveal_type(b + b)  # revealed: Literal[0]
+
+reveal_type(a - a)  # revealed: Literal[0]
+reveal_type(a - b)  # revealed: Literal[1]
+reveal_type(b - a)  # revealed: Literal[-1]
+reveal_type(b - b)  # revealed: Literal[0]
+
+reveal_type(a * a)  # revealed: Literal[1]
+reveal_type(a * b)  # revealed: Literal[0]
+reveal_type(b * a)  # revealed: Literal[0]
+reveal_type(b * b)  # revealed: Literal[0]
+
+reveal_type(a % a)  # revealed: Literal[0]
+reveal_type(b % a)  # revealed: Literal[0]
+
+reveal_type(a // a)  # revealed: Literal[1]
+reveal_type(b // a)  # revealed: Literal[0]
+
+reveal_type(a**a)  # revealed: Literal[1]
+reveal_type(a**b)  # revealed: Literal[1]
+reveal_type(b**a)  # revealed: Literal[0]
+reveal_type(b**b)  # revealed: Literal[1]
+
+# Division
+reveal_type(a / a)  # revealed: float
+reveal_type(b / a)  # revealed: float
+b / b  # error: [division-by-zero] "Cannot divide object of type `Literal[False]` by zero"
+a / b  # error: [division-by-zero] "Cannot divide object of type `Literal[True]` by zero"
+
+# bitwise OR
+reveal_type(a | a)  # revealed: Literal[True]
+reveal_type(a | b)  # revealed: Literal[True]
+reveal_type(b | a)  # revealed: Literal[True]
+reveal_type(b | b)  # revealed: Literal[False]
+```

crates/red_knot_python_semantic/resources/mdtest/binary/instances.md

@@ -0,0 +1,439 @@
+# Binary operations on instances
+
+Binary operations in Python are implemented by means of magic double-underscore methods.
+
+For references, see:
+
+- <https://snarky.ca/unravelling-binary-arithmetic-operations-in-python/>
+- <https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types>
+
+## Operations
+
+We support inference for all Python's binary operators: `+`, `-`, `*`, `@`, `/`, `//`, `%`, `**`,
+`<<`, `>>`, `&`, `^`, and `|`.
+
+```py
+class A:
+    def __add__(self, other) -> A:
+        return self
+
+    def __sub__(self, other) -> A:
+        return self
+
+    def __mul__(self, other) -> A:
+        return self
+
+    def __matmul__(self, other) -> A:
+        return self
+
+    def __truediv__(self, other) -> A:
+        return self
+
+    def __floordiv__(self, other) -> A:
+        return self
+
+    def __mod__(self, other) -> A:
+        return self
+
+    def __pow__(self, other) -> A:
+        return self
+
+    def __lshift__(self, other) -> A:
+        return self
+
+    def __rshift__(self, other) -> A:
+        return self
+
+    def __and__(self, other) -> A:
+        return self
+
+    def __xor__(self, other) -> A:
+        return self
+
+    def __or__(self, other) -> A:
+        return self
+
+class B: ...
+
+reveal_type(A() + B())  # revealed: A
+reveal_type(A() - B())  # revealed: A
+reveal_type(A() * B())  # revealed: A
+reveal_type(A() @ B())  # revealed: A
+reveal_type(A() / B())  # revealed: A
+reveal_type(A() // B())  # revealed: A
+reveal_type(A() % B())  # revealed: A
+reveal_type(A() ** B())  # revealed: A
+reveal_type(A() << B())  # revealed: A
+reveal_type(A() >> B())  # revealed: A
+reveal_type(A() & B())  # revealed: A
+reveal_type(A() ^ B())  # revealed: A
+reveal_type(A() | B())  # revealed: A
+```
+
+## Reflected
+
+We also support inference for reflected operations:
+
+```py
+class A:
+    def __radd__(self, other) -> A:
+        return self
+
+    def __rsub__(self, other) -> A:
+        return self
+
+    def __rmul__(self, other) -> A:
+        return self
+
+    def __rmatmul__(self, other) -> A:
+        return self
+
+    def __rtruediv__(self, other) -> A:
+        return self
+
+    def __rfloordiv__(self, other) -> A:
+        return self
+
+    def __rmod__(self, other) -> A:
+        return self
+
+    def __rpow__(self, other) -> A:
+        return self
+
+    def __rlshift__(self, other) -> A:
+        return self
+
+    def __rrshift__(self, other) -> A:
+        return self
+
+    def __rand__(self, other) -> A:
+        return self
+
+    def __rxor__(self, other) -> A:
+        return self
+
+    def __ror__(self, other) -> A:
+        return self
+
+class B: ...
+
+reveal_type(B() + A())  # revealed: A
+reveal_type(B() - A())  # revealed: A
+reveal_type(B() * A())  # revealed: A
+reveal_type(B() @ A())  # revealed: A
+reveal_type(B() / A())  # revealed: A
+reveal_type(B() // A())  # revealed: A
+reveal_type(B() % A())  # revealed: A
+reveal_type(B() ** A())  # revealed: A
+reveal_type(B() << A())  # revealed: A
+reveal_type(B() >> A())  # revealed: A
+reveal_type(B() & A())  # revealed: A
+reveal_type(B() ^ A())  # revealed: A
+reveal_type(B() | A())  # revealed: A
+```
+
+## Returning a different type
+
+The magic methods aren't required to return the type of `self`:
+
+```py
+class A:
+    def __add__(self, other) -> int:
+        return 1
+
+    def __rsub__(self, other) -> int:
+        return 1
+
+class B: ...
+
+reveal_type(A() + B())  # revealed: int
+reveal_type(B() - A())  # revealed: int
+```
+
+## Non-reflected precedence in general
+
+In general, if the left-hand side defines `__add__` and the right-hand side defines `__radd__` and
+the right-hand side is not a subtype of the left-hand side, `lhs.__add__` will take precedence:
+
+```py
+class A:
+    def __add__(self, other: B) -> int:
+        return 42
+
+class B:
+    def __radd__(self, other: A) -> str:
+        return "foo"
+
+reveal_type(A() + B())  # revealed:  int
+
+# Edge case: C is a subtype of C, *but* if the two sides are of *equal* types,
+# the lhs *still* takes precedence
+class C:
+    def __add__(self, other: C) -> int:
+        return 42
+
+    def __radd__(self, other: C) -> str:
+        return "foo"
+
+reveal_type(C() + C())  # revealed: int
+```
+
+## Reflected precedence for subtypes (in some cases)
+
+If the right-hand operand is a subtype of the left-hand operand and has a different implementation
+of the reflected method, the reflected method on the right-hand operand takes precedence.
+
+```py
+class A:
+    def __add__(self, other) -> str:
+        return "foo"
+
+    def __radd__(self, other) -> str:
+        return "foo"
+
+class MyString(str): ...
+
+class B(A):
+    def __radd__(self, other) -> MyString:
+        return MyString()
+
+reveal_type(A() + B())  # revealed: MyString
+
+# N.B. Still a subtype of `A`, even though `A` does not appear directly in the class's `__bases__`
+class C(B): ...
+
+# TODO: we currently only understand direct subclasses as subtypes of the superclass.
+# We need to iterate through the full MRO rather than just the class's bases;
+# if we do, we'll understand `C` as a subtype of `A`, and correctly understand this as being
+# `MyString` rather than `str`
+reveal_type(A() + C())  # revealed: str
+```
+
+## Reflected precedence 2
+
+If the right-hand operand is a subtype of the left-hand operand, but does not override the reflected
+method, the left-hand operand's non-reflected method still takes precedence:
+
+```py
+class A:
+    def __add__(self, other) -> str:
+        return "foo"
+
+    def __radd__(self, other) -> int:
+        return 42
+
+class B(A): ...
+
+reveal_type(A() + B())  # revealed: str
+```
+
+## Only reflected supported
+
+For example, at runtime, `(1).__add__(1.2)` is `NotImplemented`, but `(1.2).__radd__(1) == 2.2`,
+meaning that `1 + 1.2` succeeds at runtime (producing `2.2`). The runtime tries the second one only
+if the first one returns `NotImplemented` to signal failure.
+
+Typeshed and other stubs annotate dunder-method calls that would return `NotImplemented` as being
+"illegal" calls. `int.__add__` is annotated as only "accepting" `int`s, even though it
+strictly-speaking "accepts" any other object without raising an exception -- it will simply return
+`NotImplemented`, allowing the runtime to try the `__radd__` method of the right-hand operand as
+well.
+
+```py
+class A:
+    def __sub__(self, other: A) -> A:
+        return A()
+
+class B:
+    def __rsub__(self, other: A) -> B:
+        return B()
+
+# TODO: this should be `B` (the return annotation of `B.__rsub__`),
+# because `A.__sub__` is annotated as only accepting `A`,
+# but `B.__rsub__` will accept `A`.
+reveal_type(A() - B())  # revealed: A
+```
+
+## Callable instances as dunders
+
+Believe it or not, this is supported at runtime:
+
+```py
+class A:
+    def __call__(self, other) -> int:
+        return 42
+
+class B:
+    __add__ = A()
+
+reveal_type(B() + B())  # revealed: int
+```
+
+## Integration test: numbers from typeshed
+
+```py
+reveal_type(3j + 3.14)  # revealed: complex
+reveal_type(4.2 + 42)  # revealed: float
+reveal_type(3j + 3)  # revealed: complex
+
+# TODO should be complex, need to check arg type and fall back to `rhs.__radd__`
+reveal_type(3.14 + 3j)  # revealed: float
+
+# TODO should be float, need to check arg type and fall back to `rhs.__radd__`
+reveal_type(42 + 4.2)  # revealed: int
+
+# TODO should be complex, need to check arg type and fall back to `rhs.__radd__`
+reveal_type(3 + 3j)  # revealed: int
+
+def returns_int() -> int:
+    return 42
+
+def returns_bool() -> bool:
+    return True
+
+x = returns_bool()
+y = returns_int()
+
+reveal_type(x + y)  # revealed: int
+reveal_type(4.2 + x)  # revealed: float
+
+# TODO should be float, need to check arg type and fall back to `rhs.__radd__`
+reveal_type(y + 4.12)  # revealed: int
+```
+
+## With literal types
+
+When we have a literal type for one operand, we're able to fall back to the instance handling for
+its instance super-type.
+
+```py
+class A:
+    def __add__(self, other) -> A:
+        return self
+
+    def __radd__(self, other) -> A:
+        return self
+
+reveal_type(A() + 1)  # revealed: A
+# TODO should be `A` since `int.__add__` doesn't support `A` instances
+reveal_type(1 + A())  # revealed: int
+
+reveal_type(A() + "foo")  # revealed: A
+# TODO should be `A` since `str.__add__` doesn't support `A` instances
+# TODO overloads
+reveal_type("foo" + A())  # revealed: @Todo
+
+reveal_type(A() + b"foo")  # revealed: A
+# TODO should be `A` since `bytes.__add__` doesn't support `A` instances
+reveal_type(b"foo" + A())  # revealed: bytes
+
+reveal_type(A() + ())  # revealed: A
+# TODO this should be `A`, since `tuple.__add__` doesn't support `A` instances
+reveal_type(() + A())  # revealed: @Todo
+
+literal_string_instance = "foo" * 1_000_000_000
+# the test is not testing what it's meant to be testing if this isn't a `LiteralString`:
+reveal_type(literal_string_instance)  # revealed: LiteralString
+
+reveal_type(A() + literal_string_instance)  # revealed: A
+# TODO should be `A` since `str.__add__` doesn't support `A` instances
+# TODO overloads
+reveal_type(literal_string_instance + A())  # revealed: @Todo
+```
+
+## Operations involving instances of classes inheriting from `Any`
+
+`Any` and `Unknown` represent a set of possible runtime objects, wherein the bounds of the set are
+unknown. Whether the left-hand operand's dunder or the right-hand operand's reflected dunder depends
+on whether the right-hand operand is an instance of a class that is a subclass of the left-hand
+operand's class and overrides the reflected dunder. In the following example, because of the
+unknowable nature of `Any`/`Unknown`, we must consider both possibilities: `Any`/`Unknown` might
+resolve to an unknown third class that inherits from `X` and overrides `__radd__`; but it also might
+not. Thus, the correct answer here for the `reveal_type` is `int | Unknown`.
+
+```py
+from does_not_exist import Foo  # error: [unresolved-import]
+
+reveal_type(Foo)  # revealed: Unknown
+
+class X:
+    def __add__(self, other: object) -> int:
+        return 42
+
+class Y(Foo): ...
+
+# TODO: Should be `int | Unknown`; see above discussion.
+reveal_type(X() + Y())  # revealed: int
+```
+
+## Unsupported
+
+### Dunder as instance attribute
+
+The magic method must exist on the class, not just on the instance:
+
+```py
+def add_impl(self, other) -> int:
+    return 1
+
+class A:
+    def __init__(self):
+        self.__add__ = add_impl
+
+# error: [unsupported-operator] "Operator `+` is unsupported between objects of type `A` and `A`"
+# revealed: Unknown
+reveal_type(A() + A())
+```
+
+### Missing dunder
+
+```py
+class A: ...
+
+# error: [unsupported-operator]
+# revealed: Unknown
+reveal_type(A() + A())
+```
+
+### Wrong position
+
+A left-hand dunder method doesn't apply for the right-hand operand, or vice versa:
+
+```py
+class A:
+    def __add__(self, other) -> int: ...
+
+class B:
+    def __radd__(self, other) -> int: ...
+
+class C: ...
+
+# error: [unsupported-operator]
+# revealed: Unknown
+reveal_type(C() + A())
+
+# error: [unsupported-operator]
+# revealed: Unknown
+reveal_type(B() + C())
+```
+
+### Reflected dunder is not tried between two objects of the same type
+
+For the specific case where the left-hand operand is the exact same type as the right-hand operand,
+the reflected dunder of the right-hand operand is not tried; the runtime short-circuits after trying
+the unreflected dunder of the left-hand operand. For context, see
+[this mailing list discussion](https://mail.python.org/archives/list/python-dev@python.org/thread/7NZUCODEAPQFMRFXYRMGJXDSIS3WJYIV/).
+
+```py
+class Foo:
+    def __radd__(self, other: Foo) -> Foo:
+        return self
+
+# error: [unsupported-operator]
+# revealed: Unknown
+reveal_type(Foo() + Foo())
+```
+
+### Wrong type
+
+TODO: check signature and error if `other` is the wrong type

crates/red_knot_python_semantic/resources/mdtest/binary/integers.md

@@ -0,0 +1,70 @@
+# Binary operations on integers
+
+## Basic Arithmetic
+
+```py
+reveal_type(2 + 1)  # revealed: Literal[3]
+reveal_type(3 - 4)  # revealed: Literal[-1]
+reveal_type(3 * -1)  # revealed: Literal[-3]
+reveal_type(-3 // 3)  # revealed: Literal[-1]
+reveal_type(-3 / 3)  # revealed: float
+reveal_type(5 % 3)  # revealed: Literal[2]
+```
+
+## Power
+
+For power if the result fits in the int literal type it will be a Literal type. Otherwise the
+outcome is int.
+
+```py
+largest_u32 = 4_294_967_295
+reveal_type(2**2)  # revealed: Literal[4]
+reveal_type(1 ** (largest_u32 + 1))  # revealed: int
+reveal_type(2**largest_u32)  # revealed: int
+```
+
+## Division by Zero
+
+This error is really outside the current Python type system, because e.g. `int.__truediv__` and
+friends are not annotated to indicate that it's an error, and we don't even have a facility to
+permit such an annotation. So arguably divide-by-zero should be a lint error rather than a type
+checker error. But we choose to go ahead and error in the cases that are very likely to be an error:
+dividing something typed as `int` or `float` by something known to be `Literal[0]`.
+
+This isn't _definitely_ an error, because the object typed as `int` or `float` could be an instance
+of a custom subclass which overrides division behavior to handle zero without error. But if this
+unusual case occurs, the error can be avoided by explicitly typing the dividend as that safe custom
+subclass; we only emit the error if the LHS type is exactly `int` or `float`, not if its a subclass.
+
+```py
+a = 1 / 0  # error: "Cannot divide object of type `Literal[1]` by zero"
+reveal_type(a)  # revealed: float
+
+b = 2 // 0  # error: "Cannot floor divide object of type `Literal[2]` by zero"
+reveal_type(b)  # revealed: int
+
+c = 3 % 0  # error: "Cannot reduce object of type `Literal[3]` modulo zero"
+reveal_type(c)  # revealed: int
+
+# error: "Cannot divide object of type `int` by zero"
+# revealed: float
+reveal_type(int() / 0)
+
+# error: "Cannot divide object of type `Literal[1]` by zero"
+# revealed: float
+reveal_type(1 / False)
+# error: [division-by-zero] "Cannot divide object of type `Literal[True]` by zero"
+True / False
+# error: [division-by-zero] "Cannot divide object of type `Literal[True]` by zero"
+bool(1) / False
+
+# error: "Cannot divide object of type `float` by zero"
+# revealed: float
+reveal_type(1.0 / 0)
+
+class MyInt(int): ...
+
+# No error for a subclass of int
+# revealed: float
+reveal_type(MyInt(3) / 0)
+```

crates/red_knot_python_semantic/resources/mdtest/boolean/short_circuit.md

@@ -0,0 +1,78 @@
+# Short-Circuit Evaluation
+
+## Not all boolean expressions must be evaluated
+
+In `or` expressions, if the left-hand side is truthy, the right-hand side is not evaluated.
+Similarly, in `and` expressions, if the left-hand side is falsy, the right-hand side is not
+evaluated.
+
+```py
+def bool_instance() -> bool:
+    return True
+
+if bool_instance() or (x := 1):
+    # error: [possibly-unresolved-reference]
+    reveal_type(x)  # revealed: Literal[1]
+
+if bool_instance() and (x := 1):
+    # error: [possibly-unresolved-reference]
+    reveal_type(x)  # revealed: Literal[1]
+```
+
+## First expression is always evaluated
+
+```py
+def bool_instance() -> bool:
+    return True
+
+if (x := 1) or bool_instance():
+    reveal_type(x)  # revealed: Literal[1]
+
+if (x := 1) and bool_instance():
+    reveal_type(x)  # revealed: Literal[1]
+```
+
+## Statically known truthiness
+
+```py
+if True or (x := 1):
+    # TODO: infer that the second arm is never executed, and raise `unresolved-reference`.
+    # error: [possibly-unresolved-reference]
+    reveal_type(x)  # revealed: Literal[1]
+
+if True and (x := 1):
+    # TODO: infer that the second arm is always executed, do not raise a diagnostic
+    # error: [possibly-unresolved-reference]
+    reveal_type(x)  # revealed: Literal[1]
+```
+
+## Later expressions can always use variables from earlier expressions
+
+```py
+def bool_instance() -> bool:
+    return True
+
+bool_instance() or (x := 1) or reveal_type(x)  # revealed: Literal[1]
+
+# error: [unresolved-reference]
+bool_instance() or reveal_type(y) or (y := 1)  # revealed: Unknown
+```
+
+## Nested expressions
+
+```py
+def bool_instance() -> bool:
+    return True
+
+if bool_instance() or ((x := 1) and bool_instance()):
+    # error: [possibly-unresolved-reference]
+    reveal_type(x)  # revealed: Literal[1]
+
+if ((y := 1) and bool_instance()) or bool_instance():
+    reveal_type(y)  # revealed: Literal[1]
+
+# error: [possibly-unresolved-reference]
+if (bool_instance() and (z := 1)) or reveal_type(z):  # revealed: Literal[1]
+    # error: [possibly-unresolved-reference]
+    reveal_type(z)  # revealed: Literal[1]
+```

crates/red_knot_python_semantic/resources/mdtest/call/callable_instance.md

@@ -0,0 +1,20 @@
+# Callable instance
+
+## Dunder call
+
+```py
+class Multiplier:
+    def __init__(self, factor: float):
+        self.factor = factor
+
+    def __call__(self, number: float) -> float:
+        return number * self.factor
+
+a = Multiplier(2.0)(3.0)
+reveal_type(a)  # revealed: float
+
+class Unit: ...
+
+b = Unit()(3.0)  # error: "Object of type `Unit` is not callable"
+reveal_type(b)  # revealed: Unknown
+```

crates/red_knot_python_semantic/resources/mdtest/call/constructor.md

@@ -0,0 +1,7 @@
+# Constructor
+
+```py
+class Foo: ...
+
+reveal_type(Foo())  # revealed: Foo
+```

crates/red_knot_python_semantic/resources/mdtest/call/function.md

@@ -0,0 +1,46 @@
+# Call expression
+
+## Simple
+
+```py
+def get_int() -> int:
+    return 42
+
+reveal_type(get_int())  # revealed: int
+```
+
+## Async
+
+```py
+async def get_int_async() -> int:
+    return 42
+
+# TODO: we don't yet support `types.CoroutineType`, should be generic `Coroutine[Any, Any, int]`
+reveal_type(get_int_async())  # revealed: @Todo
+```
+
+## Decorated
+
+```py
+from typing import Callable
+
+def foo() -> int:
+    return 42
+
+def decorator(func) -> Callable[[], int]:
+    return foo
+
+@decorator
+def bar() -> str:
+    return "bar"
+
+# TODO: should reveal `int`, as the decorator replaces `bar` with `foo`
+reveal_type(bar())  # revealed: @Todo
+```
+
+## Invalid callable
+
+```py
+nonsense = 123
+x = nonsense()  # error: "Object of type `Literal[123]` is not callable"
+```

crates/red_knot_python_semantic/resources/mdtest/call/union.md

@@ -0,0 +1,104 @@
+# Unions in calls
+
+## Union of return types
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+if flag:
+
+    def f() -> int:
+        return 1
+
+else:
+
+    def f() -> str:
+        return "foo"
+
+reveal_type(f())  # revealed: int | str
+```
+
+## Calling with an unknown union
+
+```py
+from nonexistent import f  # error: [unresolved-import] "Cannot resolve import `nonexistent`"
+
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+if flag:
+
+    def f() -> int:
+        return 1
+
+reveal_type(f())  # revealed: Unknown | int
+```
+
+## Non-callable elements in a union
+
+Calling a union with a non-callable element should emit a diagnostic.
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+if flag:
+    f = 1
+else:
+
+    def f() -> int:
+        return 1
+
+x = f()  # error: "Object of type `Literal[1] | Literal[f]` is not callable (due to union element `Literal[1]`)"
+reveal_type(x)  # revealed: Unknown | int
+```
+
+## Multiple non-callable elements in a union
+
+Calling a union with multiple non-callable elements should mention all of them in the diagnostic.
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag, flag2 = bool_instance(), bool_instance()
+
+if flag:
+    f = 1
+elif flag2:
+    f = "foo"
+else:
+
+    def f() -> int:
+        return 1
+
+# error: "Object of type `Literal[1] | Literal["foo"] | Literal[f]` is not callable (due to union elements Literal[1], Literal["foo"])"
+# revealed: Unknown | int
+reveal_type(f())
+```
+
+## All non-callable union elements
+
+Calling a union with no callable elements can emit a simpler diagnostic.
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+if flag:
+    f = 1
+else:
+    f = "foo"
+
+x = f()  # error: "Object of type `Literal[1] | Literal["foo"]` is not callable"
+reveal_type(x)  # revealed: Unknown
+```

crates/red_knot_python_semantic/resources/mdtest/comparison/byte_literals.md

@@ -1,43 +1,43 @@
-### Comparison: Byte literals
+# Comparison: Byte literals
 
-These tests assert that we infer precise `Literal` types for comparisons between objects
-inferred as having `Literal` bytes types:
+These tests assert that we infer precise `Literal` types for comparisons between objects inferred as
+having `Literal` bytes types:
 
 ```py
 reveal_type(b"abc" == b"abc")  # revealed: Literal[True]
-reveal_type(b"abc" == b"ab")   # revealed: Literal[False]
+reveal_type(b"abc" == b"ab")  # revealed: Literal[False]
 
 reveal_type(b"abc" != b"abc")  # revealed: Literal[False]
-reveal_type(b"abc" != b"ab")   # revealed: Literal[True]
+reveal_type(b"abc" != b"ab")  # revealed: Literal[True]
 
-reveal_type(b"abc" < b"abd")   # revealed: Literal[True]
-reveal_type(b"abc" < b"abb")   # revealed: Literal[False]
+reveal_type(b"abc" < b"abd")  # revealed: Literal[True]
+reveal_type(b"abc" < b"abb")  # revealed: Literal[False]
 
 reveal_type(b"abc" <= b"abc")  # revealed: Literal[True]
 reveal_type(b"abc" <= b"abb")  # revealed: Literal[False]
 
-reveal_type(b"abc" > b"abd")   # revealed: Literal[False]
-reveal_type(b"abc" > b"abb")   # revealed: Literal[True]
+reveal_type(b"abc" > b"abd")  # revealed: Literal[False]
+reveal_type(b"abc" > b"abb")  # revealed: Literal[True]
 
 reveal_type(b"abc" >= b"abc")  # revealed: Literal[True]
 reveal_type(b"abc" >= b"abd")  # revealed: Literal[False]
 
-reveal_type(b"" in b"")                      # revealed: Literal[True]
-reveal_type(b"" in b"abc")                   # revealed: Literal[True]
-reveal_type(b"abc" in b"")                   # revealed: Literal[False]
-reveal_type(b"ab" in b"abc")                 # revealed: Literal[True]
-reveal_type(b"abc" in b"abc")                # revealed: Literal[True]
-reveal_type(b"d" in b"abc")                  # revealed: Literal[False]
-reveal_type(b"ac" in b"abc")                 # revealed: Literal[False]
+reveal_type(b"" in b"")  # revealed: Literal[True]
+reveal_type(b"" in b"abc")  # revealed: Literal[True]
+reveal_type(b"abc" in b"")  # revealed: Literal[False]
+reveal_type(b"ab" in b"abc")  # revealed: Literal[True]
+reveal_type(b"abc" in b"abc")  # revealed: Literal[True]
+reveal_type(b"d" in b"abc")  # revealed: Literal[False]
+reveal_type(b"ac" in b"abc")  # revealed: Literal[False]
 reveal_type(b"\x81\x82" in b"\x80\x81\x82")  # revealed: Literal[True]
 reveal_type(b"\x82\x83" in b"\x80\x81\x82")  # revealed: Literal[False]
 
-reveal_type(b"ab" not in b"abc")             # revealed: Literal[False]
-reveal_type(b"ac" not in b"abc")             # revealed: Literal[True]
+reveal_type(b"ab" not in b"abc")  # revealed: Literal[False]
+reveal_type(b"ac" not in b"abc")  # revealed: Literal[True]
 
-reveal_type(b"abc" is b"abc")      # revealed: bool
-reveal_type(b"abc" is b"ab")       # revealed: Literal[False]
+reveal_type(b"abc" is b"abc")  # revealed: bool
+reveal_type(b"abc" is b"ab")  # revealed: Literal[False]
 
 reveal_type(b"abc" is not b"abc")  # revealed: bool
-reveal_type(b"abc" is not b"ab")   # revealed: Literal[True]
+reveal_type(b"abc" is not b"ab")  # revealed: Literal[True]
 ```

crates/red_knot_python_semantic/resources/mdtest/comparison/instances/membership_test.md

@@ -0,0 +1,162 @@
+# Comparison: Membership Test
+
+In Python, the term "membership test operators" refers to the operators `in` and `not in`. To
+customize their behavior, classes can implement one of the special methods `__contains__`,
+`__iter__`, or `__getitem__`.
+
+For references, see:
+
+- <https://docs.python.org/3/reference/expressions.html#membership-test-details>
+- <https://docs.python.org/3/reference/datamodel.html#object.__contains__>
+- <https://snarky.ca/unravelling-membership-testing/>
+
+## Implements `__contains__`
+
+Classes can support membership tests by implementing the `__contains__` method:
+
+```py
+class A:
+    def __contains__(self, item: str) -> bool:
+        return True
+
+reveal_type("hello" in A())  # revealed: bool
+reveal_type("hello" not in A())  # revealed: bool
+# TODO: should emit diagnostic, need to check arg type, will fail
+reveal_type(42 in A())  # revealed: bool
+reveal_type(42 not in A())  # revealed: bool
+```
+
+## Implements `__iter__`
+
+Classes that don't implement `__contains__`, but do implement `__iter__`, also support containment
+checks; the needle will be sought in their iterated items:
+
+```py
+class StringIterator:
+    def __next__(self) -> str:
+        return "foo"
+
+class A:
+    def __iter__(self) -> StringIterator:
+        return StringIterator()
+
+reveal_type("hello" in A())  # revealed: bool
+reveal_type("hello" not in A())  # revealed: bool
+reveal_type(42 in A())  # revealed: bool
+reveal_type(42 not in A())  # revealed: bool
+```
+
+## Implements `__getitems__`
+
+The final fallback is to implement `__getitem__` for integer keys. Python will call `__getitem__`
+with `0`, `1`, `2`... until either the needle is found (leading the membership test to evaluate to
+`True`) or `__getitem__` raises `IndexError` (the raised exception is swallowed, but results in the
+membership test evaluating to `False`).
+
+```py
+class A:
+    def __getitem__(self, key: int) -> str:
+        return "foo"
+
+reveal_type("hello" in A())  # revealed: bool
+reveal_type("hello" not in A())  # revealed: bool
+reveal_type(42 in A())  # revealed: bool
+reveal_type(42 not in A())  # revealed: bool
+```
+
+## Wrong Return Type
+
+Python coerces the results of containment checks to `bool`, even if `__contains__` returns a
+non-bool:
+
+```py
+class A:
+    def __contains__(self, item: str) -> str:
+        return "foo"
+
+reveal_type("hello" in A())  # revealed: bool
+reveal_type("hello" not in A())  # revealed: bool
+```
+
+## Literal Result for `in` and `not in`
+
+`__contains__` with a literal return type may result in a `BooleanLiteral` outcome.
+
+```py
+from typing import Literal
+
+class AlwaysTrue:
+    def __contains__(self, item: int) -> Literal[1]:
+        return 1
+
+class AlwaysFalse:
+    def __contains__(self, item: int) -> Literal[""]:
+        return ""
+
+# TODO: it should be Literal[True] and Literal[False]
+reveal_type(42 in AlwaysTrue())  # revealed: @Todo
+reveal_type(42 not in AlwaysTrue())  # revealed: @Todo
+
+# TODO: it should be Literal[False] and Literal[True]
+reveal_type(42 in AlwaysFalse())  # revealed: @Todo
+reveal_type(42 not in AlwaysFalse())  # revealed: @Todo
+```
+
+## No Fallback for `__contains__`
+
+If `__contains__` is implemented, checking membership of a type it doesn't accept is an error; it
+doesn't result in a fallback to `__iter__` or `__getitem__`:
+
+```py
+class CheckContains: ...
+class CheckIter: ...
+class CheckGetItem: ...
+
+class CheckIterIterator:
+    def __next__(self) -> CheckIter:
+        return CheckIter()
+
+class A:
+    def __contains__(self, item: CheckContains) -> bool:
+        return True
+
+    def __iter__(self) -> CheckIterIterator:
+        return CheckIterIterator()
+
+    def __getitem__(self, key: int) -> CheckGetItem:
+        return CheckGetItem()
+
+reveal_type(CheckContains() in A())  # revealed: bool
+
+# TODO: should emit diagnostic, need to check arg type,
+# should not fall back to __iter__ or __getitem__
+reveal_type(CheckIter() in A())  # revealed: bool
+reveal_type(CheckGetItem() in A())  # revealed: bool
+
+class B:
+    def __iter__(self) -> CheckIterIterator:
+        return CheckIterIterator()
+
+    def __getitem__(self, key: int) -> CheckGetItem:
+        return CheckGetItem()
+
+reveal_type(CheckIter() in B())  # revealed: bool
+# Always use `__iter__`, regardless of iterated type; there's no NotImplemented
+# in this case, so there's no fallback to `__getitem__`
+reveal_type(CheckGetItem() in B())  # revealed: bool
+```
+
+## Invalid Old-Style Iteration
+
+If `__getitem__` is implemented but does not accept integer arguments, then the membership test is
+not supported and should trigger a diagnostic.
+
+```py
+class A:
+    def __getitem__(self, key: str) -> str:
+        return "foo"
+
+# TODO should emit a diagnostic
+reveal_type(42 in A())  # revealed: bool
+reveal_type("hello" in A())  # revealed: bool
+```

crates/red_knot_python_semantic/resources/mdtest/comparison/instances/rich_comparison.md

@@ -0,0 +1,328 @@
+# Comparison: Rich Comparison
+
+Rich comparison operations (`==`, `!=`, `<`, `<=`, `>`, `>=`) in Python are implemented through
+double-underscore methods that allow customization of comparison behavior.
+
+For references, see:
+
+- <https://docs.python.org/3/reference/datamodel.html#object.__lt__>
+- <https://snarky.ca/unravelling-rich-comparison-operators/>
+
+## Rich Comparison Dunder Implementations For Same Class
+
+Classes can support rich comparison by implementing dunder methods like `__eq__`, `__ne__`, etc. The
+most common case involves implementing these methods for the same type:
+
+```py
+from __future__ import annotations
+
+class A:
+    def __eq__(self, other: A) -> int:
+        return 42
+
+    def __ne__(self, other: A) -> float:
+        return 42.0
+
+    def __lt__(self, other: A) -> str:
+        return "42"
+
+    def __le__(self, other: A) -> bytes:
+        return b"42"
+
+    def __gt__(self, other: A) -> list:
+        return [42]
+
+    def __ge__(self, other: A) -> set:
+        return {42}
+
+reveal_type(A() == A())  # revealed: int
+reveal_type(A() != A())  # revealed: float
+reveal_type(A() < A())  # revealed: str
+reveal_type(A() <= A())  # revealed: bytes
+reveal_type(A() > A())  # revealed: list
+reveal_type(A() >= A())  # revealed: set
+```
+
+## Rich Comparison Dunder Implementations for Other Class
+
+In some cases, classes may implement rich comparison dunder methods for comparisons with a different
+type:
+
+```py
+from __future__ import annotations
+
+class A:
+    def __eq__(self, other: B) -> int:
+        return 42
+
+    def __ne__(self, other: B) -> float:
+        return 42.0
+
+    def __lt__(self, other: B) -> str:
+        return "42"
+
+    def __le__(self, other: B) -> bytes:
+        return b"42"
+
+    def __gt__(self, other: B) -> list:
+        return [42]
+
+    def __ge__(self, other: B) -> set:
+        return {42}
+
+class B: ...
+
+reveal_type(A() == B())  # revealed: int
+reveal_type(A() != B())  # revealed: float
+reveal_type(A() < B())  # revealed: str
+reveal_type(A() <= B())  # revealed: bytes
+reveal_type(A() > B())  # revealed: list
+reveal_type(A() >= B())  # revealed: set
+```
+
+## Reflected Comparisons
+
+Fallback to the right-hand side’s comparison methods occurs when the left-hand side does not define
+them. Note: class `B` has its own `__eq__` and `__ne__` methods to override those of `object`, but
+these methods will be ignored here because they require a mismatched operand type.
+
+```py
+from __future__ import annotations
+
+class A:
+    def __eq__(self, other: B) -> int:
+        return 42
+
+    def __ne__(self, other: B) -> float:
+        return 42.0
+
+    def __lt__(self, other: B) -> str:
+        return "42"
+
+    def __le__(self, other: B) -> bytes:
+        return b"42"
+
+    def __gt__(self, other: B) -> list:
+        return [42]
+
+    def __ge__(self, other: B) -> set:
+        return {42}
+
+class B:
+    # To override builtins.object.__eq__ and builtins.object.__ne__
+    # TODO these should emit an invalid override diagnostic
+    def __eq__(self, other: str) -> B:
+        return B()
+
+    def __ne__(self, other: str) -> B:
+        return B()
+
+# TODO: should be `int` and `float`.
+# Need to check arg type and fall back to `rhs.__eq__` and `rhs.__ne__`.
+#
+# Because `object.__eq__` and `object.__ne__` accept `object` in typeshed,
+# this can only happen with an invalid override of these methods,
+# but we still support it.
+reveal_type(B() == A())  # revealed: B
+reveal_type(B() != A())  # revealed: B
+
+reveal_type(B() < A())  # revealed: list
+reveal_type(B() <= A())  # revealed: set
+
+reveal_type(B() > A())  # revealed: str
+reveal_type(B() >= A())  # revealed: bytes
+
+class C:
+    def __gt__(self, other: C) -> int:
+        return 42
+
+    def __ge__(self, other: C) -> float:
+        return 42.0
+
+reveal_type(C() < C())  # revealed: int
+reveal_type(C() <= C())  # revealed: float
+```
+
+## Reflected Comparisons with Subclasses
+
+When subclasses override comparison methods, these overridden methods take precedence over those in
+the parent class. Class `B` inherits from `A` and redefines comparison methods to return types other
+than `A`.
+
+```py
+from __future__ import annotations
+
+class A:
+    def __eq__(self, other: A) -> A:
+        return A()
+
+    def __ne__(self, other: A) -> A:
+        return A()
+
+    def __lt__(self, other: A) -> A:
+        return A()
+
+    def __le__(self, other: A) -> A:
+        return A()
+
+    def __gt__(self, other: A) -> A:
+        return A()
+
+    def __ge__(self, other: A) -> A:
+        return A()
+
+class B(A):
+    def __eq__(self, other: A) -> int:
+        return 42
+
+    def __ne__(self, other: A) -> float:
+        return 42.0
+
+    def __lt__(self, other: A) -> str:
+        return "42"
+
+    def __le__(self, other: A) -> bytes:
+        return b"42"
+
+    def __gt__(self, other: A) -> list:
+        return [42]
+
+    def __ge__(self, other: A) -> set:
+        return {42}
+
+reveal_type(A() == B())  # revealed: int
+reveal_type(A() != B())  # revealed: float
+
+reveal_type(A() < B())  # revealed: list
+reveal_type(A() <= B())  # revealed: set
+
+reveal_type(A() > B())  # revealed: str
+reveal_type(A() >= B())  # revealed: bytes
+```
+
+## Reflected Comparisons with Subclass But Falls Back to LHS
+
+In the case of a subclass, the right-hand side has priority. However, if the overridden dunder
+method has an mismatched type to operand, the comparison will fall back to the left-hand side.
+
+```py
+from __future__ import annotations
+
+class A:
+    def __lt__(self, other: A) -> A:
+        return A()
+
+    def __gt__(self, other: A) -> A:
+        return A()
+
+class B(A):
+    def __lt__(self, other: int) -> B:
+        return B()
+
+    def __gt__(self, other: int) -> B:
+        return B()
+
+# TODO: should be `A`, need to check argument type and fall back to LHS method
+reveal_type(A() < B())  # revealed: B
+reveal_type(A() > B())  # revealed: B
+```
+
+## Operations involving instances of classes inheriting from `Any`
+
+`Any` and `Unknown` represent a set of possible runtime objects, wherein the bounds of the set are
+unknown. Whether the left-hand operand's dunder or the right-hand operand's reflected dunder depends
+on whether the right-hand operand is an instance of a class that is a subclass of the left-hand
+operand's class and overrides the reflected dunder. In the following example, because of the
+unknowable nature of `Any`/`Unknown`, we must consider both possibilities: `Any`/`Unknown` might
+resolve to an unknown third class that inherits from `X` and overrides `__gt__`; but it also might
+not. Thus, the correct answer here for the `reveal_type` is `int | Unknown`.
+
+(This test is referenced from `mdtest/binary/instances.md`)
+
+```py
+from does_not_exist import Foo  # error: [unresolved-import]
+
+reveal_type(Foo)  # revealed: Unknown
+
+class X:
+    def __lt__(self, other: object) -> int:
+        return 42
+
+class Y(Foo): ...
+
+# TODO: Should be `int | Unknown`; see above discussion.
+reveal_type(X() < Y())  # revealed: int
+```
+
+## Equality and Inequality Fallback
+
+This test confirms that `==` and `!=` comparisons default to identity comparisons (`is`, `is not`)
+when argument types do not match the method signature.
+
+Please refer to the [docs](https://docs.python.org/3/reference/datamodel.html#object.__eq__)
+
+```py
+from __future__ import annotations
+
+class A:
+    # TODO both these overrides should emit invalid-override diagnostic
+    def __eq__(self, other: int) -> A:
+        return A()
+
+    def __ne__(self, other: int) -> A:
+        return A()
+
+# TODO: it should be `bool`, need to check arg type and fall back to `is` and `is not`
+reveal_type(A() == A())  # revealed: A
+reveal_type(A() != A())  # revealed: A
+```
+
+## Object Comparisons with Typeshed
+
+```py
+class A: ...
+
+reveal_type(A() == object())  # revealed: bool
+reveal_type(A() != object())  # revealed: bool
+reveal_type(object() == A())  # revealed: bool
+reveal_type(object() != A())  # revealed: bool
+
+# error: [unsupported-operator] "Operator `<` is not supported for types `A` and `object`"
+# revealed: Unknown
+reveal_type(A() < object())
+```
+
+## Numbers Comparison with typeshed
+
+```py
+reveal_type(1 == 1.0)  # revealed: bool
+reveal_type(1 != 1.0)  # revealed: bool
+reveal_type(1 < 1.0)  # revealed: bool
+reveal_type(1 <= 1.0)  # revealed: bool
+reveal_type(1 > 1.0)  # revealed: bool
+reveal_type(1 >= 1.0)  # revealed: bool
+
+reveal_type(1 == 2j)  # revealed: bool
+reveal_type(1 != 2j)  # revealed: bool
+
+# TODO: should be Unknown and emit diagnostic,
+# need to check arg type and should be failed
+reveal_type(1 < 2j)  # revealed: bool
+reveal_type(1 <= 2j)  # revealed: bool
+reveal_type(1 > 2j)  # revealed: bool
+reveal_type(1 >= 2j)  # revealed: bool
+
+def bool_instance() -> bool:
+    return True
+
+def int_instance() -> int:
+    return 42
+
+x = bool_instance()
+y = int_instance()
+
+reveal_type(x < y)  # revealed: bool
+reveal_type(y < x)  # revealed: bool
+reveal_type(4.2 < x)  # revealed: bool
+reveal_type(x < 4.2)  # revealed: bool
+```

crates/red_knot_python_semantic/resources/mdtest/comparison/integers.md

@@ -0,0 +1,29 @@
+# Comparison: Integers
+
+## Integer literals
+
+```py
+reveal_type(1 == 1 == True)  # revealed: Literal[True]
+reveal_type(1 == 1 == 2 == 4)  # revealed: Literal[False]
+reveal_type(False < True <= 2 < 3 != 6)  # revealed: Literal[True]
+reveal_type(1 < 1)  # revealed: Literal[False]
+reveal_type(1 > 1)  # revealed: Literal[False]
+reveal_type(1 is 1)  # revealed: bool
+reveal_type(1 is not 1)  # revealed: bool
+reveal_type(1 is 2)  # revealed: Literal[False]
+reveal_type(1 is not 7)  # revealed: Literal[True]
+# TODO: should be Unknown, and emit diagnostic, once we check call argument types
+reveal_type(1 <= "" and 0 < 1)  # revealed: bool
+```
+
+## Integer instance
+
+```py
+# TODO: implement lookup of `__eq__` on typeshed `int` stub.
+def int_instance() -> int:
+    return 42
+
+reveal_type(1 == int_instance())  # revealed: bool
+reveal_type(9 < int_instance())  # revealed: bool
+reveal_type(int_instance() < int_instance())  # revealed: bool
+```

crates/red_knot_python_semantic/resources/mdtest/comparison/non_boolean_returns.md

@@ -0,0 +1,41 @@
+# Comparison: Non boolean returns
+
+Walking through examples:
+
+- `a = A() < B() < C()`
+
+    1. `A() < B() and B() < C()` - split in N comparison
+    1. `A()` and `B()` - evaluate outcome types
+    1. `bool` and `bool` - evaluate truthiness
+    1. `A | B` - union of "first true" types
+
+- `b = 0 < 1 < A() < 3`
+
+    1. `0 < 1 and 1 < A() and A() < 3` - split in N comparison
+    1. `True` and `bool` and `A` - evaluate outcome types
+    1. `True` and `bool` and `bool` - evaluate truthiness
+    1. `bool | A` - union of "true" types
+
+- `c = 10 < 0 < A() < B() < C()` short-circuit to False
+
+```py
+from __future__ import annotations
+
+class A:
+    def __lt__(self, other) -> A: ...
+
+class B:
+    def __lt__(self, other) -> B: ...
+
+class C:
+    def __lt__(self, other) -> C: ...
+
+x = A() < B() < C()
+reveal_type(x)  # revealed: A | B
+
+y = 0 < 1 < A() < 3
+reveal_type(y)  # revealed: bool | A
+
+z = 10 < 0 < A() < B() < C()
+reveal_type(z)  # revealed: Literal[False]
+```

crates/red_knot_python_semantic/resources/mdtest/comparison/strings.md

@@ -0,0 +1,20 @@
+# Comparison: Strings
+
+## String literals
+
+```py
+def str_instance() -> str: ...
+
+reveal_type("abc" == "abc")  # revealed: Literal[True]
+reveal_type("ab_cd" <= "ab_ce")  # revealed: Literal[True]
+reveal_type("abc" in "ab cd")  # revealed: Literal[False]
+reveal_type("" not in "hello")  # revealed: Literal[False]
+reveal_type("--" is "--")  # revealed: bool
+reveal_type("A" is "B")  # revealed: Literal[False]
+reveal_type("--" is not "--")  # revealed: bool
+reveal_type("A" is not "B")  # revealed: Literal[True]
+reveal_type(str_instance() < "...")  # revealed: bool
+
+# ensure we're not comparing the interned salsa symbols, which compare by order of declaration.
+reveal_type("ab" < "ab_cd")  # revealed: Literal[True]
+```

crates/red_knot_python_semantic/resources/mdtest/comparison/tuples.md

@@ -0,0 +1,204 @@
+# Comparison: Tuples
+
+## Heterogeneous
+
+For tuples like `tuple[int, str, Literal[1]]`
+
+### Value Comparisons
+
+"Value Comparisons" refers to the operators: `==`, `!=`, `<`, `<=`, `>`, `>=`
+
+#### Results without Ambiguity
+
+Cases where the result can be definitively inferred as a `BooleanLiteral`.
+
+```py
+a = (1, "test", (3, 13), True)
+b = (1, "test", (3, 14), False)
+
+reveal_type(a == a)  # revealed: Literal[True]
+reveal_type(a != a)  # revealed: Literal[False]
+reveal_type(a < a)  # revealed: Literal[False]
+reveal_type(a <= a)  # revealed: Literal[True]
+reveal_type(a > a)  # revealed: Literal[False]
+reveal_type(a >= a)  # revealed: Literal[True]
+
+reveal_type(a == b)  # revealed: Literal[False]
+reveal_type(a != b)  # revealed: Literal[True]
+reveal_type(a < b)  # revealed: Literal[True]
+reveal_type(a <= b)  # revealed: Literal[True]
+reveal_type(a > b)  # revealed: Literal[False]
+reveal_type(a >= b)  # revealed: Literal[False]
+```
+
+Even when tuples have different lengths, comparisons should be handled appropriately.
+
+```py path=different_length.py
+a = (1, 2, 3)
+b = (1, 2, 3, 4)
+
+reveal_type(a == b)  # revealed: Literal[False]
+reveal_type(a != b)  # revealed: Literal[True]
+reveal_type(a < b)  # revealed: Literal[True]
+reveal_type(a <= b)  # revealed: Literal[True]
+reveal_type(a > b)  # revealed: Literal[False]
+reveal_type(a >= b)  # revealed: Literal[False]
+
+c = ("a", "b", "c", "d")
+d = ("a", "b", "c")
+
+reveal_type(c == d)  # revealed: Literal[False]
+reveal_type(c != d)  # revealed: Literal[True]
+reveal_type(c < d)  # revealed: Literal[False]
+reveal_type(c <= d)  # revealed: Literal[False]
+reveal_type(c > d)  # revealed: Literal[True]
+reveal_type(c >= d)  # revealed: Literal[True]
+```
+
+#### Results with Ambiguity
+
+```py
+def bool_instance() -> bool: ...
+def int_instance() -> int:
+    return 42
+
+a = (bool_instance(),)
+b = (int_instance(),)
+
+reveal_type(a == a)  # revealed: bool
+reveal_type(a != a)  # revealed: bool
+reveal_type(a < a)  # revealed: bool
+reveal_type(a <= a)  # revealed: bool
+reveal_type(a > a)  # revealed: bool
+reveal_type(a >= a)  # revealed: bool
+
+reveal_type(a == b)  # revealed: bool
+reveal_type(a != b)  # revealed: bool
+reveal_type(a < b)  # revealed: bool
+reveal_type(a <= b)  # revealed: bool
+reveal_type(a > b)  # revealed: bool
+reveal_type(a >= b)  # revealed: bool
+```
+
+#### Comparison Unsupported
+
+If two tuples contain types that do not support comparison, the result may be `Unknown`. However,
+`==` and `!=` are exceptions and can still provide definite results.
+
+```py
+a = (1, 2)
+b = (1, "hello")
+
+# TODO: should be Literal[False], once we implement (in)equality for mismatched literals
+reveal_type(a == b)  # revealed: bool
+
+# TODO: should be Literal[True], once we implement (in)equality for mismatched literals
+reveal_type(a != b)  # revealed: bool
+
+# TODO: should be Unknown and add more informative diagnostics
+reveal_type(a < b)  # revealed: bool
+reveal_type(a <= b)  # revealed: bool
+reveal_type(a > b)  # revealed: bool
+reveal_type(a >= b)  # revealed: bool
+```
+
+However, if the lexicographic comparison completes without reaching a point where str and int are
+compared, Python will still produce a result based on the prior elements.
+
+```py path=short_circuit.py
+a = (1, 2)
+b = (999999, "hello")
+
+reveal_type(a == b)  # revealed: Literal[False]
+reveal_type(a != b)  # revealed: Literal[True]
+reveal_type(a < b)  # revealed: Literal[True]
+reveal_type(a <= b)  # revealed: Literal[True]
+reveal_type(a > b)  # revealed: Literal[False]
+reveal_type(a >= b)  # revealed: Literal[False]
+```
+
+#### Matryoshka Tuples
+
+```py
+a = (1, True, "Hello")
+b = (a, a, a)
+c = (b, b, b)
+
+reveal_type(c == c)  # revealed: Literal[True]
+reveal_type(c != c)  # revealed: Literal[False]
+reveal_type(c < c)  # revealed: Literal[False]
+reveal_type(c <= c)  # revealed: Literal[True]
+reveal_type(c > c)  # revealed: Literal[False]
+reveal_type(c >= c)  # revealed: Literal[True]
+```
+
+#### Non Boolean Rich Comparisons
+
+```py
+class A:
+    def __eq__(self, o) -> str: ...
+    def __ne__(self, o) -> int: ...
+    def __lt__(self, o) -> float: ...
+    def __le__(self, o) -> object: ...
+    def __gt__(self, o) -> tuple: ...
+    def __ge__(self, o) -> list: ...
+
+a = (A(), A())
+
+reveal_type(a == a)  # revealed: bool
+reveal_type(a != a)  # revealed: bool
+reveal_type(a < a)  # revealed: bool
+reveal_type(a <= a)  # revealed: bool
+reveal_type(a > a)  # revealed: bool
+reveal_type(a >= a)  # revealed: bool
+```
+
+### Membership Test Comparisons
+
+"Membership Test Comparisons" refers to the operators `in` and `not in`.
+
+```py
+def int_instance() -> int:
+    return 42
+
+a = (1, 2)
+b = ((3, 4), (1, 2))
+c = ((1, 2, 3), (4, 5, 6))
+d = ((int_instance(), int_instance()), (int_instance(), int_instance()))
+
+reveal_type(a in b)  # revealed: Literal[True]
+reveal_type(a not in b)  # revealed: Literal[False]
+
+reveal_type(a in c)  # revealed: Literal[False]
+reveal_type(a not in c)  # revealed: Literal[True]
+
+reveal_type(a in d)  # revealed: bool
+reveal_type(a not in d)  # revealed: bool
+```
+
+### Identity Comparisons
+
+"Identity Comparisons" refers to `is` and `is not`.
+
+```py
+a = (1, 2)
+b = ("a", "b")
+c = (1, 2, 3)
+
+reveal_type(a is (1, 2))  # revealed: bool
+reveal_type(a is not (1, 2))  # revealed: bool
+
+# TODO should be Literal[False] once we implement comparison of mismatched literal types
+reveal_type(a is b)  # revealed: bool
+# TODO should be Literal[True] once we implement comparison of mismatched literal types
+reveal_type(a is not b)  # revealed: bool
+
+reveal_type(a is c)  # revealed: Literal[False]
+reveal_type(a is not c)  # revealed: Literal[True]
+```
+
+## Homogeneous
+
+For tuples like `tuple[int, ...]`, `tuple[Any, ...]`
+
+// TODO

crates/red_knot_python_semantic/resources/mdtest/comparison/unions.md

@@ -0,0 +1,88 @@
+# Comparison: Unions
+
+## Union on one side of the comparison
+
+Comparisons on union types need to consider all possible cases:
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+one_or_two = 1 if flag else 2
+
+reveal_type(one_or_two <= 2)  # revealed: Literal[True]
+reveal_type(one_or_two <= 1)  # revealed: bool
+reveal_type(one_or_two <= 0)  # revealed: Literal[False]
+
+reveal_type(2 >= one_or_two)  # revealed: Literal[True]
+reveal_type(1 >= one_or_two)  # revealed: bool
+reveal_type(0 >= one_or_two)  # revealed: Literal[False]
+
+reveal_type(one_or_two < 1)  # revealed: Literal[False]
+reveal_type(one_or_two < 2)  # revealed: bool
+reveal_type(one_or_two < 3)  # revealed: Literal[True]
+
+reveal_type(one_or_two > 0)  # revealed: Literal[True]
+reveal_type(one_or_two > 1)  # revealed: bool
+reveal_type(one_or_two > 2)  # revealed: Literal[False]
+
+reveal_type(one_or_two == 3)  # revealed: Literal[False]
+reveal_type(one_or_two == 1)  # revealed: bool
+
+reveal_type(one_or_two != 3)  # revealed: Literal[True]
+reveal_type(one_or_two != 1)  # revealed: bool
+
+a_or_ab = "a" if flag else "ab"
+
+reveal_type(a_or_ab in "ab")  # revealed: Literal[True]
+reveal_type("a" in a_or_ab)  # revealed: Literal[True]
+
+reveal_type("c" not in a_or_ab)  # revealed: Literal[True]
+reveal_type("a" not in a_or_ab)  # revealed: Literal[False]
+
+reveal_type("b" in a_or_ab)  # revealed: bool
+reveal_type("b" not in a_or_ab)  # revealed: bool
+
+one_or_none = 1 if flag else None
+
+reveal_type(one_or_none is None)  # revealed: bool
+reveal_type(one_or_none is not None)  # revealed: bool
+```
+
+## Union on both sides of the comparison
+
+With unions on both sides, we need to consider the full cross product of options when building the
+resulting (union) type:
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag_s, flag_l = bool_instance(), bool_instance()
+small = 1 if flag_s else 2
+large = 2 if flag_l else 3
+
+reveal_type(small <= large)  # revealed: Literal[True]
+reveal_type(small >= large)  # revealed: bool
+
+reveal_type(small < large)  # revealed: bool
+reveal_type(small > large)  # revealed: Literal[False]
+```
+
+## Unsupported operations
+
+Make sure we emit a diagnostic if *any* of the possible comparisons is unsupported. For now, we fall
+back to `bool` for the result type instead of trying to infer something more precise from the other
+(supported) variants:
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = [1, 2] if flag else 1
+
+result = 1 in x  # error: "Operator `in` is not supported"
+reveal_type(result)  # revealed: bool
+```

crates/red_knot_python_semantic/resources/mdtest/comparison/unsupported.md

@@ -0,0 +1,36 @@
+# Comparison: Unsupported operators
+
+```py
+def bool_instance() -> bool:
+    return True
+
+a = 1 in 7  # error: "Operator `in` is not supported for types `Literal[1]` and `Literal[7]`"
+reveal_type(a)  # revealed: bool
+
+b = 0 not in 10  # error: "Operator `not in` is not supported for types `Literal[0]` and `Literal[10]`"
+reveal_type(b)  # revealed: bool
+
+# TODO: should error, once operand type check is implemented
+# ("Operator `<` is not supported for types `object` and `int`")
+c = object() < 5
+# TODO: should be Unknown, once operand type check is implemented
+reveal_type(c)  # revealed: bool
+
+# TODO: should error, once operand type check is implemented
+# ("Operator `<` is not supported for types `int` and `object`")
+d = 5 < object()
+# TODO: should be Unknown, once operand type check is implemented
+reveal_type(d)  # revealed: bool
+
+flag = bool_instance()
+int_literal_or_str_literal = 1 if flag else "foo"
+# error: "Operator `in` is not supported for types `Literal[42]` and `Literal[1]`, in comparing `Literal[42]` with `Literal[1] | Literal["foo"]`"
+e = 42 in int_literal_or_str_literal
+reveal_type(e)  # revealed: bool
+
+# TODO: should error, need to check if __lt__ signature is valid for right operand
+# error may be "Operator `<` is not supported for types `int` and `str`, in comparing `tuple[Literal[1], Literal[2]]` with `tuple[Literal[1], Literal["hello"]]`
+f = (1, 2) < (1, "hello")
+# TODO: should be Unknown, once operand type check is implemented
+reveal_type(f)  # revealed: bool
+```

crates/red_knot_python_semantic/resources/mdtest/conditional/if_expression.md

@@ -0,0 +1,49 @@
+# If expressions
+
+## Simple if-expression
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = 1 if flag else 2
+reveal_type(x)  # revealed: Literal[1, 2]
+```
+
+## If-expression with walrus operator
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+y = 0
+z = 0
+x = (y := 1) if flag else (z := 2)
+reveal_type(x)  # revealed: Literal[1, 2]
+reveal_type(y)  # revealed: Literal[0, 1]
+reveal_type(z)  # revealed: Literal[0, 2]
+```
+
+## Nested if-expression
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag, flag2 = bool_instance(), bool_instance()
+x = 1 if flag else 2 if flag2 else 3
+reveal_type(x)  # revealed: Literal[1, 2, 3]
+```
+
+## None
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = 1 if flag else None
+reveal_type(x)  # revealed: Literal[1] | None
+```

crates/red_knot_python_semantic/resources/mdtest/conditional/if_statement.md

@@ -0,0 +1,130 @@
+# If statements
+
+## Simple if
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+y = 1
+y = 2
+
+if flag:
+    y = 3
+
+reveal_type(y)  # revealed: Literal[2, 3]
+```
+
+## Simple if-elif-else
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag, flag2 = bool_instance(), bool_instance()
+y = 1
+y = 2
+if flag:
+    y = 3
+elif flag2:
+    y = 4
+else:
+    r = y
+    y = 5
+    s = y
+x = y
+
+reveal_type(x)  # revealed: Literal[3, 4, 5]
+
+# revealed: Literal[2]
+# error: [possibly-unresolved-reference]
+reveal_type(r)
+
+# revealed: Literal[5]
+# error: [possibly-unresolved-reference]
+reveal_type(s)
+```
+
+## Single symbol across if-elif-else
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag, flag2 = bool_instance(), bool_instance()
+
+if flag:
+    y = 1
+elif flag2:
+    y = 2
+else:
+    y = 3
+reveal_type(y)  # revealed: Literal[1, 2, 3]
+```
+
+## if-elif-else without else assignment
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag, flag2 = bool_instance(), bool_instance()
+y = 0
+if flag:
+    y = 1
+elif flag2:
+    y = 2
+else:
+    pass
+reveal_type(y)  # revealed: Literal[0, 1, 2]
+```
+
+## if-elif-else with intervening assignment
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag, flag2 = bool_instance(), bool_instance()
+y = 0
+if flag:
+    y = 1
+    z = 3
+elif flag2:
+    y = 2
+else:
+    pass
+reveal_type(y)  # revealed: Literal[0, 1, 2]
+```
+
+## Nested if statement
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag, flag2 = bool_instance(), bool_instance()
+y = 0
+if flag:
+    if flag2:
+        y = 1
+reveal_type(y)  # revealed: Literal[0, 1]
+```
+
+## if-elif without else
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag, flag2 = bool_instance(), bool_instance()
+y = 1
+y = 2
+if flag:
+    y = 3
+elif flag2:
+    y = 4
+
+reveal_type(y)  # revealed: Literal[2, 3, 4]
+```

crates/red_knot_python_semantic/resources/mdtest/conditional/match.md

@@ -0,0 +1,41 @@
+# Pattern matching
+
+## With wildcard
+
+```py
+match 0:
+    case 1:
+        y = 2
+    case _:
+        y = 3
+
+reveal_type(y)  # revealed: Literal[2, 3]
+```
+
+## Without wildcard
+
+```py
+match 0:
+    case 1:
+        y = 2
+    case 2:
+        y = 3
+
+# revealed: Literal[2, 3]
+# error: [possibly-unresolved-reference]
+reveal_type(y)
+```
+
+## Basic match
+
+```py
+y = 1
+y = 2
+match 0:
+    case 1:
+        y = 3
+    case 2:
+        y = 4
+
+reveal_type(y)  # revealed: Literal[2, 3, 4]
+```

crates/red_knot_python_semantic/resources/mdtest/declaration/error.md

@@ -0,0 +1,51 @@
+# Errors while declaring
+
+## Violates previous assignment
+
+```py
+x = 1
+x: str  # error: [invalid-declaration] "Cannot declare type `str` for inferred type `Literal[1]`"
+```
+
+## Incompatible declarations
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+if flag:
+    x: str
+else:
+    x: int
+x = 1  # error: [conflicting-declarations] "Conflicting declared types for `x`: str, int"
+```
+
+## Partial declarations
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+if flag:
+    x: int
+x = 1  # error: [conflicting-declarations] "Conflicting declared types for `x`: Unknown, int"
+```
+
+## Incompatible declarations with bad assignment
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+if flag:
+    x: str
+else:
+    x: int
+
+# error: [conflicting-declarations]
+# error: [invalid-assignment]
+x = b"foo"
+```

crates/red_knot_python_semantic/resources/mdtest/exception/basic.md

@@ -0,0 +1,61 @@
+# Exception Handling
+
+## Single Exception
+
+```py
+import re
+
+try:
+    help()
+except NameError as e:
+    reveal_type(e)  # revealed: NameError
+except re.error as f:
+    reveal_type(f)  # revealed: error
+```
+
+## Unknown type in except handler does not cause spurious diagnostic
+
+```py
+from nonexistent_module import foo  # error: [unresolved-import]
+
+try:
+    help()
+except foo as e:
+    reveal_type(foo)  # revealed: Unknown
+    reveal_type(e)  # revealed: Unknown
+```
+
+## Multiple Exceptions in a Tuple
+
+```py
+EXCEPTIONS = (AttributeError, TypeError)
+
+try:
+    help()
+except (RuntimeError, OSError) as e:
+    reveal_type(e)  # revealed: RuntimeError | OSError
+except EXCEPTIONS as f:
+    reveal_type(f)  # revealed: AttributeError | TypeError
+```
+
+## Dynamic exception types
+
+```py
+# TODO: we should not emit these `call-possibly-unbound-method` errors for `tuple.__class_getitem__`
+def foo(
+    x: type[AttributeError],
+    y: tuple[type[OSError], type[RuntimeError]],  # error: [call-possibly-unbound-method]
+    z: tuple[type[BaseException], ...],  # error: [call-possibly-unbound-method]
+):
+    try:
+        help()
+    except x as e:
+        # TODO: should be `AttributeError`
+        reveal_type(e)  # revealed: @Todo
+    except y as f:
+        # TODO: should be `OSError | RuntimeError`
+        reveal_type(f)  # revealed: @Todo
+    except z as g:
+        # TODO: should be `BaseException`
+        reveal_type(g)  # revealed: @Todo
+```

crates/red_knot_python_semantic/resources/mdtest/exception/control_flow.md

@@ -0,0 +1,622 @@
+# Control flow for exception handlers
+
+These tests assert that we understand the possible "definition states" (which symbols might or might
+not be defined) in the various branches of a `try`/`except`/`else`/`finally` block.
+
+For a full writeup on the semantics of exception handlers, see [this document][1].
+
+The tests throughout this Markdown document use functions with names starting with `could_raise_*`
+to mark definitions that might or might not succeed (as the function could raise an exception). A
+type checker must assume that any arbitrary function call could raise an exception in Python; this
+is just a naming convention used in these tests for clarity, and to future-proof the tests against
+possible future improvements whereby certain statements or expressions could potentially be inferred
+as being incapable of causing an exception to be raised.
+
+## A single bare `except`
+
+Consider the following `try`/`except` block, with a single bare `except:`. There are different types
+for the variable `x` in the two branches of this block, and we can't determine which branch might
+have been taken from the perspective of code following this block. The inferred type after the
+block's conclusion is therefore the union of the type at the end of the `try` suite (`str`) and the
+type at the end of the `except` suite (`Literal[2]`).
+
+*Within* the `except` suite, we must infer a union of all possible "definition states" we could have
+been in at any point during the `try` suite. This is because control flow could have jumped to the
+`except` suite without any of the `try`-suite definitions successfully completing, with only *some*
+of the `try`-suite definitions successfully completing, or indeed with *all* of them successfully
+completing. The type of `x` at the beginning of the `except` suite in this example is therefore
+`Literal[1] | str`, taking into account that we might have jumped to the `except` suite before the
+`x = could_raise_returns_str()` redefinition, but we *also* could have jumped to the `except` suite
+*after* that redefinition.
+
+```py path=union_type_inferred.py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+x = 1
+
+try:
+    reveal_type(x)  # revealed: Literal[1]
+    x = could_raise_returns_str()
+    reveal_type(x)  # revealed: str
+except:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = 2
+    reveal_type(x)  # revealed: Literal[2]
+
+reveal_type(x)  # revealed: str | Literal[2]
+```
+
+If `x` has the same type at the end of both branches, however, the branches unify and `x` is not
+inferred as having a union type following the `try`/`except` block:
+
+```py path=branches_unify_to_non_union_type.py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+x = 1
+
+try:
+    x = could_raise_returns_str()
+except:
+    x = could_raise_returns_str()
+
+reveal_type(x)  # revealed: str
+```
+
+## A non-bare `except`
+
+For simple `try`/`except` blocks, an `except TypeError:` handler has the same control flow semantics
+as an `except:` handler. An `except TypeError:` handler will not catch *all* exceptions: if this is
+the only handler, it opens up the possibility that an exception might occur that would not be
+handled. However, as described in [the document on exception-handling semantics][1], that would lead
+to termination of the scope. It's therefore irrelevant to consider this possibility when it comes to
+control-flow analysis.
+
+```py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+x = 1
+
+try:
+    reveal_type(x)  # revealed: Literal[1]
+    x = could_raise_returns_str()
+    reveal_type(x)  # revealed: str
+except TypeError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = 2
+    reveal_type(x)  # revealed: Literal[2]
+
+reveal_type(x)  # revealed: str | Literal[2]
+```
+
+## Multiple `except` branches
+
+If the scope reaches the final `reveal_type` call in this example, either the `try`-block suite of
+statements was executed in its entirety, or exactly one `except` suite was executed in its entirety.
+The inferred type of `x` at this point is the union of the types at the end of the three suites:
+
+- At the end of `try`, `type(x) == str`
+- At the end of `except TypeError`, `x == 2`
+- At the end of `except ValueError`, `x == 3`
+
+```py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+x = 1
+
+try:
+    reveal_type(x)  # revealed: Literal[1]
+    x = could_raise_returns_str()
+    reveal_type(x)  # revealed: str
+except TypeError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = 2
+    reveal_type(x)  # revealed: Literal[2]
+except ValueError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = 3
+    reveal_type(x)  # revealed: Literal[3]
+
+reveal_type(x)  # revealed: str | Literal[2, 3]
+```
+
+## Exception handlers with `else` branches (but no `finally`)
+
+If we reach the `reveal_type` call at the end of this scope, either the `try` and `else` suites were
+both executed in their entireties, or the `except` suite was executed in its entirety. The type of
+`x` at this point is the union of the type at the end of the `else` suite and the type at the end of
+the `except` suite:
+
+- At the end of `else`, `x == 3`
+- At the end of `except`, `x == 2`
+
+```py path=single_except.py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+x = 1
+
+try:
+    reveal_type(x)  # revealed: Literal[1]
+    x = could_raise_returns_str()
+    reveal_type(x)  # revealed: str
+except TypeError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = 2
+    reveal_type(x)  # revealed: Literal[2]
+else:
+    reveal_type(x)  # revealed: str
+    x = 3
+    reveal_type(x)  # revealed: Literal[3]
+
+reveal_type(x)  # revealed: Literal[2, 3]
+```
+
+For a block that has multiple `except` branches and an `else` branch, the same principle applies. In
+order to reach the final `reveal_type` call, either exactly one of the `except` suites must have
+been executed in its entirety, or the `try` suite and the `else` suite must both have been executed
+in their entireties:
+
+```py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+x = 1
+
+try:
+    reveal_type(x)  # revealed: Literal[1]
+    x = could_raise_returns_str()
+    reveal_type(x)  # revealed: str
+except TypeError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = 2
+    reveal_type(x)  # revealed: Literal[2]
+except ValueError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = 3
+    reveal_type(x)  # revealed: Literal[3]
+else:
+    reveal_type(x)  # revealed: str
+    x = 4
+    reveal_type(x)  # revealed: Literal[4]
+
+reveal_type(x)  # revealed: Literal[2, 3, 4]
+```
+
+## Exception handlers with `finally` branches (but no `except` branches)
+
+A `finally` suite is *always* executed. As such, if we reach the `reveal_type` call at the end of
+this example, we know that `x` *must* have been reassigned to `2` during the `finally` suite. The
+type of `x` at the end of the example is therefore `Literal[2]`:
+
+```py path=redef_in_finally.py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+x = 1
+
+try:
+    reveal_type(x)  # revealed: Literal[1]
+    x = could_raise_returns_str()
+    reveal_type(x)  # revealed: str
+finally:
+    x = 2
+    reveal_type(x)  # revealed: Literal[2]
+
+reveal_type(x)  # revealed: Literal[2]
+```
+
+If `x` was *not* redefined in the `finally` suite, however, things are somewhat more complicated. If
+we reach the final `reveal_type` call, unlike the state when we're visiting the `finally` suite, we
+know that the `try`-block suite ran to completion. This means that there are fewer possible states
+at this point than there were when we were inside the `finally` block.
+
+(Our current model does *not* correctly infer the types *inside* `finally` suites, however; this is
+still a TODO item for us.)
+
+```py path=no_redef_in_finally.py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+x = 1
+
+try:
+    reveal_type(x)  # revealed: Literal[1]
+    x = could_raise_returns_str()
+    reveal_type(x)  # revealed: str
+finally:
+    # TODO: should be Literal[1] | str
+    reveal_type(x)  # revealed: str
+
+reveal_type(x)  # revealed: str
+```
+
+## Combining an `except` branch with a `finally` branch
+
+As previously stated, we do not yet have accurate inference for types *inside* `finally` suites.
+When we do, however, we will have to take account of the following possibilities inside `finally`
+suites:
+
+- The `try` suite could have run to completion
+- Or we could have jumped from halfway through the `try` suite to an `except` suite, and the
+    `except` suite ran to completion
+- Or we could have jumped from halfway through the `try` suite straight to the `finally` suite due
+    to an unhandled exception
+- Or we could have jumped from halfway through the `try` suite to an `except` suite, only for an
+    exception raised in the `except` suite to cause us to jump to the `finally` suite before the
+    `except` suite ran to completion
+
+```py path=redef_in_finally.py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+def could_raise_returns_bytes() -> bytes:
+    return b"foo"
+
+def could_raise_returns_bool() -> bool:
+    return True
+
+x = 1
+
+try:
+    reveal_type(x)  # revealed: Literal[1]
+    x = could_raise_returns_str()
+    reveal_type(x)  # revealed: str
+except TypeError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = could_raise_returns_bytes()
+    reveal_type(x)  # revealed: bytes
+    x = could_raise_returns_bool()
+    reveal_type(x)  # revealed: bool
+finally:
+    # TODO: should be `Literal[1] | str | bytes | bool`
+    reveal_type(x)  # revealed: str | bool
+    x = 2
+    reveal_type(x)  # revealed: Literal[2]
+
+reveal_type(x)  # revealed: Literal[2]
+```
+
+Now for an example without a redefinition in the `finally` suite. As before, there *should* be fewer
+possibilities after completion of the `finally` suite than there were during the `finally` suite
+itself. (In some control-flow possibilities, some exceptions were merely *suspended* during the
+`finally` suite; these lead to the scope's termination following the conclusion of the `finally`
+suite.)
+
+```py path=no_redef_in_finally.py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+def could_raise_returns_bytes() -> bytes:
+    return b"foo"
+
+def could_raise_returns_bool() -> bool:
+    return True
+
+x = 1
+
+try:
+    reveal_type(x)  # revealed: Literal[1]
+    x = could_raise_returns_str()
+    reveal_type(x)  # revealed: str
+except TypeError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = could_raise_returns_bytes()
+    reveal_type(x)  # revealed: bytes
+    x = could_raise_returns_bool()
+    reveal_type(x)  # revealed: bool
+finally:
+    # TODO: should be `Literal[1] | str | bytes | bool`
+    reveal_type(x)  # revealed: str | bool
+
+reveal_type(x)  # revealed: str | bool
+```
+
+An example with multiple `except` branches and a `finally` branch:
+
+```py path=multiple_except_branches.py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+def could_raise_returns_bytes() -> bytes:
+    return b"foo"
+
+def could_raise_returns_bool() -> bool:
+    return True
+
+def could_raise_returns_memoryview() -> memoryview:
+    return memoryview(b"")
+
+def could_raise_returns_float() -> float:
+    return 3.14
+
+x = 1
+
+try:
+    reveal_type(x)  # revealed: Literal[1]
+    x = could_raise_returns_str()
+    reveal_type(x)  # revealed: str
+except TypeError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = could_raise_returns_bytes()
+    reveal_type(x)  # revealed: bytes
+    x = could_raise_returns_bool()
+    reveal_type(x)  # revealed: bool
+except ValueError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = could_raise_returns_memoryview()
+    reveal_type(x)  # revealed: memoryview
+    x = could_raise_returns_float()
+    reveal_type(x)  # revealed: float
+finally:
+    # TODO: should be `Literal[1] | str | bytes | bool | memoryview | float`
+    reveal_type(x)  # revealed: str | bool | float
+
+reveal_type(x)  # revealed: str | bool | float
+```
+
+## Combining `except`, `else` and `finally` branches
+
+If the exception handler has an `else` branch, we must also take into account the possibility that
+control flow could have jumped to the `finally` suite from partway through the `else` suite due to
+an exception raised *there*.
+
+```py path=single_except_branch.py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+def could_raise_returns_bytes() -> bytes:
+    return b"foo"
+
+def could_raise_returns_bool() -> bool:
+    return True
+
+def could_raise_returns_memoryview() -> memoryview:
+    return memoryview(b"")
+
+def could_raise_returns_float() -> float:
+    return 3.14
+
+x = 1
+
+try:
+    reveal_type(x)  # revealed: Literal[1]
+    x = could_raise_returns_str()
+    reveal_type(x)  # revealed: str
+except TypeError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = could_raise_returns_bytes()
+    reveal_type(x)  # revealed: bytes
+    x = could_raise_returns_bool()
+    reveal_type(x)  # revealed: bool
+else:
+    reveal_type(x)  # revealed: str
+    x = could_raise_returns_memoryview()
+    reveal_type(x)  # revealed: memoryview
+    x = could_raise_returns_float()
+    reveal_type(x)  # revealed: float
+finally:
+    # TODO: should be `Literal[1] | str | bytes | bool | memoryview | float`
+    reveal_type(x)  # revealed: bool | float
+
+reveal_type(x)  # revealed: bool | float
+```
+
+The same again, this time with multiple `except` branches:
+
+```py path=multiple_except_branches.py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+def could_raise_returns_bytes() -> bytes:
+    return b"foo"
+
+def could_raise_returns_bool() -> bool:
+    return True
+
+def could_raise_returns_memoryview() -> memoryview:
+    return memoryview(b"")
+
+def could_raise_returns_float() -> float:
+    return 3.14
+
+def could_raise_returns_range() -> range:
+    return range(42)
+
+def could_raise_returns_slice() -> slice:
+    return slice(None)
+
+x = 1
+
+try:
+    reveal_type(x)  # revealed: Literal[1]
+    x = could_raise_returns_str()
+    reveal_type(x)  # revealed: str
+except TypeError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = could_raise_returns_bytes()
+    reveal_type(x)  # revealed: bytes
+    x = could_raise_returns_bool()
+    reveal_type(x)  # revealed: bool
+except ValueError:
+    reveal_type(x)  # revealed: Literal[1] | str
+    x = could_raise_returns_memoryview()
+    reveal_type(x)  # revealed: memoryview
+    x = could_raise_returns_float()
+    reveal_type(x)  # revealed: float
+else:
+    reveal_type(x)  # revealed: str
+    x = could_raise_returns_range()
+    reveal_type(x)  # revealed: range
+    x = could_raise_returns_slice()
+    reveal_type(x)  # revealed: slice
+finally:
+    # TODO: should be `Literal[1] | str | bytes | bool | memoryview | float | range | slice`
+    reveal_type(x)  # revealed: bool | float | slice
+
+reveal_type(x)  # revealed: bool | float | slice
+```
+
+## Nested `try`/`except` blocks
+
+It would take advanced analysis, which we are not yet capable of, to be able to determine that an
+exception handler always suppresses all exceptions. This is partly because it is possible for
+statements in `except`, `else` and `finally` suites to raise exceptions as well as statements in
+`try` suites. This means that if an exception handler is nested inside the `try` statement of an
+enclosing exception handler, it should (at least for now) be treated the same as any other node: as
+a suite containing statements that could possibly raise exceptions, which would lead to control flow
+jumping out of that suite prior to the suite running to completion.
+
+```py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+def could_raise_returns_bytes() -> bytes:
+    return b"foo"
+
+def could_raise_returns_bool() -> bool:
+    return True
+
+def could_raise_returns_memoryview() -> memoryview:
+    return memoryview(b"")
+
+def could_raise_returns_float() -> float:
+    return 3.14
+
+def could_raise_returns_range() -> range:
+    return range(42)
+
+def could_raise_returns_slice() -> slice:
+    return slice(None)
+
+def could_raise_returns_complex() -> complex:
+    return 3j
+
+def could_raise_returns_bytearray() -> bytearray:
+    return bytearray()
+
+class Foo: ...
+class Bar: ...
+
+def could_raise_returns_Foo() -> Foo:
+    return Foo()
+
+def could_raise_returns_Bar() -> Bar:
+    return Bar()
+
+x = 1
+
+try:
+    try:
+        reveal_type(x)  # revealed: Literal[1]
+        x = could_raise_returns_str()
+        reveal_type(x)  # revealed: str
+    except TypeError:
+        reveal_type(x)  # revealed: Literal[1] | str
+        x = could_raise_returns_bytes()
+        reveal_type(x)  # revealed: bytes
+        x = could_raise_returns_bool()
+        reveal_type(x)  # revealed: bool
+    except ValueError:
+        reveal_type(x)  # revealed: Literal[1] | str
+        x = could_raise_returns_memoryview()
+        reveal_type(x)  # revealed: memoryview
+        x = could_raise_returns_float()
+        reveal_type(x)  # revealed: float
+    else:
+        reveal_type(x)  # revealed: str
+        x = could_raise_returns_range()
+        reveal_type(x)  # revealed: range
+        x = could_raise_returns_slice()
+        reveal_type(x)  # revealed: slice
+    finally:
+        # TODO: should be `Literal[1] | str | bytes | bool | memoryview | float | range | slice`
+        reveal_type(x)  # revealed: bool | float | slice
+        x = 2
+        reveal_type(x)  # revealed: Literal[2]
+    reveal_type(x)  # revealed: Literal[2]
+except:
+    reveal_type(x)  # revealed: Literal[1, 2] | str | bytes | bool | memoryview | float | range | slice
+    x = could_raise_returns_complex()
+    reveal_type(x)  # revealed: complex
+    x = could_raise_returns_bytearray()
+    reveal_type(x)  # revealed: bytearray
+else:
+    reveal_type(x)  # revealed: Literal[2]
+    x = could_raise_returns_Foo()
+    reveal_type(x)  # revealed: Foo
+    x = could_raise_returns_Bar()
+    reveal_type(x)  # revealed: Bar
+finally:
+    # TODO: should be `Literal[1, 2] | str | bytes | bool | memoryview | float | range | slice | complex | bytearray | Foo | Bar`
+    reveal_type(x)  # revealed: bytearray | Bar
+
+# Either one `except` branch or the `else`
+# must have been taken and completed to get here:
+reveal_type(x)  # revealed: bytearray | Bar
+```
+
+## Nested scopes inside `try` blocks
+
+Shadowing a variable in an inner scope has no effect on type inference of the variable by that name
+in the outer scope:
+
+```py
+def could_raise_returns_str() -> str:
+    return "foo"
+
+def could_raise_returns_bytes() -> bytes:
+    return b"foo"
+
+def could_raise_returns_range() -> range:
+    return range(42)
+
+def could_raise_returns_bytearray() -> bytearray:
+    return bytearray()
+
+def could_raise_returns_float() -> float:
+    return 3.14
+
+x = 1
+
+try:
+
+    def foo(param=could_raise_returns_str()):
+        x = could_raise_returns_str()
+
+        try:
+            reveal_type(x)  # revealed: str
+            x = could_raise_returns_bytes()
+            reveal_type(x)  # revealed: bytes
+        except:
+            reveal_type(x)  # revealed: str | bytes
+            x = could_raise_returns_bytearray()
+            reveal_type(x)  # revealed: bytearray
+            x = could_raise_returns_float()
+            reveal_type(x)  # revealed: float
+        finally:
+            # TODO: should be `str | bytes | bytearray | float`
+            reveal_type(x)  # revealed: bytes | float
+        reveal_type(x)  # revealed: bytes | float
+    x = foo
+    reveal_type(x)  # revealed: Literal[foo]
+except:
+    reveal_type(x)  # revealed: Literal[1] | Literal[foo]
+
+    class Bar:
+        x = could_raise_returns_range()
+        reveal_type(x)  # revealed: range
+
+    x = Bar
+    reveal_type(x)  # revealed: Literal[Bar]
+finally:
+    # TODO: should be `Literal[1] | Literal[foo] | Literal[Bar]`
+    reveal_type(x)  # revealed: Literal[foo] | Literal[Bar]
+
+reveal_type(x)  # revealed: Literal[foo] | Literal[Bar]
+```
+
+[1]: https://astral-sh.notion.site/Exception-handler-control-flow-11348797e1ca80bb8ce1e9aedbbe439d

crates/red_knot_python_semantic/resources/mdtest/exception/except_star.md

@@ -0,0 +1,30 @@
+# Except star
+
+## Except\* with BaseException
+
+```py
+try:
+    help()
+except* BaseException as e:
+    reveal_type(e)  # revealed: BaseExceptionGroup
+```
+
+## Except\* with specific exception
+
+```py
+try:
+    help()
+except* OSError as e:
+    # TODO(Alex): more precise would be `ExceptionGroup[OSError]`
+    reveal_type(e)  # revealed: BaseExceptionGroup
+```
+
+## Except\* with multiple exceptions
+
+```py
+try:
+    help()
+except* (TypeError, AttributeError) as e:
+    # TODO(Alex): more precise would be `ExceptionGroup[TypeError | AttributeError]`.
+    reveal_type(e)  # revealed: BaseExceptionGroup
+```

crates/red_knot_python_semantic/resources/mdtest/expression/boolean.md

@@ -0,0 +1,110 @@
+# Expressions
+
+## OR
+
+```py
+def foo() -> str:
+    pass
+
+reveal_type(True or False)  # revealed: Literal[True]
+reveal_type("x" or "y" or "z")  # revealed: Literal["x"]
+reveal_type("" or "y" or "z")  # revealed: Literal["y"]
+reveal_type(False or "z")  # revealed: Literal["z"]
+reveal_type(False or True)  # revealed: Literal[True]
+reveal_type(False or False)  # revealed: Literal[False]
+reveal_type(foo() or False)  # revealed: str | Literal[False]
+reveal_type(foo() or True)  # revealed: str | Literal[True]
+```
+
+## AND
+
+```py
+def foo() -> str:
+    pass
+
+reveal_type(True and False)  # revealed: Literal[False]
+reveal_type(False and True)  # revealed: Literal[False]
+reveal_type(foo() and False)  # revealed: str | Literal[False]
+reveal_type(foo() and True)  # revealed: str | Literal[True]
+reveal_type("x" and "y" and "z")  # revealed: Literal["z"]
+reveal_type("x" and "y" and "")  # revealed: Literal[""]
+reveal_type("" and "y")  # revealed: Literal[""]
+```
+
+## Simple function calls to bool
+
+```py
+def returns_bool() -> bool:
+    return True
+
+if returns_bool():
+    x = True
+else:
+    x = False
+
+reveal_type(x)  # revealed: bool
+```
+
+## Complex
+
+```py
+def foo() -> str:
+    pass
+
+reveal_type("x" and "y" or "z")  # revealed: Literal["y"]
+reveal_type("x" or "y" and "z")  # revealed: Literal["x"]
+reveal_type("" and "y" or "z")  # revealed: Literal["z"]
+reveal_type("" or "y" and "z")  # revealed: Literal["z"]
+reveal_type("x" and "y" or "")  # revealed: Literal["y"]
+reveal_type("x" or "y" and "")  # revealed: Literal["x"]
+```
+
+## `bool()` function
+
+## Evaluates to builtin
+
+```py path=a.py
+redefined_builtin_bool = bool
+
+def my_bool(x) -> bool:
+    return True
+```
+
+```py
+from a import redefined_builtin_bool, my_bool
+
+reveal_type(redefined_builtin_bool(0))  # revealed: Literal[False]
+reveal_type(my_bool(0))  # revealed: bool
+```
+
+## Truthy values
+
+```py
+reveal_type(bool(1))  # revealed: Literal[True]
+reveal_type(bool((0,)))  # revealed: Literal[True]
+reveal_type(bool("NON EMPTY"))  # revealed: Literal[True]
+reveal_type(bool(True))  # revealed: Literal[True]
+
+def foo(): ...
+
+reveal_type(bool(foo))  # revealed: Literal[True]
+```
+
+## Falsy values
+
+```py
+reveal_type(bool(0))  # revealed: Literal[False]
+reveal_type(bool(()))  # revealed: Literal[False]
+reveal_type(bool(None))  # revealed: Literal[False]
+reveal_type(bool(""))  # revealed: Literal[False]
+reveal_type(bool(False))  # revealed: Literal[False]
+reveal_type(bool())  # revealed: Literal[False]
+```
+
+## Ambiguous values
+
+```py
+reveal_type(bool([]))  # revealed: bool
+reveal_type(bool({}))  # revealed: bool
+reveal_type(bool(set()))  # revealed: bool
+```

crates/red_knot_python_semantic/resources/mdtest/generics.md

@@ -0,0 +1,68 @@
+# PEP 695 Generics
+
+## Class Declarations
+
+Basic PEP 695 generics
+
+```py
+class MyBox[T]:
+    # TODO: `T` is defined here
+    # error: [unresolved-reference] "Name `T` used when not defined"
+    data: T
+    box_model_number = 695
+
+    # TODO: `T` is defined here
+    # error: [unresolved-reference] "Name `T` used when not defined"
+    def __init__(self, data: T):
+        self.data = data
+
+box: MyBox[int] = MyBox(5)
+
+# TODO should emit a diagnostic here (str is not assignable to int)
+wrong_innards: MyBox[int] = MyBox("five")
+
+# TODO reveal int
+reveal_type(box.data)  # revealed: @Todo
+
+reveal_type(MyBox.box_model_number)  # revealed: Literal[695]
+```
+
+## Subclassing
+
+```py
+class MyBox[T]:
+    # TODO: `T` is defined here
+    # error: [unresolved-reference] "Name `T` used when not defined"
+    data: T
+
+    # TODO: `T` is defined here
+    # error: [unresolved-reference] "Name `T` used when not defined"
+    def __init__(self, data: T):
+        self.data = data
+
+# TODO not error on the subscripting or the use of type param
+# error: [unresolved-reference] "Name `T` used when not defined"
+# error: [non-subscriptable]
+class MySecureBox[T](MyBox[T]): ...
+
+secure_box: MySecureBox[int] = MySecureBox(5)
+reveal_type(secure_box)  # revealed: MySecureBox
+# TODO reveal int
+reveal_type(secure_box.data)  # revealed: @Todo
+```
+
+## Cyclical class definition
+
+In type stubs, classes can reference themselves in their base class definitions. For example, in
+`typeshed`, we have `class str(Sequence[str]): ...`.
+
+This should hold true even with generics at play.
+
+```py path=a.pyi
+class Seq[T]: ...
+
+# TODO not error on the subscripting
+class S[T](Seq[S]): ...  # error: [non-subscriptable]
+
+reveal_type(S)  # revealed: Literal[S]
+```

crates/red_knot_python_semantic/resources/mdtest/import/basic.md

@@ -0,0 +1,27 @@
+# Structures
+
+## Class import following
+
+```py
+from b import C as D
+
+E = D
+reveal_type(E)  # revealed: Literal[C]
+```
+
+```py path=b.py
+class C: ...
+```
+
+## Module member resolution
+
+```py
+import b
+
+D = b.C
+reveal_type(D)  # revealed: Literal[C]
+```
+
+```py path=b.py
+class C: ...
+```

crates/red_knot_python_semantic/resources/mdtest/import/builtins.md

@@ -0,0 +1,8 @@
+# Importing builtin module
+
+```py
+import builtins
+
+x = builtins.copyright
+reveal_type(x)  # revealed: Literal[copyright]
+```

crates/red_knot_python_semantic/resources/mdtest/import/conditional.md

@@ -0,0 +1,126 @@
+# Conditional imports
+
+## Maybe unbound
+
+```py path=maybe_unbound.py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+if flag:
+    y = 3
+
+x = y  # error: [possibly-unresolved-reference]
+
+# revealed: Literal[3]
+reveal_type(x)
+
+# revealed: Literal[3]
+# error: [possibly-unresolved-reference]
+reveal_type(y)
+```
+
+```py
+from maybe_unbound import x, y
+
+reveal_type(x)  # revealed: Literal[3]
+reveal_type(y)  # revealed: Literal[3]
+```
+
+## Maybe unbound annotated
+
+```py path=maybe_unbound_annotated.py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+if flag:
+    y: int = 3
+x = y  # error: [possibly-unresolved-reference]
+
+# revealed: Literal[3]
+reveal_type(x)
+
+# revealed: Literal[3]
+# error: [possibly-unresolved-reference]
+reveal_type(y)
+```
+
+Importing an annotated name prefers the declared type over the inferred type:
+
+```py
+from maybe_unbound_annotated import x, y
+
+reveal_type(x)  # revealed: Literal[3]
+reveal_type(y)  # revealed: int
+```
+
+## Maybe undeclared
+
+Importing a possibly undeclared name still gives us its declared type:
+
+```py path=maybe_undeclared.py
+def bool_instance() -> bool:
+    return True
+
+if bool_instance():
+    x: int
+```
+
+```py
+from maybe_undeclared import x
+
+reveal_type(x)  # revealed: int
+```
+
+## Reimport
+
+```py path=c.py
+def f(): ...
+```
+
+```py path=b.py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+if flag:
+    from c import f
+else:
+
+    def f(): ...
+```
+
+```py
+from b import f
+
+# TODO: We should disambiguate in such cases, showing `Literal[b.f, c.f]`.
+reveal_type(f)  # revealed: Literal[f, f]
+```
+
+## Reimport with stub declaration
+
+When we have a declared type in one path and only an inferred-from-definition type in the other, we
+should still be able to unify those:
+
+```py path=c.pyi
+x: int
+```
+
+```py path=b.py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+if flag:
+    from c import x
+else:
+    x = 1
+```
+
+```py
+from b import x
+
+reveal_type(x)  # revealed: int
+```

crates/red_knot_python_semantic/resources/mdtest/import/errors.md

@@ -0,0 +1,57 @@
+# Unresolved Imports
+
+## Unresolved import statement
+
+```py
+import bar  # error: "Cannot resolve import `bar`"
+
+reveal_type(bar)  # revealed: Unknown
+```
+
+## Unresolved import from statement
+
+```py
+from bar import baz  # error: "Cannot resolve import `bar`"
+
+reveal_type(baz)  # revealed: Unknown
+```
+
+## Unresolved import from resolved module
+
+```py path=a.py
+```
+
+```py
+from a import thing  # error: "Module `a` has no member `thing`"
+
+reveal_type(thing)  # revealed: Unknown
+```
+
+## Resolved import of symbol from unresolved import
+
+```py path=a.py
+import foo as foo  # error: "Cannot resolve import `foo`"
+
+reveal_type(foo)  # revealed: Unknown
+```
+
+Importing the unresolved import into a second file should not trigger an additional "unresolved
+import" violation:
+
+```py
+from a import foo
+
+reveal_type(foo)  # revealed: Unknown
+```
+
+## No implicit shadowing
+
+```py path=b.py
+x: int
+```
+
+```py
+from b import x
+
+x = "foo"  # error: [invalid-assignment] "Object of type `Literal["foo"]"
+```

crates/red_knot_python_semantic/resources/mdtest/import/relative.md

@@ -0,0 +1,143 @@
+# Relative
+
+## Non-existent
+
+```py path=package/__init__.py
+```
+
+```py path=package/bar.py
+from .foo import X  # error: [unresolved-import]
+
+reveal_type(X)  # revealed: Unknown
+```
+
+## Simple
+
+```py path=package/__init__.py
+```
+
+```py path=package/foo.py
+X = 42
+```
+
+```py path=package/bar.py
+from .foo import X
+
+reveal_type(X)  # revealed: Literal[42]
+```
+
+## Dotted
+
+```py path=package/__init__.py
+```
+
+```py path=package/foo/bar/baz.py
+X = 42
+```
+
+```py path=package/bar.py
+from .foo.bar.baz import X
+
+reveal_type(X)  # revealed: Literal[42]
+```
+
+## Bare to package
+
+```py path=package/__init__.py
+X = 42
+```
+
+```py path=package/bar.py
+from . import X
+
+reveal_type(X)  # revealed: Literal[42]
+```
+
+## Non-existent + bare to package
+
+```py path=package/bar.py
+from . import X  # error: [unresolved-import]
+
+reveal_type(X)  # revealed: Unknown
+```
+
+## Dunder init
+
+```py path=package/__init__.py
+from .foo import X
+
+reveal_type(X)  # revealed: Literal[42]
+```
+
+```py path=package/foo.py
+X = 42
+```
+
+## Non-existent + dunder init
+
+```py path=package/__init__.py
+from .foo import X  # error: [unresolved-import]
+
+reveal_type(X)  # revealed: Unknown
+```
+
+## Long relative import
+
+```py path=package/__init__.py
+```
+
+```py path=package/foo.py
+X = 42
+```
+
+```py path=package/subpackage/subsubpackage/bar.py
+from ...foo import X
+
+reveal_type(X)  # revealed: Literal[42]
+```
+
+## Unbound symbol
+
+```py path=package/__init__.py
+```
+
+```py path=package/foo.py
+x  # error: [unresolved-reference]
+```
+
+```py path=package/bar.py
+from .foo import x  # error: [unresolved-import]
+
+reveal_type(x)  # revealed: Unknown
+```
+
+## Bare to module
+
+```py path=package/__init__.py
+```
+
+```py path=package/foo.py
+X = 42
+```
+
+```py path=package/bar.py
+# TODO: support submodule imports
+from . import foo  # error: [unresolved-import]
+
+y = foo.X
+
+# TODO: should be `Literal[42]`
+reveal_type(y)  # revealed: Unknown
+```
+
+## Non-existent + bare to module
+
+```py path=package/__init__.py
+```
+
+```py path=package/bar.py
+# TODO: support submodule imports
+from . import foo  # error: [unresolved-import]
+
+reveal_type(foo)  # revealed: Unknown
+```

crates/red_knot_python_semantic/resources/mdtest/import/stubs.md

@@ -0,0 +1,27 @@
+# Stubs
+
+## Import from stub declaration
+
+```py
+from b import x
+
+y = x
+reveal_type(y)  # revealed: int
+```
+
+```py path=b.pyi
+x: int
+```
+
+## Import from non-stub with declaration and definition
+
+```py
+from b import x
+
+y = x
+reveal_type(y)  # revealed: int
+```
+
+```py path=b.py
+x: int = 1
+```

crates/red_knot_python_semantic/resources/mdtest/literal/boolean.md

@@ -0,0 +1,6 @@
+# Boolean literals
+
+```py
+reveal_type(True)  # revealed: Literal[True]
+reveal_type(False)  # revealed: Literal[False]
+```

crates/red_knot_python_semantic/resources/mdtest/literal/bytes.md

@@ -0,0 +1,10 @@
+# Bytes literals
+
+## Simple
+
+```py
+reveal_type(b"red" b"knot")  # revealed: Literal[b"redknot"]
+reveal_type(b"hello")  # revealed: Literal[b"hello"]
+reveal_type(b"world" + b"!")  # revealed: Literal[b"world!"]
+reveal_type(b"\xff\x00")  # revealed: Literal[b"\xff\x00"]
+```

crates/red_knot_python_semantic/resources/mdtest/literal/collections/dictionary.md

@@ -0,0 +1,7 @@
+# Dictionaries
+
+## Empty dictionary
+
+```py
+reveal_type({})  # revealed: dict
+```

crates/red_knot_python_semantic/resources/mdtest/literal/collections/list.md

@@ -0,0 +1,7 @@
+# Lists
+
+## Empty list
+
+```py
+reveal_type([])  # revealed: list
+```

crates/red_knot_python_semantic/resources/mdtest/literal/collections/set.md

@@ -0,0 +1,7 @@
+# Sets
+
+## Basic set
+
+```py
+reveal_type({1, 2})  # revealed: set
+```

crates/red_knot_python_semantic/resources/mdtest/literal/collections/tuple.md

@@ -0,0 +1,17 @@
+# Tuples
+
+## Empty tuple
+
+```py
+reveal_type(())  # revealed: tuple[()]
+```
+
+## Heterogeneous tuple
+
+```py
+reveal_type((1, "a"))  # revealed: tuple[Literal[1], Literal["a"]]
+
+reveal_type((1, (2, 3)))  # revealed: tuple[Literal[1], tuple[Literal[2], Literal[3]]]
+
+reveal_type(((1, "a"), 2))  # revealed: tuple[tuple[Literal[1], Literal["a"]], Literal[2]]
+```

crates/red_knot_python_semantic/resources/mdtest/literal/complex.md

@@ -0,0 +1,7 @@
+# Complex literals
+
+## Complex numbers
+
+```py
+reveal_type(2j)  # revealed: complex
+```

crates/red_knot_python_semantic/resources/mdtest/literal/f_string.md

@@ -0,0 +1,33 @@
+# f-strings
+
+## Expression
+
+```py
+x = 0
+y = str()
+z = False
+
+reveal_type(f"hello")  # revealed: Literal["hello"]
+reveal_type(f"h {x}")  # revealed: Literal["h 0"]
+reveal_type("one " f"single " f"literal")  # revealed: Literal["one single literal"]
+reveal_type("first " f"second({x})" f" third")  # revealed: Literal["first second(0) third"]
+reveal_type(f"-{y}-")  # revealed: str
+reveal_type(f"-{y}-" f"--" "--")  # revealed: str
+reveal_type(f"{z} == {False} is {True}")  # revealed: Literal["False == False is True"]
+```
+
+## Conversion Flags
+
+```py
+string = "hello"
+
+# TODO: should be `Literal["'hello'"]`
+reveal_type(f"{string!r}")  # revealed: str
+```
+
+## Format Specifiers
+
+```py
+# TODO: should be `Literal["01"]`
+reveal_type(f"{1:02}")  # revealed: str
+```

crates/red_knot_python_semantic/resources/mdtest/literal/float.md

@@ -0,0 +1,7 @@
+# Float literals
+
+## Basic
+
+```py
+reveal_type(1.0)  # revealed: float
+```

crates/red_knot_python_semantic/resources/mdtest/literal/integer.md

@@ -0,0 +1,56 @@
+# Integer literals
+
+## Literals
+
+We can infer an integer literal type:
+
+```py
+reveal_type(1)  # revealed: Literal[1]
+```
+
+## Variable
+
+```py
+x = 1
+reveal_type(x)  # revealed: Literal[1]
+```
+
+## Overflow
+
+We only track integer literals within the range of an i64:
+
+```py
+reveal_type(9223372036854775808)  # revealed: int
+```
+
+## Big int
+
+We don't support big integer literals; we just infer `int` type instead:
+
+```py
+x = 10_000_000_000_000_000_000
+reveal_type(x)  # revealed: int
+```
+
+## Negated
+
+```py
+x = -1
+y = -1234567890987654321
+z = --987
+reveal_type(x)  # revealed: Literal[-1]
+reveal_type(y)  # revealed: Literal[-1234567890987654321]
+reveal_type(z)  # revealed: Literal[987]
+```
+
+## Floats
+
+```py
+reveal_type(1.0)  # revealed: float
+```
+
+## Complex
+
+```py
+reveal_type(2j)  # revealed: complex
+```

crates/red_knot_python_semantic/resources/mdtest/literal/string.md

@@ -0,0 +1,21 @@
+# String literals
+
+## Simple
+
+```py
+reveal_type("Hello")  # revealed: Literal["Hello"]
+reveal_type("world")  # revealed: Literal["world"]
+reveal_type("Guten " + "Tag")  # revealed: Literal["Guten Tag"]
+reveal_type("bon " + "jour")  # revealed: Literal["bon jour"]
+```
+
+## Nested Quotes
+
+```py
+reveal_type('I say "hello" to you')  # revealed: Literal["I say \"hello\" to you"]
+
+# revealed: Literal["You say \"hey\" back"]
+reveal_type("You say \"hey\" back")  # fmt: skip
+
+reveal_type('No "closure here')  # revealed: Literal["No \"closure here"]
+```

crates/red_knot_python_semantic/resources/mdtest/loops/async_for_loops.md

@@ -0,0 +1,45 @@
+# Async
+
+Async `for` loops do not work according to the synchronous iteration protocol.
+
+## Invalid async for loop
+
+```py
+async def foo():
+    class Iterator:
+        def __next__(self) -> int:
+            return 42
+
+    class Iterable:
+        def __iter__(self) -> Iterator:
+            return Iterator()
+
+    async for x in Iterator():
+        pass
+
+    # TODO: should reveal `Unknown` because `__aiter__` is not defined
+    # revealed: @Todo
+    # error: [possibly-unresolved-reference]
+    reveal_type(x)
+```
+
+## Basic async for loop
+
+```py
+async def foo():
+    class IntAsyncIterator:
+        async def __anext__(self) -> int:
+            return 42
+
+    class IntAsyncIterable:
+        def __aiter__(self) -> IntAsyncIterator:
+            return IntAsyncIterator()
+
+    # TODO(Alex): async iterables/iterators!
+    async for x in IntAsyncIterable():
+        pass
+
+    # error: [possibly-unresolved-reference]
+    # revealed: @Todo
+    reveal_type(x)
+```

crates/red_knot_python_semantic/resources/mdtest/loops/for_loop.md

@@ -0,0 +1,283 @@
+# For loops
+
+## Basic `for` loop
+
+```py
+class IntIterator:
+    def __next__(self) -> int:
+        return 42
+
+class IntIterable:
+    def __iter__(self) -> IntIterator:
+        return IntIterator()
+
+for x in IntIterable():
+    pass
+
+# revealed: int
+# error: [possibly-unresolved-reference]
+reveal_type(x)
+```
+
+## With previous definition
+
+```py
+class IntIterator:
+    def __next__(self) -> int:
+        return 42
+
+class IntIterable:
+    def __iter__(self) -> IntIterator:
+        return IntIterator()
+
+x = "foo"
+
+for x in IntIterable():
+    pass
+
+reveal_type(x)  # revealed: Literal["foo"] | int
+```
+
+## With `else` (no break)
+
+```py
+class IntIterator:
+    def __next__(self) -> int:
+        return 42
+
+class IntIterable:
+    def __iter__(self) -> IntIterator:
+        return IntIterator()
+
+for x in IntIterable():
+    pass
+else:
+    x = "foo"
+
+reveal_type(x)  # revealed: Literal["foo"]
+```
+
+## May `break`
+
+```py
+class IntIterator:
+    def __next__(self) -> int:
+        return 42
+
+class IntIterable:
+    def __iter__(self) -> IntIterator:
+        return IntIterator()
+
+for x in IntIterable():
+    if x > 5:
+        break
+else:
+    x = "foo"
+
+reveal_type(x)  # revealed: int | Literal["foo"]
+```
+
+## With old-style iteration protocol
+
+```py
+class OldStyleIterable:
+    def __getitem__(self, key: int) -> int:
+        return 42
+
+for x in OldStyleIterable():
+    pass
+
+# revealed: int
+# error: [possibly-unresolved-reference]
+reveal_type(x)
+```
+
+## With heterogeneous tuple
+
+```py
+for x in (1, "a", b"foo"):
+    pass
+
+# revealed: Literal[1] | Literal["a"] | Literal[b"foo"]
+# error: [possibly-unresolved-reference]
+reveal_type(x)
+```
+
+## With non-callable iterator
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+class NotIterable:
+    if flag:
+        __iter__ = 1
+    else:
+        __iter__ = None
+
+for x in NotIterable():  # error: "Object of type `NotIterable` is not iterable"
+    pass
+
+# revealed: Unknown
+# error: [possibly-unresolved-reference]
+reveal_type(x)
+```
+
+## Invalid iterable
+
+```py
+nonsense = 123
+for x in nonsense:  # error: "Object of type `Literal[123]` is not iterable"
+    pass
+```
+
+## New over old style iteration protocol
+
+```py
+class NotIterable:
+    def __getitem__(self, key: int) -> int:
+        return 42
+    __iter__ = None
+
+for x in NotIterable():  # error: "Object of type `NotIterable` is not iterable"
+    pass
+```
+
+## Union type as iterable
+
+```py
+class TestIter:
+    def __next__(self) -> int:
+        return 42
+
+class Test:
+    def __iter__(self) -> TestIter:
+        return TestIter()
+
+class Test2:
+    def __iter__(self) -> TestIter:
+        return TestIter()
+
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+for x in Test() if flag else Test2():
+    reveal_type(x)  # revealed: int
+```
+
+## Union type as iterator
+
+```py
+class TestIter:
+    def __next__(self) -> int:
+        return 42
+
+class TestIter2:
+    def __next__(self) -> int:
+        return 42
+
+class Test:
+    def __iter__(self) -> TestIter | TestIter2:
+        return TestIter()
+
+for x in Test():
+    reveal_type(x)  # revealed: int
+```
+
+## Union type as iterable and union type as iterator
+
+```py
+class TestIter:
+    def __next__(self) -> int | Exception:
+        return 42
+
+class TestIter2:
+    def __next__(self) -> str | tuple[int, int]:
+        return "42"
+
+class TestIter3:
+    def __next__(self) -> bytes:
+        return b"42"
+
+class TestIter4:
+    def __next__(self) -> memoryview:
+        return memoryview(b"42")
+
+class Test:
+    def __iter__(self) -> TestIter | TestIter2:
+        return TestIter()
+
+class Test2:
+    def __iter__(self) -> TestIter3 | TestIter4:
+        return TestIter3()
+
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+for x in Test() if flag else Test2():
+    reveal_type(x)  # revealed: int | Exception | str | tuple[int, int] | bytes | memoryview
+```
+
+## Union type as iterable where one union element has no `__iter__` method
+
+```py
+class TestIter:
+    def __next__(self) -> int:
+        return 42
+
+class Test:
+    def __iter__(self) -> TestIter:
+        return TestIter()
+
+def coinflip() -> bool:
+    return True
+
+# TODO: we should emit a diagnostic here (it might not be iterable)
+for x in Test() if coinflip() else 42:
+    reveal_type(x)  # revealed: int
+```
+
+## Union type as iterable where one union element has invalid `__iter__` method
+
+```py
+class TestIter:
+    def __next__(self) -> int:
+        return 42
+
+class Test:
+    def __iter__(self) -> TestIter:
+        return TestIter()
+
+class Test2:
+    def __iter__(self) -> int:
+        return 42
+
+def coinflip() -> bool:
+    return True
+
+# error: "Object of type `Test | Test2` is not iterable"
+for x in Test() if coinflip() else Test2():
+    reveal_type(x)  # revealed: Unknown
+```
+
+## Union type as iterator where one union element has no `__next__` method
+
+```py
+class TestIter:
+    def __next__(self) -> int:
+        return 42
+
+class Test:
+    def __iter__(self) -> TestIter | int:
+        return TestIter()
+
+# error: [not-iterable] "Object of type `Test` is not iterable"
+for x in Test():
+    reveal_type(x)  # revealed: Unknown
+```

crates/red_knot_python_semantic/resources/mdtest/loops/iterators.md

@@ -0,0 +1,18 @@
+# Iterators
+
+## Yield must be iterable
+
+```py
+class NotIterable: ...
+
+class Iterator:
+    def __next__(self) -> int:
+        return 42
+
+class Iterable:
+    def __iter__(self) -> Iterator: ...
+
+def generator_function():
+    yield from Iterable()
+    yield from NotIterable()  # error: "Object of type `NotIterable` is not iterable"
+```

crates/red_knot_python_semantic/resources/mdtest/loops/while_loop.md

@@ -0,0 +1,54 @@
+# While loops
+
+## Basic While Loop
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = 1
+while flag:
+    x = 2
+
+reveal_type(x)  # revealed: Literal[1, 2]
+```
+
+## While with else (no break)
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = 1
+while flag:
+    x = 2
+else:
+    reveal_type(x)  # revealed: Literal[1, 2]
+    x = 3
+
+reveal_type(x)  # revealed: Literal[3]
+```
+
+## While with Else (may break)
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag, flag2 = bool_instance(), bool_instance()
+x = 1
+y = 0
+while flag:
+    x = 2
+    if flag2:
+        y = 4
+        break
+else:
+    y = x
+    x = 3
+
+reveal_type(x)  # revealed: Literal[2, 3]
+reveal_type(y)  # revealed: Literal[1, 2, 4]
+```

crates/red_knot_python_semantic/resources/mdtest/narrow/boolean.md

@@ -0,0 +1,93 @@
+# Narrowing in boolean expressions
+
+In `or` expressions, the right-hand side is evaluated only if the left-hand side is **falsy**. So
+when the right-hand side is evaluated, we know the left side has failed.
+
+Similarly, in `and` expressions, the right-hand side is evaluated only if the left-hand side is
+**truthy**. So when the right-hand side is evaluated, we know the left side has succeeded.
+
+## Narrowing in `or`
+
+```py
+def bool_instance() -> bool:
+    return True
+
+class A: ...
+
+x: A | None = A() if bool_instance() else None
+
+isinstance(x, A) or reveal_type(x)  # revealed: None
+x is None or reveal_type(x)  # revealed: A
+reveal_type(x)  # revealed: A | None
+```
+
+## Narrowing in `and`
+
+```py
+def bool_instance() -> bool:
+    return True
+
+class A: ...
+
+x: A | None = A() if bool_instance() else None
+
+isinstance(x, A) and reveal_type(x)  # revealed: A
+x is None and reveal_type(x)  # revealed: None
+reveal_type(x)  # revealed: A | None
+```
+
+## Multiple `and` arms
+
+```py
+def bool_instance() -> bool:
+    return True
+
+class A: ...
+
+x: A | None = A() if bool_instance() else None
+
+bool_instance() and isinstance(x, A) and reveal_type(x)  # revealed: A
+isinstance(x, A) and bool_instance() and reveal_type(x)  # revealed: A
+reveal_type(x) and isinstance(x, A) and bool_instance()  # revealed: A | None
+```
+
+## Multiple `or` arms
+
+```py
+def bool_instance() -> bool:
+    return True
+
+class A: ...
+
+x: A | None = A() if bool_instance() else None
+
+bool_instance() or isinstance(x, A) or reveal_type(x)  # revealed: None
+isinstance(x, A) or bool_instance() or reveal_type(x)  # revealed: None
+reveal_type(x) or isinstance(x, A) or bool_instance()  # revealed: A | None
+```
+
+## Multiple predicates
+
+```py
+def bool_instance() -> bool:
+    return True
+
+class A: ...
+
+x: A | None | Literal[1] = A() if bool_instance() else None if bool_instance() else 1
+
+x is None or isinstance(x, A) or reveal_type(x)  # revealed: Literal[1]
+```
+
+## Mix of `and` and `or`
+
+```py
+def bool_instance() -> bool:
+    return True
+
+class A: ...
+
+x: A | None | Literal[1] = A() if bool_instance() else None if bool_instance() else 1
+
+isinstance(x, A) or x is not None and reveal_type(x)  # revealed: Literal[1]
+```

crates/red_knot_python_semantic/resources/mdtest/narrow/conditionals_elif_else.md

@@ -0,0 +1,57 @@
+# Narrowing for conditionals with elif and else
+
+## Positive contributions become negative in elif-else blocks
+
+```py
+def int_instance() -> int:
+    return 42
+
+x = int_instance()
+
+if x == 1:
+    # cannot narrow; could be a subclass of `int`
+    reveal_type(x)  # revealed: int
+elif x == 2:
+    reveal_type(x)  # revealed: int & ~Literal[1]
+elif x != 3:
+    reveal_type(x)  # revealed: int & ~Literal[1] & ~Literal[2] & ~Literal[3]
+```
+
+## Positive contributions become negative in elif-else blocks, with simplification
+
+```py
+def bool_instance() -> bool:
+    return True
+
+x = 1 if bool_instance() else 2 if bool_instance() else 3
+
+if x == 1:
+    # TODO should be Literal[1]
+    reveal_type(x)  # revealed: Literal[1, 2, 3]
+elif x == 2:
+    # TODO should be Literal[2]
+    reveal_type(x)  # revealed: Literal[2, 3]
+else:
+    reveal_type(x)  # revealed: Literal[3]
+```
+
+## Multiple negative contributions using elif, with simplification
+
+```py
+def bool_instance() -> bool:
+    return True
+
+x = 1 if bool_instance() else 2 if bool_instance() else 3
+
+if x != 1:
+    reveal_type(x)  # revealed: Literal[2, 3]
+elif x != 2:
+    # TODO should be `Literal[1]`
+    reveal_type(x)  # revealed: Literal[1, 3]
+elif x == 3:
+    # TODO should be Never
+    reveal_type(x)  # revealed: Literal[1, 2, 3]
+else:
+    # TODO should be Never
+    reveal_type(x)  # revealed: Literal[1, 2]
+```

crates/red_knot_python_semantic/resources/mdtest/narrow/conditionals_is.md

@@ -0,0 +1,79 @@
+# Narrowing for `is` conditionals
+
+## `is None`
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = None if flag else 1
+
+if x is None:
+    reveal_type(x)  # revealed: None
+else:
+    reveal_type(x)  # revealed: Literal[1]
+
+reveal_type(x)  # revealed: None | Literal[1]
+```
+
+## `is` for other types
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+class A: ...
+
+x = A()
+y = x if flag else None
+
+if y is x:
+    reveal_type(y)  # revealed: A
+else:
+    reveal_type(y)  # revealed: A | None
+
+reveal_type(y)  # revealed: A | None
+```
+
+## `is` in chained comparisons
+
+```py
+def bool_instance() -> bool:
+    return True
+
+x_flag, y_flag = bool_instance(), bool_instance()
+x = True if x_flag else False
+y = True if y_flag else False
+
+reveal_type(x)  # revealed: bool
+reveal_type(y)  # revealed: bool
+
+if y is x is False:  # Interpreted as `(y is x) and (x is False)`
+    reveal_type(x)  # revealed: Literal[False]
+    reveal_type(y)  # revealed: bool
+else:
+    # The negation of the clause above is (y is not x) or (x is not False)
+    # So we can't narrow the type of x or y here, because each arm of the `or` could be true
+    reveal_type(x)  # revealed: bool
+    reveal_type(y)  # revealed: bool
+```
+
+## `is` in elif clause
+
+```py
+def bool_instance() -> bool:
+    return True
+
+x = None if bool_instance() else (1 if bool_instance() else True)
+
+reveal_type(x)  # revealed: None | Literal[1] | Literal[True]
+if x is None:
+    reveal_type(x)  # revealed: None
+elif x is True:
+    reveal_type(x)  # revealed: Literal[True]
+else:
+    reveal_type(x)  # revealed: Literal[1]
+```

crates/red_knot_python_semantic/resources/mdtest/narrow/conditionals_is_not.md

@@ -0,0 +1,96 @@
+# Narrowing for `is not` conditionals
+
+## `is not None`
+
+The type guard removes `None` from the union type:
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = None if flag else 1
+
+if x is not None:
+    reveal_type(x)  # revealed: Literal[1]
+else:
+    reveal_type(x)  # revealed: None
+
+reveal_type(x)  # revealed: None | Literal[1]
+```
+
+## `is not` for other singleton types
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = True if flag else False
+reveal_type(x)  # revealed: bool
+
+if x is not False:
+    reveal_type(x)  # revealed: Literal[True]
+else:
+    reveal_type(x)  # revealed: Literal[False]
+```
+
+## `is not` for non-singleton types
+
+Non-singleton types should *not* narrow the type: two instances of a non-singleton class may occupy
+different addresses in memory even if they compare equal.
+
+```py
+x = 345
+y = 345
+
+if x is not y:
+    reveal_type(x)  # revealed: Literal[345]
+else:
+    reveal_type(x)  # revealed: Literal[345]
+```
+
+## `is not` for other types
+
+```py
+def bool_instance() -> bool:
+    return True
+
+class A: ...
+
+x = A()
+y = x if bool_instance() else None
+
+if y is not x:
+    reveal_type(y)  # revealed: A | None
+else:
+    reveal_type(y)  # revealed: A
+
+reveal_type(y)  # revealed: A | None
+```
+
+## `is not` in chained comparisons
+
+The type guard removes `False` from the union type of the tested value only.
+
+```py
+def bool_instance() -> bool:
+    return True
+
+x_flag, y_flag = bool_instance(), bool_instance()
+x = True if x_flag else False
+y = True if y_flag else False
+
+reveal_type(x)  # revealed: bool
+reveal_type(y)  # revealed: bool
+
+if y is not x is not False:  # Interpreted as `(y is not x) and (x is not False)`
+    reveal_type(x)  # revealed: Literal[True]
+    reveal_type(y)  # revealed: bool
+else:
+    # The negation of the clause above is (y is x) or (x is False)
+    # So we can't narrow the type of x or y here, because each arm of the `or` could be true
+
+    reveal_type(x)  # revealed: bool
+    reveal_type(y)  # revealed: bool
+```

crates/red_knot_python_semantic/resources/mdtest/narrow/conditionals_nested.md

@@ -0,0 +1,56 @@
+# Narrowing for nested conditionals
+
+## Multiple negative contributions
+
+```py
+def int_instance() -> int:
+    return 42
+
+x = int_instance()
+
+if x != 1:
+    if x != 2:
+        if x != 3:
+            reveal_type(x)  # revealed: int & ~Literal[1] & ~Literal[2] & ~Literal[3]
+```
+
+## Multiple negative contributions with simplification
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag1, flag2 = bool_instance(), bool_instance()
+x = 1 if flag1 else 2 if flag2 else 3
+
+if x != 1:
+    reveal_type(x)  # revealed: Literal[2, 3]
+    if x != 2:
+        reveal_type(x)  # revealed: Literal[3]
+```
+
+## elif-else blocks
+
+```py
+def bool_instance() -> bool:
+    return True
+
+x = 1 if bool_instance() else 2 if bool_instance() else 3
+
+if x != 1:
+    reveal_type(x)  # revealed: Literal[2, 3]
+    if x == 2:
+        # TODO should be `Literal[2]`
+        reveal_type(x)  # revealed: Literal[2, 3]
+    elif x == 3:
+        reveal_type(x)  # revealed: Literal[3]
+    else:
+        reveal_type(x)  # revealed: Never
+
+elif x != 2:
+    # TODO should be Literal[1]
+    reveal_type(x)  # revealed: Literal[1, 3]
+else:
+    # TODO should be Never
+    reveal_type(x)  # revealed: Literal[1, 2, 3]
+```

crates/red_knot_python_semantic/resources/mdtest/narrow/conditionals_not.md

@@ -0,0 +1,33 @@
+# Narrowing for `not` conditionals
+
+The `not` operator negates a constraint.
+
+## `not is None`
+
+```py
+def bool_instance() -> bool:
+    return True
+
+x = None if bool_instance() else 1
+
+if not x is None:
+    reveal_type(x)  # revealed: Literal[1]
+else:
+    reveal_type(x)  # revealed: None
+
+reveal_type(x)  # revealed: None | Literal[1]
+```
+
+## `not isinstance`
+
+```py
+def bool_instance() -> bool:
+    return True
+
+x = 1 if bool_instance() else "a"
+
+if not isinstance(x, (int)):
+    reveal_type(x)  # revealed: Literal["a"]
+else:
+    reveal_type(x)  # revealed: Literal[1]
+```

crates/red_knot_python_semantic/resources/mdtest/narrow/conditionals_not_eq.md

@@ -0,0 +1,119 @@
+# Narrowing for `!=` conditionals
+
+## `x != None`
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = None if flag else 1
+
+if x != None:
+    reveal_type(x)  # revealed: Literal[1]
+else:
+    # TODO should be None
+    reveal_type(x)  # revealed: None | Literal[1]
+```
+
+## `!=` for other singleton types
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = True if flag else False
+
+if x != False:
+    reveal_type(x)  # revealed: Literal[True]
+else:
+    # TODO should be Literal[False]
+    reveal_type(x)  # revealed: bool
+```
+
+## `x != y` where `y` is of literal type
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = 1 if flag else 2
+
+if x != 1:
+    reveal_type(x)  # revealed: Literal[2]
+```
+
+## `x != y` where `y` is a single-valued type
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+class A: ...
+class B: ...
+
+C = A if flag else B
+
+if C != A:
+    reveal_type(C)  # revealed: Literal[B]
+else:
+    # TODO should be Literal[A]
+    reveal_type(C)  # revealed: Literal[A, B]
+```
+
+## `x != y` where `y` has multiple single-valued options
+
+```py
+def bool_instance() -> bool:
+    return True
+
+x = 1 if bool_instance() else 2
+y = 2 if bool_instance() else 3
+
+if x != y:
+    reveal_type(x)  # revealed: Literal[1, 2]
+else:
+    # TODO should be Literal[2]
+    reveal_type(x)  # revealed: Literal[1, 2]
+```
+
+## `!=` for non-single-valued types
+
+Only single-valued types should narrow the type:
+
+```py
+def bool_instance() -> bool:
+    return True
+
+def int_instance() -> int:
+    return 42
+
+flag = bool_instance()
+x = int_instance() if flag else None
+y = int_instance()
+
+if x != y:
+    reveal_type(x)  # revealed: int | None
+```
+
+## Mix of single-valued and non-single-valued types
+
+```py
+def int_instance() -> int:
+    return 42
+
+def bool_instance() -> bool:
+    return True
+
+x = 1 if bool_instance() else 2
+y = 2 if bool_instance() else int_instance()
+
+if x != y:
+    reveal_type(x)  # revealed: Literal[1, 2]
+else:
+    reveal_type(x)  # revealed: Literal[1, 2]
+```

crates/red_knot_python_semantic/resources/mdtest/narrow/isinstance.md

@@ -0,0 +1,208 @@
+# Narrowing for `isinstance` checks
+
+Narrowing for `isinstance(object, classinfo)` expressions.
+
+## `classinfo` is a single type
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+x = 1 if flag else "a"
+
+if isinstance(x, int):
+    reveal_type(x)  # revealed: Literal[1]
+
+if isinstance(x, str):
+    reveal_type(x)  # revealed: Literal["a"]
+    if isinstance(x, int):
+        reveal_type(x)  # revealed: Never
+
+if isinstance(x, (int, object)):
+    reveal_type(x)  # revealed: Literal[1] | Literal["a"]
+```
+
+## `classinfo` is a tuple of types
+
+Note: `isinstance(x, (int, str))` should not be confused with `isinstance(x, tuple[(int, str)])`.
+The former is equivalent to `isinstance(x, int | str)`:
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag, flag1, flag2 = bool_instance(), bool_instance(), bool_instance()
+
+x = 1 if flag else "a"
+
+if isinstance(x, (int, str)):
+    reveal_type(x)  # revealed: Literal[1] | Literal["a"]
+else:
+    reveal_type(x)  # revealed: Never
+
+if isinstance(x, (int, bytes)):
+    reveal_type(x)  # revealed: Literal[1]
+
+if isinstance(x, (bytes, str)):
+    reveal_type(x)  # revealed: Literal["a"]
+
+# No narrowing should occur if a larger type is also
+# one of the possibilities:
+if isinstance(x, (int, object)):
+    reveal_type(x)  # revealed: Literal[1] | Literal["a"]
+else:
+    reveal_type(x)  # revealed: Never
+
+y = 1 if flag1 else "a" if flag2 else b"b"
+if isinstance(y, (int, str)):
+    reveal_type(y)  # revealed: Literal[1] | Literal["a"]
+
+if isinstance(y, (int, bytes)):
+    reveal_type(y)  # revealed: Literal[1] | Literal[b"b"]
+
+if isinstance(y, (str, bytes)):
+    reveal_type(y)  # revealed: Literal["a"] | Literal[b"b"]
+```
+
+## `classinfo` is a nested tuple of types
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+x = 1 if flag else "a"
+
+if isinstance(x, (bool, (bytes, int))):
+    reveal_type(x)  # revealed: Literal[1]
+else:
+    reveal_type(x)  # revealed: Literal["a"]
+```
+
+## Class types
+
+```py
+class A: ...
+class B: ...
+class C: ...
+
+def get_object() -> object: ...
+
+x = get_object()
+
+if isinstance(x, A):
+    reveal_type(x)  # revealed: A
+    if isinstance(x, B):
+        reveal_type(x)  # revealed: A & B
+    else:
+        reveal_type(x)  # revealed: A & ~B
+
+if isinstance(x, (A, B)):
+    reveal_type(x)  # revealed: A | B
+elif isinstance(x, (A, C)):
+    reveal_type(x)  # revealed: C & ~A & ~B
+else:
+    # TODO: Should be simplified to ~A & ~B & ~C
+    reveal_type(x)  # revealed: object & ~A & ~B & ~C
+```
+
+## No narrowing for instances of `builtins.type`
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+t = type("t", (), {})
+
+# This isn't testing what we want it to test if we infer anything more precise here:
+reveal_type(t)  # revealed: type
+x = 1 if flag else "foo"
+
+if isinstance(x, t):
+    reveal_type(x)  # revealed: Literal[1] | Literal["foo"]
+```
+
+## Do not use custom `isinstance` for narrowing
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+def isinstance(x, t):
+    return True
+
+x = 1 if flag else "a"
+if isinstance(x, int):
+    reveal_type(x)  # revealed: Literal[1] | Literal["a"]
+```
+
+## Do support narrowing if `isinstance` is aliased
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+isinstance_alias = isinstance
+
+x = 1 if flag else "a"
+if isinstance_alias(x, int):
+    reveal_type(x)  # revealed: Literal[1]
+```
+
+## Do support narrowing if `isinstance` is imported
+
+```py
+from builtins import isinstance as imported_isinstance
+
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = 1 if flag else "a"
+if imported_isinstance(x, int):
+    reveal_type(x)  # revealed: Literal[1]
+```
+
+## Do not narrow if second argument is not a type
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = 1 if flag else "a"
+
+# TODO: this should cause us to emit a diagnostic during
+# type checking
+if isinstance(x, "a"):
+    reveal_type(x)  # revealed: Literal[1] | Literal["a"]
+
+# TODO: this should cause us to emit a diagnostic during
+# type checking
+if isinstance(x, "int"):
+    reveal_type(x)  # revealed: Literal[1] | Literal["a"]
+```
+
+## Do not narrow if there are keyword arguments
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+x = 1 if flag else "a"
+
+# TODO: this should cause us to emit a diagnostic
+# (`isinstance` has no `foo` parameter)
+if isinstance(x, int, foo="bar"):
+    reveal_type(x)  # revealed: Literal[1] | Literal["a"]
+```

crates/red_knot_python_semantic/resources/mdtest/narrow/match.md

@@ -0,0 +1,21 @@
+# Narrowing for `match` statements
+
+## Single `match` pattern
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+x = None if flag else 1
+reveal_type(x)  # revealed: None | Literal[1]
+
+y = 0
+
+match x:
+    case None:
+        y = x
+
+reveal_type(y)  # revealed: Literal[0] | None
+```

crates/red_knot_python_semantic/resources/mdtest/numbers.md

@@ -1,35 +0,0 @@
-# Numbers
-
-## Integers
-
-### Literals
-
-We can infer an integer literal type:
-
-```py
-reveal_type(1)  # revealed: Literal[1]
-```
-
-### Overflow
-
-We only track integer literals within the range of an i64:
-
-```py
-reveal_type(9223372036854775808)  # revealed: int
-```
-
-## Floats
-
-There aren't literal float types, but we infer the general float type:
-
-```py
-reveal_type(1.0)  # revealed: float
-```
-
-## Complex
-
-Same for complex:
-
-```py
-reveal_type(2j)  # revealed: complex
-```

crates/red_knot_python_semantic/resources/mdtest/scopes/builtin.md

@@ -0,0 +1,32 @@
+# Builtin scope
+
+## Conditionally global or builtin
+
+If a builtin name is conditionally defined as a global, a name lookup should union the builtin type
+with the conditionally-defined type:
+
+```py
+def returns_bool() -> bool:
+    return True
+
+if returns_bool():
+    copyright = 1
+
+def f():
+    reveal_type(copyright)  # revealed: Literal[copyright] | Literal[1]
+```
+
+## Conditionally global or builtin, with annotation
+
+Same is true if the name is annotated:
+
+```py
+def returns_bool() -> bool:
+    return True
+
+if returns_bool():
+    copyright: int = 1
+
+def f():
+    reveal_type(copyright)  # revealed: Literal[copyright] | int
+```

crates/red_knot_python_semantic/resources/mdtest/scopes/moduletype_attrs.md

@@ -0,0 +1,138 @@
+# Implicit globals from `types.ModuleType`
+
+## Implicit `ModuleType` globals
+
+All modules are instances of `types.ModuleType`. If a name can't be found in any local or global
+scope, we look it up as an attribute on `types.ModuleType` in typeshed before deciding that the name
+is unbound.
+
+```py
+reveal_type(__name__)  # revealed: str
+reveal_type(__file__)  # revealed: str | None
+reveal_type(__loader__)  # revealed: LoaderProtocol | None
+reveal_type(__package__)  # revealed: str | None
+reveal_type(__doc__)  # revealed: str | None
+
+# TODO: Should be `ModuleSpec | None`
+# (needs support for `*` imports)
+reveal_type(__spec__)  # revealed: Unknown | None
+
+# TODO: generics
+reveal_type(__path__)  # revealed: @Todo
+
+class X:
+    reveal_type(__name__)  # revealed: str
+
+def foo():
+    reveal_type(__name__)  # revealed: str
+```
+
+However, three attributes on `types.ModuleType` are not present as implicit module globals; these
+are excluded:
+
+```py path=unbound_dunders.py
+# error: [unresolved-reference]
+# revealed: Unknown
+reveal_type(__getattr__)
+
+# error: [unresolved-reference]
+# revealed: Unknown
+reveal_type(__dict__)
+
+# error: [unresolved-reference]
+# revealed: Unknown
+reveal_type(__init__)
+```
+
+## Accessed as attributes
+
+`ModuleType` attributes can also be accessed as attributes on module-literal types. The special
+attributes `__dict__` and `__init__`, and all attributes on `builtins.object`, can also be accessed
+as attributes on module-literal types, despite the fact that these are inaccessible as globals from
+inside the module:
+
+```py
+import typing
+
+reveal_type(typing.__name__)  # revealed: str
+reveal_type(typing.__init__)  # revealed: Literal[__init__]
+
+# These come from `builtins.object`, not `types.ModuleType`:
+# TODO: we don't currently understand `types.ModuleType` as inheriting from `object`;
+# these should not reveal `Unknown`:
+reveal_type(typing.__eq__)  # revealed: Unknown
+reveal_type(typing.__class__)  # revealed: Unknown
+reveal_type(typing.__module__)  # revealed: Unknown
+
+# TODO: needs support for attribute access on instances, properties and generics;
+# should be `dict[str, Any]`
+reveal_type(typing.__dict__)  # revealed: @Todo
+```
+
+Typeshed includes a fake `__getattr__` method in the stub for `types.ModuleType` to help out with
+dynamic imports; but we ignore that for module-literal types where we know exactly which module
+we're dealing with:
+
+```py path=__getattr__.py
+import typing
+
+reveal_type(typing.__getattr__)  # revealed: Unknown
+```
+
+## `types.ModuleType.__dict__` takes precedence over global variable `__dict__`
+
+It's impossible to override the `__dict__` attribute of `types.ModuleType` instances from inside the
+module; we should prioritise the attribute in the `types.ModuleType` stub over a variable named
+`__dict__` in the module's global namespace:
+
+```py path=foo.py
+__dict__ = "foo"
+
+reveal_type(__dict__)  # revealed: Literal["foo"]
+```
+
+```py path=bar.py
+import foo
+from foo import __dict__ as foo_dict
+
+# TODO: needs support for attribute access on instances, properties, and generics;
+# should be `dict[str, Any]` for both of these:
+reveal_type(foo.__dict__)  # revealed: @Todo
+reveal_type(foo_dict)  # revealed: @Todo
+```
+
+## Conditionally global or `ModuleType` attribute
+
+Attributes overridden in the module namespace take priority. If a builtin name is conditionally
+defined as a global, however, a name lookup should union the `ModuleType` type with the
+conditionally defined type:
+
+```py
+__file__ = 42
+
+def returns_bool() -> bool:
+    return True
+
+if returns_bool():
+    __name__ = 1
+
+reveal_type(__file__)  # revealed: Literal[42]
+reveal_type(__name__)  # revealed: Literal[1] | str
+```
+
+## Conditionally global or `ModuleType` attribute, with annotation
+
+The same is true if the name is annotated:
+
+```py
+__file__: int = 42
+
+def returns_bool() -> bool:
+    return True
+
+if returns_bool():
+    __name__: int = 1
+
+reveal_type(__file__)  # revealed: Literal[42]
+reveal_type(__name__)  # revealed: Literal[1] | str
+```

crates/red_knot_python_semantic/resources/mdtest/shadowing/class.md

@@ -0,0 +1,19 @@
+# Classes shadowing
+
+## Implicit error
+
+```py
+class C: ...
+
+C = 1  # error: "Implicit shadowing of class `C`; annotate to make it explicit if this is intentional"
+```
+
+## Explicit
+
+No diagnostic is raised in the case of explicit shadowing:
+
+```py
+class C: ...
+
+C: int = 1
+```

crates/red_knot_python_semantic/resources/mdtest/shadowing/function.md

@@ -0,0 +1,27 @@
+# Function shadowing
+
+## Parameter
+
+Parameter `x` of type `str` is shadowed and reassigned with a new `int` value inside the function.
+No diagnostics should be generated.
+
+```py path=a.py
+def f(x: str):
+    x: int = int(x)
+```
+
+## Implicit error
+
+```py path=a.py
+def f(): ...
+
+f = 1  # error: "Implicit shadowing of function `f`; annotate to make it explicit if this is intentional"
+```
+
+## Explicit shadowing
+
+```py path=a.py
+def f(): ...
+
+f: int = 1
+```

crates/red_knot_python_semantic/resources/mdtest/shadowing/variable_declaration.md

@@ -0,0 +1,16 @@
+# Shadwing declaration
+
+## Shadow after incompatible declarations is OK
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+if flag:
+    x: str
+else:
+    x: int
+x: bytes = b"foo"
+```

crates/red_knot_python_semantic/resources/mdtest/stubs/class.md

@@ -0,0 +1,12 @@
+# Class defenitions in stubs
+
+## Cyclical class definition
+
+In type stubs, classes can reference themselves in their base class definitions. For example, in
+`typeshed`, we have `class str(Sequence[str]): ...`.
+
+```py path=a.pyi
+class C(C): ...
+
+reveal_type(C)  # revealed: Literal[C]
+```

crates/red_knot_python_semantic/resources/mdtest/subscript/bytes.md

@@ -0,0 +1,57 @@
+# Bytes subscripts
+
+## Indexing
+
+```py
+b = b"\x00abc\xff"
+
+reveal_type(b[0])  # revealed: Literal[b"\x00"]
+reveal_type(b[1])  # revealed: Literal[b"a"]
+reveal_type(b[4])  # revealed: Literal[b"\xff"]
+
+reveal_type(b[-1])  # revealed: Literal[b"\xff"]
+reveal_type(b[-2])  # revealed: Literal[b"c"]
+reveal_type(b[-5])  # revealed: Literal[b"\x00"]
+
+reveal_type(b[False])  # revealed: Literal[b"\x00"]
+reveal_type(b[True])  # revealed: Literal[b"a"]
+
+x = b[5]  # error: [index-out-of-bounds] "Index 5 is out of bounds for bytes literal `Literal[b"\x00abc\xff"]` with length 5"
+reveal_type(x)  # revealed: Unknown
+
+y = b[-6]  # error: [index-out-of-bounds] "Index -6 is out of bounds for bytes literal `Literal[b"\x00abc\xff"]` with length 5"
+reveal_type(y)  # revealed: Unknown
+
+def int_instance() -> int:
+    return 42
+
+a = b"abcde"[int_instance()]
+# TODO: Support overloads... Should be `bytes`
+reveal_type(a)  # revealed: @Todo
+```
+
+## Slices
+
+```py
+b = b"\x00abc\xff"
+
+reveal_type(b[0:2])  # revealed: Literal[b"\x00a"]
+reveal_type(b[-3:])  # revealed: Literal[b"bc\xff"]
+
+b[0:4:0]  # error: [zero-stepsize-in-slice]
+b[:4:0]  # error: [zero-stepsize-in-slice]
+b[0::0]  # error: [zero-stepsize-in-slice]
+b[::0]  # error: [zero-stepsize-in-slice]
+
+def int_instance() -> int: ...
+
+byte_slice1 = b[int_instance() : int_instance()]
+# TODO: Support overloads... Should be `bytes`
+reveal_type(byte_slice1)  # revealed: @Todo
+
+def bytes_instance() -> bytes: ...
+
+byte_slice2 = bytes_instance()[0:5]
+# TODO: Support overloads... Should be `bytes`
+reveal_type(byte_slice2)  # revealed: @Todo
+```

crates/red_knot_python_semantic/resources/mdtest/subscript/class.md

@@ -0,0 +1,93 @@
+# Class subscript
+
+## Class getitem unbound
+
+```py
+class NotSubscriptable: ...
+
+a = NotSubscriptable[0]  # error: "Cannot subscript object of type `Literal[NotSubscriptable]` with no `__class_getitem__` method"
+```
+
+## Class getitem
+
+```py
+class Identity:
+    def __class_getitem__(cls, item: int) -> str:
+        return item
+
+reveal_type(Identity[0])  # revealed: str
+```
+
+## Class getitem union
+
+```py
+flag = True
+
+class UnionClassGetItem:
+    if flag:
+
+        def __class_getitem__(cls, item: int) -> str:
+            return item
+    else:
+
+        def __class_getitem__(cls, item: int) -> int:
+            return item
+
+reveal_type(UnionClassGetItem[0])  # revealed: str | int
+```
+
+## Class getitem with class union
+
+```py
+flag = True
+
+class A:
+    def __class_getitem__(cls, item: int) -> str:
+        return item
+
+class B:
+    def __class_getitem__(cls, item: int) -> int:
+        return item
+
+x = A if flag else B
+
+reveal_type(x)  # revealed: Literal[A, B]
+reveal_type(x[0])  # revealed: str | int
+```
+
+## Class getitem with unbound method union
+
+```py
+flag = True
+
+if flag:
+    class Spam:
+        def __class_getitem__(self, x: int) -> str:
+            return "foo"
+
+else:
+    class Spam: ...
+
+# error: [call-possibly-unbound-method] "Method `__class_getitem__` of type `Literal[Spam, Spam]` is possibly unbound"
+# revealed: str
+reveal_type(Spam[42])
+```
+
+## TODO: Class getitem non-class union
+
+```py
+flag = True
+
+if flag:
+    class Eggs:
+        def __class_getitem__(self, x: int) -> str:
+            return "foo"
+
+else:
+    Eggs = 1
+
+a = Eggs[42]  # error: "Cannot subscript object of type `Literal[Eggs] | Literal[1]` with no `__getitem__` method"
+
+# TODO: should _probably_ emit `str | Unknown`
+reveal_type(a)  # revealed: Unknown
+```

crates/red_knot_python_semantic/resources/mdtest/subscript/instance.md

@@ -0,0 +1,46 @@
+# Instance subscript
+
+## Getitem unbound
+
+```py
+class NotSubscriptable: ...
+
+a = NotSubscriptable()[0]  # error: "Cannot subscript object of type `NotSubscriptable` with no `__getitem__` method"
+```
+
+## Getitem not callable
+
+```py
+class NotSubscriptable:
+    __getitem__ = None
+
+a = NotSubscriptable()[0]  # error: "Method `__getitem__` of type `None` is not callable on object of type `NotSubscriptable`"
+```
+
+## Valid getitem
+
+```py
+class Identity:
+    def __getitem__(self, index: int) -> int:
+        return index
+
+reveal_type(Identity()[0])  # revealed: int
+```
+
+## Getitem union
+
+```py
+flag = True
+
+class Identity:
+    if flag:
+
+        def __getitem__(self, index: int) -> int:
+            return index
+    else:
+
+        def __getitem__(self, index: int) -> str:
+            return str(index)
+
+reveal_type(Identity()[0])  # revealed: int | str
+```

crates/red_knot_python_semantic/resources/mdtest/subscript/lists.md

@@ -0,0 +1,37 @@
+# List subscripts
+
+## Indexing into lists
+
+A list can be indexed into with:
+
+- numbers
+- slices
+
+```py
+x = [1, 2, 3]
+reveal_type(x)  # revealed: list
+
+# TODO reveal int
+reveal_type(x[0])  # revealed: @Todo
+
+# TODO reveal list
+reveal_type(x[0:1])  # revealed: @Todo
+
+# TODO error
+reveal_type(x["a"])  # revealed: @Todo
+```
+
+## Assignments within list assignment
+
+In assignment, we might also have a named assignment. This should also get type checked.
+
+```py
+x = [1, 2, 3]
+x[0 if (y := 2) else 1] = 5
+
+# TODO error? (indeterminite index type)
+x["a" if (y := 2) else 1] = 6
+
+# TODO error (can't index via string)
+x["a" if (y := 2) else "b"] = 6
+```

crates/red_knot_python_semantic/resources/mdtest/subscript/stepsize_zero.md

@@ -0,0 +1,13 @@
+# Stepsize zero in slices
+
+We raise a `zero-stepsize-in-slice` diagnostic when trying to slice a literal string, bytes, or
+tuple with a step size of zero (see tests in `string.md`, `bytes.md` and `tuple.md`). But we don't
+want to raise this diagnostic when slicing a custom type:
+
+```py
+class MySequence:
+    def __getitem__(self, s: slice) -> int:
+        return 0
+
+MySequence()[0:1:0]  # No error
+```

crates/red_knot_python_semantic/resources/mdtest/subscript/string.md

@@ -0,0 +1,99 @@
+# String subscripts
+
+## Indexing
+
+```py
+s = "abcde"
+
+reveal_type(s[0])  # revealed: Literal["a"]
+reveal_type(s[1])  # revealed: Literal["b"]
+reveal_type(s[-1])  # revealed: Literal["e"]
+reveal_type(s[-2])  # revealed: Literal["d"]
+
+reveal_type(s[False])  # revealed: Literal["a"]
+reveal_type(s[True])  # revealed: Literal["b"]
+
+a = s[8]  # error: [index-out-of-bounds] "Index 8 is out of bounds for string `Literal["abcde"]` with length 5"
+reveal_type(a)  # revealed: Unknown
+
+b = s[-8]  # error: [index-out-of-bounds] "Index -8 is out of bounds for string `Literal["abcde"]` with length 5"
+reveal_type(b)  # revealed: Unknown
+
+def int_instance() -> int: ...
+
+a = "abcde"[int_instance()]
+# TODO: Support overloads... Should be `str`
+reveal_type(a)  # revealed: @Todo
+```
+
+## Slices
+
+```py
+s = "abcde"
+
+reveal_type(s[0:0])  # revealed: Literal[""]
+reveal_type(s[0:1])  # revealed: Literal["a"]
+reveal_type(s[0:2])  # revealed: Literal["ab"]
+reveal_type(s[0:5])  # revealed: Literal["abcde"]
+reveal_type(s[0:6])  # revealed: Literal["abcde"]
+reveal_type(s[1:3])  # revealed: Literal["bc"]
+
+reveal_type(s[-3:5])  # revealed: Literal["cde"]
+reveal_type(s[-4:-2])  # revealed: Literal["bc"]
+reveal_type(s[-10:10])  # revealed: Literal["abcde"]
+
+reveal_type(s[0:])  # revealed: Literal["abcde"]
+reveal_type(s[2:])  # revealed: Literal["cde"]
+reveal_type(s[5:])  # revealed: Literal[""]
+reveal_type(s[:2])  # revealed: Literal["ab"]
+reveal_type(s[:0])  # revealed: Literal[""]
+reveal_type(s[:2])  # revealed: Literal["ab"]
+reveal_type(s[:10])  # revealed: Literal["abcde"]
+reveal_type(s[:])  # revealed: Literal["abcde"]
+
+reveal_type(s[::-1])  # revealed: Literal["edcba"]
+reveal_type(s[::2])  # revealed: Literal["ace"]
+reveal_type(s[-2:-5:-1])  # revealed: Literal["dcb"]
+reveal_type(s[::-2])  # revealed: Literal["eca"]
+reveal_type(s[-1::-3])  # revealed: Literal["eb"]
+
+reveal_type(s[None:2:None])  # revealed: Literal["ab"]
+reveal_type(s[1:None:1])  # revealed: Literal["bcde"]
+reveal_type(s[None:None:None])  # revealed: Literal["abcde"]
+
+start = 1
+stop = None
+step = 2
+reveal_type(s[start:stop:step])  # revealed: Literal["bd"]
+
+reveal_type(s[False:True])  # revealed: Literal["a"]
+reveal_type(s[True:3])  # revealed: Literal["bc"]
+
+s[0:4:0]  # error: [zero-stepsize-in-slice]
+s[:4:0]  # error: [zero-stepsize-in-slice]
+s[0::0]  # error: [zero-stepsize-in-slice]
+s[::0]  # error: [zero-stepsize-in-slice]
+
+def int_instance() -> int: ...
+
+substring1 = s[int_instance() : int_instance()]
+# TODO: Support overloads... Should be `LiteralString`
+reveal_type(substring1)  # revealed: @Todo
+
+def str_instance() -> str: ...
+
+substring2 = str_instance()[0:5]
+# TODO: Support overloads... Should be `str`
+reveal_type(substring2)  # revealed: @Todo
+```
+
+## Unsupported slice types
+
+```py
+# TODO: It would be great if we raised an error here. This can be done once
+# we have support for overloads and generics, and once typeshed has a more
+# precise annotation for `str.__getitem__`, that makes use of the generic
+# `slice[..]` type. We could then infer `slice[str, str]` here and see that
+# it doesn't match the signature of `str.__getitem__`.
+"foo"["bar":"baz"]
+```

crates/red_knot_python_semantic/resources/mdtest/subscript/tuple.md

@@ -0,0 +1,75 @@
+# Tuple subscripts
+
+## Indexing
+
+```py
+t = (1, "a", "b")
+
+reveal_type(t[0])  # revealed: Literal[1]
+reveal_type(t[1])  # revealed: Literal["a"]
+reveal_type(t[-1])  # revealed: Literal["b"]
+reveal_type(t[-2])  # revealed: Literal["a"]
+
+reveal_type(t[False])  # revealed: Literal[1]
+reveal_type(t[True])  # revealed: Literal["a"]
+
+a = t[4]  # error: [index-out-of-bounds]
+reveal_type(a)  # revealed: Unknown
+
+b = t[-4]  # error: [index-out-of-bounds]
+reveal_type(b)  # revealed: Unknown
+```
+
+## Slices
+
+```py
+t = (1, "a", None, b"b")
+
+reveal_type(t[0:0])  # revealed: tuple[()]
+reveal_type(t[0:1])  # revealed: tuple[Literal[1]]
+reveal_type(t[0:2])  # revealed: tuple[Literal[1], Literal["a"]]
+reveal_type(t[0:4])  # revealed: tuple[Literal[1], Literal["a"], None, Literal[b"b"]]
+reveal_type(t[0:5])  # revealed: tuple[Literal[1], Literal["a"], None, Literal[b"b"]]
+reveal_type(t[1:3])  # revealed: tuple[Literal["a"], None]
+
+reveal_type(t[-2:4])  # revealed: tuple[None, Literal[b"b"]]
+reveal_type(t[-3:-1])  # revealed: tuple[Literal["a"], None]
+reveal_type(t[-10:10])  # revealed: tuple[Literal[1], Literal["a"], None, Literal[b"b"]]
+
+reveal_type(t[0:])  # revealed: tuple[Literal[1], Literal["a"], None, Literal[b"b"]]
+reveal_type(t[2:])  # revealed: tuple[None, Literal[b"b"]]
+reveal_type(t[4:])  # revealed: tuple[()]
+reveal_type(t[:0])  # revealed: tuple[()]
+reveal_type(t[:2])  # revealed: tuple[Literal[1], Literal["a"]]
+reveal_type(t[:10])  # revealed: tuple[Literal[1], Literal["a"], None, Literal[b"b"]]
+reveal_type(t[:])  # revealed: tuple[Literal[1], Literal["a"], None, Literal[b"b"]]
+
+reveal_type(t[::-1])  # revealed: tuple[Literal[b"b"], None, Literal["a"], Literal[1]]
+reveal_type(t[::2])  # revealed: tuple[Literal[1], None]
+reveal_type(t[-2:-5:-1])  # revealed: tuple[None, Literal["a"], Literal[1]]
+reveal_type(t[::-2])  # revealed: tuple[Literal[b"b"], Literal["a"]]
+reveal_type(t[-1::-3])  # revealed: tuple[Literal[b"b"], Literal[1]]
+
+reveal_type(t[None:2:None])  # revealed: tuple[Literal[1], Literal["a"]]
+reveal_type(t[1:None:1])  # revealed: tuple[Literal["a"], None, Literal[b"b"]]
+reveal_type(t[None:None:None])  # revealed: tuple[Literal[1], Literal["a"], None, Literal[b"b"]]
+
+start = 1
+stop = None
+step = 2
+reveal_type(t[start:stop:step])  # revealed: tuple[Literal["a"], Literal[b"b"]]
+
+reveal_type(t[False:True])  # revealed: tuple[Literal[1]]
+reveal_type(t[True:3])  # revealed: tuple[Literal["a"], None]
+
+t[0:4:0]  # error: [zero-stepsize-in-slice]
+t[:4:0]  # error: [zero-stepsize-in-slice]
+t[0::0]  # error: [zero-stepsize-in-slice]
+t[::0]  # error: [zero-stepsize-in-slice]
+
+def int_instance() -> int: ...
+
+tuple_slice = t[int_instance() : int_instance()]
+# TODO: Support overloads... Should be `tuple[Literal[1, 'a', b"b"] | None, ...]`
+reveal_type(tuple_slice)  # revealed: @Todo
+```

crates/red_knot_python_semantic/resources/mdtest/unary/instance.md

@@ -0,0 +1,29 @@
+# Unary Operations
+
+```py
+class Number:
+    def __init__(self, value: int):
+        self.value = 1
+
+    def __pos__(self) -> int:
+        return +self.value
+
+    def __neg__(self) -> int:
+        return -self.value
+
+    def __invert__(self) -> Literal[True]:
+        return True
+
+a = Number()
+
+reveal_type(+a)  # revealed: int
+reveal_type(-a)  # revealed: int
+reveal_type(~a)  # revealed: @Todo
+
+class NoDunder: ...
+
+b = NoDunder()
++b  # error: [unsupported-operator] "Unary operator `+` is unsupported for type `NoDunder`"
+-b  # error: [unsupported-operator] "Unary operator `-` is unsupported for type `NoDunder`"
+~b  # error: [unsupported-operator] "Unary operator `~` is unsupported for type `NoDunder`"
+```

crates/red_knot_python_semantic/resources/mdtest/unary/integers.md

@@ -0,0 +1,25 @@
+# Unary Operations
+
+## Unary Addition
+
+```py
+reveal_type(+0)  # revealed: Literal[0]
+reveal_type(+1)  # revealed: Literal[1]
+reveal_type(+True)  # revealed: Literal[1]
+```
+
+## Unary Subtraction
+
+```py
+reveal_type(-0)  # revealed: Literal[0]
+reveal_type(-1)  # revealed: Literal[-1]
+reveal_type(-True)  # revealed: Literal[-1]
+```
+
+## Unary Bitwise Inversion
+
+```py
+reveal_type(~0)  # revealed: Literal[-1]
+reveal_type(~1)  # revealed: Literal[-2]
+reveal_type(~True)  # revealed: Literal[-2]
+```

crates/red_knot_python_semantic/resources/mdtest/unary/not.md

@@ -0,0 +1,117 @@
+# Unary not
+
+## None
+
+```py
+reveal_type(not None)  # revealed: Literal[True]
+reveal_type(not not None)  # revealed: Literal[False]
+```
+
+## Function
+
+```py
+from typing import reveal_type
+
+def f():
+    return 1
+
+reveal_type(not f)  # revealed: Literal[False]
+# TODO Unknown should not be part of the type of typing.reveal_type
+# reveal_type(not reveal_type)  revealed: Literal[False]
+```
+
+## Module
+
+```py
+import b
+import warnings
+
+reveal_type(not b)  # revealed: Literal[False]
+reveal_type(not warnings)  # revealed: Literal[False]
+```
+
+```py path=b.py
+y = 1
+```
+
+## Union
+
+```py
+def bool_instance() -> bool:
+    return True
+
+flag = bool_instance()
+
+if flag:
+    p = 1
+    q = 3.3
+    r = "hello"
+    s = "world"
+    t = 0
+else:
+    p = "hello"
+    q = 4
+    r = ""
+    s = 0
+    t = ""
+
+reveal_type(not p)  # revealed: Literal[False]
+reveal_type(not q)  # revealed: bool
+reveal_type(not r)  # revealed: bool
+reveal_type(not s)  # revealed: bool
+reveal_type(not t)  # revealed: Literal[True]
+```
+
+## Integer literal
+
+```py
+reveal_type(not 1)  # revealed: Literal[False]
+reveal_type(not 1234567890987654321)  # revealed: Literal[False]
+reveal_type(not 0)  # revealed: Literal[True]
+reveal_type(not -1)  # revealed: Literal[False]
+reveal_type(not -1234567890987654321)  # revealed: Literal[False]
+reveal_type(not --987)  # revealed: Literal[False]
+```
+
+## Boolean literal
+
+```py
+w = True
+reveal_type(w)  # revealed: Literal[True]
+
+x = False
+reveal_type(x)  # revealed: Literal[False]
+
+reveal_type(not w)  # revealed: Literal[False]
+
+reveal_type(not x)  # revealed: Literal[True]
+```
+
+## String literal
+
+```py
+reveal_type(not "hello")  # revealed: Literal[False]
+reveal_type(not "")  # revealed: Literal[True]
+reveal_type(not "0")  # revealed: Literal[False]
+reveal_type(not "hello" + "world")  # revealed: Literal[False]
+```
+
+## Bytes literal
+
+```py
+reveal_type(not b"hello")  # revealed: Literal[False]
+reveal_type(not b"")  # revealed: Literal[True]
+reveal_type(not b"0")  # revealed: Literal[False]
+reveal_type(not b"hello" + b"world")  # revealed: Literal[False]
+```
+
+## Tuple
+
+```py
+reveal_type(not (1,))  # revealed: Literal[False]
+reveal_type(not (1, 2))  # revealed: Literal[False]
+reveal_type(not (1, 2, 3))  # revealed: Literal[False]
+reveal_type(not ())  # revealed: Literal[True]
+reveal_type(not ("hello",))  # revealed: Literal[False]
+reveal_type(not (1, "hello"))  # revealed: Literal[False]
+```