.github/workflows/test.yml

@@ -45,7 +45,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.9']
+        python-version: ['3.11']
     steps:
       - uses: actions/checkout@v3
       - name: Setup system dependencies
@@ -64,15 +64,36 @@ jobs:
       - name: Run tests
         run: PYTHONPATH='.' pytest
 
-  typecheck:
+  stubtest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11']
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install binutils libproj-dev gdal-bin
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          pip install -U pip setuptools wheel
+          pip install -r ./requirements.txt
+
+      - name: Run stubtest
+        run: bash ./scripts/stubtest.sh
+
+  matrix-test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
         python-version: ['3.8', '3.9', '3.10']
         django-version: ['3.2', '4.2']
         include:
-          - python-version: '3.8'
-            django-version: '2.2'
           - python-version: '3.11'
             django-version: '4.1'
     steps:
@@ -89,6 +110,8 @@ jobs:
         run: |
           pip install -U pip setuptools wheel
           pip install -r ./requirements.txt
+          pip install "Django==${{ matrix.django-version }}"
+          pip check
 
-      - name: Run tests
-        run: python ./scripts/typecheck_tests.py --django_version="${{ matrix.django-version }}"
+      - name: Run django-stubs-ext tests
+        run: PYTHONPATH='.' pytest django_stubs_ext

.gitignore

@@ -3,6 +3,7 @@
 .idea/
 .mypy_cache/
 .pytest_cache/
+.ruff_cache/
 .venv/
 __pycache__/
 django-source/

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 default_language_version:
-  python: python3.9
+  python: python3.11
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0
@@ -12,19 +12,11 @@ repos:
       - id: debug-statements
       - id: check-merge-conflict
       - id: end-of-file-fixer
-  - repo: https://github.com/asottile/pyupgrade
-    rev: v3.4.0
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.0.275
     hooks:
-      - id: pyupgrade
-        args: ["--py38-plus"]
-  - repo: https://github.com/pycqa/isort
-    rev: 5.12.0
-    hooks:
-      - id: isort
-        name: isort (python)
-      - id: isort
-        name: isort (pyi)
-        types: [pyi]
+      - id: ruff
+        args: ["--fix", "--exit-non-zero-on-fix"]
   - repo: https://github.com/psf/black
     rev: 23.3.0
     hooks:
@@ -34,8 +26,8 @@ repos:
     hooks:
       - id: flake8
         additional_dependencies:
-        - flake8-no-pep420==2.4.0
-        - flake8-pyi==22.11.0
+        - flake8-no-pep420==2.6.0
+        - flake8-pyi==23.5.0
         types: []
         files: ^.*.pyi?$
 

CONTRIBUTING.md

@@ -7,6 +7,7 @@ This project is open source and community driven. As such we encourage code cont
 3. Improve plugin code and extend its capabilities
 4. Write tests
 5. Update dependencies
+6. Fix and remove things from our `scripts/stubtest/allowlist_todo.txt`
 
 ## Tutorials
 
@@ -76,30 +77,19 @@ If you get some unexpected results or want to be sure that tests run is not affe
 rm -r .mypy_cache
 ```
 
-We also test the stubs against Django's own test suite. This is done in CI but you can also do this locally.
-To execute the script run:
-
-```bash
-python ./scripts/typecheck_tests.py --django_version 3.2
-```
+### Testing stubs with `stubtest`
 
+Run `bash ./scripts/stubtest.sh` to test that stubs and sources are in-line.
 
-### Generating Stubs using Stubgen
+We have two special files to allow errors:
+1. `scripts/stubtest/allowlist.txt` where we store things that we really don't care about: hacks, django internal utility modules, things that are handled by our plugin, things that are not representable by type system, etc
+2. `scripts/stubtest/allowlist_todo.txt` where we store all errors there are right now. Basically, this is a TODO list: we need to work through this list and fix things (or move entries to real `allowlist.txt`). In the end, ideally we can remove this file
 
-The stubs are based on auto-generated code created by Mypy's stubgen tool (see: [the stubgen docs](https://mypy.readthedocs.io/en/stable/stubgen.html)).
-To make life easier we have a helper script that auto generates these stubs. To use it you can run:
+You might also want to disable `incremental` mode while working on `stubtest` changes.
+This mode leads to several known problems (stubs do not show up or have strange errors).
 
-```bash
-python ./scripts/stubgen-django.py --django_version 3.2
-```
-
-You can also pass an optional commit hash as a second kwarg to checkout a specific commit, e.g.
-
-```bash
-python ./scripts/stubgen-django.py --django_version 3.2 --commit_sha <commit_sha>
-```
+**Important**: right now we only run `stubtest` on Python 3.11 (because it is the latest released version at the moment), any other versions might generate different outputs. Any work to create per-version allowlists is welcome.
 
-The output for this is a gitignored folder called "stubgen" in the repo's root.
 
 ## Submission Guidelines
 

README.md

@@ -49,6 +49,7 @@ We rely on different `django` and `mypy` versions:
 
 | django-stubs   | Mypy version | Django version | Django partial support | Python version |
 |----------------|--------------|----------------|------------------------|----------------|
+| 4.2.2          | 1.4.x        | 4.2            | 4.1, 3.2               | 3.8 - 3.11     |
 | 4.2.1          | 1.3.x        | 4.2            | 4.1, 3.2               | 3.8 - 3.11     |
 | 4.2.0          | 1.2.x        | 4.2            | 4.1, 4.0, 3.2          | 3.7 - 3.11     |
 | 1.16.0         | 1.1.x        | 4.1            | 4.0, 3.2               | 3.7 - 3.11     |
@@ -76,6 +77,26 @@ class MyModel(models.Model):
         ]
 ```
 
