add return value docstring descriptions

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

@@ -301,6 +301,7 @@ def graph_from_gdfs(
     Returns
     -------
     G
+        The converted MultiDiGraph.
     """
     _validate_node_edge_gdfs(gdf_nodes, gdf_edges)
 
@@ -353,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()
@@ -396,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()
@@ -459,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
 
@@ -530,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

@@ -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)]
@@ -605,6 +611,7 @@ def _create_graph(
     Returns
     -------
     G
+        The resulting MultiDiGraph.
     """
     # each dict's keys are OSM IDs and values are dicts of attributes
     nodes: dict[int, dict[str, Any]] = {}
@@ -669,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:
@@ -690,6 +698,7 @@ def _convert_path(element: dict[str, Any]) -> dict[str, Any]:
     Returns
     -------
     path
+        The converted path.
     """
     path = {"osmid": element["id"]}
 
@@ -746,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:
@@ -792,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

osmnx/plot.py

@@ -55,20 +55,21 @@ def get_colors(
     Parameters
     ----------
     n
-        How many colors to generate.
+        How many colors to sample.
     cmap
-        Name of the matplotlib colormap from which to choose the colors.
+        Name of the matplotlib colormap from which to sample the colors.
     start
-        Where to start in the colorspace (from 0 to 1).
+        Where to start sampling from the colorspace (from 0 to 1).
     stop
-        Where to end in the colorspace (from 0 to 1).
+        Where to end sampling from the colorspace (from 0 to 1).
     alpha
         If `None`, return colors as HTML-like hex triplet "#rrggbb" RGB
         strings. If `float`, return as "#rrggbbaa" RGBa strings.
 
     Returns
     -------
     color_list
+        The sampled colors.
     """
     _verify_mpl()
     color_gen = (colormaps[cmap](x) for x in np.linspace(start, stop, n))
@@ -237,6 +238,7 @@ def plot_graph(  # noqa: PLR0913
     Returns
     -------
     fig, ax
+        The resulting matplotlib figure and axes objects.
     """
     _verify_mpl()
     max_node_size = max(node_size) if isinstance(node_size, Sequence) else node_size
@@ -331,6 +333,7 @@ def plot_graph_route(
     Returns
     -------
     fig, ax
+        The resulting matplotlib figure and axes objects.
     """
     _verify_mpl()
     if ax is None:
@@ -400,6 +403,7 @@ def plot_graph_routes(
     Returns
     -------
     fig, ax
+        The resulting matplotlib figure and axes objects.
     """
     # make iterables lists (so we're guaranteed to be able to get their sizes)
     routes = list(routes)
@@ -493,6 +497,7 @@ def plot_figure_ground(
     Returns
     -------
     fig, ax
+        The resulting matplotlib figure and axes objects.
     """
     _verify_mpl()
 
@@ -628,6 +633,7 @@ def plot_footprints(  # noqa: PLR0913
     Returns
     -------
     fig, ax
+        The resulting matplotlib figure and axes objects.
     """
     _verify_mpl()
     fig, ax = _get_fig_ax(ax=ax, figsize=figsize, bgcolor=bgcolor, polar=False)
@@ -731,6 +737,7 @@ def plot_orientation(  # noqa: PLR0913
     Returns
     -------
     fig, ax
+        The resulting matplotlib figure and polar axes objects.
     """
     _verify_mpl()
 
@@ -903,6 +910,7 @@ def _save_and_show(
     Returns
     -------
     fig, ax
+        The matplotlib figure and axes objects.
     """
     fig.canvas.draw()
     fig.canvas.flush_events()
@@ -964,6 +972,7 @@ def _config_ax(ax: Axes, crs: Any, bbox: tuple[float, float, float, float], padd
     Returns
     -------
     ax
+        The configured matplotlib axes object.
     """
     # set the axes view limits to bbox + relative padding
     left, bottom, right, top = bbox
@@ -1035,6 +1044,7 @@ def _get_fig_ax(
     Returns
     -------
     fig, ax
+        The resulting matplotlib figure and axes objects.
     """
     if ax is None:
         if polar:

osmnx/routing.py

@@ -198,6 +198,7 @@ def route_to_gdf(
     Returns
     -------
     gdf_edges
+        The ordered edges in the path.
     """
     pairs = zip(route[:-1], route[1:])
     uvk = ((u, v, min(G[u][v].items(), key=lambda i: i[1][weight])[0]) for u, v in pairs)

osmnx/simplification.py

@@ -55,7 +55,7 @@ def _is_endpoint(
     G
         Input graph.
     node
-        The ID of the node.
+        The ID of the node to check.
     node_attrs_include
         Node attribute names for relaxing the strictness of endpoint
         determination. A node is always an endpoint if it possesses one or
@@ -69,6 +69,7 @@ def _is_endpoint(
     Returns
     -------
     endpoint
+        True if node is an endpoint, otherwise False.
     """
     neighbors = set(list(G.predecessors(node)) + list(G.successors(node)))
     n = len(neighbors)