ENH: Add type hints

Author: snowman2

.travis.yml

@@ -115,6 +115,12 @@ install:
 script:
   - python -c "import pyproj; pyproj.Proj('epsg:4269')"
   - make test-coverage
+  - |
+    if [ "$TRAVIS_PYTHON_VERSION" = "3.5" ]; then
+        make check-type;
+    else
+        make check;
+    fi
   # Building and uploading docs with doctr
   - set -e
   - |

MANIFEST.in

@@ -7,6 +7,7 @@ include pyproj/*.pyd
 include pyproj/*.pyx
 include pyproj/*.pxd
 include pyproj/*.pxi
+include pyproj/*.pyi
 include test/sample.out
 include test/conftest.py
 recursive-include docs *

Makefile

@@ -63,7 +63,10 @@ clean-cython: ## clean the cython files
 lint: ## check style with flake8
 	flake8 --max-line-length 88 setup.py pyproj/ test/ docs/
 
-check: lint ## flake8 black isort check
+check-type:
+	mypy pyproj
+
+check: lint check-type ## flake8 black isort check
 	black --check setup.py pyproj/ test/ docs/
 	isort --check --recursive -m 3 -w 88 -tc -p test setup.py pyproj/ test/ docs/
 

docs/history.rst

@@ -4,6 +4,7 @@ Change Log
 2.6.0
 ~~~~~
 * ENH: Added Proj.get_factors() (issue #503) 
+* ENH: Added type hints (issue #369)
 
 2.5.0
 ~~~~~

pyproj/_crs.pxd

@@ -33,7 +33,7 @@ cdef class Base:
     cdef readonly object name
     cdef readonly object _remarks
     cdef readonly object _scope
-
+    cdef _set_base_info(self)
 
 cdef class _CRSParts(Base):
     pass

pyproj/_crs.pyi

@@ -0,0 +1,236 @@
+from typing import Any, Iterable, List, Optional, Tuple, Union
+
+from pyproj.crs.enums import CoordinateOperationType
+from pyproj.enums import ProjVersion, WktVersion
+
+class Axis:
+    name: str
+    abbrev: str
+    direction: str
+    unit_conversion_factor: float
+    unit_name: str
+    unit_auth_code: str
+    unit_code: str
+    def __str__(self) -> str: ...
+    def __repr__(self) -> str: ...
+
+class AreaOfUse:
+    west: float
+    south: float
+    east: float
+    north: float
+    name: str
+    def __str__(self) -> str: ...
+    def __repr__(self) -> str: ...
+    @property
+    def bounds(self) -> tuple[float]: ...
+
+class Base:
+    name: str
+    @property
+    def remarks(self) -> str: ...
+    @property
+    def scope(self) -> str: ...
+    def to_wkt(
+        self,
+        version: Union[WktVersion, str] = WktVersion.WKT2_2019,
+        pretty: bool = False,
+    ) -> str: ...
+    def to_json(self, pretty: bool = False, indentation: int = 2) -> str: ...
+    def to_json_dict(self) -> dict: ...
+    def __str__(self) -> str: ...
+    def __repr__(self) -> str: ...
+    def __eq__(self, other: Any) -> bool: ...
+    def is_exact_same(self, other: Any) -> bool: ...
+
+class _CRSParts(Base):
+    @classmethod
+    def from_user_input(cls, user_input: Any) -> "_CRSParts": ...
+
+class Ellipsoid(_CRSParts):
+    semi_major_metre: float
+    semi_minor_metre: float
+    is_semi_minor_computed: float
+    inverse_flattening: float
+    @staticmethod
+    def from_authority(auth_name: str, code: Union[int, str]) -> "Ellipsoid": ...
+    @staticmethod
+    def from_epsg(code: Union[int, str]) -> "Ellipsoid": ...
+    @staticmethod
+    def from_string(ellipsoid_string: str) -> "Ellipsoid": ...
+    @staticmethod
+    def from_json_dict(ellipsoid_dict: dict) -> "Ellipsoid": ...
+    @staticmethod
+    def from_json(ellipsoid_json_str: str) -> "Ellipsoid": ...
+    @staticmethod
+    def from_name(
+        ellipsoid_name: str, auth_name: Optional[str] = None
+    ) -> "Ellipsoid": ...
+
+class PrimeMeridian(_CRSParts):
+    longitude: float
+    unit_conversion_factor: str
+    unit_name: str
+    @staticmethod
+    def from_authority(auth_name: str, code: Union[int, str]) -> "PrimeMeridian": ...
+    @staticmethod
+    def from_epsg(code: Union[int, str]) -> "PrimeMeridian": ...
+    @staticmethod
+    def from_string(prime_meridian_string: str) -> "PrimeMeridian": ...
+    @staticmethod
+    def from_json_dict(prime_meridian_dict: dict) -> "PrimeMeridian": ...
+    @staticmethod
+    def from_json(prime_meridian_json_str: str) -> "PrimeMeridian": ...
+    @staticmethod
+    def from_name(
+        prime_meridian_name: str, auth_name: Optional[str] = None
+    ) -> "PrimeMeridian": ...
+
+class Datum(_CRSParts):
+    type_name: str
+    @property
+    def ellipsoid(self) -> Optional[Ellipsoid]: ...
+    @property
+    def prime_meridian(self) -> Optional[PrimeMeridian]: ...
+    @staticmethod
+    def from_authority(auth_name: str, code: Union[int, str]) -> "Datum": ...
+    @staticmethod
+    def from_epsg(code: Union[int, str]) -> "Datum": ...
+    @staticmethod
+    def from_string(datum_string: str) -> "Datum": ...
+    @staticmethod
+    def from_json_dict(datum_dict: dict) -> "Datum": ...
+    @staticmethod
+    def from_json(datum_json_str: str) -> "Datum": ...
+    @staticmethod
+    def from_name(datum_name: str, auth_name: Optional[str] = None) -> "Datum": ...
+
+class CoordinateSystem(_CRSParts):
+    def __init__(self) -> None: ...
+    @property
+    def axis_list(self) -> Iterable[Axis]: ...
+    @staticmethod
+    def from_string(coordinate_system_string: str) -> "CoordinateSystem": ...
+    @staticmethod
+    def from_json_dict(coordinate_system_dict: dict) -> "CoordinateSystem": ...
+    @staticmethod
+    def from_json(coordinate_system_json_str: str) -> "CoordinateSystem": ...
+
+class Param:
+    name: str
+    auth_name: str
+    code: str
+    value: str
+    unit_conversion_factor: float
+    unit_name: str
+    unit_auth_name: str
+    unit_code: str
+    unit_category: str
+    def __str__(self) -> str: ...
+    def __repr__(self) -> str: ...
+
+class Grid:
+    short_name: str
+    full_name: str
+    package_name: str
+    url: str
+    direct_download: str
+    open_license: str
+    available: str
+    def __str__(self) -> str: ...
+    def __repr__(self) -> str: ...
+
+class CoordinateOperation(_CRSParts):
+    method_name: str
+    method_auth_name: str
+    method_code: str
+    accuracy: float
+    is_instantiable: bool
+    has_ballpark_transformation: bool
+    type_name: str
+    @property
+    def params(self) -> Iterable[Param]: ...
+    @property
+    def grids(self) -> Iterable[Grid]: ...
+    @property
+    def area_of_use(self) -> Optional[AreaOfUse]: ...
+    @property
+    def towgs84(self) -> Iterable[float]: ...
+    @property
+    def operations(self) -> Tuple["CoordinateOperation"]: ...
+    def __init__(self) -> None: ...
+    def __repr__(self) -> str: ...
+    @staticmethod
+    def from_authority(
+        auth_name: str, code: Union[int, str]
+    ) -> "CoordinateOperation": ...
+    @staticmethod
+    def from_epsg(code: Union[int, str]) -> "CoordinateOperation": ...
+    @staticmethod
+    def from_string(ellipsoid_string: str) -> "CoordinateOperation": ...
+    @staticmethod
+    def from_json_dict(ellipsoid_dict: dict) -> "CoordinateOperation": ...
+    @staticmethod
+    def from_json(ellipsoid_json_str: str) -> "CoordinateOperation": ...
+    def to_proj4(
+        self, version: Union[ProjVersion, int] = ProjVersion.PROJ_5
+    ) -> str: ...
+    @staticmethod
+    def from_name(
+        coordinate_operation_name: str,
+        auth_name: Optional[str] = None,
+        coordinate_operation_type: Union[
+            CoordinateOperationType, str
+        ] = CoordinateOperationType.CONVERSION,
+    ) -> "CoordinateOperation": ...
+
+class _CRS(Base):
+    srs: str
+    type_name: str
+    def __init__(self, proj_string: str) -> None: ...
+    @property
+    def ellipsoid(self) -> Optional[Ellipsoid]: ...
+    @property
+    def area_of_use(self) -> Optional[AreaOfUse]: ...
+    @property
+    def axis_info(self) -> List[Axis]: ...
+    @property
+    def prime_meridian(self) -> Optional[PrimeMeridian]: ...
+    @property
+    def datum(self) -> Optional[Datum]: ...
+    @property
+    def sub_crs_list(self) -> Iterable["_CRS"]: ...
+    @property
+    def source_crs(self) -> Optional["_CRS"]: ...
+    @property
+    def target_crs(self) -> Optional["_CRS"]: ...
+    @property
+    def geodetic_crs(self) -> Optional["_CRS"]: ...
+    @property
+    def coordinate_system(self) -> Optional[CoordinateSystem]: ...
+    @property
+    def coordinate_operation(self) -> Optional[CoordinateOperation]: ...
+    def to_proj4(
+        self, version: Union[ProjVersion, int] = ProjVersion.PROJ_5
+    ) -> str: ...
+    def to_epsg(self, min_confidence: int = 70) -> Optional[int]: ...
+    def to_authority(
+        self, auth_name: Optional[str] = None, min_confidence: int = 70
+    ): ...
+    @property
+    def is_geographic(self) -> bool: ...
+    @property
+    def is_projected(self) -> bool: ...
+    @property
+    def is_vertical(self) -> bool: ...
+    @property
+    def is_bound(self) -> bool: ...
+    @property
+    def is_engineering(self) -> bool: ...
+    @property
+    def is_geocentric(self) -> bool: ...
+    def equals(self, other: Any, ignore_axis_order: bool) -> bool: ...
+
+def is_proj(proj_string: str) -> bool: ...
+def is_wkt(proj_string: str) -> bool: ...
+def _load_proj_json(in_proj_json: str) -> dict: ...

pyproj/_crs.pyx

@@ -389,7 +389,7 @@ cdef class Base:
         if self.context != NULL:
             proj_context_destroy(self.context)
 
-    def _set_base_info(self):
+    cdef _set_base_info(self):
         """
         Set the name of the PJ
         """
@@ -2327,7 +2327,7 @@ cdef class _CRS(Base):
         """
         Returns
         -------
-        list[Axis]: The list of axis information.
+        List[Axis]: The list of axis information.
         """
         return self.coordinate_system.axis_list if self.coordinate_system else []
 

pyproj/_datadir.pyi

@@ -0,0 +1 @@
+def pyproj_global_context_initialize() -> None: ...

pyproj/_geod.pxd

@@ -28,8 +28,8 @@ cdef extern from "geodesic.h":
 cdef class Geod:
     cdef geod_geodesic _geod_geodesic
     cdef readonly object initstring
-    cdef readonly object a
-    cdef readonly object b
-    cdef readonly object f
-    cdef readonly object es
-    cdef readonly object sphere
+    cdef readonly double a
+    cdef readonly double b
+    cdef readonly double f
+    cdef readonly double es
+    cdef readonly bint sphere

pyproj/_geod.pyi

@@ -0,0 +1,35 @@
+from typing import Any, Tuple, Type
+
+geodesic_version_str: str
+
+class Geod:
+    initstring: str
+    a: float
+    b: float
+    f: float
+    es: float
+    sphere: bool
+    def __init__(
+        self, a: float, f: float, sphere: bool, b: float, es: float
+    ) -> None: ...
+    def __reduce__(self) -> Tuple[Type["Geod"], str]: ...
+    def __repr__(self) -> str: ...
+    def _fwd(
+        self, lons: Any, lats: Any, az: Any, dist: Any, radians: bool = False
+    ) -> None: ...
+    def _inv(
+        self, lons1: Any, lats1: Any, lons2: Any, lats2: Any, radians: bool = False
+    ) -> None: ...
+    def _npts(
+        self,
+        lon1: float,
+        lat1: float,
+        lon2: float,
+        lat2: float,
+        npts: int,
+        radians: bool = False,
+    ) -> Tuple[Tuple[float], Tuple[float]]: ...
+    def _line_length(self, lons: Any, lats: Any, radians: bool = False) -> float: ...
+    def _polygon_area_perimeter(
+        self, lons: Any, lats: Any, radians: bool = False
+    ) -> Tuple[float, float]: ...

pyproj/_geod.pyx

@@ -12,16 +12,14 @@ geodesic_version_str = "{0}.{1}.{2}".format(
 )
 
 cdef class Geod:
-    def __init__(self, a, f, sphere, b, es):
+    def __init__(self, double a, double f, bint sphere, double b, double es):
         geod_init(&self._geod_geodesic, <double> a, <double> f)
         self.a = a
         self.f = f
-        if isinstance(a, float) and a.is_integer():
-            # convert 'a' only for initstring
-            a = int(a)
-        if f == 0.0:
-            f = 0
-        self.initstring = pystrdecode(cstrencode("+a=%s +f=%s" % (a, f)))
+        # convert 'a' only for initstring
+        a_str = int(a) if a.is_integer() else a
+        f_str = int(f) if f.is_integer() else f
+        self.initstring = pystrdecode(cstrencode("+a=%s +f=%s" % (a_str, f_str)))
         self.sphere = sphere
         self.b = b
         self.es = es

pyproj/_list.pyi

@@ -0,0 +1,20 @@
+from typing import Dict, List, NamedTuple, Union
+
+from pyproj.enums import PJType
+
+def get_proj_operations_map() -> Dict[str, str]: ...
+def get_ellps_map() -> Dict[str, Dict[str, float]]: ...
+def get_prime_meridians_map() -> Dict[str, str]: ...
+
+class Unit(NamedTuple):
+    id: str
+    to_meter: str
+    name: str
+    factor: float
+
+def get_units_map() -> Dict[str, Unit]: ...
+def get_angular_units_map() -> Dict[str, Unit]: ...
+def get_authorities() -> List[str]: ...
+def get_codes(
+    auth_name: str, pj_type: Union[PJType, str], allow_deprecated: bool = False
+) -> List[str]: ...