Updates and improvements (#4)

.gitignore

@@ -1,4 +1,3 @@
-# dirs
 __pycache__/
 /build/
 /dist/
@@ -8,6 +7,5 @@ __pycache__/
 /venv/
 /env/
 
-# files
 .coverage
 *.pyc

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -10,7 +10,7 @@ repos:
       - id: mixed-line-ending
       - id: check-case-conflict
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.2.1 # must match requirements-tests.txt
+    rev: v0.4.3 # must match requirements-tests.txt
     hooks:
       - id: ruff
       - id: ruff-format

README.md

@@ -83,7 +83,7 @@ This project is licensed under the MIT License.
       <a href="https://github.com/geopandas/geopandas">GitHub</a>
     </th>
     <th>Complete</th>
-    <th>No</th>
+    <th>Partially</th>
   </tr>
   <tr>
     <th>shapely</th>

requirements-tests.txt

@@ -1,16 +1,16 @@
 # Tools
-ruff==0.2.1  # must match .pre-commit-config.yaml
+ruff==0.4.3  # must match .pre-commit-config.yaml
 pytest>=8.0
-mypy==1.8.0
-pyright==1.1.350
+mypy==1.10.0
+pyright==1.1.361
 
 # Runtime
 shapely>=2.0,<2.1
-geopandas>=0.14.3,<1.0
+geopandas>=0.14.4,<1.0
 
 # Transient dependencies
 matplotlib>=3.8.0
 pyproj>=3.6.1
 folium>=0.15.1
 rtree>=1.1.0
-pandas-stubs>=2.1.4.231227
+pandas-stubs>=2.2.1.240316

run.py

@@ -6,12 +6,21 @@
 import subprocess
 import sys
 
+try:
+    from rich.text import Text  # pyright: ignore[reportAssignmentType]
+    from rich_argparse import RawDescriptionRichHelpFormatter as RawDescriptionHelpFormatter
+except ModuleNotFoundError:
+    RawDescriptionHelpFormatter = argparse.RawDescriptionHelpFormatter
+
+    class Text(str): ...
+
+
 default_args = {
+    "ruff-check": ["tests", "stubs"],
+    "ruff-format": ["tests", "stubs"],
     "mypy": ["tests", "stubs/shapely-stubs", "stubs/geopandas-stubs"],
     "pyright": ["tests", "stubs/shapely-stubs", "stubs/geopandas-stubs"],
     "stubtest": ["--allowlist=stubtest_allowlist.txt", "shapely", "geopandas"],
-    "ruff-check": ["tests", "stubs"],
-    "ruff-format": ["tests", "stubs"],
     "pytest": [],
 }
 
@@ -36,16 +45,21 @@
 
 
 def main() -> int:
-    parser = argparse.ArgumentParser(
-        usage="%(prog)s [-h] command [args]",
-        description=description,
-        formatter_class=argparse.RawTextHelpFormatter,
-        add_help=False,
+    parser = argparse.ArgumentParser(description=Text(description), formatter_class=RawDescriptionHelpFormatter, add_help=False)
+    parser.add_argument(
+        "tool",
+        nargs="?",
+        metavar="command",
+        choices=default_args,
+        help="A command from (%(choices)s) to run, optionally with args. See the table above for more information.",
+    )
+    parser.add_argument(
+        "-h",
+        "--help",
+        action="store_true",
+        help="Show this help message and exit. Use `--help CMD` to print the help of a command `CMD`.",
     )
-    parser.add_argument("tool", nargs="?", metavar="tool", choices=default_args, help=argparse.SUPPRESS)
-    options = parser.add_argument_group("Options")
-    options.add_argument("-h", "--help", action="store_true", help="show this help message and exit")
-    options.add_argument("--all", action="store_true", help="run all checks")
+    parser.add_argument("--all", action="store_true", help="Run all the commands in the table above.")
 
     args, rest = parser.parse_known_args()
 
@@ -65,8 +79,7 @@ def main() -> int:
     elif tool:
         tools = [tool]
     else:
-        parser.print_usage()
-        parser.exit(1)
+        parser.error(f"missing command from ({', '.join(default_args)}) or `--all`")
 
     ret = 0
     for tool in tools:

stubs/geopandas-stubs/array.pyi

@@ -191,7 +191,7 @@ class GeometryArray(ExtensionArray):
     def shift(self, periods: int = 1, fill_value: Geometry | None = None) -> GeometryArray: ...  # type: ignore[override]
     def argmin(self, skipna: bool = True) -> NoReturn: ...
     def argmax(self, skipna: bool = True) -> NoReturn: ...
-    def __array__(self, dtype: Unused | None = None) -> NDArray[np.object_]: ...
+    def __array__(self, dtype: DTypeLike | None = None, copy: bool | None = None) -> NDArray[np.object_]: ...
     def __eq__(self, other: object) -> NDArray[np.bool_]: ...  # type: ignore[override]
     def __ne__(self, other: object) -> NDArray[np.bool_]: ...  # type: ignore[override]
     def __contains__(self, item: object) -> bool: ...

stubs/geopandas-stubs/base.pyi

@@ -1,7 +1,7 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, SupportsGetItem
 from collections.abc import Iterable
-from typing import Any, Literal, Protocol, overload
-from typing_extensions import TypeAlias, deprecated
+from typing import Any, Literal, Protocol, SupportsIndex, overload, type_check_only
+from typing_extensions import Self, TypeAlias, deprecated
 
 import numpy as np
 import pandas as pd
@@ -15,6 +15,7 @@ from geopandas.array import _Origin
 from geopandas.geoseries import GeoSeries
 from geopandas.sindex import BaseSpatialIndex
 
+@type_check_only
 class _SupportsToWkt(Protocol):
     def to_wkt(self) -> str: ...
 
@@ -128,7 +129,7 @@ class GeoPandasBase:
     def scale(self, xfact: float = 1.0, yfact: float = 1.0, zfact: float = 1.0, origin: _Origin = "center") -> GeoSeries: ...
     def skew(self, xs: float = 0.0, ys: float = 0.0, origin: _Origin = "center", use_radians: bool = False) -> GeoSeries: ...
     @property
-    def cx(self) -> _CoordinateIndexer: ...
+    def cx(self) -> SupportsGetItem[tuple[SupportsIndex | slice, SupportsIndex | slice], Self]: ...
     def get_coordinates(self, include_z: bool = False, ignore_index: bool = False, index_parts: bool = False) -> pd.DataFrame: ...
     def hilbert_distance(
         self, total_bounds: tuple[float, float, float, float] | Iterable[float] | None = None, level: int = 16
@@ -138,6 +139,7 @@ class GeoPandasBase:
         self,
         size: int | ArrayLike,
         method: str = "uniform",
+        seed: None = None,
         rng: int | ArrayLike | SeedSequence | BitGenerator | RandomGenerator | None = None,
         **kwargs,
     ) -> GeoSeries: ...
@@ -147,12 +149,8 @@ class GeoPandasBase:
         self,
         size: int | ArrayLike,
         method: str = "uniform",
-        seed: int | ArrayLike | SeedSequence | BitGenerator | RandomGenerator | None = None,
+        *,
+        seed: int | ArrayLike | SeedSequence | BitGenerator | RandomGenerator,
         rng: int | ArrayLike | SeedSequence | BitGenerator | RandomGenerator | None = None,
         **kwargs,
     ) -> GeoSeries: ...
-
-class _CoordinateIndexer:
-    obj: GeoPandasBase
-    def __init__(self, obj: GeoPandasBase) -> None: ...
-    def __getitem__(self, key: tuple[int | slice, int | slice]) -> GeoSeries: ...

stubs/geopandas-stubs/geodataframe.pyi

@@ -1,13 +1,13 @@
 import os
-from _typeshed import Incomplete, SupportsRead, SupportsWrite
-from collections.abc import Generator, Hashable, Iterable, Mapping, Sequence
-from typing import Any, Literal, overload
+from _typeshed import Incomplete, SupportsGetItem, SupportsRead, SupportsWrite
+from collections.abc import Callable, Generator, Hashable, Iterable, Mapping, Sequence
+from typing import Any, Literal, Protocol, overload, type_check_only
 from typing_extensions import Self, TypeAlias, deprecated
 
 import numpy as np
 import pandas as pd
 from numpy.typing import NDArray
-from pandas._typing import Axes, Dtype, ListLikeU, Scalar
+from pandas._typing import AggFuncTypeFrame, AstypeArg, Axes, Axis, Dtype, GroupByObject, IndexLabel, ListLikeU, Scalar
 from pyproj import CRS
 from shapely import Geometry
 
@@ -26,6 +26,11 @@ _ConvertibleToDataFrame: TypeAlias = (
     ListLikeU | pd.DataFrame | dict[Any, Any] | Iterable[ListLikeU | tuple[Hashable, ListLikeU] | dict[Any, Any]]
 )
 
+@type_check_only
+class _SupportsGeoInterface(Protocol):
+    @property
+    def __geo_interface__(self) -> dict[str, Any]: ...
+
 crs_mismatch_error: str
 
 class GeoDataFrame(GeoPandasBase, pd.DataFrame):  # type: ignore[misc]
@@ -73,7 +78,7 @@ class GeoDataFrame(GeoPandasBase, pd.DataFrame):  # type: ignore[misc]
     def set_geometry(
         self, col: _GeometryColumn, drop: bool = False, inplace: bool = False, crs: _ConvertibleToCRS | None = None
     ): ...
-    def rename_geometry(self, col: Hashable, inplace: bool = False): ...
+    def rename_geometry(self, col: Hashable, inplace: bool = False) -> Self: ...
     @property
     def crs(self) -> CRS | None: ...
     @crs.setter
@@ -95,7 +100,16 @@ class GeoDataFrame(GeoPandasBase, pd.DataFrame):  # type: ignore[misc]
         **kwargs: Any,  # depends on engine
     ) -> Self: ...
     @classmethod
