Merge pull request #2608 from ElLorans/master

Type hints

Author: samuelhwilliams

flask_admin/_backwards.py

@@ -6,10 +6,12 @@
 """
 
 import sys
+import typing as t
 import warnings
+from types import ModuleType
 
 
-def get_property(obj, name, old_name, default=None):
+def get_property(obj: t.Any, name: str, old_name: str, default: t.Any = None) -> t.Any:
     """
     Check if old property name exists and if it does - show warning message
     and return value.
@@ -34,13 +36,13 @@ def get_property(obj, name, old_name, default=None):
 
 
 class ObsoleteAttr:
-    def __init__(self, new_name, old_name, default):
+    def __init__(self, new_name: str, old_name: str, default: t.Any):
         self.new_name = new_name
         self.old_name = old_name
         self.cache = "_cache_" + new_name
         self.default = default
 
-    def __get__(self, obj, objtype=None):
+    def __get__(self, obj: t.Any, objtype: t.Optional[type] = None) -> "ObsoleteAttr":
         if obj is None:
             return self
 
@@ -62,20 +64,23 @@ def __get__(self, obj, objtype=None):
         # Return default otherwise
         return self.default
 
-    def __set__(self, obj, value):
+    def __set__(self, obj: t.Any, value: t.Any) -> None:
         setattr(obj, self.cache, value)
 
 
 class ImportRedirect:
-    def __init__(self, prefix, target):
+    def __init__(self, prefix: str, target: str):
         self.prefix = prefix
         self.target = target
 
-    def find_module(self, fullname, path=None):
+    def find_module(
+        self, fullname: str, path: t.Optional[str] = None
+    ) -> t.Optional["ImportRedirect"]:
         if fullname.startswith(self.prefix):
             return self
+        return None
 
-    def load_module(self, fullname):
+    def load_module(self, fullname: str) -> ModuleType:
         if fullname in sys.modules:
             return sys.modules[fullname]
 
@@ -86,5 +91,5 @@ def load_module(self, fullname):
         return module
 
 
-def import_redirect(old, new):
-    sys.meta_path.append(ImportRedirect(old, new))
+def import_redirect(old: str, new: str) -> None:
+    sys.meta_path.append(ImportRedirect(old, new))  # type: ignore[arg-type]

flask_admin/_compat.py

@@ -11,37 +11,43 @@
 :license: BSD, see LICENSE for more details.
 """
 
-from typing import Callable
+import typing as t
+from types import MappingProxyType
+from flask_admin._types import T_TRANSLATABLE, T_ITER_CHOICES
 
 text_type = str
 string_types = (str,)
 
 
-def itervalues(d: dict):
+def itervalues(d: dict) -> t.Iterator[t.Any]:
     return iter(d.values())
 
 
-def iteritems(d: dict):
+def iteritems(
+    d: t.Union[dict, MappingProxyType[str, t.Any], t.Mapping[str, t.Any]],
+) -> t.Iterator[tuple[t.Any, t.Any]]:
     return iter(d.items())
 
 
-def filter_list(f: Callable, l: list):
+def filter_list(f: t.Callable, l: list) -> list[t.Any]:
     return list(filter(f, l))
 
 
-def as_unicode(s):
+def as_unicode(s: t.Union[str, bytes]) -> str:
     if isinstance(s, bytes):
         return s.decode("utf-8")
 
     return str(s)
 
 
-def csv_encode(s):
+def csv_encode(s: t.Union[str, bytes]) -> str:
     """Returns unicode string expected by Python 3's csv module"""
     return as_unicode(s)
 
 
