From 6778353b002a0fede06df9e9906cd0f4f217c302 Mon Sep 17 00:00:00 2001 From: Charles Graham SWT Date: Tue, 11 Feb 2025 08:35:36 -0600 Subject: [PATCH 1/2] Add developer docs section to readme --- README.md | 23 +++++++++++++++++++++++ docs/images/poetry-venv.png | Bin 0 -> 2542 bytes 2 files changed, 23 insertions(+) create mode 100644 docs/images/poetry-venv.png diff --git a/README.md b/README.md index b333c2ad..470b4c9a 100644 --- a/README.md +++ b/README.md @@ -77,3 +77,26 @@ print(json) Currently, the TimeSeries Profile API may not be fully supported until a new version of cwms-data-access is released with the updated endpoint implementation. + +## Developer Documentation +For the Contributors/Maintainers of cwms-python + +cwms-python uses: + +- [Poetry](https://python-poetry.org/) for package and dependency management. +- [pytest](https://pypi.org/project/pytest/) for testing of python functions as they are made. +- [requests-mock](https://pypi.org/project/requests-mock/) for simulating CDA to provide network-less tests, effectively mocking the requests to CDA. + +### Setting up Dev Environment + +1. To install poetry (with python 3.8+) run: + `python -m pip install poetry` or `pip install poetry` +2. To install dependencies with poetry run: + `poetry install` + 1. In VSCode you will be prompted to "activate venv", click accept on this to switch to this new poetry venv. ![alt text](docs/images/poetry-venv.png) + 2. *NOTE: If you do not have your python `Scripts` directory in your path this will fail. + `Scripts` is located in your python install directory, add this to your PATH.* +3. Run poetry against all files in the `tests` directory with: + `poetry run pytest` +4. Run poetry against a single file with: + `poetry run pytest tests/turbines/turbines_test.py` - from the root of the project diff --git a/docs/images/poetry-venv.png b/docs/images/poetry-venv.png new file mode 100644 index 0000000000000000000000000000000000000000..bea05ede9101dc2876b434d7ffead219ac940666 GIT binary patch literal 2542 zcmV*P)Px#1ZP1_K>z@;j|==^1poj532;bRa{vGi!vFvd!vV){sAK>D34=*QK~#8N?VMYP zRaF?r*O?g|D=( z6q;xNkwOyI>mL2 z8s@`?3+wNm=DPOnuWKIo&bgJ@|`87M;!t&f44m@}D$?mrEj&8coxp#n>9Y?w+ zKl;U$9$f1m8fFj~%sf!;p-Veld)we9QQ~`M9XlX@?(-Ym-tIoHoG57;QvQ!O|L*JE z{Q72h{z*rArO3kr<+@V-qQL^gc-i?xq4LgWBQP&{=cX1YJ$=4@`q)ezsYPxBxN`aT zZt=T6S7HY`@XhwW-PB`7xH+c`UQGm++W*+Oi7SrS{a3GhcxBgse0GNy*6#Gia>>Mz zJ}rrBrj2zw{^)U!f6(RQ>=v(nwcAY|-|meg3-Tw78Rp(tzq^uBZ1T?Mp~Nd+{N@+R zTmBCNNP?}m78A#|yPx*%_p3VYNfJ-3`qe*{jk~&CcTbc$tj>{s@IDA!u_E)ymfzjz_7->InBkR_LmTG(yB*CLZBqt-zZ@!H2)^k_PkxzM zrV)@w+ZciU_!G)~0t_e($}?yTp6wTXO>>9Xy0_hb)}VoAC+S{tj^F77ZUnoYp3toz zj;wnxJkIT1JaeF&bq|n-+;AtOed?+#{gwZ(yrh0MO871GH_7GDIH;WMgS>zI@!hvQdVaNHfd=3E=lXHmt>qp=3au=1q zB{YH)M-Ow4%_Sp8;dC-@?P03B|OANu2W? zV@?@%dsueeBrgZ|iga8o9>SxStgD)%n`VylZZCNY-`wn7Tl!;Re(8^$UoCW6`0AxD z17LDx;jI4QM+_AVE+5O`)}A{;$m8IQg3+gC*G}|dl{|#X`W4CQ&$HnmI zJ4#618)l62D{FWYch`z7zJ1PLK;JH#GR7;mZeysA91ImXwP2xJ*Y#J`8StGAdwhSa zp(QPf7%N7b<|@~sE(2h@#X@;lflxZTZ4U)Z1gi$YGm#mqafizHbdo#r<$m%0S#`th;R^C?aH*>w%2*|ar0EU1; z)Z@CP5nhAZ-5f*XY?TLG4~&UL%YHM)MS31kbS^I}^u_Lg7#l`6)UIDshhTNOQU6Qu zf%uyk6TYyv(k#?w+Q6ZVS>OWM6*&)9AvGav)mn{N!FA&$#nRKh__L~&D-Ypno3sKR z4C+}`8Gnq4c?-Xpr`9f>1-pt4xLR~{))Ms?YZ6TvK$;TPi&i%L`Mi^xW_(i2tSef- zJ(pdedO1;%8+#U6={8L1b$qkz3|ug zXXbbMRavek{bL+ZQhRMl`>XCay{aE+MwNzk!0E>wQFYd`=nT^6BAm+rG|ASt)wNeM zTbxDr!{L*4pyiyv;M>C-+u`LeZp<_$4QzPBk_Rayw>aU1AeS2$@@=0mh}XVu{1<1f z`a^N}%}d(1Fuqs4{KJ4w06L&QrBFF^<=gGm{nc)UygU~bpgQ)fWnmFZ%gaMy|63GR zWfYUE$h>Y>qEPU#Lz3DNX=x%&rcF-@hxM|` zi?Cjj46tdCRZd}xl@G)j>rk$+a+2y2_A^C*1QoJxg@puYLdjQs#g(SG-c|{OEeon| z!^*eiz?Q4^<_YVAO(UGuhWbw#r3vXZTGiX&HLgpJ$wc-uT1mQ0nGe4)7B zNo9aEJ&J=ZPdI!8VO!Vc5!aJdPGQ~(+j=~NtsdG3!m^56N|Po{>PJXxYpd(+?e%X^ zm^_}gwzjH#H4F$VT~$Sv;z*a>UcZBK%&Pr#if8hqA;Ozn-3+fwZs=X`uO2e|dxLhsMLoAx;_P zDV@0Oqu!DSsw2o#KfuaTIr5|vlEs@xebXBVtB%Usx}dtGGgiEb`*aFO2pI^La0-wn z<(6P8T!NKGIm(j`D$ipZ1_ncIN)D(Gss}b-?OB=1(?F=6(m`p0_JyruA>K%T;&FlDH(eyP6X^G+I1D3wa?UzlmA8>IR)asU7T07*qoM6N<$ Ef{CpB0RR91 literal 0 HcmV?d00001 From a66e2a95acb3465bbc6af8bf4a0e0605af9e69e7 Mon Sep 17 00:00:00 2001 From: Charles Graham SWT Date: Tue, 11 Feb 2025 10:26:43 -0600 Subject: [PATCH 2/2] Move dev docs diff into CONTRIBUTING. Add reference to CONTRIBUTING Move all dependency links to the top of the CONTRIBUTING --- CONTRIBUTING.md | 46 +++++++++++++++++++++++++++++++++++----------- README.md | 25 +++---------------------- 2 files changed, 38 insertions(+), 33 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63e92ce9..1863635c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,38 @@ # Contributing to cwms-python +For the Contributors/Maintainers of cwms-python + +cwms-python uses: + +- [Poetry](https://python-poetry.org/docs/) for package and dependency management. +- [pytest](https://pypi.org/project/pytest/) for testing of python functions as they are made. +- [requests-mock](https://pypi.org/project/requests-mock/) for simulating CDA to provide network-less tests, effectively mocking the requests to CDA. +- [black](https://black.readthedocs.io/en/stable/) for code formatting. +- [isort](https://pycqa.github.io/isort/index.html) - for python imports sorting. + + ## Getting Started -In order to set up the development environment you will need to have [poetry][poetry] installed on your computer. You can then install all of the project dependencies by running the following command. +In order to set up the development environment you will need to have [poetry][poetry] installed on your computer. -```sh -poetry install -``` +1. To install poetry (with python 3.8+) run: + `python -m pip install poetry` or `pip install poetry` + +2. You can then install all of the project dependencies by running the following command. -This will create a virtual environment in `.venv/` in the project's root directory. + ```sh + poetry install + ``` + + 1. In VSCode you will be prompted to "activate venv", click accept on this to switch to this new poetry venv. ![alt text](docs/images/poetry-venv.png) + 2. *NOTE: If you do not have your python `Scripts` directory in your path this will fail. + `Scripts` is located in your python install directory, add this to your PATH.* + + This will create a virtual environment in `.venv/` in the project's root directory. ### Check Your Changes -Before submitting a pull request, you should verify that all the tests are passing and that the types are correct. +**Before submitting** a pull request (PR), you should verify that all the tests are passing and that the types are correct. ```sh poetry run pytest -v tests/ @@ -20,6 +40,13 @@ poetry run pytest -v tests/ poetry run mypy --strict cwms/ ``` +Run poetry against a single file with: +*\*From the root of the project\** + +```sh +poetry run pytest tests/turbines/turbines_test.py` +``` + ### Code Style In order for a pull request to be accepted, python code must be formatted using [black][black] and [isort][isort]. YAML files should also be formatted using either Prettier or the provided pre-commit hook. Developer are encouraged to integrate these tools into their workflow. Pre-commit hooks can be installed to automatically validate any code changes, and reformat if necessary. @@ -38,16 +65,13 @@ poetry run pre-commit run poetry run pre-commit run --all-files ``` -[black]: https://black.readthedocs.io/en/stable/ -[isort]: https://pycqa.github.io/isort/index.html -[poetry]: https://python-poetry.org/docs/ ### Commiting to main and releases -when creating a pull request to main and you want the build to be pushed to test pypi the verion needs to be updated in pyproject.toml file. For pull requests that are only updating testpypi increase the third number 0.1.2 -> 0.1.3. Releases that will also update to pypi tag a new release in the repo and update the pyproject.toml increasing the minor version 0.1.1 -> 0.2.0. +when creating a pull request to main and you want the build to be pushed to test pypi the verion needs to be updated in pyproject.toml file. For pull requests that are only updating testpypi increase the third number `0.1.2` -> `0.1.3`. Releases that will also update to pypi tag a new release in the repo and update the pyproject.toml increasing the minor version `0.1.1` -> `0.2.0`. to grab the module from testpypi for testin run ```sh python3 -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ cwms-python -``` +``` \ No newline at end of file diff --git a/README.md b/README.md index 470b4c9a..9976f63e 100644 --- a/README.md +++ b/README.md @@ -78,25 +78,6 @@ Currently, the TimeSeries Profile API may not be fully supported until a new version of cwms-data-access is released with the updated endpoint implementation. -## Developer Documentation -For the Contributors/Maintainers of cwms-python - -cwms-python uses: - -- [Poetry](https://python-poetry.org/) for package and dependency management. -- [pytest](https://pypi.org/project/pytest/) for testing of python functions as they are made. -- [requests-mock](https://pypi.org/project/requests-mock/) for simulating CDA to provide network-less tests, effectively mocking the requests to CDA. - -### Setting up Dev Environment - -1. To install poetry (with python 3.8+) run: - `python -m pip install poetry` or `pip install poetry` -2. To install dependencies with poetry run: - `poetry install` - 1. In VSCode you will be prompted to "activate venv", click accept on this to switch to this new poetry venv. ![alt text](docs/images/poetry-venv.png) - 2. *NOTE: If you do not have your python `Scripts` directory in your path this will fail. - `Scripts` is located in your python install directory, add this to your PATH.* -3. Run poetry against all files in the `tests` directory with: - `poetry run pytest` -4. Run poetry against a single file with: - `poetry run pytest tests/turbines/turbines_test.py` - from the root of the project +## Contributing + +Please view the contribution documentation here: [CONTRIBUTING.md]