src/nominatim_core/typing.py

   1 # SPDX-License-Identifier: GPL-3.0-or-later
   2 #
   3 # This file is part of Nominatim. (https://nominatim.org)
   4 #
   5 # Copyright (C) 2024 by the Nominatim developer community.
   6 # For a full list of authors see the git log.
   7 """
   8 Type definitions for typing annotations.
   9
  10 Complex type definitions are moved here, to keep the source files readable.
  11 """
  12 from typing import Any, Union, Mapping, TypeVar, Sequence, TYPE_CHECKING
  13
  14 # Generics variable names do not confirm to naming styles, ignore globally here.
  15 # pylint: disable=invalid-name,abstract-method,multiple-statements
  16 # pylint: disable=missing-class-docstring,useless-import-alias
  17
  18 if TYPE_CHECKING:
  19     import psycopg2.sql
  20     import psycopg2.extensions
  21     import psycopg2.extras
  22     import os
  23
  24 StrPath = Union[str, 'os.PathLike[str]']
  25
  26 SysEnv = Mapping[str, str]
  27
  28 # psycopg2-related types
  29
  30 Query = Union[str, bytes, 'psycopg2.sql.Composable']
  31
  32 T_ResultKey = TypeVar('T_ResultKey', int, str)
  33
  34 class DictCursorResult(Mapping[str, Any]):
  35     def __getitem__(self, x: Union[int, str]) -> Any: ...
  36
  37 DictCursorResults = Sequence[DictCursorResult]
  38
  39 T_cursor = TypeVar('T_cursor', bound='psycopg2.extensions.cursor')
  40
  41 # The following typing features require typing_extensions to work
  42 # on all supported Python versions.
  43 # Only require this for type checking but not for normal operations.
  44
  45 if TYPE_CHECKING:
  46     from typing_extensions import (Protocol as Protocol,
  47                                    Final as Final,
  48                                    TypedDict as TypedDict)
  49 else:
  50     Protocol = object
  51     Final = 'Final'
  52     TypedDict = dict
  53
  54
  55 # SQLAlchemy introduced generic types in version 2.0 making typing
  56 # incompatible with older versions. Add wrappers here so we don't have
  57 # to litter the code with bare-string types.
  58
  59 if TYPE_CHECKING:
  60     import sqlalchemy as sa
  61     from typing_extensions import (TypeAlias as TypeAlias)
  62 else:
  63     TypeAlias = str
  64
  65 SaLambdaSelect: TypeAlias = 'Union[sa.Select[Any], sa.StatementLambdaElement]'
  66 SaSelect: TypeAlias = 'sa.Select[Any]'
  67 SaScalarSelect: TypeAlias = 'sa.ScalarSelect[Any]'
  68 SaRow: TypeAlias = 'sa.Row[Any]'
  69 SaColumn: TypeAlias = 'sa.ColumnElement[Any]'
  70 SaExpression: TypeAlias = 'sa.ColumnElement[bool]'
  71 SaLabel: TypeAlias = 'sa.Label[Any]'
  72 SaFromClause: TypeAlias = 'sa.FromClause'
  73 SaSelectable: TypeAlias = 'sa.Selectable'
  74 SaBind: TypeAlias = 'sa.BindParameter[Any]'
  75 SaDialect: TypeAlias = 'sa.Dialect'