Merge pull request #1272 from gboeing/docs

add numpydoc validation to pre-commit

.pre-commit-config.yaml

@@ -29,8 +29,13 @@ repos:
       - id: yamllint
         args: [--strict, --config-file=./tests/.yamllint.yml]
 
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.8.0
+    hooks:
+      - id: numpydoc-validation
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.9.1
+    rev: v0.9.3
     hooks:
       - id: ruff
         args: [--fix]

environments/make-env-files.py

@@ -38,7 +38,7 @@ def make_requirement(
     Parameters
     ----------
     requirement
-        A requirement object
+        A requirement object.
     pin_exact
         If True, pin requirement to version rather than using existing
         specifier. Allows you to convert minimum versions to pinned versions.
@@ -49,6 +49,7 @@ def make_requirement(
     Returns
     -------
     requirement_str
+        The requirement's name and its specifier(s).
     """
     specifiers = list(requirement.specifier)
     if pin_exact and len(specifiers) == 1:

osmnx/_http.py

@@ -164,6 +164,7 @@ def _get_http_headers(
     Returns
     -------
     headers
+        The updated HTTP headers.
     """
     if user_agent is None:
         user_agent = settings.http_user_agent

osmnx/_nominatim.py

@@ -39,6 +39,7 @@ def _download_nominatim_element(
     Returns
     -------
     response_json
+        The Nominatim API's response.
     """
     # define the parameters
     params: OrderedDict[str, int | str] = OrderedDict()
@@ -102,6 +103,7 @@ def _nominatim_request(
     Returns
     -------
     response_json
+        The Nominatim API's response.
     """
     if request_type not in {"search", "reverse", "lookup"}:  # pragma: no cover
         msg = "Nominatim `request_type` must be 'search', 'reverse', or 'lookup'."

osmnx/_overpass.py

@@ -296,6 +296,7 @@ def _create_overpass_features_query(  # noqa: PLR0912
     Returns
     -------
     query
+        The Overpass features query.
     """
     # create overpass settings string
     overpass_settings = _make_overpass_settings()
@@ -450,6 +451,7 @@ def _overpass_request(
     Returns
     -------
     response_json
+        The Overpass API's response.
     """
     # resolve url to same IP even if there is server round-robin redirecting
     _http._config_dns(settings.overpass_url)

osmnx/convert.py

@@ -223,7 +223,6 @@ def _validate_node_edge_gdfs(
         GeoDataFrame of graph nodes uniquely indexed by `osmid`.
     gdf_edges
         GeoDataFrame of graph edges uniquely multi-indexed by `(u, v, key)`.
-    graph_attrs
 
     Returns
     -------
@@ -302,6 +301,7 @@ def graph_from_gdfs(
     Returns
     -------
     G
+        The converted MultiDiGraph.
     """
     _validate_node_edge_gdfs(gdf_nodes, gdf_edges)
 
@@ -354,7 +354,8 @@ def to_digraph(G: nx.MultiDiGraph, *, weight: str = "length") -> nx.DiGraph:
 
     Returns
     -------
-    G
+    D
+        The converted DiGraph.
     """
     # make a copy to not mutate original graph object caller passed in
     G = G.copy()
@@ -397,6 +398,7 @@ def to_undirected(G: nx.MultiDiGraph) -> nx.MultiGraph:
     Returns
     -------
     Gu
+        The converted MultiGraph.
     """
     # make a copy to not mutate original graph object caller passed in
     G = G.copy()
@@ -460,6 +462,7 @@ def _is_duplicate_edge(data1: dict[str, Any], data2: dict[str, Any]) -> bool:
     Returns
     -------
     is_dupe
+        True if `osmid` and `geometry` are the same, otherwise False.
     """
     is_dupe = False
 
@@ -531,6 +534,7 @@ def _update_edge_keys(G: nx.MultiDiGraph) -> nx.MultiDiGraph:
     Returns
     -------
     G
+        Graph with incremented keys where needed.
     """
     # identify all the edges that are duplicates based on a sorted combination
     # of their origin, destination, and key. that is, edge uv will match edge vu

osmnx/elevation.py

@@ -288,7 +288,7 @@ def add_node_elevations_google(
 
 def _elevation_request(url: str, pause: float) -> dict[str, Any]:
     """
-    Send a HTTP GET request to a Google Maps-style Elevation API.
+    Send a HTTP GET request to a Google Maps-style elevation API.
 
     Parameters
     ----------
@@ -300,6 +300,7 @@ def _elevation_request(url: str, pause: float) -> dict[str, Any]:
     Returns
     -------
     response_json
+        The elevation API's response.
     """
     # check if request already exists in cache
     cached_response_json = _http._retrieve_from_cache(url)

osmnx/features.py

@@ -351,10 +351,10 @@ def features_from_xml(
     ----------
     filepath
         Path to file containing OSM XML data.
-    tags
-        Query tags to optionally filter the final GeoDataFrame.
     polygon
         Spatial boundaries to optionally filter the final GeoDataFrame.
+    tags
+        Query tags to optionally filter the final GeoDataFrame.
     encoding
         The OSM XML file's character encoding.
 
@@ -444,6 +444,7 @@ def _process_features(
     Returns
     -------
     features
+        The features with geometries.
     """
     nodes = []  # all nodes, including ones that just compose ways
     feature_nodes = []  # nodes that possibly match our query tags
@@ -534,6 +535,7 @@ def _build_way_geometry(
     Returns
     -------
     geometry
+        The way's geometry.
     """
     # a way is a LineString by default, but if it's a closed way and it's not
     # tagged area=no, check if any of its tags denote it as a polygon instead
@@ -584,6 +586,7 @@ def _build_relation_geometry(
     Returns
     -------
     geometry
+        The relation's geometry.
     """
     inner_linestrings = []
     outer_linestrings = []
@@ -641,6 +644,7 @@ def _remove_polygon_holes(
     Returns
     -------
     geometry
+        The geometry minus inner holes.
     """
     if len(inner_polygons) == 0:
         # if there are no holes to remove, geom is the union of outer polygons

osmnx/graph.py

@@ -90,6 +90,7 @@ def graph_from_bbox(
     Returns
     -------
     G
+        The resulting MultiDiGraph.
 
     Notes
     -----
@@ -180,6 +181,7 @@ def graph_from_point(
     Returns
     -------
     G
+        The resulting MultiDiGraph.
 
     Notes
     -----
@@ -224,7 +226,7 @@ def graph_from_address(
     retain_all: bool = False,
     truncate_by_edge: bool = False,
     custom_filter: str | list[str] | None = None,
-) -> nx.MultiDiGraph | tuple[nx.MultiDiGraph, tuple[float, float]]:
+) -> nx.MultiDiGraph:
     """
     Download and create a graph within some distance of an address.
 
@@ -277,7 +279,8 @@ def graph_from_address(
 
     Returns
     -------
-    G or (G, (lat, lon))
+    G
+        The resulting MultiDiGraph.
 
     Notes
     -----
@@ -375,6 +378,7 @@ def graph_from_place(
     Returns
     -------
     G
+        The resulting MultiDiGraph.
 
     Notes
     -----
@@ -456,6 +460,7 @@ def graph_from_polygon(
     Returns
     -------
     G
+        The resulting MultiDiGraph.
 
     Notes
     -----
@@ -564,6 +569,7 @@ def graph_from_xml(
     Returns
     -------
     G
+        The resulting MultiDiGraph.
     """
     # transmogrify file of OSM XML data into JSON
     response_jsons = [_osm_xml._overpass_json_from_xml(Path(filepath), encoding)]
@@ -599,15 +605,13 @@ def _create_graph(
     ----------
     response_jsons
         Iterable of JSON responses from the Overpass API.
-    retain_all
-        If True, return the entire graph even if it is not connected.
-        Otherwise, retain only the largest weakly connected component.
     bidirectional
         If True, create bidirectional edges for one-way streets.
 
     Returns
     -------
     G
+        The resulting MultiDiGraph.
     """
     # each dict's keys are OSM IDs and values are dicts of attributes
     nodes: dict[int, dict[str, Any]] = {}
@@ -672,6 +676,7 @@ def _convert_node(element: dict[str, Any]) -> dict[str, Any]:
     Returns
     -------
     node
+        The converted node.
     """
     node = {"y": element["lat"], "x": element["lon"]}
     if "tags" in element:
@@ -693,6 +698,7 @@ def _convert_path(element: dict[str, Any]) -> dict[str, Any]:
     Returns
     -------
     path
+        The converted path.
     """
     path = {"osmid": element["id"]}
 
@@ -749,6 +755,7 @@ def _is_path_one_way(attrs: dict[str, Any], bidirectional: bool, oneway_values:
     Returns
     -------
     is_one_way
+        True if path allows travel in only one direction, otherwise False.
     """
     # rule 1
     if settings.all_oneway:
@@ -795,6 +802,7 @@ def _is_path_reversed(attrs: dict[str, Any], reversed_values: set[str]) -> bool:
     Returns
     -------
     is_reversed
+        True if nodes' order should be reversed, otherwise False.
     """
     return "oneway" in attrs and attrs["oneway"] in reversed_values
 

osmnx/io.py

@@ -179,6 +179,7 @@ def load_graphml(
     Returns
     -------
     G
+        The loaded MultiDiGraph.
     """
     if (filepath is None and graphml_str is None) or (
         filepath is not None and graphml_str is not None
@@ -310,6 +311,7 @@ def _convert_graph_attr_types(G: nx.MultiDiGraph, dtypes: dict[str, Any]) -> nx.
     Returns
     -------
     G
+        The graph with its graph-level attributes' types converted.
     """
     # remove node_default and edge_default metadata keys if they exist
     G.graph.pop("node_default", None)
@@ -335,6 +337,7 @@ def _convert_node_attr_types(G: nx.MultiDiGraph, dtypes: dict[str, Any]) -> nx.M
     Returns
     -------
     G
+        The graph with its nodes' attributes' types converted.
     """
     for _, data in G.nodes(data=True):
         # first, eval stringified lists, dicts, or sets to convert them to objects
@@ -365,6 +368,7 @@ def _convert_edge_attr_types(G: nx.MultiDiGraph, dtypes: dict[str, Any]) -> nx.M
     Returns
     -------
     G
+        The graph with its edges' attributes' types converted.
     """
     # for each edge in the graph, eval attribute value lists and convert types
     for _, _, data in G.edges(data=True, keys=False):
@@ -411,11 +415,12 @@ def _convert_bool_string(value: bool | str) -> bool:
     Parameters
     ----------
     value
-        The string value to convert to bool.
+        The string to convert to bool.
 
     Returns
     -------
     bool_value
+        The boolean equivalent of the string literal.
     """
     if isinstance(value, bool):
         return value