diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..ab56e30 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,53 @@ +# Changelog + +All notable user-visible changes are recorded here. UrbanPy follows semantic +versioning and uses the headings from [Keep a Changelog](https://keepachangelog.com/). + +## [Unreleased] + +### Added + +- A uv-managed PEP 621 build with a reproducible development lockfile and Python + 3.11–3.14 CI matrix. +- Strict Pydantic boundary models for coordinates, bounding boxes, travel + profiles, Geofabrik records, and the OSRM lifecycle. +- Canonical Geofabrik catalog resolution using official IDs, exact ISO aliases, + and provider-advertised PBF URLs. +- A cross-platform Python OSRM manager with atomic downloads/preparation, + pinned containers, ownership protection, readiness checks, and dry-run cleanup. +- A Docker-independent typed OSRM route/table client. +- Hermetic provider contract tests, mandatory SonarQube enforcement, Trunk code + quality, dependency auditing, and agent governance. + +### Changed + +- H3 4.x, OSMnx 2.x, GeoPandas 1.x, and current HDX behavior are supported and + regression-tested. +- OSRM durations are documented in seconds, matching the upstream API. +- Geospatial outputs retain their input or declared CRS in the corrected paths. +- HDX searches use the current client and return stable UrbanPy provider errors. + +### Fixed + +- `merge_shape_hex` can be rerun on its own result. +- One-resource HDX selections no longer pass a pandas Series to `read_csv`. +- OSMnx nearest-node coordinate order and graph isochrone coordinate fields. +- OSRM nested Geofabrik regions, platform divergence, false readiness, unsafe + container collisions, partial downloads, and incorrect MLD path extensions. + +### Deprecated + +- `start_osrm_server` and `stop_osrm_server`; migrate to `OSRMConfig` and + `OSRMManager` before the next breaking release. + +### Removed + +- The unsupported OSRM Bash, PowerShell, legacy class, and notebook launchers. + +## [0.2.2] - 2024-07-18 + +The historical release predates the structured changelog. See the +[GitHub release](https://github.com/EL-BID/urbanpy/releases/tag/v0.2.2). + +[Unreleased]: https://github.com/EL-BID/urbanpy/compare/v0.2.2...HEAD +[0.2.2]: https://github.com/EL-BID/urbanpy/releases/tag/v0.2.2 diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..e28d096 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,34 @@ +cff-version: 1.2.0 +message: "If you use UrbanPy, please cite the software and its reference paper." +title: "UrbanPy" +type: software +version: 0.3.0a0 +license: GPL-3.0-only +repository-code: "https://github.com/EL-BID/urbanpy" +url: "https://el-bid.github.io/urbanpy/" +authors: + - family-names: Regal + given-names: Andres + - family-names: Ortega + given-names: Claudio + - family-names: Vazquez Brust + given-names: Antonio +preferred-citation: + type: conference-paper + title: "UrbanPy: A Library to Download, Process and Visualize High Resolution Urban Data to Support Transportation and Urban Planning Decisions" + year: 2022 + doi: 10.1007/978-3-031-06862-1_34 + collection-title: "Production and Operations Management" + publisher: + name: Springer International Publishing + authors: + - family-names: Regal + given-names: Andres + - family-names: Ortega + given-names: Claudio + - family-names: Vazquez Brust + given-names: Antonio + - family-names: Rodriguez + given-names: Michelle + - family-names: Zambrano-Barragan + given-names: Patricio diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..d220ca7 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,35 @@ +# Governance + +UrbanPy is an EL-BID open-source project maintained in public on GitHub. + +## Roles and decisions + +Maintainers triage issues, define supported APIs, review contributions, manage +security reports, and approve releases. Contributors propose work through issues +and pull requests. Technical decisions are documented in the relevant issue or +PR; public API, dependency, data-license, security, and migration impact must be +explicit. + +Changes are accepted by maintainer review after required automation is green. +SonarQube is mandatory under EL-BID policy. Dependency/license findings require +an explicit maintainer disposition and are not dismissed by automation. + +## Automation and agents + +Automation may create branches, issues, and dependency-ordered pull requests. +It may not approve or merge its own work, publish packages, change repository +secrets or branch protection, or dismiss security and license findings. Human +maintainers retain release and administrative authority. The repository's +`AGENTS.md`, CODEOWNERS, and pull-request template define the operational rules. + +## Releases and compatibility + +UrbanPy follows semantic versioning. Deprecations emit a documented warning for +at least one minor release when practical. Breaking changes require an issue, +migration notes, and a major version unless needed to correct a security or data +integrity defect during a prerelease. + +Release artifacts are built once from a reviewed tag and promoted through +protected environments. A maintainer approves publication and post-release +support. The release-engineering workstream maintains the operational runbook +alongside the publish workflows. diff --git a/README.md b/README.md index 0aa090a..442686c 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,16 @@ -[![Test and deploy](https://github.com/EL-BID/urbanpy/actions/workflows/main.yml/badge.svg)](https://github.com/EL-BID/urbanpy/actions/workflows/main.yml) +[![CI](https://github.com/EL-BID/urbanpy/actions/workflows/main.yml/badge.svg)](https://github.com/EL-BID/urbanpy/actions/workflows/main.yml) +[![SonarQube](https://github.com/EL-BID/urbanpy/actions/workflows/build.yml/badge.svg)](https://github.com/EL-BID/urbanpy/actions/workflows/build.yml) [![Downloads](https://static.pepy.tech/badge/urbanpy)](https://pepy.tech/project/urbanpy) [![Downloads](https://static.pepy.tech/badge/urbanpy/month)](https://pepy.tech/project/urbanpy) [![Downloads](https://static.pepy.tech/badge/urbanpy/week)](https://pepy.tech/project/urbanpy) -![analytics image (flat)](https://raw.githubusercontent.com/vitr/google-analytics-beacon/master/static/badge.svg) -![analytics](https://www.google-analytics.com/collect?v=1&cid=555&t=pageview&ec=repo&ea=open&dp=/urbanpy/readme&dt=&tid=UA-4677001-16) +# UrbanPy 🏙️ -# Welcome to UrbanPy :city_sunrise: +**Download, process, route, and visualize high-resolution urban geospatial data.** -**A library to download, process and visualize high resolution urban data in an easy and fast way.** - -UrbanPy is an open source project to automate data extraction, measurement, and visualization of urban accessibility metrics. +UrbanPy is an EL-BID open-source Python library for reproducible urban data and +accessibility workflows. Version 0.3 is currently an alpha modernization: use a +stable 0.2 release for established production deployments and test 0.3 against +your data before upgrading. # Functional goals @@ -40,28 +41,26 @@ UrbanPy is an open source project to automate data extraction, measurement, and ### For users -To install the urbanpy library you can use: +Install the stable release from PyPI: ```sh -$ pip install urbanpy +python -m pip install urbanpy ``` Then use `import urbanpy` in your python scripts to use the library. -If you plan to use the [OSRM Server](http://project-osrm.org/) route or distance matrix calculation functionalities\* you must have Docker installed in your system, refer to Docker [Installation](https://www.docker.com/products/docker-desktop). For Windows users, make sure to run the following command in powershell to avoid execution errors. - -```powershell - Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser -``` - -### Additional Dependecies Notes - -- It is important to note that for travel time computation, if needed, a method is implements the Open Source Routing Machine (OSRM). This method pulls, extracts and adds graph weights to the downloaded network and runs the routing server. Make sure to have docker installed for the library to work correctly. Also, verify in the docker settings that containers can use the necessary cpu cores and ram memory (it depends in the country size). +The normal routing, geometry, and provider clients do not require a local OSRM +container. To prepare and operate a local OSRM service, install Docker and follow +the [OSRM guide](https://el-bid.github.io/urbanpy/usage/osrm.html). UrbanPy 0.3 +uses a cross-platform Python lifecycle; it never requires weakening PowerShell's +execution policy. -- Urbanpy provides a simple approximation with nearest neighbor search using a BallTree and haversine distance, but the difference between real travel time and the approximation may vary from city to city. +### Geospatial dependencies -- Additionally, the use of spatial libraries like osmnx, geopandas and h3 require certain extra packages. Specifically, for rtree (spatial indexing to allow spatial joins) libspatialindex is required. OSMnx and Geopandas requiere GDAL as well. If not handled by installing geopandas's dependencies, installing fiona, pyproj and shapely should satisfy the requirements. Another way to ensure all dependencies are met, installing osmnx via conda should suffice. H3 requires cc, make, and cmake in your $PATH when installing, otherwise installation will not be successful. Please refer to [h3's documentation](https://github.com/uber/h3) for a more - detailed guide on installation options and requirements. +Current GeoPandas, Shapely, OSMnx, and H3 releases provide wheels for common +platforms. If installation must compile a dependency, install that project's +documented system toolchain. Large OSRM regions require substantial disk, memory, +and processing time; begin with a small canonical Geofabrik region. # Examples @@ -80,28 +79,24 @@ Since `boundaries` is a GeoDataFrame it can be easily plotted with the method `. hexes = up.geom.gen_hexagons(resolution=9, city=boundaries) ``` -Also check our [example notebooks](https://nbviewer.org/github/EL-BID/urbanpy/tree/master/notebooks/), and if you have examples or visualizations of your own, we encourage you to share contribute. +See the [documentation](https://el-bid.github.io/urbanpy/) and +[example notebooks](https://nbviewer.org/github/EL-BID/urbanpy/tree/master/notebooks/). ### For developers -If you plan to contribute or customize urbanpy first clone this repo and cd into it. Then, we strongly recommend you to create a virtual environment. You can use conda, this installation manage some complicated C spatial library dependencies: - -```sh -$ conda env create -n urbanpy -f environment.yml python=3.6 -$ conda activate urbanpy -``` - -Or if you are more confident about your setup, you can use pip: +Install [uv](https://docs.astral.sh/uv/), clone the repository, and create the +locked development environment: ```sh -$ python3 -m venv .env -$ source .env/bin/activate -(.env) $ pip install -r requirements.txt +uv sync --locked --all-groups +uv run pytest +trunk check ``` ## License -UrbanPy is licensed under the [GPL-3](LICENSE) license. +UrbanPy is licensed under [GPL-3.0-only](LICENSE). Data downloaded through +UrbanPy remains subject to each provider's terms and license. ## Authors @@ -114,7 +109,10 @@ UrbanPy's original authors are Claudio Ortega ([socials](https://www.linkedin.co [code of conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.** -\*Current support is tested on Linux Ubuntu 18.04 & Mac OS Catalina, coming soon we will test and support Windows 10. +See [SUPPORT.md](SUPPORT.md), [GOVERNANCE.md](GOVERNANCE.md), and +[SECURITY.md](SECURITY.md) for maintenance, decision-making, and private +vulnerability reporting. Supported Python versions are tested in CI; OSRM +platform claims require separate Docker release evidence. ## Citation @@ -129,7 +127,7 @@ If you use this library or find the documentation useful for your research, plea publisher="Springer International Publishing", address="Cham", pages="463--473", - isbn="978-3-031-06862-1" + isbn="978-3-031-06862-1", url="https://doi.org/10.1007/978-3-031-06862-1_34" } ``` diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..6edb865 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,36 @@ +# Security policy + +## Supported versions + +Security fixes are made on the default branch and released in the newest +maintained minor series. During the 0.3 prerelease cycle, `0.3.0a*`, `0.3.0b*`, +and `0.3.0rc*` are evaluation builds and may receive breaking fixes. The 0.2 +series receives critical fixes only until 0.3.0 is stable; older versions are +unsupported. + +## Report a vulnerability privately + +Do not disclose vulnerabilities in a public issue, pull request, discussion, +notebook, or chat. Use **Security → Advisories → Report a vulnerability** in +the [UrbanPy repository](https://github.com/EL-BID/urbanpy/security/advisories/new). +GitHub private vulnerability reporting is enabled for this repository. + +Include the affected version or commit, impact, reproduction prerequisites, +minimal proof of concept, and any suggested mitigation. Remove credentials, +personal data, and sensitive provider responses. + +Maintainers aim to acknowledge a report within five working days, provide a +triage decision within ten working days, and coordinate publication after a fix +is available. These are response targets, not a bug-bounty or compensation +commitment. + +## Scope + +UrbanPy code, packaging, published artifacts, release automation, and unsafe +handling of external data are in scope. Vulnerabilities in upstream services or +dependencies should also be reported to their owners; tell UrbanPy privately +when the library needs a mitigation or dependency update. + +Security advisories, CVEs when appropriate, patched-version ranges, and upgrade +instructions are published through GitHub and the changelog. SonarQube remains +a mandatory EL-BID quality gate and does not replace coordinated disclosure. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..f768f81 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,20 @@ +# Support policy + +UrbanPy is community-maintained open-source software. Public support is provided +on a best-effort basis; no service-level agreement is implied. + +- Use [GitHub Issues](https://github.com/EL-BID/urbanpy/issues) for reproducible + bugs and scoped feature proposals. +- Use the bug form and include UrbanPy/Python versions, operating system, CRS, + a minimal synthetic example, and redacted logs. +- Search existing issues before opening a new report. +- Do not use public issues for vulnerabilities; follow [SECURITY.md](SECURITY.md). +- Questions about institutional deployments, private data, or EL-BID policy + should use the appropriate institutional support channel rather than the + public tracker. + +The supported Python range is declared in `pyproject.toml` and exercised in CI. +Provider-backed features depend on third-party availability and policy; unit +tests use captured contracts, while scheduled live checks detect upstream drift. +Docker-backed OSRM support is limited to platforms for which release evidence is +recorded. See the OSRM guide before processing large regions. diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 549dea4..2086111 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -1,62 +1,39 @@ -Contributing guidelines -======================= +Contributing +============ -Pull request checklist ----------------------- +Search existing issues before proposing work. Reproducible bug reports should +include UrbanPy and Python versions, operating system, CRS, a small synthetic +example, and redacted logs. Never put credentials, personal data, or private +provider payloads in an issue or fixture. -Before sending a pull request, be sure to follow this list. +Development setup +----------------- -- Read the `contributing guidelines `__ -- Read the `code of conduct `__ -- Check if your changes comply with the `style - guide `__ +.. code-block:: console -How to become a contributor and submit your own code ----------------------------------------------------- + uv sync --locked --all-groups + uv run pytest + trunk check -We'd love to accept your changes, suggestions and patches! Be sure that -your changes, source code, and other ideas/implementations do not cause -intellectual property issues. +The default tests disable network sockets. Captured provider contracts belong +in the normal suite; real-provider tests use ``@pytest.mark.live`` and Docker +tests use ``@pytest.mark.docker``. Run those only in an explicitly prepared +environment. -Contributing code ------------------ +Pull requests +------------- + +Keep changes focused, link an issue with acceptance criteria, and add regression +tests for fixes. Dependency-ordered stacked pull requests are welcome when each +layer remains independently reviewable. Update documentation and the changelog +for user-visible behavior. -If you have any improvements or new functionality that is interesting -for UrbanPy, send us your pull requests! If you are new to pull -requests, see Github's `how to -guide `__. - -UrbanPy team members will be assigned to review your pull requests. Once -the pull requests are approved and pass continuous integration checks, a -UrbanPy team member will apply ready to pull label to your change. This -means we are working on getting your pull request submitted to our -internal repository. After the change has been submitted internally, -your pull request will be merged automatically on GitHub. - -Contribution guidelines and standards -------------------------------------- - -Before sending your pull request for review, make sure your changes are -consistent with the guidelines and follow the Google coding style. - -General guidelines and philosophy for contribution -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Include unit tests when you contribute new features, as they help to - a) prove that your code works correctly, and b) guard against future - breaking changes to lower the maintenance cost. -- Bug fixes also generally require unit tests, because the presence of - bugs usually indicates insufficient test coverage. -- When you contribute a new feature to UrbanPy, the maintenance burden - is (by default) transferred to the UrbanPy team. This means that the - benefit of the contribution must be compared against the cost of - maintaining the feature. -- Full new features (e.g., a cutting-edge travel time matrix - computation algorithm) typically will live in urbanpy/utils to get - some airtime before a decision is made regarding whether they are to - be migrated to the core modules. -- As every PR may require several CPU hours of CI testing, we - discourage submitting PRs to fix one typo, one warning, etc. We - recommend fixing the same issue at the file level at least (e.g.: fix - all typos in a file, fix all compiler warning in a file, etc.) +Required CI, security, dependency-compliance, and documentation checks must +pass. SonarQube is mandatory under EL-BID policy and is never best effort. A +human maintainer reviews and merges changes; automation and agents do not +approve, merge, or release their own work. +Read the full `repository contribution guide +`__, `governance +policy `__, and +:doc:`code_of_conduct` before contributing. diff --git a/docs/source/index.rst b/docs/source/index.rst index a9e4a34..ea58f21 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,163 +1,77 @@ -Welcome to urbanpy's documentation! -=================================== - -**A library to download, process and visualize high resolution urban -data in an easy and fast way.** - -UrbanPy is an open source project to automate data extraction, -measurement, and visualization of urban accessibility metrics. - -Functional goals ----------------- - -- [x] Download open source spatial data (Limits & Points of Interests) -- [x] Allow for the use of a grid system or administrative boundaries - as spatial units -- [x] Origin-destination matrix calculation by any mode using a routing - API -- [x] Obtain travel time from spatial units to the closest facilities -- [x] Consolidate the results as tables and/or shapefiles (georeferenced datasets) -- [x] Visualise the results as maps - -UX goals --------- - -- [ ] Atomic functions (one purpose per function) -- [x] Use the power of Python Geospatial Ecosystem under the hood -- [x] Allow to flexible processing pipelines (custom layer/metrics - aggregations) -- [x] Clear documentation with usage and examples -- [x] Clear and replicable example notebooks - -Main modules ------------- - -- download: Main functions for data download from Nominatin API, - OverPass API and HDX population data -- geom: Spatial operations, grid partitioning, spatial filtering and - street network statistics -- plotting: Visualization wrappers for plotly interactive choropleth - maps -- routing: Distance matrix computations (may require your own API keys) -- utils: Data handling helpers - -Installation ------------- - -For users -~~~~~~~~~ - -To install the urbanpy library you can use: - -.. code:: sh - - $ pip install urbanpy - -Then use ``import urbanpy`` in your python scripts to use the library. - -If you plan to use the `OSRM Server `__ route -or distance matrix calculation functionalities\* you must have Docker -installed in your system, refer to Docker -`Installation `__. - -Additional Dependecies Notes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- It is important to note that for travel time computation, if needed, - a method is implements the Open Source Routing Machine (OSRM). This - method pulls, extracts and adds graph weights to the downloaded - network and runs the routing server. Make sure to have docker - installed for the library to work correctly. - -- Urbanpy provides a simple approximation with nearest neighbor search - using a BallTree and haversine distance, but the difference between - real travel time and the approximation may vary from city to city. - -- Additionally, the use of spatial libraries like osmnx, geopandas and - h3 require certain extra packages. Specifically, for rtree (spatial - indexing to allow spatial joins) libspatialindex is required. OSMnx - and Geopandas requiere GDAL as well. If not handled by installing - geopandas's dependencies, installing fiona, pyproj and shapely should - satisfy the requirements. Another way to ensure all dependencies are - met, installing osmnx via conda should suffice. H3 requires cc, make, - and cmake in your $PATH when installing, otherwise installation will - not be successful. Please refer to `h3's - documentation `__ for a more detailed - guide on installation options and requirements. - -Examples -~~~~~~~~ - -UrbanPy lets you download and visualize city boundaries extremely easy: - -.. code:: python - - import urbanpy as up - - boundaries = up.download.nominatim_osm('Lima, Peru', expected_position=2) - boundaries.plot() - -Since ``boundaries`` is a GeoDataFrame it can be easily plotted with the -method ``.plot()``. You can also generate hexagons to fill the city -boundaries in a oneliner. - -.. code:: python +UrbanPy +******* - hexs, hexs_centroids = up.geom.gen_hexagons(resolution=9, city=boundaries) +**Download, process, route, and visualize high-resolution urban geospatial +data.** -Also check our `example notebooks `__, and if you have -examples or visualizations of your own, we encourage you to share -contribute. +UrbanPy is an EL-BID open-source Python library for reproducible urban data and +accessibility workflows. It integrates common geospatial libraries and public +data providers behind focused helpers while preserving GeoDataFrame-native +outputs. -For developers -~~~~~~~~~~~~~~ +Version 0.3 is currently an alpha modernization. Evaluate prereleases against +your own data before production use and review the changelog for migrations. -If you plan to contribute or customize urbanpy first clone this repo and -cd into it. Then, we strongly recommend you to create a virtual -environment. You can use conda, this installation manage some -complicated C spatial library dependencies: - -.. code:: sh - - $ conda env create -n urbanpy -f environment.yml python=3.6 - $ conda activate urbanpy - -Or if you are more confident about your setup, you can use pip: - -.. code:: sh +Capabilities +------------ - $ python3 -m venv .env - $ source .env/bin/activate - (.env) $ pip install -r requirements.txt +- Download boundaries, points of interest, street networks, and selected HDX + population resources. +- Generate H3 grids, filter population points, overlay polygons, and aggregate + urban indicators. +- Query routing providers or manage a reproducible local OSRM service. +- Compute accessibility surfaces and visualize geospatial results. +- Validate new provider and lifecycle boundaries with explicit typed models. +Quick example +------------- -Authors -------- +.. code-block:: python -UrbanPy's original authors are Claudio Ortega -(`socials `__) and Andrés -Regal (`socials `__). + import urbanpy as up -\*Current support is tested on Linux Ubuntu 18.04 & Mac OS Catalina, -coming soon we will test and support Windows 10. + boundary = up.download.nominatim_osm( + "Lima, Peru", + expected_position=0, + email="your-project-contact@example.org", + ) + hexagons = up.geom.gen_hexagons(resolution=9, city=boundary) + hexagons.plot() -Indices and tables -================== +Nominatim requires an identifying contact address. Provider-backed functions +remain subject to provider usage policies and data licenses. -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +Project links +------------- +- `Source and issues `__ +- `Changelog `__ +- `Support policy `__ +- `Private security reporting `__ +- `Governance `__ .. toctree:: - :caption: Table of Contents - :maxdepth: 4 + :caption: User guide + :maxdepth: 2 usage/installation usage/quickstart usage/geofabrik usage/osrm + usage/support + +.. toctree:: + :caption: API and project + :maxdepth: 3 + urbanpy - license contributing code_of_conduct + license + +Indices +------- + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/usage/installation.rst b/docs/source/usage/installation.rst index 629f7dd..484ddb4 100644 --- a/docs/source/usage/installation.rst +++ b/docs/source/usage/installation.rst @@ -1,44 +1,55 @@ Installation ============ -For users -~~~~~~~~~ +Users +----- -To install the urbanpy library you can use: +Install the stable release from PyPI in a virtual environment: -.. code:: sh +.. code-block:: console - $ pip install urbanpy + python -m pip install urbanpy -Then use ``import urbanpy`` in your python scripts to use the library. +Then verify the import and version: -If you plan to use the `OSRM Server `__ route -or distance matrix calculation functionalities\* you must have Docker -installed in your system, refer to Docker -`Installation `__. +.. code-block:: pycon -For developers -~~~~~~~~~~~~~~ + >>> import urbanpy + >>> urbanpy.__version__ -If you plan to contribute or customize urbanpy first clone this repo and -cd into it. Then, we strongly recommend you to create a virtual -environment. You can use conda, this installation manage some -complicated C spatial library dependencies: +UrbanPy supports the Python versions declared in ``pyproject.toml`` and tested +in CI. Current geospatial dependencies publish wheels for common platforms. If +your platform must compile a dependency, follow that dependency's system +toolchain documentation. -.. code:: sh +Local OSRM is optional. Install and start Docker, then follow :doc:`osrm`. +Normal geometry operations and calls to independently operated routing services +do not require Docker. - $ conda env create -f environment.yml - $ conda activate urbanpy +Prereleases +----------- -Or if you are more confident about your setup, you can use pip: +Version 0.3 alpha, beta, and release-candidate builds are evaluation releases. +Install a specific prerelease only when intentionally testing its migration: -.. code:: sh +.. code-block:: console - $ python3 -m venv .env - $ source .env/bin/activate - (.env) $ pip install -r requirements.txt + python -m pip install --pre "urbanpy==0.3.0a0" +Do not assume cache, model, or deprecated API stability between alpha builds. +Review the project changelog and test representative geospatial data first. -\*Current support is tested on Linux Ubuntu 18.04 & Mac OS Catalina, +Developers +---------- -coming soon we will test and support Windows 10. +Install `uv `__, clone the repository, then run: + +.. code-block:: console + + uv sync --locked --all-groups + uv run pytest + trunk check + +The committed ``uv.lock`` is authoritative for development and CI. Runtime +users receive the compatible dependency ranges declared in ``pyproject.toml``. +See :doc:`../contributing` for test markers and pull-request requirements. diff --git a/docs/source/usage/support.rst b/docs/source/usage/support.rst new file mode 100644 index 0000000..dc086d8 --- /dev/null +++ b/docs/source/usage/support.rst @@ -0,0 +1,32 @@ +Support, stability, and reporting +================================= + +UrbanPy is community-maintained on a best-effort basis. Use the repository's +structured issue forms for reproducible bugs and scoped enhancements. Provider +availability and mutable third-party datasets are outside UrbanPy's control; +scheduled live contracts detect drift, while pull-request tests remain +deterministic. + +Public API stability +-------------------- + +UrbanPy follows semantic versioning. Supported public APIs are documented and +exported from package modules. Deprecations normally emit warnings for at least +one minor release and are listed in the changelog. Prereleases may make breaking +corrections with migration notes. + +Security +-------- + +Do not report vulnerabilities in public issues. Use GitHub's `private +vulnerability reporting +`__. Include affected +versions, impact, a minimal reproduction, and suggested mitigations without +credentials or sensitive data. + +Data and licenses +----------------- + +UrbanPy software is GPL-3.0-only. Downloaded data remains governed by its +provider's terms and license. Users are responsible for attribution, permitted +use, retention, and redistribution of provider data. diff --git a/pyproject.toml b/pyproject.toml index a3f1299..b3d81ef 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,7 +8,8 @@ version = "0.3.0a0" description = "Download, process, route, and visualize high-resolution urban geospatial data." readme = "README.md" requires-python = ">=3.11" -license = { file = "LICENSE" } +license = "GPL-3.0-only" +license-files = ["LICENSE"] authors = [ { name = "Andres Regal" }, { name = "Claudio Ortega" }, @@ -58,6 +59,7 @@ dependencies = [ [project.urls] Documentation = "https://el-bid.github.io/urbanpy/" +Changelog = "https://github.com/EL-BID/urbanpy/blob/master/CHANGELOG.md" Issues = "https://github.com/EL-BID/urbanpy/issues" Repository = "https://github.com/EL-BID/urbanpy" @@ -100,9 +102,14 @@ default-groups = ["dev"] [tool.hatch.build.targets.sdist] include = [ "/CODE_OF_CONDUCT.md", + "/CHANGELOG.md", + "/CITATION.cff", "/CONTRIBUTING.md", + "/GOVERNANCE.md", "/LICENSE", "/README.md", + "/SECURITY.md", + "/SUPPORT.md", "/docs", "/pyproject.toml", "/tests",