-    def from_features(cls, features: Incomplete, crs: _ConvertibleToCRS | None = None, columns: Axes | None = None) -> Self: ...
+    def from_features(
+        cls,
+        features: (
+            _SupportsGeoInterface
+            | Mapping[str, _SupportsGeoInterface | SupportsGetItem[str, Any]]
+            | Iterable[_SupportsGeoInterface | SupportsGetItem[str, Any]]
+        ),
+        crs: _ConvertibleToCRS | None = None,
+        columns: Axes | None = None,
+    ) -> Self: ...
     @overload
     @classmethod
     def from_postgis(
@@ -165,7 +179,10 @@ class GeoDataFrame(GeoPandasBase, pd.DataFrame):  # type: ignore[misc]
         mode: Literal["w", "a"] = "w",
         crs: _ConvertibleToCRS | None = None,
         engine: Literal["fiona", "pyogrio"] | None = None,
-        **kwargs: Any,  # depends on driver
+        layer: int | str | None = None,
+        encoding: str | None = None,
+        overwrite: bool | Incomplete = ...,  # TODO can it be None? (accepted by fiona, not sure about pyogrio)
+        **kwargs: Any,  # engine and driver dependent
     ) -> None: ...
     def set_crs(
         self, crs: _ConvertibleToCRS | None = None, epsg: int | None = None, inplace: bool = False, allow_override: bool = False
@@ -176,23 +193,38 @@ class GeoDataFrame(GeoPandasBase, pd.DataFrame):  # type: ignore[misc]
     # def __setitem__(self, key, value) -> None: ...
     def copy(self, deep: bool = True) -> Self: ...
     def merge(self, *args, **kwargs) -> GeoDataFrame | pd.DataFrame: ...
-    def apply(self, func, axis: int = 0, raw: bool = False, result_type: Incomplete | None = None, args=(), **kwargs): ...  # type: ignore[override]
-    def __finalize__(self, other, method: Incomplete | None = None, **kwargs) -> Self: ...
+    def apply(  # type: ignore[override]
+        self,
+        func: Callable[..., Incomplete],
+        axis: Axis = 0,
+        raw: bool = False,
+        result_type: Literal["expand", "reduce", "broadcast"] | None = None,
+        args: tuple[Any, ...] = (),
+        *,
+        by_row: Literal[False, "compat"] = "compat",
+        engine: Literal["python", "numba"] = "python",
+        engine_kwargs: dict[str, bool] | None = None,
+        **kwargs,
+    ) -> pd.DataFrame | pd.Series[Any]: ...
+    def __finalize__(self, other, method: str | None = None, **kwargs) -> Self: ...
     def dissolve(
         self,
-        by: Incomplete | None = None,
-        aggfunc: str | Incomplete = "first",
+        by: GroupByObject | None = None,
+        aggfunc: AggFuncTypeFrame = "first",
         as_index: bool = True,
-        level: Incomplete | None = None,
+        level: IndexLabel | None = None,
         sort: bool = True,
         observed: bool = False,
         dropna: bool = True,
         **kwargs,
     ) -> GeoDataFrame: ...
-    def explode(
-        self, column: Hashable | None = None, ignore_index: bool = False, index_parts: bool | None = None, **kwargs
-    ) -> Self: ...
-    def astype(self, dtype, copy: bool = True, errors: str = "raise", **kwargs) -> GeoDataFrame | pd.DataFrame: ...
+    def explode(self, column: IndexLabel | None = None, ignore_index: bool = False, index_parts: bool | None = None) -> Self: ...
+    def astype(
+        self,
+        dtype: AstypeArg | Mapping[Any, Dtype] | pd.Series[Any],
+        copy: bool | None = None,
+        errors: Literal["ignore", "raise"] = "raise",
+    ) -> GeoDataFrame | pd.DataFrame: ...
     def convert_dtypes(
         self,
         infer_objects: bool = True,
@@ -207,11 +239,11 @@ class GeoDataFrame(GeoPandasBase, pd.DataFrame):  # type: ignore[misc]
         name: str,
         con: _SQLConnection,
         schema: str | None = None,
-        if_exists: str = "fail",
+        if_exists: Literal["fail", "replace", "append"] = "fail",
         index: bool = False,
-        index_label: Incomplete | None = None,
+        index_label: IndexLabel | None = None,
         chunksize: int | None = None,
-        dtype: Incomplete | None = None,
+        dtype: dict[Any, Incomplete] | None = None,
     ) -> None: ...
     @deprecated("'^' operator is deprecated. Use method `symmetric_difference` instead.")
     def __xor__(self, other: GeoSeries | Geometry) -> GeoSeries: ...  # type: ignore[override]

stubs/geopandas-stubs/geoseries.pyi

@@ -125,7 +125,10 @@ class GeoSeries(GeoPandasBase, pd.Series[BaseGeometry]):  # type: ignore[type-va
         mode: Literal["w", "a"] = "w",
         crs: _ConvertibleToCRS | None = None,
         engine: Literal["fiona", "pyogrio"] | None = None,
-        **kwargs: Any,  # depends on driver
+        layer: int | str | None = None,
+        encoding: str | None = None,
+        overwrite: bool | Incomplete = ...,  # TODO can it be None? (accepted by fiona, not sure about pyogrio)
+        **kwargs: Any,  # engine and driver dependent
     ) -> None: ...
     # *** TODO: compare `__getitem__` with pandas-stubs ***
     # def __getitem__(self, key): ...