+### Other typed base classes
+
+* `django_stubs_ext.db.router.TypedDatabaseRouter` can be used as base when implementing custom database routers.
+
+## Settings
+
+django-stubs has a few settings, which you can list in:
+
+* `pyproject.toml`, under the table `[tool.django-stubs]`
+* `mypy.ini` under the table `[mypy.plugins.django-stubs]`
+
+The supported settings are:
+
+- `django_settings_module`, a string.
+
+  Specify the import path of your settings module, the same as Django’s [`DJANGO_SETTINGS_MODULE` environment variable](https://docs.djangoproject.com/en/stable/topics/settings/#designating-the-settings).
+
+- `strict_settings`, a boolean, default `true`.
+
+  Set to `false` if using dynamic settings, as [described below](https://github.com/typeddjango/django-stubs#how-to-use-a-custom-library-to-handle-django-settings).
 
 ## FAQ
 
@@ -308,6 +329,53 @@ If you encounter this error in your own code, you can either cast the `Promise`
 
 If this is reported on Django code, please report an issue or open a pull request to fix the type hints.
 
+### How to use a custom library to handle Django settings?
+
+Using something like [`django-split-settings`](https://github.com/wemake-services/django-split-settings) or [`django-configurations`](https://github.com/jazzband/django-configurations) will make it hard for mypy to infer your settings.
+
+This might also be the case when using something like:
+
+```python
+try:
+    from .local_settings import *
+except Exception:
+    pass
+```
+
+So, mypy would not like this code:
+
+```python
+from django.conf import settings
+
+settings.CUSTOM_VALUE  # E: 'Settings' object has no attribute 'CUSTOM_SETTING'
+```
+
+To handle this corner case we have a special setting `strict_settings` (`True` by default),
+you can switch it to `False` to always return `Any` and not raise any errors if runtime settings module has the given value,
+for example `pyproject.toml`:
+
+```toml
+[tool.django-stubs]
+strict_settings = false
+```
+
+or `mypy.ini`:
+
+```ini
+[mypy.plugins.django-stubs]
+strict_settings = false
+```
+
+And then:
+
+```python
+# Works:
+reveal_type(settings.EXISTS_IN_RUNTIME)  # N: Any
+
+# Errors:
+reveal_type(settings.MISSING)  # E: 'Settings' object has no attribute 'MISSING'
+```
+
 ## Related projects
 
 - [`awesome-python-typing`](https://github.com/typeddjango/awesome-python-typing) - Awesome list of all typing-related things in Python.

django-stubs/apps/config.pyi

@@ -3,8 +3,9 @@ from collections.abc import Iterator
 
 from django.apps.registry import Apps
 from django.db.models.base import Model
-from django.utils.functional import _StrOrPromise
+from django.utils.functional import _StrOrPromise, cached_property
 
+APPS_MODULE_NAME: str
 MODELS_MODULE_NAME: str
 
 class AppConfig:
@@ -17,6 +18,8 @@ class AppConfig:
     models_module: str | None
     models: dict[str, type[Model]]
     def __init__(self, app_name: str, app_module: types.ModuleType | None) -> None: ...
+    @cached_property
+    def default_auto_field(self) -> str: ...
     @classmethod
     def create(cls, entry: str) -> AppConfig: ...
     def get_model(self, model_name: str, require_ready: bool = ...) -> type[Model]: ...

django-stubs/conf/__init__.pyi

@@ -1,11 +1,10 @@
-from typing import Any
+from typing import Any, Literal
 
 from _typeshed import Self
 from django.utils.functional import LazyObject
-from typing_extensions import Literal
 
 # explicit dependency on standard settings to make it loaded
-from . import global_settings
+from . import global_settings  # noqa: F401
 
 ENVIRONMENT_VARIABLE: Literal["DJANGO_SETTINGS_MODULE"]
 DEFAULT_STORAGE_ALIAS: Literal["default"]

django-stubs/conf/global_settings.pyi

@@ -3,9 +3,9 @@ from re import Pattern
 
 # This is defined here as a do-nothing function because we can't import
 # django.utils.translation -- that module depends on the settings.
-from typing import Any, Protocol
+from typing import Any, Literal, Protocol
 
-from typing_extensions import Literal, TypeAlias
+from typing_extensions import TypeAlias
 
 _Admins: TypeAlias = list[tuple[str, str]]
 
@@ -40,6 +40,7 @@ TIME_ZONE: str
 
 # If you set this to True, Django will use timezone-aware datetimes.
 USE_TZ: bool
+USE_DEPRECATED_PYTZ: bool
 
 # Language code for this installation. All choices can be found here:
 # http://www.i18nguy.com/unicode/language-identifiers.html
@@ -210,6 +211,10 @@ DATA_UPLOAD_MAX_MEMORY_SIZE: int  # i.e. 2.5 MB
 # SuspiciousOperation (TooManyFieldsSent) is raised.
 DATA_UPLOAD_MAX_NUMBER_FIELDS: int
 
+# Maximum number of files encoded in a multipart upload that will be read
+# before a SuspiciousOperation (TooManyFilesSent) is raised.
+DATA_UPLOAD_MAX_NUMBER_FILES: int
+
 # Directory in which upload streamed files will be temporarily saved. A value of
 # `None` will make Django use the operating system's default temporary directory
 # (i.e. "/tmp" on *nix systems).
@@ -301,6 +306,9 @@ THOUSAND_SEPARATOR: str
 DEFAULT_TABLESPACE: str
 DEFAULT_INDEX_TABLESPACE: str
 
+# Default primary key field type.
+DEFAULT_AUTO_FIELD: str
+
 # Default X-Frame-Options header value
 X_FRAME_OPTIONS: str
 
@@ -425,6 +433,10 @@ CSRF_HEADER_NAME: str
 CSRF_TRUSTED_ORIGINS: list[str]
 CSRF_USE_SESSIONS: bool
 
+# Whether to mask CSRF cookie value. It's a transitional setting helpful in
+# migrating multiple instance of the same project to Django 4.1+.
+CSRF_COOKIE_MASKED: bool
+
 ############
 # MESSAGES #
 ############
@@ -445,6 +457,10 @@ LOGGING_CONFIG: str
 # Custom logging configuration.
 LOGGING: dict[str, Any]
 
+# Default exception reporter class used in case none has been
+# specifically assigned to the HttpRequest instance.
+DEFAULT_EXCEPTION_REPORTER: str
+
 # Default exception reporter filter class used in case none has been
 # specifically assigned to the HttpRequest instance.
 DEFAULT_EXCEPTION_REPORTER_FILTER: str
@@ -501,11 +517,12 @@ SILENCED_SYSTEM_CHECKS: list[str]
 #######################
 # SECURITY MIDDLEWARE #
 #######################
-SECURE_BROWSER_XSS_FILTER: bool
 SECURE_CONTENT_TYPE_NOSNIFF: bool
+SECURE_CROSS_ORIGIN_OPENER_POLICY: str
 SECURE_HSTS_INCLUDE_SUBDOMAINS: bool
 SECURE_HSTS_PRELOAD: bool
 SECURE_HSTS_SECONDS: int
 SECURE_REDIRECT_EXEMPT: list[str]
+SECURE_REFERRER_POLICY: str
 SECURE_SSL_HOST: str | None
 SECURE_SSL_REDIRECT: bool

django-stubs/contrib/admin/checks.pyi

@@ -3,7 +3,7 @@ from typing import Any
 
 from django.apps.config import AppConfig
 from django.contrib.admin.options import BaseModelAdmin
-from django.core.checks.messages import CheckMessage, Error
+from django.core.checks.messages import CheckMessage
 
 def check_admin_app(app_configs: Sequence[AppConfig] | None, **kwargs: Any) -> list[CheckMessage]: ...
 def check_dependencies(**kwargs: Any) -> list[CheckMessage]: ...