Python CI: pyright 1.1.308 is not compatible with django-stubs 6.1.1

Summary

The Check Python types (3.14) job in Python CI fails on main. No Positron pull request caused this error but instead the django-stubs dependency has no version ceiling. django-stubs 6.1.1 came out on 2026-09-14, and it is not compatible with our pinned pyright 1.1.308.

Latest failing run on main: https://github.com/posit-dev/positron/actions/runs/35263777910

Error

Pyright reports 4 errors in a test fixture that nobody has changed since 2024:

extensions/positron-python/python_files/tests/unittestadapter/.data/simple_django/polls/tests.py:16:46 - error: Argument of type "ModelBase" cannot be assigned to parameter "cls" of type "Type[_Self@__getattr__]" in function "__getattr__"
  Type "ModelBase" cannot be assigned to type "Model"
    "ModelBase" is incompatible with "Model" (reportGeneralTypeIssues)

The same error repeats on lines 16, 25, 33, and 34.

Root cause

django-stubs #3593 removed objects: ClassVar[Manager[Self]] from Model. It added a fallback on the metaclass instead:

class ModelBase(type):
    def __getattr__(cls: type[_Self], name: Literal["objects"]) -> Manager[_Self]: ...

Pyright 1.1.308 does not bind that annotated cls parameter correctly on a metaclass. Newer versions of pyright bind it correctly. django-stubs tests itself against pyright 1.1.414.

Evidence

These results come from a local run against the same fixture:

pyright	django-stubs	Result
1.1.308 (our pin)	6.1.0	0 errors
1.1.308	6.1.1	The same 4 errors, on lines 16, 25, 33, and 34
1.1.414 (latest)	6.1.1	0 errors

Why only the 3.14 job fails

django 6.1 needs Python 3.12 or later. The Check Python types (3.9) job resolves an older set of stubs, so that job still passes.

Timeline

• 2026-09-12: last green Python CI run
• 2026-09-14: django-stubs 6.1.1 released
• 2026-09-16: first failed run
• 2026-09-17: main fails

Python CI has a path filter on extensions/positron-python/**. When a change lands under that path, main runs this workflow. The break therefore looks intermittent.

Short-term fix

Pin the ceiling in extensions/positron-python/build/test-requirements.txt:

# typing for Django files
# --- Start Positron ---
# django-stubs 6.1.1 resolves `objects` through a ModelBase.__getattr__ overload
# that pyright 1.1.308 mishandles. Unpin when we bump pyright.
django-stubs<6.1.1
# --- End Positron ---

The existing pytest<9.1.0 pin in the same file uses this style. With this pin, a local run on Python 3.14 and pyright 1.1.308 gives 0 errors.

This is a one-line change. It can ride along on any open pull request that already touches extensions/positron-python/.

Real fix

Bump pyright from 1.1.308 in .github/workflows/positron-python-ci.yml. The current pin dates from March 2024 and is 106 releases behind. django-stubs is not the last package that will outrun it.

This bump needs its own pull request. A local pass over python_files with pyright 1.1.414 showed error categories that 1.1.308 never reported: reportPossiblyUnbound, reportIncompatibleMethodOverride, and reportArgumentType. Those need real fixes.

I think what we should do is add a ceiling in the short term and then use this issue to track the pyright bump, and remove the django-stubs ceiling.

Start with extensions/positron-python/build/test-requirements.txt and compare the existing pytest pin style with the proposed django-stubs ceiling. Run the Check Python types (3.14) job or its equivalent against the simple_django fixture; done means pyright 1.1.308 reports zero errors with django-stubs 6.1.1 excluded.