From 8fe78a62aadb1a86ccf910f0fd4a09824eeb7e9d Mon Sep 17 00:00:00 2001 From: alifeee Date: Mon, 5 Jun 2023 19:23:57 +0100 Subject: [PATCH 01/13] update list style to use - not * --- .github/CONTRIBUTING.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 28c092d6e..fd5a1703e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,19 +1,22 @@ # Contributing Guide -* Check the [GitHub Issues](https://github.com/burnash/gspread/issues) for open issues that need attention. -* Follow the [How to submit a contribution](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution) Guide. +- Check the [GitHub Issues](https://github.com/burnash/gspread/issues) for open issues that need attention. +- Follow the [How to submit a contribution](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution) Guide. -* Make sure unit tests pass. Please read how to run unit tests below. +- Make sure unit tests pass. Please read how to run unit tests below. -* If you are fixing a bug: - * If you are resolving an existing issue, reference the issue id in a commit message `(fixed #XXX)`. - * If the issue has not been reported, please add a detailed description of the bug in the PR. - * Please add a regression test case. +- If you are fixing a bug: + - If you are resolving an existing issue, reference the issue ID in a commit message `(e.g., fixed #XXXX)`. + - If the issue has not been reported, please add a detailed description of the bug in the Pull Request (PR). + - Please add a regression test case to check the bug is fixed. + +- If you are adding a new feature: + - Please open a suggestion issue first. + - Provide a convincing reason to add this feature and have it greenlighted before working on it. + - Add tests to cover the functionality. + +- Please follow [Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/). -* If you are adding a new feature: - * Please open a suggestion issue first. - * Provide a convincing reason to add this feature and have it greenlighted before working on it. - * Add tests to cover the functionality. * Please follow [Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/). From 9ca674dc096743afcb64e0243f8d9e1acfae61b0 Mon Sep 17 00:00:00 2001 From: alifeee Date: Mon, 5 Jun 2023 19:24:38 +0100 Subject: [PATCH 02/13] Spelling fixes --- .github/CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index fd5a1703e..6b35b07a5 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -27,10 +27,10 @@ 2. Run tests offline: Run the test suite using your current python version, in offline mode. -This will use the curently recorded HTTP requests + responses. It does not make any HTTP call, does not require an active internet connection. +This will use the currently recorded HTTP requests + responses. It does not make any HTTP call, does not require an active internet connection. -**Note:** the CI runs that command, if it fail you won't be able to merge -your changes in GSpread. +**Note:** the CI runs that command, if it fails you won't be able to merge +your changes in gspread. ``` tox -e py From 3c7ecc2c395c5ce11ea46b1dd76a9da23964bc15 Mon Sep 17 00:00:00 2001 From: alifeee Date: Mon, 5 Jun 2023 19:24:55 +0100 Subject: [PATCH 03/13] spelling changes 2 --- .github/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 6b35b07a5..26101461a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -36,7 +36,7 @@ your changes in gspread. tox -e py ``` -**Tip:** To run a specific test method use the option `-k` to specifcy a test name and `-v` and `-s` to get test's output on console. +**Tip:** To run a specific test method use the option `-k` to specify a test name and `-v` and `-s` to get test's output on console. Example: From 9782cefa992af1cc56d06fec2f5c388153249170 Mon Sep 17 00:00:00 2001 From: alifeee Date: Mon, 5 Jun 2023 19:25:08 +0100 Subject: [PATCH 04/13] add languages to code blocks --- .github/CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 26101461a..3866ed590 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -32,7 +32,7 @@ This will use the currently recorded HTTP requests + responses. It does not make **Note:** the CI runs that command, if it fails you won't be able to merge your changes in gspread. -``` +```bash tox -e py ``` @@ -40,7 +40,7 @@ tox -e py Example: -``` +```python tox -e py -- -k test_find -v -s ``` @@ -51,7 +51,7 @@ You must in that case provide a service account credentials in order to make the You can control vcrpy's [Record Mode](https://vcrpy.readthedocs.io/en/latest/usage.html#record-modes) using `GS_RECORD_MODE` environment variable. The following command will run the entire test suite and record every HTTP request. -``` +```python GS_RECORD_MODE=all GS_CREDS_FILENAME= tox -e py ``` From 171e3eee951b64faafbace9311036c1c43616e19 Mon Sep 17 00:00:00 2001 From: alifeee Date: Mon, 5 Jun 2023 19:27:07 +0100 Subject: [PATCH 05/13] style/grammar changes --- .github/CONTRIBUTING.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 3866ed590..682c7426a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -51,6 +51,7 @@ You must in that case provide a service account credentials in order to make the You can control vcrpy's [Record Mode](https://vcrpy.readthedocs.io/en/latest/usage.html#record-modes) using `GS_RECORD_MODE` environment variable. The following command will run the entire test suite and record every HTTP request. + ```python GS_RECORD_MODE=all GS_CREDS_FILENAME= tox -e py ``` @@ -58,56 +59,57 @@ GS_RECORD_MODE=all GS_CREDS_FILENAME= tox -e py You need to update the recorded HTTP requests in the following cases: - new test is added -- a existing test is updated and does a new HTTP request +- an existing test is updated and does a new HTTP request - gspread is updated and does a new HTTP request In any of the above cases: -- remove the file holding the init/teardown of the test suite. +- Remove the file holding the recorded HTTP requests of the test(s). - ex: for the file `tests/cell_test.py` delete `tests/cassettes/CellTest.json` + e.g.: for the file `tests/cell_test.py` delete `tests/cassettes/CellTest.json` - please update the HTTP recording using the command above - set the `GS_RECORD_MODE` to `new_episodes`. This will tell `vcrpy` to record only new episodes and replay existing episodes. -**Note:** this will mostly result in a lot of udpated files under `tests/cassettes/` don't forget to add them in your PR. +**Note:** this will mostly result in a lot of updated files under `tests/cassettes/` don't forget to add them in your PR. Add these new files a dedicated commit, in order to make the review process easier please. The following command will replay existing requests and record new requests: -``` + +```bash GS_RECORD_MODE=new_episodes GS_CREDS_FILENAME= tox -e py ``` Then run the tests in offline mode to make sure you have recorded everything. -``` +```bash tox -e py ``` -**Note::** In some cases if the test suite can't record new episodes or it can't +**Note::** In some cases if the test suite can't record new episodes, or it can't replay them offline, you can run a complete update of the cassettes using the following command: -``` +```bash GS_RECORD_MODE=all GS_CREDS_FILENAME= tox -e py ``` -3. Format your code: +1. Format your code: Use the following command to format your code. Doing so will ensure all code respects the same format. -``` +```bash tox -e format ``` Then run the linter to validate change, if any. -**Note:** the CI runs that command, if it fail you won't be able to merge -your changes in GSpread. +**Note:** the CI runs that command, if it fails you won't be able to merge +your changes in gspread. -``` +```bash tox -e lint ``` @@ -117,7 +119,7 @@ The documentation uses [reStructuredText](http://www.sphinx-doc.org/en/master/us To build the documentation locally, use the following command: -``` +```bash tox -e doc ``` From 2b6e04d1ba82a6ffdacac065d4f9fdd3cc1dbe92 Mon Sep 17 00:00:00 2001 From: alifeee Date: Mon, 5 Jun 2023 19:54:21 +0100 Subject: [PATCH 06/13] ignore .vscode folder I have grammar/spelling checks in here which we don't need in the repo --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index e3a3c5e2f..3016756aa 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,6 @@ env/ # tox testrunner support .tox/ gspread.egg-info/ + +# vscode +.vscode/ From fb7204e6b8b8012760247da73eb954bcb010204e Mon Sep 17 00:00:00 2001 From: alifeee Date: Mon, 5 Jun 2023 19:54:31 +0100 Subject: [PATCH 07/13] Rewrite contributing guide --- .github/CONTRIBUTING.md | 122 +++++++++++++++++++--------------------- 1 file changed, 58 insertions(+), 64 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 682c7426a..521d6c88b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -3,7 +3,7 @@ - Check the [GitHub Issues](https://github.com/burnash/gspread/issues) for open issues that need attention. - Follow the [How to submit a contribution](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution) Guide. -- Make sure unit tests pass. Please read how to run unit tests below. +- Make sure unit tests pass. Please read how to run unit tests [below](#run-tests-offline). - If you are fixing a bug: - If you are resolving an existing issue, reference the issue ID in a commit message `(e.g., fixed #XXXX)`. @@ -17,110 +17,104 @@ - Please follow [Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/). +## CI checks -* Please follow [Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/). +If the [test](#run-tests-offline) or [lint](#lint) commands fail, the CI will fail, and you won't be able to merge your changes into gspread. -## Testing +Use [format](#format) to format your code before submitting a PR. Not doing so may cause [lint](#lint) to fail. -1. [Obtain OAuth2 credentials from Google Developers Console](http://gspread.readthedocs.org/en/latest/oauth2.html) +## Install dependencies -2. Run tests offline: - -Run the test suite using your current python version, in offline mode. -This will use the currently recorded HTTP requests + responses. It does not make any HTTP call, does not require an active internet connection. - -**Note:** the CI runs that command, if it fails you won't be able to merge -your changes in gspread. +Installing all the `*.txt` files is optional (tox installs dependencies per-run). ```bash -tox -e py +pip install tox +pip install -r ./test-requirements.txt -r ./lint-requirements.txt -r ./docs/requirements.txt ``` -**Tip:** To run a specific test method use the option `-k` to specify a test name and `-v` and `-s` to get test's output on console. +## Run tests (offline) -Example: +If the calls to the Sheets API have not changed, you can run the tests offline. Otherwise, you will have to [run them online](#run-tests-online) to record the new API calls. -```python -tox -e py -- -k test_find -v -s -``` +This will use the currently recorded HTTP requests + responses. It does not make any HTTP calls, and does not require an active internet connection. -**Note:** gspread uses [vcrpy](https://github.com/kevin1024/vcrpy) to record and replay HTTP interactions with Sheets API. +```bash +tox -e py +``` -You must in that case provide a service account credentials in order to make the real HTTP requests, using `GS_CREDS_FILENAME` environment variable. +### Run a specific test -You can control vcrpy's [Record Mode](https://vcrpy.readthedocs.io/en/latest/usage.html#record-modes) using `GS_RECORD_MODE` environment variable. +```bash +tox -e py -- -k TEST_NAME -v -s +``` -The following command will run the entire test suite and record every HTTP request. +## Format -```python -GS_RECORD_MODE=all GS_CREDS_FILENAME= tox -e py +```bash +tox -e format ``` -You need to update the recorded HTTP requests in the following cases: +## Lint -- new test is added -- an existing test is updated and does a new HTTP request -- gspread is updated and does a new HTTP request - -In any of the above cases: +```bash +tox -e lint +``` -- Remove the file holding the recorded HTTP requests of the test(s). +## Render Documentation - e.g.: for the file `tests/cell_test.py` delete `tests/cassettes/CellTest.json` -- please update the HTTP recording using the command above -- set the `GS_RECORD_MODE` to `new_episodes`. +The documentation uses [reStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index) markup and is rendered by [Sphinx](http://www.sphinx-doc.org/). -This will tell `vcrpy` to record only new episodes and replay existing episodes. +```bash +tox -e doc +``` -**Note:** this will mostly result in a lot of updated files under `tests/cassettes/` don't forget to add them in your PR. +The rendered documentation is placed into `docs/build/html`. `index.html` is an entry point. -Add these new files a dedicated commit, in order to make the review process easier please. +## Run tests (online) -The following command will replay existing requests and record new requests: +gspread uses [vcrpy](https://github.com/kevin1024/vcrpy) to record and replay HTTP interactions with Sheets API. -```bash -GS_RECORD_MODE=new_episodes GS_CREDS_FILENAME= tox -e py -``` +### `GS_CREDS_FILENAME` environment variable -Then run the tests in offline mode to make sure you have recorded everything. +You must provide service account credentials using the `GS_CREDS_FILENAME` environment variable in order to make HTTP requests to the Sheets API. -```bash -tox -e py -``` +[Obtain OAuth2 credentials from Google Developers Console](http://gspread.readthedocs.org/en/latest/oauth2.html). -**Note::** In some cases if the test suite can't record new episodes, or it can't -replay them offline, you can run a complete update of the cassettes using the following command: +### `GS_RECORD_MODE` environment variable -```bash -GS_RECORD_MODE=all GS_CREDS_FILENAME= tox -e py -``` +You can control vcrpy's [Record Mode](https://vcrpy.readthedocs.io/en/latest/usage.html#record-modes) using `GS_RECORD_MODE` environment variable. It can be: -1. Format your code: +- `all` - record all HTTP requests, overwriting existing ones +- `new_episodes` - record new HTTP requests and replay existing ones +- `none` - replay existing HTTP requests only -Use the following command to format your code. Doing so will ensure -all code respects the same format. +In the following cases, you must record new HTTP requests: -```bash -tox -e format -``` +- a new test is added +- an existing test is updated and does a new HTTP request +- gspread is updated and does a new HTTP request -Then run the linter to validate change, if any. +### Run test, capturing *all* HTTP requests -**Note:** the CI runs that command, if it fails you won't be able to merge -your changes in gspread. +In some cases if the test suite can't record new episodes, or it can't replay them offline, you can run a complete update of the cassettes. ```bash -tox -e lint +GS_CREDS_FILENAME=<./YOUR_CREDS.json> GS_RECORD_MODE=all tox -e py ``` -## Render Documentation +### Run test, capturing *only new* HTTP requests -The documentation uses [reStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index) markup and is rendered by [Sphinx](http://www.sphinx-doc.org/). +To record new HTTP requests: -To build the documentation locally, use the following command: +1. Remove the file holding the recorded HTTP requests of the test(s). + (e.g.: for the file `tests/cell_test.py` delete `tests/cassettes/CellTest.json`) +1. Run the tests with `GS_RECORD_MODE=new_episodes`. ```bash -tox -e doc +GS_CREDS_FILENAME=<./YOUR_CREDS.json> GS_RECORD_MODE=new_episodes tox -e py ``` -Once finished, the rendered documentation will be in `docs/build/html` folder. `index.html` is an entry point. +This will mostly result in a lot of updated files in `tests/cassettes/`. Don't forget to add them in your PR. +Please add them in a dedicated commit, in order to make the review process easier. + +Afterwards, remember to [run the tests in offline mode](#run-tests-offline) to make sure you have recorded everything correctly. From c74d6a88f45d515332c043f9e8ea6912d01334e6 Mon Sep 17 00:00:00 2001 From: alifeee Date: Mon, 5 Jun 2023 19:57:03 +0100 Subject: [PATCH 08/13] move "ask questions" section in readme --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 56ab2fd41..e17303be4 100644 --- a/README.md +++ b/README.md @@ -176,16 +176,16 @@ worksheet.batch_update([{ ## [Documentation](https://gspread.readthedocs.io/en/latest/) +### Ask Questions + +The best way to get an answer to a question is to ask on [Stack Overflow with a gspread tag](http://stackoverflow.com/questions/tagged/gspread?sort=votes&pageSize=50). + ## [Contributors](https://github.com/burnash/gspread/graphs/contributors) ## How to Contribute Please make sure to take a moment and read the [Code of Conduct](https://github.com/burnash/gspread/blob/master/.github/CODE_OF_CONDUCT.md). -### Ask Questions - -The best way to get an answer to a question is to ask on [Stack Overflow with a gspread tag](http://stackoverflow.com/questions/tagged/gspread?sort=votes&pageSize=50). - ### Report Issues Please report bugs and suggest features via the [GitHub Issues](https://github.com/burnash/gspread/issues). From 38ed030bfda1fd46ef5fb94c449f393799f8a05b Mon Sep 17 00:00:00 2001 From: alifeee Date: Tue, 6 Jun 2023 22:39:01 +0100 Subject: [PATCH 09/13] remove redundant dependency install --- .github/CONTRIBUTING.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 521d6c88b..623552cb7 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -25,11 +25,8 @@ Use [format](#format) to format your code before submitting a PR. Not doing so m ## Install dependencies -Installing all the `*.txt` files is optional (tox installs dependencies per-run). - ```bash pip install tox -pip install -r ./test-requirements.txt -r ./lint-requirements.txt -r ./docs/requirements.txt ``` ## Run tests (offline) From 311465a0f9c106aa5f41da83ea217692b0d4e377 Mon Sep 17 00:00:00 2001 From: alifeee Date: Tue, 6 Jun 2023 22:40:06 +0100 Subject: [PATCH 10/13] update credentials link and text --- .github/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 623552cb7..fe43ea878 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -75,7 +75,7 @@ gspread uses [vcrpy](https://github.com/kevin1024/vcrpy) to record and replay HT You must provide service account credentials using the `GS_CREDS_FILENAME` environment variable in order to make HTTP requests to the Sheets API. -[Obtain OAuth2 credentials from Google Developers Console](http://gspread.readthedocs.org/en/latest/oauth2.html). +[Obtain service account credentials from Google Developers Console](https://docs.gspread.org/en/latest/oauth2.html#for-bots-using-service-account). ### `GS_RECORD_MODE` environment variable From cf3cd6e26a19d47e2dee5fd3ed83b7b89782c1ab Mon Sep 17 00:00:00 2001 From: alifeee Date: Tue, 6 Jun 2023 22:42:23 +0100 Subject: [PATCH 11/13] improve clarity of cassettes --- .github/CONTRIBUTING.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index fe43ea878..506a9d101 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -104,7 +104,10 @@ GS_CREDS_FILENAME=<./YOUR_CREDS.json> GS_RECORD_MODE=all tox -e py To record new HTTP requests: 1. Remove the file holding the recorded HTTP requests of the test(s). - (e.g.: for the file `tests/cell_test.py` delete `tests/cassettes/CellTest.json`) + e.g., + 1. for the file `tests/cell_test.py`: + 2. for the test `test_a1_value` + 3. remove the file `tests/cassettes/CellTest.test_a1_value.json` 1. Run the tests with `GS_RECORD_MODE=new_episodes`. ```bash From 9f26a71009d8d81f06c41c3947de612ab717ac4a Mon Sep 17 00:00:00 2001 From: alifeee Date: Tue, 6 Jun 2023 22:47:06 +0100 Subject: [PATCH 12/13] remove urls from headers --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e17303be4..3523695d6 100644 --- a/README.md +++ b/README.md @@ -174,13 +174,19 @@ worksheet.batch_update([{ }]) ``` -## [Documentation](https://gspread.readthedocs.io/en/latest/) +## Documentation + +[Documentation]\: [https://gspread.readthedocs.io/][Documentation] + +[Documentation]: https://gspread.readthedocs.io/en/latest/ ### Ask Questions The best way to get an answer to a question is to ask on [Stack Overflow with a gspread tag](http://stackoverflow.com/questions/tagged/gspread?sort=votes&pageSize=50). -## [Contributors](https://github.com/burnash/gspread/graphs/contributors) +## Contributors + +[List of contributors](https://github.com/burnash/gspread/graphs/contributors) ## How to Contribute From c7441387b83b50f88f8a14e2c6e540830dc8501b Mon Sep 17 00:00:00 2001 From: alifeee Date: Tue, 6 Jun 2023 22:47:12 +0100 Subject: [PATCH 13/13] minor formatting changes --- README.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 3523695d6..7a5329b0d 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,19 @@ # Google Spreadsheets Python API v4 -![latest workflow](https://github.com/burnash/gspread/actions/workflows/main.yaml/badge.svg?branch=master) - [![GitHub version](https://badge.fury.io/gh/burnash%2Fgspread.svg)](https://badge.fury.io/gh/burnash%2Fgspread) ![pypi]( https://badge.fury.io/py/gspread.svg) ![downloads](https://img.shields.io/pypi/dm/gspread.svg) ![doc](https://readthedocs.org/projects/gspread/badge/?version=latest) +![latest workflow](https://github.com/burnash/gspread/actions/workflows/main.yaml/badge.svg?branch=master) +[![GitHub version](https://badge.fury.io/gh/burnash%2Fgspread.svg)](https://badge.fury.io/gh/burnash%2Fgspread) +![PyPi]( https://badge.fury.io/py/gspread.svg) +![downloads](https://img.shields.io/pypi/dm/gspread.svg) +![doc](https://readthedocs.org/projects/gspread/badge/?version=latest) Simple interface for working with Google Sheets. Features: -* Open a spreadsheet by **title**, **key** or **url**. -* Read, write, and format cell ranges. -* Sharing and access control. -* Batching updates. +- Open a spreadsheet by **title**, **key** or **URL**. +- Read, write, and format cell ranges. +- Sharing and access control. +- Batching updates. ## Installation @@ -20,7 +23,6 @@ pip install gspread Requirements: Python 3.6+. - ## Basic Usage 1. [Create credentials in Google API Console](http://gspread.readthedocs.org/en/latest/oauth2.html)