Version 2.0.0 development

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -19,7 +19,7 @@ body:
     id: documentation_examples
     attributes:
       label: Documentation
-      description: Before you proceed, review the [documentation](https://osmnx.readthedocs.io/) and [OSMnx examples](https://github.com/gboeing/osmnx-examples) gallery, which cover key concepts, installation, and package usage.
+      description: Before you proceed, review the [documentation](https://osmnx.readthedocs.io/) and [examples gallery](https://github.com/gboeing/osmnx-examples), which cover key concepts, installation, and package usage.
       options:
         - label: My problem is not addressed by the documentation or examples
           required: true

.github/ISSUE_TEMPLATE/feature_proposal.yml

@@ -19,7 +19,7 @@ body:
     id: documentation_examples
     attributes:
       label: Documentation
-      description: Before you proceed, review the [documentation](https://osmnx.readthedocs.io/) and [OSMnx examples](https://github.com/gboeing/osmnx-examples) gallery, which cover key concepts, installation, and package usage.
+      description: Before you proceed, review the [documentation](https://osmnx.readthedocs.io/) and [examples gallery](https://github.com/gboeing/osmnx-examples), which cover key concepts, installation, and package usage.
       options:
         - label: My proposal is not addressed by the documentation or examples
           required: true

.github/dependabot.yml

@@ -1,6 +1,5 @@
 version: 2
 updates:
-  # Maintain dependencies for GitHub Actions
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

.github/pull_request_template.md

@@ -1,4 +1,4 @@
-**Read these instructions carefully**
+# Read these instructions carefully
 
 Before you proceed, review the contributing guidelines in the CONTRIBUTING.md file, especially the sections on project coding standards and tests. Please edit the changelog to reflect your changes.
 

.github/workflows/ci.yml

@@ -6,7 +6,8 @@ on:
   pull_request:
     branches: [main]
   schedule:
-    - cron: "0 6 * * 1" # Every Monday at 06:00 UTC
+    - cron: "0 5 * * 1" # every monday at 05:00 UTC
+  workflow_dispatch:
 
 jobs:
   build:
@@ -15,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
         os: [ubuntu-latest]
 
     defaults:
@@ -34,7 +35,7 @@ jobs:
           cache-downloads: true
           cache-environment: true
           create-args: python=${{ matrix.python-version }}
-          environment-file: tests/environments/env-ci.yml
+          environment-file: environments/tests/env-ci.yml
           post-cleanup: none
 
       - name: Install OSMnx
@@ -43,14 +44,16 @@ jobs:
           conda list
           conda info --all
 
-      - name: Lint code
+      - name: Run pre-commit checks
         run: SKIP=no-commit-to-branch pre-commit run --all-files
 
       - name: Test docs
-        run: make -C ./docs html
+        run: make -C ./docs html SPHINXOPTS="-E -W --keep-going"
 
-      - name: Test code
-        run: pytest --cov=./osmnx --cov-report=xml --cov-report=term-missing --verbose
+      - name: Test code and coverage
+        run: pytest --verbose --maxfail=1 --typeguard-packages=osmnx --cov=osmnx --cov-report=xml
 
       - name: Upload coverage report
         uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/test-build.yml

@@ -0,0 +1,41 @@
+name: Build and check package/docs
+
+on:
+  schedule:
+    - cron: "0 6 * * 1" # every monday at 06:00 UTC
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+
+    defaults:
+      run:
+        shell: bash -elo pipefail {0}
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Create environment with Micromamba
+        uses: mamba-org/setup-micromamba@v1
+        with:
+          cache-downloads: true
+          cache-environment: true
+          environment-file: environments/tests/env-test-build.yml
+          post-cleanup: none
+
+      - name: Build package and twine check
+        run: |
+          hatch build --clean
+          twine check --strict ./dist/*
+
+      - name: Build docs and check links
+        run: python -m sphinx -E -W --keep-going -b linkcheck ./docs/source ./docs/build/linkcheck

.github/workflows/test-minimal.yml

@@ -2,7 +2,7 @@ name: Test minimal versions
 
 on:
   schedule:
-    - cron: "0 7 * * 1" # Every Monday at 07:00 UTC
+    - cron: "0 4 * * 1" # every monday at 04:00 UTC
   workflow_dispatch:
 
 jobs:
@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest]
+        os: [macos-latest, ubuntu-latest, windows-latest]
 
     defaults:
       run:
@@ -29,7 +29,7 @@ jobs:
         with:
           cache-downloads: true
           cache-environment: true
-          environment-file: tests/environments/env-test-minimal.yml
+          environment-file: environments/tests/env-test-minimal.yml
           post-cleanup: none
 
       - name: Install OSMnx
@@ -38,16 +38,11 @@ jobs:
           conda list
           conda info --all
 
-      - name: Lint code
-        run: |
-          SKIP=no-commit-to-branch pre-commit run --all-files
-          hatch build --clean
-          twine check --strict ./dist/*
+      - name: Run pre-commit checks
+        run: SKIP=no-commit-to-branch pre-commit run --all-files
 
       - name: Test docs
-        run: |
-          make -C ./docs html
-          python -m sphinx -b linkcheck ./docs/source ./docs/build/linkcheck
+        run: make -C ./docs html SPHINXOPTS="-E -W --keep-going"
 
       - name: Test code
-        run: pytest --cov=./osmnx --cov-report=term-missing --verbose
+        run: pytest --verbose --maxfail=1 --typeguard-packages=osmnx

.gitignore

@@ -1,6 +1,5 @@
 .temp
 .pytest_cache
-tests/run_tests.bat
 *.vrt
 .DS_Store
 

.pre-commit-config.yaml

@@ -1,20 +1,19 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: "v4.5.0"
+    rev: "v4.6.0"
     hooks:
       - id: check-added-large-files
         args: [--maxkb=50]
       - id: check-ast
-      - id: check-builtin-literals
       - id: check-case-conflict
-      - id: check-docstring-first
+      - id: check-executables-have-shebangs
       - id: check-json
       - id: check-merge-conflict
         args: [--assume-in-merge]
+      - id: check-shebang-scripts-are-executable
       - id: check-toml
       - id: check-xml
       - id: check-yaml
-      - id: debug-statements
       - id: detect-private-key
       - id: end-of-file-fixer
       - id: fix-byte-order-marker
@@ -29,15 +28,27 @@ repos:
       - id: prettier
         types_or: [markdown, yaml]
 
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: "v0.39.0"
+    hooks:
+      - id: markdownlint
+        args: [--disable=MD013]
+
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: "v0.16"
+    hooks:
+      - id: validate-pyproject
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.1.15"
+    rev: "v0.4.1"
     hooks:
       - id: ruff
         args: [--fix]
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: "v1.8.0"
+    rev: "v1.9.0"
     hooks:
       - id: mypy
-        additional_dependencies: [types-requests]
+        additional_dependencies:
+          [matplotlib, pandas-stubs, pytest, types-requests]

CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 2.0.0 (in development)
+
+Read the v2 [migration guide](https://github.com/gboeing/osmnx/issues/1123)
+
+- add type annotations to all public and private functions throughout package (#1107)
+- remove all functionality previously deprecated in v1 (#1113 #1122 #1135 #1148)
+- drop Python 3.8 support (#1106)
+- bump minimum required numpy version to 1.21 for typing support (#1133)
+- improve docstrings throughout package (#1116)
+- improve logging and warnings throughout package (#1125)
+- improve error messages throughout package (#1131)
+- refactor features module for speed improvement and memory efficiency (#1157)
+- refactor save_graph_xml function and \_osm_xml module for speed improvement and bug fixes (#1135)
+- make save_graph_xml function accept only an unsimplified MultiDiGraph as its input data (#1135)
+- replace save_graph_xml function's edge_tag_aggs tuple parameter with way_tag_aggs dict parameter (#1135)
+- add OSM junction and railway tags to the default settings.useful_tags_node (#1144)
+- add node_attrs_include argument to simplification.simplify_graph function to flexibly relax strictness (#1145)
+- add edge_attr_aggs argument to simplify_graph function to specify aggregation behavior (#1155)
+- add node_attr_aggs argument to the consolidate_intersections function to specify aggregation behavior (#1155)
+- allow per-node tolerance values for intersection consolidation (#1160)
+- make consolidate_intersections function retain unique attribute values when consolidating nodes (#1144)
+- make which_result function parameters consistently able to accept a list throughout package (#1113)
+- handle implicit maxspeed values in add_edge_speeds function (#1153)
+- change add_node_elevations_google default batch_size to 512 to match Google's limit (#1115)
+- allow analysis of MultiDiGraph directional edge bearings and orientation (#1139)
+- fix graph projection creating useless lat and lon node attributes (#1144)
+- fix bug in \_downloader.\_save_to_cache function usage (#1107)
+- fix bug in handling requests ConnectionError when querying Overpass status endpoint (#1113)
+- fix minor bugs throughout to address inconsistencies revealed by type enforcement (#1107 #1114)
+- make optional function parameters keyword-only throughout package (#1134)
+- make dist function parameters required rather than optional throughout package (#1134)
+- make utils_geo.bbox_from_point function return a tuple of floats for consistency with rest of package (#1113)
+- rename truncate.truncate_graph_dist max_dist argument to dist for consistency with rest of package (#1134)
+- remove retain_all argument from all truncate module functions (#1148)
+- remove settings module's deprecated and now replaced settings (#1129 #1136)
+- rename osm_xml module to \_osm_xml to make it private, as all its functions are private (#1113)
+- rename private \_downloader module to \_http (#1114)
+- remove unnecessary private \_api module (#1114)
+
 ## 1.9.3 (2024-05-01)
 
 - update the official package reference paper (#1169)

CONTRIBUTING.md

@@ -1,29 +1,28 @@
 # Contributing guidelines
 
-Thanks for using OSMnx and for considering contributing to it by opening an issue or pull request. Every piece of software is a work in progress. This project is the result of many hours of work contributed freely its contributors and the many people that build the projects it depends on. Thank you for contributing!
+Thanks for using OSMnx and for considering contributing to it by opening an issue or pull request. Every piece of software is a work in progress. This project is the result of many hours of work contributed freely its contributors and the many people that build the projects on which it depends. Thank you for contributing!
 
-#### If you have a "how-to" or usage question:
+## If you have a "how-to" or usage question
 
-- please ask your question on [StackOverflow](https://stackoverflow.com/search?q=osmnx), as we reserve the issue tracker for bug reports and new feature development. Any such questions asked in the issue tracker will be automatically closed.
+Please ask your question on [StackOverflow](https://stackoverflow.com/search?q=osmnx), as we reserve the issue tracker for bug reports and new feature development. Any such questions asked in the issue tracker will be automatically closed.
 
-#### If you're having an installation problem:
+## If you have an installation problem
 
-- make sure you've followed the installation instructions in the [documentation](https://osmnx.readthedocs.io/)
-- if you installed OSMnx via conda-forge, please open an issue at its [feedstock](https://github.com/conda-forge/osmnx-feedstock/issues)
+Ensure you have followed the installation instructions in the [documentation](https://osmnx.readthedocs.io/). If you installed OSMnx via conda-forge, please open an issue at its [feedstock](https://github.com/conda-forge/osmnx-feedstock/issues).
 
-#### If you've found a bug:
+## If you found a bug
 
-- read the error message, then review the [documentation](https://osmnx.readthedocs.io/) and [OSMnx examples](https://github.com/gboeing/osmnx-examples) gallery, which cover key concepts, installation, and package usage
-- search through the [open issues](https://github.com/gboeing/osmnx/issues?q=is%3Aopen+is%3Aissue) and [closed issues](https://github.com/gboeing/osmnx/issues?q=is%3Aissue+is%3Aclosed) to see if the problem has already been reported
-- if the problem is with a dependency of OSMnx, open an issue in the dependency's repo
-- if the problem is with OSMnx itself and you can fix it simply, please open a pull request
-- if the problem persists, please open an issue in the [issue tracker](https://github.com/gboeing/osmnx/issues), and _provide all the information requested in the template_, including a minimal working example so others can independently and completely reproduce the problem
+- Read the error message, then review the [documentation](https://osmnx.readthedocs.io/) and OSMnx [Examples Gallery](https://github.com/gboeing/osmnx-examples), which cover key concepts, installation, and package usage.
+- Search through the open and closed [issues](https://github.com/gboeing/osmnx/issues) to see if the problem has already been reported.
+- If the problem is with a dependency of OSMnx, open an issue in that dependency's repo.
+- If the problem is with OSMnx itself and you can fix it simply, please open a pull request.
+- If the problem persists, please open an issue in the [issue tracker](https://github.com/gboeing/osmnx/issues), and _provide all the information requested in the template_, including a minimal working example so others can independently and completely reproduce the bug.
 
-#### If you have a feature proposal or want to contribute:
+## If you have a feature proposal
 
-- post your proposal on the [issue tracker](https://github.com/gboeing/osmnx/issues), and _provide all the information requested in the template_, so we can review it together (some proposals may not be a good fit for the project)
-- fork the repo, make your change, update the [changelog](./CHANGELOG.md), run the [tests](./tests), and submit a PR
-- adhere to the project's code and docstring standards by running its [pre-commit](.pre-commit-config.yaml) hooks
-- respond to code review
+- Post your proposal on the [issue tracker](https://github.com/gboeing/osmnx/issues), and _provide all the information requested in the template_, so we can review it together (some proposals may not be a good fit for the project).
+- Fork the repo, make your change, update the [changelog](./CHANGELOG.md), run the [tests](./tests), and submit a pull request.
+- Adhere to the project's code and docstring standards by running its [pre-commit](.pre-commit-config.yaml) hooks.
+- Respond to code review.
 
-This project requires minimum Python and NumPy versions in accordance with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html).
+The OSMnx project follows three principles when adding new functionality: 1) it is useful for a broad set of users, 2) it generalizes well, and 3) it is not trivially easy for users to implement themselves.

docs/requirements.txt

@@ -1,2 +1,3 @@
 furo
 sphinx == 7.*  # same value as needs_sphinx in /docs/source/conf.py
+sphinx-autodoc-typehints

docs/source/conf.py

@@ -1,23 +1,23 @@
+# ruff: noqa: INP001
 """
 Configuration file for the Sphinx documentation builder.
 
 For the full list of built-in configuration values, see the documentation:
 https://www.sphinx-doc.org/en/master/usage/configuration.html
 """
 
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 import sys
 from pathlib import Path
 
-# go up two levels from current working dir (/docs/source) to package root
-pkg_root_path = str(Path.cwd().parent.parent)
-sys.path.insert(0, pkg_root_path)
-
+# project info
 author = "Geoff Boeing"
 copyright = "2016-2024, Geoff Boeing"  # noqa: A001
 project = "OSMnx"
 
+# go up two levels from current working dir (/docs/source) to package root
+pkg_root_path = str(Path.cwd().parent.parent)
+sys.path.insert(0, pkg_root_path)
+
 # dynamically load version from /osmnx/_version.py
 with Path.open(Path("../../osmnx/_version.py")) as f:
     version = release = f.read().split(" = ")[1].replace('"', "")
@@ -41,17 +41,22 @@
 # linkcheck for stackoverflow gets HTTP 403 in CI environment
 linkcheck_ignore = [r"https://stackoverflow\.com/.*"]
 
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+# type annotations configuration
+autodoc_typehints = "description"
+napoleon_use_param = True
+napoleon_use_rtype = False
+typehints_document_rtype = True
+typehints_use_rtype = False
+typehints_fully_qualified = False
+
+# general configuration and options for HTML output
+# see https://www.sphinx-doc.org/en/master/usage/configuration.html
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_autodoc_typehints"]
+html_static_path: list[str] = []
+html_theme = "furo"
 language = "en"
 needs_sphinx = "7"  # same value as pinned in /docs/requirements.txt
 root_doc = "index"
 source_suffix = ".rst"
-templates_path: list = []
-
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-html_static_path: list = []
-html_theme = "furo"
+templates_path: list[str] = []