Improve GeoDjango type-hints (#1299)

- Provide more specific type-hints for GeoDjango modules.
- Fixed some missing exports in `contrib/gis/**/__init__.py`.
- Removed unintentional re-exports in many modules.

django-stubs/contrib/gis/admin/__init__.pyi

@@ -4,8 +4,11 @@ from django.contrib.admin import AdminSite as AdminSite
 from django.contrib.admin import ModelAdmin as ModelAdmin
 from django.contrib.admin import StackedInline as StackedInline
 from django.contrib.admin import TabularInline as TabularInline
+from django.contrib.admin import action as action
 from django.contrib.admin import autodiscover as autodiscover
 from django.contrib.admin import register as register
 from django.contrib.admin import site as site
 from django.contrib.gis.admin.options import GeoModelAdmin as GeoModelAdmin
+from django.contrib.gis.admin.options import GISModelAdmin as GISModelAdmin
 from django.contrib.gis.admin.options import OSMGeoAdmin as OSMGeoAdmin
+from django.contrib.gis.admin.widgets import OpenLayersWidget as OpenLayersWidget

django-stubs/contrib/gis/admin/options.pyi

@@ -1,9 +1,14 @@
 from typing import Any
 
-from django.contrib.admin import ModelAdmin as ModelAdmin
+from django.contrib.admin import ModelAdmin
+from django.contrib.gis.forms import BaseGeometryWidget
 
 spherical_mercator_srid: int
 
+class GISModelAdmin(ModelAdmin):
+    gis_widget: BaseGeometryWidget
+    gis_widget_kwargs: dict[str, Any]
+
 class GeoModelAdmin(ModelAdmin):
     default_lon: int
     default_lat: int

django-stubs/contrib/gis/apps.pyi

@@ -1,8 +1,3 @@
-from typing import Any
+from django.apps import AppConfig
 
-from django.apps import AppConfig as AppConfig
-
-class GISConfig(AppConfig):
-    name: str
-    verbose_name: Any
-    def ready(self) -> None: ...
+class GISConfig(AppConfig): ...

django-stubs/contrib/gis/db/models/fields.pyi

@@ -1,6 +1,17 @@
 from collections.abc import Iterable
 from typing import Any, NamedTuple, TypeVar
 
+from django.contrib.gis import forms
+from django.contrib.gis.geos import (
+    GeometryCollection,
+    GEOSGeometry,
+    LineString,
+    MultiLineString,
+    MultiPoint,
+    MultiPolygon,
+    Point,
+    Polygon,
+)
 from django.core.validators import _ValidatorCallable
 from django.db.models.fields import Field, _ErrorMessagesT, _FieldChoices
 from django.utils.functional import _StrOrPromise
@@ -19,6 +30,12 @@ class SRIDCacheEntry(NamedTuple):
 def get_srid_info(srid: int, connection: Any) -> SRIDCacheEntry: ...
 
 class BaseSpatialField(Field[_ST, _GT]):
+    form_class: type[forms.GeometryField]
+    geom_type: str
+    geom_class: type[GEOSGeometry] | None
+    geography: bool
+    spatial_index: bool
+    srid: int
     def __init__(
         self,
         verbose_name: _StrOrPromise | None = ...,
@@ -59,12 +76,7 @@ class BaseSpatialField(Field[_ST, _GT]):
     def get_prep_value(self, value: Any) -> Any: ...
 
 class GeometryField(BaseSpatialField):
-    description: Any
-    form_class: Any
-    geom_type: str
-    geom_class: Any
-    dim: Any
-    geography: Any
+    dim: int
     def __init__(
         self,
         verbose_name: _StrOrPromise | None = ...,
@@ -101,56 +113,38 @@ class GeometryField(BaseSpatialField):
     def select_format(self, compiler: Any, sql: Any, params: Any) -> Any: ...
 
 class PointField(GeometryField):
-    geom_type: str
-    geom_class: Any
-    form_class: Any
-    description: Any
+    geom_class: type[Point]
+    form_class: type[forms.PointField]
 
 class LineStringField(GeometryField):
-    geom_type: str
-    geom_class: Any
-    form_class: Any
-    description: Any
+    geom_class: type[LineString]
+    form_class: type[forms.LineStringField]
 
 class PolygonField(GeometryField):
-    geom_type: str
-    geom_class: Any
-    form_class: Any
-    description: Any
+    geom_class: type[Polygon]
+    form_class: type[forms.PolygonField]
 
 class MultiPointField(GeometryField):
-    geom_type: str
-    geom_class: Any
-    form_class: Any
-    description: Any
+    geom_class: type[MultiPoint]
+    form_class: type[forms.MultiPointField]
 
 class MultiLineStringField(GeometryField):
-    geom_type: str
-    geom_class: Any
-    form_class: Any
-    description: Any
+    geom_class: type[MultiLineString]
+    form_class: type[forms.MultiLineStringField]
 
 class MultiPolygonField(GeometryField):
-    geom_type: str
-    geom_class: Any
-    form_class: Any
-    description: Any
+    geom_class: type[MultiPolygon]
+    form_class: type[forms.MultiPolygonField]
 
 class GeometryCollectionField(GeometryField):
-    geom_type: str
-    geom_class: Any
-    form_class: Any
-    description: Any
+    geom_class: type[GeometryCollection]
+    form_class: type[forms.GeometryCollectionField]
 
 class ExtentField(Field):
-    description: Any
     def get_internal_type(self) -> Any: ...
     def select_format(self, compiler: Any, sql: Any, params: Any) -> Any: ...
 
 class RasterField(BaseSpatialField):
-    description: Any
-    geom_type: str
-    geography: bool
     def db_type(self, connection: Any) -> Any: ...
     def from_db_value(self, value: Any, expression: Any, connection: Any) -> Any: ...
     def get_transform(self, name: Any) -> Any: ...

django-stubs/contrib/gis/db/models/sql/__init__.pyi

@@ -0,0 +1,2 @@
+from django.contrib.gis.db.models.sql.conversion import AreaField as AreaField
+from django.contrib.gis.db.models.sql.conversion import DistanceField as DistanceField

django-stubs/contrib/gis/feeds.pyi

@@ -1,29 +1,21 @@
+from collections.abc import Iterable, Sequence
 from typing import Any
 
 from django.contrib.syndication.views import Feed as BaseFeed
 from django.utils.feedgenerator import Atom1Feed, Rss201rev2Feed
+from django.utils.xmlutils import SimplerXMLGenerator
 
 class GeoFeedMixin:
-    def georss_coords(self, coords: Any) -> Any: ...
-    def add_georss_point(self, handler: Any, coords: Any, w3c_geo: bool = ...) -> None: ...
-    def add_georss_element(self, handler: Any, item: Any, w3c_geo: bool = ...) -> None: ...
+    def georss_coords(self, coords: Iterable[Sequence[float]]) -> str: ...
+    def add_georss_point(self, handler: SimplerXMLGenerator, coords: Sequence[float], w3c_geo: bool = ...) -> None: ...
+    def add_georss_element(self, handler: SimplerXMLGenerator, item: dict[str, Any], w3c_geo: bool = ...) -> None: ...
 
 class GeoRSSFeed(Rss201rev2Feed, GeoFeedMixin):
-    def rss_attributes(self) -> Any: ...
-    def add_item_elements(self, handler: Any, item: Any) -> None: ...
-    def add_root_elements(self, handler: Any) -> None: ...
+    def rss_attributes(self) -> dict[str, str]: ...
 
-class GeoAtom1Feed(Atom1Feed, GeoFeedMixin):
-    def root_attributes(self) -> Any: ...
-    def add_item_elements(self, handler: Any, item: Any) -> None: ...
-    def add_root_elements(self, handler: Any) -> None: ...
+class GeoAtom1Feed(Atom1Feed, GeoFeedMixin): ...
 
 class W3CGeoFeed(Rss201rev2Feed, GeoFeedMixin):
-    def rss_attributes(self) -> Any: ...
-    def add_item_elements(self, handler: Any, item: Any) -> None: ...
-    def add_root_elements(self, handler: Any) -> None: ...
+    def rss_attributes(self) -> dict[str, str]: ...
 
-class Feed(BaseFeed):
-    feed_type: Any
-    def feed_extra_kwargs(self, obj: Any) -> Any: ...
-    def item_extra_kwargs(self, item: Any) -> Any: ...
+class Feed(BaseFeed): ...

django-stubs/contrib/gis/forms/__init__.pyi

@@ -0,0 +1,13 @@
+from django.forms import *
+
+from .fields import GeometryCollectionField as GeometryCollectionField
+from .fields import GeometryField as GeometryField
+from .fields import LineStringField as LineStringField
+from .fields import MultiLineStringField as MultiLineStringField
+from .fields import MultiPointField as MultiPointField
+from .fields import MultiPolygonField as MultiPolygonField
+from .fields import PointField as PointField
+from .fields import PolygonField as PolygonField
+from .widgets import BaseGeometryWidget as BaseGeometryWidget
+from .widgets import OpenLayersWidget as OpenLayersWidget
+from .widgets import OSMWidget as OSMWidget

django-stubs/contrib/gis/gdal/datasource.pyi

@@ -1,16 +1,18 @@
 from typing import Any
 
-from django.contrib.gis.gdal.base import GDALBase as GDALBase
+from django.contrib.gis.gdal.base import GDALBase
+from django.contrib.gis.gdal.driver import Driver
+from django.contrib.gis.gdal.layer import Layer
 
 class DataSource(GDALBase):
     destructor: Any
-    encoding: Any
+    encoding: str
     ptr: Any
-    driver: Any
+    driver: Driver
     def __init__(self, ds_input: Any, ds_driver: bool = ..., write: bool = ..., encoding: str = ...) -> None: ...
-    def __getitem__(self, index: Any) -> Any: ...
+    def __getitem__(self, index: str | int) -> Layer: ...
     def __len__(self) -> int: ...
     @property
-    def layer_count(self) -> Any: ...
+    def layer_count(self) -> int: ...
     @property
-    def name(self) -> Any: ...
+    def name(self) -> str: ...

django-stubs/contrib/gis/gdal/driver.pyi

@@ -1,13 +1,13 @@
 from typing import Any
 
-from django.contrib.gis.gdal.base import GDALBase as GDALBase
+from django.contrib.gis.gdal.base import GDALBase
 
 class Driver(GDALBase):
     ptr: Any
     def __init__(self, dr_input: Any) -> None: ...
     @classmethod
     def ensure_registered(cls) -> None: ...
     @classmethod
-    def driver_count(cls) -> Any: ...
+    def driver_count(cls) -> int: ...
     @property
-    def name(self) -> Any: ...
+    def name(self) -> str: ...

django-stubs/contrib/gis/gdal/envelope.pyi

@@ -6,20 +6,20 @@ class OGREnvelope(Structure): ...
 class Envelope:
     def __init__(self, *args: Any) -> None: ...
     def __eq__(self, other: object) -> bool: ...
-    def expand_to_include(self, *args: Any) -> Any: ...
+    def expand_to_include(self, *args: Any) -> None: ...
     @property
-    def min_x(self) -> Any: ...
+    def min_x(self) -> float: ...
     @property
-    def min_y(self) -> Any: ...
+    def min_y(self) -> float: ...
     @property
-    def max_x(self) -> Any: ...
+    def max_x(self) -> float: ...
     @property
-    def max_y(self) -> Any: ...
+    def max_y(self) -> float: ...
     @property
-    def ur(self) -> Any: ...
+    def ur(self) -> tuple[float, float]: ...
     @property
-    def ll(self) -> Any: ...
+    def ll(self) -> tuple[float, float]: ...
     @property
-    def tuple(self) -> Any: ...
+    def tuple(self) -> tuple[float, float, float, float]: ...
     @property
-    def wkt(self) -> Any: ...
+    def wkt(self) -> str: ...

django-stubs/contrib/gis/gdal/feature.pyi

@@ -1,27 +1,30 @@
 from typing import Any
 
-from django.contrib.gis.gdal.base import GDALBase as GDALBase
+from django.contrib.gis.gdal.base import GDALBase
+from django.contrib.gis.gdal.field import Field
+from django.contrib.gis.gdal.geometries import OGRGeometry
+from django.contrib.gis.gdal.geomtype import OGRGeomType
 
 class Feature(GDALBase):
     destructor: Any
     ptr: Any
     def __init__(self, feat: Any, layer: Any) -> None: ...
-    def __getitem__(self, index: Any) -> Any: ...
+    def __getitem__(self, index: str | int) -> Field: ...
     def __len__(self) -> int: ...
     def __eq__(self, other: object) -> bool: ...
     @property
-    def encoding(self) -> Any: ...
+    def encoding(self) -> str: ...
     @property
-    def fid(self) -> Any: ...
+    def fid(self) -> int: ...
     @property
-    def layer_name(self) -> Any: ...
+    def layer_name(self) -> str: ...
     @property
-    def num_fields(self) -> Any: ...
+    def num_fields(self) -> int: ...
     @property
-    def fields(self) -> Any: ...
+    def fields(self) -> list[str]: ...
     @property
-    def geom(self) -> Any: ...
+    def geom(self) -> OGRGeometry: ...
     @property
-    def geom_type(self) -> Any: ...
-    def get(self, field: Any) -> Any: ...
-    def index(self, field_name: Any) -> Any: ...
+    def geom_type(self) -> OGRGeomType: ...
+    def get(self, field: str) -> Any: ...
+    def index(self, field_name: str) -> Any: ...

django-stubs/contrib/gis/gdal/field.pyi

@@ -1,28 +1,28 @@
 from typing import Any
 
-from django.contrib.gis.gdal.base import GDALBase as GDALBase
+from django.contrib.gis.gdal.base import GDALBase
 
 class Field(GDALBase):
     ptr: Any
     def __init__(self, feat: Any, index: Any) -> None: ...
-    def as_double(self) -> Any: ...
-    def as_int(self, is_64: bool = ...) -> Any: ...
-    def as_string(self) -> Any: ...
-    def as_datetime(self) -> Any: ...
+    def as_double(self) -> float | None: ...
+    def as_int(self, is_64: bool = ...) -> int | None: ...
+    def as_string(self) -> str | None: ...
+    def as_datetime(self) -> tuple[int, int, int, int, int, int, int] | None: ...
     @property
-    def is_set(self) -> Any: ...
+    def is_set(self) -> bool: ...
     @property
-    def name(self) -> Any: ...
+    def name(self) -> str: ...
     @property
-    def precision(self) -> Any: ...
+    def precision(self) -> int: ...
     @property
-    def type(self) -> Any: ...
+    def type(self) -> int: ...
     @property
-    def type_name(self) -> Any: ...
+    def type_name(self) -> bytes: ...
     @property
     def value(self) -> Any: ...
     @property
-    def width(self) -> Any: ...
+    def width(self) -> int: ...
 
 class OFTInteger(Field):
     @property