From 59163a29a26b9a194775d7f485a637a8e27df53a Mon Sep 17 00:00:00 2001 From: Julia Signell Date: Thu, 13 Apr 2023 12:49:57 -0400 Subject: [PATCH 1/4] Consolidate contributing docs into one place --- README.md | 113 +-------------------------------- docs/contributing.rst | 142 +++++++++++++++++++++++++++++++----------- 2 files changed, 108 insertions(+), 147 deletions(-) diff --git a/README.md b/README.md index 67734153..e0ebbfe4 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,6 @@ A Python client for working with [STAC](https://stacspec.org/) Catalogs and APIs - [Installation](#installation) - [Documentation](#documentation) - [Development](#development) - - [Pull Requests](#pull-requests) - - [Benchmark](#benchmark) ## Installation @@ -32,113 +30,4 @@ See the [documentation page](https://pystac-client.readthedocs.io/en/latest/) fo ## Development -For development, clone the repository and use the standard Python method for installing -the library as an "editable link", then install the development dependencies: - -```shell -$ git clone https://github.com/stac-utils/pystac-client.git -$ cd pystac-client -$ pip install -e . -$ pip install -r requirements-dev.txt -``` - -[pre-commit](https://pre-commit.com/) is used to ensure a standard set of formatting and -linting is run before every commit. These hooks should be installed with: - -```shell -$ pre-commit install -``` - -These can then be run independent of a commit with: - -```shell -$ pre-commit run --all-files -``` - -To run just the tests: - -```shell -$ pytest -v -s --block-network --cov pystac_client --cov-report term-missing -``` - -The pystac-client tests use [vcrpy](https://vcrpy.readthedocs.io/en/latest/) to mock API calls -with "pre-recorded" API responses. When adding new tests use the `@pytest.mark.vcr` decorator -function to indicate `vcrpy` should be used. Record the new responses and commit them to the -repository. - -```shell -$ pytest -v -s --record-mode new_episodes --block-network -$ git add -$ git commit -a -m 'new test episodes' -``` - -To update pystac-client to use future versions of STAC API, the existing recorded API responses -should be "re-recorded": - -```shell -$ pytest -v -s --record-mode rewrite --block-network -$ git commit -a -m 'updated test episodes' -``` - -### Pull Requests - -To make Pull Requests to pystac-client, the code must pass linting, formatting, and code tests. To run -the entire suit of checks and tests that will be run the GitHub Action Pipeline, use the `test` script. - -```shell -$ scripts/test -``` - -If automatic formatting is desired (incorrect formatting will cause the GitHub Action to fail), -use the format script and commit the resulting files: - -```shell -$ scripts/format -$ git commit -a -m 'formatting updates' -``` - -To build the documentation, [install Pandoc](https://pandoc.org/installing.html), install the -Python documentation requirements via pip, then use the `build-docs` script: - -```shell -$ pip install -r requirements-docs.txt -$ scripts/build-docs -``` - -### Benchmark - -By default, pystac-client benchmarks are skipped during test runs. -To run the benchmarks, use the `--benchmark-only` flag: - -```shell -$ pytest --benchmark-only -============================= test session starts ============================== -platform darwin -- Python 3.9.13, pytest-6.2.4, py-1.10.0, pluggy-0.13.1 -benchmark: 3.4.1 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000) -rootdir: /Users/gadomski/Code/pystac-client, configfile: pytest.ini -plugins: benchmark-3.4.1, recording-0.11.0, console-scripts-1.1.0, requests-mock-1.9.3, cov-2.11.1, typeguard-2.13.3 -collected 75 items - -tests/test_cli.py ss [ 2%] -tests/test_client.py ssssssssssssssss [ 24%] -tests/test_collection_client.py ss [ 26%] -tests/test_item_search.py ...sssssssssssssssssssssssssssssssssssssssssss [ 88%] -s [ 89%] -tests/test_stac_api_io.py ssssssss [100%] - - ---------------------------------------------------------------------------------------- benchmark: 3 tests -------------------------------------------------------------------------------------- -Name (time in ms) Min Max Mean StdDev Median IQR Outliers OPS Rounds Iterations -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -test_single_item_search 213.4729 (1.0) 284.8732 (1.0) 254.9405 (1.0) 32.9424 (3.27) 271.0926 (1.0) 58.2907 (4.95) 1;0 3.9225 (1.0) 5 1 -test_single_item 314.6746 (1.47) 679.7592 (2.39) 563.9692 (2.21) 142.7451 (14.18) 609.5605 (2.25) 93.9942 (7.98) 1;1 1.7731 (0.45) 5 1 -test_requests 612.9212 (2.87) 640.5024 (2.25) 625.6871 (2.45) 10.0637 (1.0) 625.1143 (2.31) 11.7822 (1.0) 2;0 1.5982 (0.41) 5 1 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - -Legend: - Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile. - OPS: Operations Per Second, computed as 1 / Mean -======================== 3 passed, 72 skipped in 11.86s ======================== -``` - -For more information on running and comparing benchmarks, see the [pytest-benchmark documentation](https://pytest-benchmark.readthedocs.io/en/latest/). +See the [contributing page](https://pystac-client.readthedocs.io/en/latest/contributing) for the latest development instructions. diff --git a/docs/contributing.rst b/docs/contributing.rst index 76a22ae6..512b3b9d 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -7,88 +7,160 @@ way is to coordinate with the core developers via an issue or pull request conve Development installation ^^^^^^^^^^^^^^^^^^^^^^^^ -Fork PySTAC-Client into your GitHub account. Then, clone the repo and install -it locally with pip as follows: +Fork PySTAC Client into your GitHub account. Clone the repo, install +the library as an "editable link", then install the development dependencies: .. code-block:: bash $ git clone git@github.com:your_user_name/pystac-client.git $ cd pystac $ pip install -e . + $ pip install -r requirements-dev.txt Testing ^^^^^^^ -PySTAC-Client runs tests using ``unittest``. You can find unit tests in the ``tests/`` +tl;dr: Run ``./scripts/test`` to run all tests and linters. + +PySTAC Client runs tests using `pytest `_. You can find unit tests in the ``tests/`` directory. -Run a single test with: +To run the tests and generate the coverage report: .. code-block:: bash - python -m unittest tests/test_catalog.py + $ pytest -v -s --block-network --cov pystac_client --cov-report term-missing -or an entire folder using: +The PySTAC Client tests use `vcrpy `_ to mock API calls +with "pre-recorded" API responses. When adding new tests use the ``@pytest.mark.vcr`` decorator +function to indicate ``vcrpy`` should be used. Record the new responses and commit them to the +repository. .. code-block:: bash - python -m unittest discover -v -s tests/ + $ pytest -v -s --record-mode new_episodes + $ git add + $ git commit -a -m 'new test episodes' -or the entire project using: -.. code-block:: bash +To update PySTAC Client to use future versions of STAC API, the existing recorded API responses +should be "re-recorded": - ./scripts/test +.. code-block:: bash -The last command will also check test coverage. To view the coverage report, you can run -`coverage report` (to view the report in the terminal) or `coverage html` (to generate -an HTML report that can be opened in a browser). + $ pytest -v -s --record-mode rewrite --block-network + $ git commit -a -m 'updated test episodes' -More details on using ``unittest`` are `here -`_. Code quality checks ^^^^^^^^^^^^^^^^^^^ -tl;dr: Run ``pre-commit install --overwrite`` to perform checks when committing, and -``./scripts/test`` to run the tests. +`pre-commit `_ is used to ensure a standard set of formatting and +linting is run before every commit. These hooks should be installed with: + +.. code-block:: bash + + $ pre-commit install -PySTAC-Client uses +These can then be run independent of a commit with: + +.. code-block:: bash + + $ pre-commit run --all-files + +PySTAC Client uses - `black `_ for Python code formatting - `codespell `_ to check code for common misspellings -- `doc8 `__ for style checking on RST files in the docs +- `doc8 `_ for style checking on RST files in the docs - `ruff `_ for Python style checks - `mypy `_ for Python type annotation checks -Run all of these with ``pre-commit run --all-files`` or a single one using -``pre-commit run --all-files ID``, where ``ID`` is one of the command names above. For -example, to format all the Python code, run ``pre-commit run --all-files black``. - -You can also install a Git pre-commit hook which will run the relevant linters and -formatters on any staged code when committing. This will be much faster than running on -all files, which is usually [#]_ only required when changing the pre-commit version or -configuration. Once installed you can bypass this check by adding the ``--no-verify`` +Once installed you can bypass pre-commit by adding the ``--no-verify`` (or ``-n``) flag to Git commit commands, as in ``git commit --no-verify``. -.. [#] In rare cases changes to one file might invalidate an unchanged file, such as - when modifying the return type of a function used in another file. +Pull Requests +^^^^^^^^^^^^^ + +To make Pull Requests to PySTAC Client, the code must pass linting, formatting, and code tests. To run +the entire suit of checks and tests that will be run the GitHub Action Pipeline, use the ``test`` script. + +.. code-block:: bash + + $ scripts/test + +If automatic formatting is desired (incorrect formatting will cause the GitHub Action to fail), +use the format script and commit the resulting files: + +.. code-block:: bash + + $ scripts/format + $ git commit -a -m 'formatting updates' + + +To build the documentation, `install Pandoc `_, install the +Python documentation requirements via pip, then use the ``build-docs`` script: + +.. code-block:: bash + + $ pip install -r requirements-docs.txt + $ scripts/build-docs CHANGELOG ^^^^^^^^^ -PySTAC-Client maintains a -`changelog `__ -to track changes between releases. All PRs should make a changelog entry unless +PySTAC Client maintains a +`changelog `_ +to track changes between releases. All Pull Requests should make a changelog entry unless the change is trivial (e.g. fixing typos) or is entirely invisible to users who may be upgrading versions (e.g. an improvement to the CI system). For changelog entries, please link to the PR of that change. This needs to happen in a few steps: -- Make a PR to PySTAC-Client with your changes -- Record the link to the PR +- Make a Pull Request (see above) to PySTAC Client with your changes +- Record the link to the Pull Request - Push an additional commit to your branch with the changelog entry with the link to the - PR. + Pull Request. For more information on changelogs and how to write a good entry, see `keep a changelog `_. + +Benchmark +^^^^^^^^^ + +By default, PySTAC Client benchmarks are skipped during test runs. +To run the benchmarks, use the ``--benchmark-only`` flag: + +.. code-block:: bash + + $ pytest --benchmark-only + ============================= test session starts ============================== + platform darwin -- Python 3.9.13, pytest-6.2.4, py-1.10.0, pluggy-0.13.1 + benchmark: 3.4.1 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000) + rootdir: /Users/gadomski/Code/pystac-client, configfile: pytest.ini + plugins: benchmark-3.4.1, recording-0.11.0, console-scripts-1.1.0, requests-mock-1.9.3, cov-2.11.1, typeguard-2.13.3 + collected 75 items + + tests/test_cli.py ss [ 2%] + tests/test_client.py ssssssssssssssss [ 24%] + tests/test_collection_client.py ss [ 26%] + tests/test_item_search.py ...sssssssssssssssssssssssssssssssssssssssssss [ 88%] + s [ 89%] + tests/test_stac_api_io.py ssssssss [100%] + + + --------------------------------------------------------------------------------------- benchmark: 3 tests -------------------------------------------------------------------------------------- + Name (time in ms) Min Max Mean StdDev Median IQR Outliers OPS Rounds Iterations + ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + test_single_item_search 213.4729 (1.0) 284.8732 (1.0) 254.9405 (1.0) 32.9424 (3.27) 271.0926 (1.0) 58.2907 (4.95) 1;0 3.9225 (1.0) 5 1 + test_single_item 314.6746 (1.47) 679.7592 (2.39) 563.9692 (2.21) 142.7451 (14.18) 609.5605 (2.25) 93.9942 (7.98) 1;1 1.7731 (0.45) 5 1 + test_requests 612.9212 (2.87) 640.5024 (2.25) 625.6871 (2.45) 10.0637 (1.0) 625.1143 (2.31) 11.7822 (1.0) 2;0 1.5982 (0.41) 5 1 + ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + + Legend: + Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile. + OPS: Operations Per Second, computed as 1 / Mean + ======================== 3 passed, 72 skipped in 11.86s ======================== + + +For more information on running and comparing benchmarks, see the `pytest-benchmark documentation `_. From 97e8daa7084a5dcf4a99887fb1d31e47072db3bc Mon Sep 17 00:00:00 2001 From: Julia Signell Date: Thu, 13 Apr 2023 12:52:38 -0400 Subject: [PATCH 2/4] Update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0dd04b52..03a35562 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Switched to Ruff from isort/flake8 [#457](https://github.com/stac-utils/pystac-client/pull/457) - Move to `FutureWarning` from `DeprecationWarning` for item search interface functions that are to be removed [#464](https://github.com/stac-utils/pystac-client/pull/464) +- Consolidate contributing docs into one place [#442](https://github.com/stac-utils/pystac-client/issues/442) ### Fixed From 1734a45947110d87447ffe3202845573d02e886d Mon Sep 17 00:00:00 2001 From: Julia Signell Date: Thu, 13 Apr 2023 12:53:17 -0400 Subject: [PATCH 3/4] PR number not issue --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 03a35562..5d417ff7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Switched to Ruff from isort/flake8 [#457](https://github.com/stac-utils/pystac-client/pull/457) - Move to `FutureWarning` from `DeprecationWarning` for item search interface functions that are to be removed [#464](https://github.com/stac-utils/pystac-client/pull/464) -- Consolidate contributing docs into one place [#442](https://github.com/stac-utils/pystac-client/issues/442) +- Consolidate contributing docs into one place [#478](https://github.com/stac-utils/pystac-client/issues/478) ### Fixed From 0c709660643b1e3fee9854a40680b912cc5bbcc4 Mon Sep 17 00:00:00 2001 From: Pete Gadomski Date: Wed, 19 Apr 2023 08:41:52 -0600 Subject: [PATCH 4/4] docs, fix: contributing link --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e0ebbfe4..e8cf292d 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,6 @@ [![Documentation](https://readthedocs.org/projects/pystac-client/badge/?version=latest)](https://pystac-client.readthedocs.io/en/latest/) [![codecov](https://codecov.io/gh/stac-utils/pystac-client/branch/main/graph/badge.svg)](https://codecov.io/gh/stac-utils/pystac-client) - A Python client for working with [STAC](https://stacspec.org/) Catalogs and APIs. ## Table of Contents @@ -21,7 +20,7 @@ A Python client for working with [STAC](https://stacspec.org/) Catalogs and APIs Install from PyPi. Other than [PySTAC](https://pystac.readthedocs.io) itself, the only dependencies for pystac-client is the Python [requests](https://docs.python-requests.org) and [dateutil](https://dateutil.readthedocs.io) libraries. ```shell -$ pip install pystac-client +pip install pystac-client ``` ## Documentation @@ -30,4 +29,4 @@ See the [documentation page](https://pystac-client.readthedocs.io/en/latest/) fo ## Development -See the [contributing page](https://pystac-client.readthedocs.io/en/latest/contributing) for the latest development instructions. +See the [contributing page](https://pystac-client.readthedocs.io/en/latest/contributing.html) for the latest development instructions.