-def _iter_choices_wtforms_compat(val, label, selected):
+def _iter_choices_wtforms_compat(
+    val: str, label: T_TRANSLATABLE, selected: bool
+) -> T_ITER_CHOICES:
     """Compatibility for 3-tuples and 4-tuples in iter_choices
 
     https://wtforms.readthedocs.io/en/3.2.x/changes/#version-3-2-0

flask_admin/_types.py

@@ -1,12 +1,230 @@
-from collections.abc import Sequence
-from typing import Any
-from typing import Callable
-from typing import TYPE_CHECKING
-from typing import Union
+import typing as t
+from enum import Enum
+from os import PathLike
+from types import TracebackType
 
-if TYPE_CHECKING:
+import wtforms.widgets
+from flask import Response
+from jinja2.runtime import Context
+from markupsafe import Markup
+from typing_extensions import NotRequired
+from werkzeug.wrappers import Response as Wkzg_Response
+from wtforms import Field
+from wtforms.form import BaseForm
+from wtforms.utils import UnsetValue
+from wtforms.widgets import Input
+
+if t.TYPE_CHECKING:
+    from flask_admin.base import BaseView as T_VIEW  # noqa
+    from flask_admin.contrib.sqla.validators import InputRequired as T_INPUT_REQUIRED
+    from flask_admin.contrib.sqla.validators import (
+        TimeZoneValidator as T_TIMEZONE_VALIDATOR,
+    )
+    from flask_admin.contrib.sqla.validators import Unique as T_UNIQUE
+    from flask_admin.form import FormOpts as T_FORM_OPTS  # noqa
+    from flask_admin.model import BaseModelView as T_MODEL_VIEW
+    from flask_admin.model.ajax import AjaxModelLoader as T_AJAX_MODEL_LOADER  # noqa
+    from flask_admin.model.fields import AjaxSelectField as T_AJAX_SELECT_FIELD  # noqa
+    from flask_admin.model.form import (  # noqa
+        InlineBaseFormAdmin as T_INLINE_BASE_FORM_ADMIN,
+    )
+    from flask_admin.model.form import InlineFormAdmin as T_INLINE_FORM_ADMIN
+    from flask_admin.model.widgets import (
+        InlineFieldListWidget as T_INLINE_FIELD_LIST_WIDGET,
+    )
+    from flask_admin.model.widgets import InlineFormWidget as T_INLINE_FORM_WIDGET
+    from flask_admin.model.widgets import (
+        AjaxSelect2Widget as T_INLINE_AJAX_SELECT2_WIDGET,
+    )
+    from flask_admin.model.widgets import XEditableWidget as T_INLINE_X_EDITABLE_WIDGET
+
+    # optional dependencies
+    from arrow import Arrow as T_ARROW  # noqa
+    from flask_babel import LazyString as T_LAZY_STRING  # noqa
+
+    from flask_sqlalchemy import Model as T_SQLALCHEMY_MODEL
+    from flask_admin.contrib.peewee.form import BaseModel as T_PEEWEE_MODEL
+    from peewee import Field as T_PEEWEE_FIELD  # noqa
+    from pymongo import MongoClient as T_MONGO_CLIENT
     import sqlalchemy  # noqa
+    from sqlalchemy import Column as T_SQLALCHEMY_COLUMN
+    from sqlalchemy import Table as T_TABLE  # noqa
+    from sqlalchemy.orm import scoped_session as T_SQLALCHEMY_SESSION  # noqa
+    from sqlalchemy.orm.query import Query
+    from sqlalchemy.sql.selectable import Select
+
+    T_SQLALCHEMY_QUERY = t.Union[Query, Select]
+    from redis import Redis as T_REDIS  # noqa
+    from flask_admin.contrib.peewee.ajax import (
+        QueryAjaxModelLoader as T_PEEWEE_QUERY_AJAX_MODEL_LOADER,
+    )  # noqa
+    from flask_admin.contrib.sqla.ajax import (
+        QueryAjaxModelLoader as T_SQLA_QUERY_AJAX_MODEL_LOADER,
+    )  # noqa
+else:
+    T_VIEW = "flask_admin.base.BaseView"
+    T_INPUT_REQUIRED = "InputRequired"
+    T_TIMEZONE_VALIDATOR = "TimeZoneValidator"
+    T_UNIQUE = "Unique"
+    T_FORM_OPTS = "flask_admin.form.FormOpts"
+    T_MODEL_VIEW = "flask_admin.model.BaseModelView"
+    T_AJAX_MODEL_LOADER = "flask_admin.model.ajax.AjaxModelLoader"
+    T_AJAX_SELECT_FIELD = "flask_admin.model.fields.AjaxSelectField"
+    T_INLINE_BASE_FORM_ADMIN = "flask_admin.model.form.InlineBaseFormAdmin"
+    T_INLINE_FORM_ADMIN = "flask_admin.model.form.InlineFormAdmin"
+    T_INLINE_FIELD_LIST_WIDGET = "flask_admin.model.widgets.InlineFieldListWidget"
+    T_INLINE_FORM_WIDGET = "flask_admin.model.widgets.InlineFormWidget"
+    T_INLINE_AJAX_SELECT2_WIDGET = "flask_admin.model.widgets.AjaxSelect2Widget"
+    T_INLINE_X_EDITABLE_WIDGET = "flask_admin.model.widgets.XEditableWidget"
+
+    # optional dependencies
+    T_ARROW = "arrow.Arrow"
+    T_LAZY_STRING = "flask_babel.LazyString"
+    T_SQLALCHEMY_COLUMN = "sqlalchemy.Column"
+    T_SQLALCHEMY_MODEL = "flask_sqlalchemy.Model"
+    T_PEEWEE_FIELD = "peewee.Field"
+    T_PEEWEE_MODEL = "peewee.BaseModel"
+    T_MONGO_CLIENT = "pymongo.MongoClient"
+    T_TABLE = "sqlalchemy.Table"
+    T_SQLALCHEMY_QUERY = t.Union[
+        "sqlalchemy.sql.selectable.Select", "sqlalchemy.orm.query.Query"
+    ]
+    T_SQLALCHEMY_SESSION = "sqlalchemy.orm.scoped_session"
+    T_REDIS = "redis.Redis"
+    T_PEEWEE_QUERY_AJAX_MODEL_LOADER = (
+        "flask_admin.contrib.peewee.ajax.QueryAjaxModelLoader"
+    )
+    T_SQLA_QUERY_AJAX_MODEL_LOADER = (
+        "flask_admin.contrib.sqla.ajax.QueryAjaxModelLoader"
+    )
+
+T_COLUMN = t.Union[str, T_SQLALCHEMY_COLUMN]
+T_FILTER = tuple[int, T_COLUMN, str]
+T_COLUMN_LIST = t.Sequence[T_COLUMN]
+# Compatibility for 3-tuples and 4-tuples in iter_choices
+# https://wtforms.readthedocs.io/en/3.2.x/changes/#version-3-2-0
+T_ITER_CHOICES = t.Union[
+    tuple[t.Any, str, bool, dict[str, t.Any]], tuple[str, str, bool]
+]
+T_FORMATTER = t.Callable[[T_MODEL_VIEW, t.Optional[Context], t.Any, str], str]
+T_COLUMN_FORMATTERS = dict[str, T_FORMATTER]
+T_TYPE_FORMATTER = t.Callable[[T_MODEL_VIEW, t.Any, str], t.Union[str, Markup]]
+T_COLUMN_TYPE_FORMATTERS = dict[type, T_TYPE_FORMATTER]
+T_TRANSLATABLE = t.Union[str, T_LAZY_STRING]
+T_OPTION = tuple[str, T_TRANSLATABLE]
+T_OPTION_LIST = t.Sequence[T_OPTION]
+T_OPTIONS = t.Union[None, T_OPTION_LIST, t.Callable[[], T_OPTION_LIST]]
+T_ORM_MODEL = t.Union[T_SQLALCHEMY_MODEL, T_PEEWEE_MODEL, T_MONGO_CLIENT]
+T_QUERY_AJAX_MODEL_LOADER = t.Union[
+    T_PEEWEE_QUERY_AJAX_MODEL_LOADER, T_SQLA_QUERY_AJAX_MODEL_LOADER
+]
+T_RESPONSE = t.Union[Response, Wkzg_Response]
+T_SQLALCHEMY_INLINE_MODELS = t.Union[
+    t.Sequence[t.Union[T_INLINE_FORM_ADMIN, T_SQLALCHEMY_MODEL]],
+    tuple[T_SQLALCHEMY_MODEL, dict[str, t.Any]],
+]
+T_VALIDATOR = t.Union[
+    t.Callable[[t.Any, t.Any], t.Any],
+    T_UNIQUE,
+    T_INPUT_REQUIRED,
+    wtforms.validators.Optional,
+    wtforms.validators.Length,
+    wtforms.validators.AnyOf,
+    wtforms.validators.Email,
+    wtforms.validators.URL,
+    wtforms.validators.IPAddress,
+    T_TIMEZONE_VALIDATOR,
+    wtforms.validators.NumberRange,
+    wtforms.validators.MacAddress,
+]
+T_PATH_LIKE = t.Union[str, bytes, PathLike[str], PathLike[bytes]]
+
+
+class WidgetProtocol(t.Protocol):
+    def __call__(self, field: Field, **kwargs: t.Any) -> t.Union[str, Markup]: ...
+
+
+T_WIDGET = t.Union[
+    Input,
+    T_INLINE_FIELD_LIST_WIDGET,
+    T_INLINE_FORM_WIDGET,
+    T_INLINE_AJAX_SELECT2_WIDGET,
+    T_INLINE_X_EDITABLE_WIDGET,
+    WidgetProtocol,
+]
+
+T_WIDGET_TYPE = t.Optional[
+    t.Union[
+        t.Literal[
+            "daterangepicker",
+            "datetimepicker",
+            "datetimerangepicker",
+            "datepicker",
+            "select2-tags",
+            "timepicker",
+            "timerangepicker",
+            "uuid",
+        ],
+        str,
+    ]
+]
+
+
+class T_FIELD_ARGS_DESCRIPTION(t.TypedDict, total=False):
+    description: NotRequired[str]
+
+
+class T_FIELD_ARGS_FILTERS(t.TypedDict):
+    filters: NotRequired[list[t.Callable[[t.Any], t.Any]]]
+    allow_blank: NotRequired[bool]
+    choices: NotRequired[t.Union[list[tuple[int, str]], list[Enum]]]
+    validators: NotRequired[list[T_VALIDATOR]]
+    coerce: NotRequired[t.Callable[[t.Any], t.Any]]
+
+
+class T_FIELD_ARGS_LABEL(t.TypedDict):
+    label: NotRequired[str]
+
+
+class T_FIELD_ARGS_PLACES(t.TypedDict):
+    places: t.Optional[UnsetValue]
+
+
+class T_FIELD_ARGS_VALIDATORS(t.TypedDict, total=False):
+    label: NotRequired[str]
+    description: NotRequired[str]
+    filters: NotRequired[list[t.Callable[[t.Any], t.Any]]]
+    default: NotRequired[t.Any]
+    widget: NotRequired[Input]
+    validators: NotRequired[list[T_VALIDATOR]]
+    render_kw: NotRequired[dict[str, t.Any]]
+    name: NotRequired[str]
+    _form: NotRequired[BaseForm]
+    _prefix: NotRequired[str]
+
+
+class T_FIELD_ARGS_VALIDATORS_ALLOW_BLANK(T_FIELD_ARGS_VALIDATORS):
+    allow_blank: NotRequired[bool]
+
+
+# Flask types
+_ExcInfo = tuple[
+    t.Optional[type[BaseException]],
+    t.Optional[BaseException],
+    t.Optional[TracebackType],
+]
+_StartResponse = t.Callable[
+    [str, list[tuple[str, str]], t.Optional[_ExcInfo]], t.Callable[[bytes], t.Any]
+]
+_WSGICallable = t.Callable[[dict[str, t.Any], _StartResponse], t.Iterable[bytes]]
+_Status = t.Union[str, int]
+_Headers = t.Union[dict[t.Any, t.Any], list[tuple[t.Any, t.Any]]]
+_Body = t.Union[str, t.ByteString, dict[str, t.Any], Response, _WSGICallable]
+_ViewFuncReturnType = t.Union[
+    _Body,
+    tuple[_Body, _Status, _Headers],
+    tuple[_Body, _Status],
+    tuple[_Body, _Headers],
+]
 
-T_COLUMN_LIST = Sequence[Union[str, "sqlalchemy.Column"]]
-T_FORMATTER = Callable[[Any, Any, Any], Any]
-T_FORMATTERS = dict[type, T_FORMATTER]
+_ViewFunc = t.Union[t.Callable[..., t.NoReturn], t.Callable[..., _ViewFuncReturnType]]