stubs/geopandas-stubs/io/file.pyi

@@ -1,7 +1,8 @@
 import os
 from _typeshed import SupportsRead, SupportsWrite
+from collections import OrderedDict
 from collections.abc import Sequence
-from typing import Any, Literal, overload
+from typing import Any, Literal, TypedDict, overload
 from typing_extensions import TypeAlias, deprecated
 
 import numpy as np
@@ -25,6 +26,8 @@ def _read_file(
     engine: Literal["fiona", "pyogrio"] | None = None,
     *,
     ignore_geometry: Literal[False] = False,
+    layer: int | str | None = None,
+    encoding: str | None = None,
     **kwargs: Any,  # depends on engine
 ) -> GeoDataFrame: ...
 @overload
@@ -36,6 +39,8 @@ def _read_file(
     engine: Literal["fiona", "pyogrio"] | None = None,
     *,
     ignore_geometry: Literal[True],
+    layer: int | str | None = None,
+    encoding: str | None = None,
     **kwargs: Any,  # depends on engine
 ) -> pd.DataFrame: ...
 @deprecated("Function `geopandas.io.read_file` is deprecated. Use function `geopandas.from_file()` instead.")
@@ -47,6 +52,8 @@ def read_file(
     engine: Literal["fiona", "pyogrio"] | None = None,
     *,
     ignore_geometry: bool,
+    layer: int | str | None = None,
+    encoding: str | None = None,
     **kwargs: Any,
 ) -> pd.DataFrame: ...
 @deprecated("Function `geopandas.io.to_file` is deprecated. Use `GeoDataFrame.to_file()` or `GeoSeries.to_file()` instead.")
@@ -61,4 +68,9 @@ def to_file(
     engine: Literal["fiona", "pyogrio"] | None = None,
     **kwargs: Any,  # depends on driver
 ) -> None: ...
-def infer_schema(df: GeoDataFrame) -> dict[str, Any]: ...
+
+class _Schema(TypedDict):
+    geometry: str | list[str]
+    properties: OrderedDict[str, str]
+
+def infer_schema(df: GeoDataFrame) -> _Schema: ...