Update readme. Add other linting hooks. Review Fixes.

department-of-veterans-affairs · Dec 11, 2024 · 76a2eca · 76a2eca
1 parent e30a653
commit 76a2eca
Show file tree

Hide file tree

Showing 4 changed files with 105 additions and 95 deletions.
diff --git a/.github/workflows/test-code.yml b/.github/workflows/test-code.yml
@@ -23,20 +23,20 @@ jobs:
 
       - name: Install Poetry
         uses: snok/install-poetry@v1
+        with:
+          poetry-version: 'latest'
 
-      - name: Load cached venv
-        id: cached-poetry-dependencies
+      - name: Load or Install Dependencies
         uses: actions/cache@v4
+        id: poetry-cache
         with:
           path: .venv
-          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
-
-      - name: Install dependencies if not in cached venv
-        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
-        run: poetry install --no-interaction --no-root
+          key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
+        continue-on-error: true # Ensures workflow runs even if cache retrieval fails
 
-      - name: Install project
-        run: poetry install --no-interaction
+      - name: Install dependencies if cache missed
+        if: steps.poetry-cache.outputs.cache-hit != 'true'
+        run: poetry install --no-root
 
       - name: "Run ruff format"
         run: poetry run ruff format

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,32 +1,50 @@
 repos:
-- repo: https://github.com/abravalheri/validate-pyproject
-  rev: v0.23
-  hooks:
+  - repo: meta
+    hooks:
+      - id: check-useless-excludes
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks: # https://github.com/pre-commit/pre-commit-hooks#hooks-available
+      - id: check-merge-conflict
+      - id: check-executables-have-shebangs
+      - id: check-shebang-scripts-are-executable
+        exclude: ^(scripts/.*\.src)|(entrypoint.sh)$
+      - id: check-yaml
+      - id: destroyed-symlinks
+      - id: detect-private-key
+      - id: end-of-file-fixer # https://stackoverflow.com/questions/2287967/why-is-it-recommended-to-have-empty-line-in-the-end-of-a-source-file
+      - id: fix-byte-order-marker
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.23
+    hooks:
       - id: validate-pyproject
 
--   repo: https://github.com/astral-sh/ruff-pre-commit
+  - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.8.2
-
     hooks:
-    -   id: ruff
-        args: [--fix]
-    -   id: ruff-format
+      - id: ruff
+        args: [ --fix ]
+      - id: ruff-format
 
--   repo: https://github.com/python-poetry/poetry
+  - repo: https://github.com/python-poetry/poetry
     rev: '1.8.5'  # Must be updated manually (see https://python-poetry.org/docs/pre-commit-hooks/#why-does-pre-commit-autoupdate-not-update-to-the-latest-version
     hooks:
-    -   id: poetry-check
-    -   id: poetry-lock
-    -   id: poetry-install
+      - id: poetry-check
+      - id: poetry-lock
+      - id: poetry-install
 
--   repo: https://github.com/pre-commit/mirrors-mypy
+  - repo: https://github.com/pre-commit/mirrors-mypy
     rev: 'v1.13.0'
     hooks:
-    -   id: mypy
+      - id: mypy
         pass_filenames: false  # Pass all files in the repository except those excluded in pyproject.toml
         args:
-            - '.'  # Check all files in the repository
-            - "--config-file=pyproject.toml"
+          - '.'  # Check all files in the repository
+          - "--config-file=pyproject.toml"
         additional_dependencies:
-            - 'pydantic'
-            - 'fastapi'
+          - 'pydantic'
+          - 'fastapi'
diff --git a/README.md b/README.md
@@ -6,7 +6,8 @@
 
 ## Getting started
 
-Install Python3.10
+### Install Python3.10
+
 If you're on a Mac, you can use pyenv to handle multiple python versions
 
 ```
@@ -15,28 +16,62 @@ pyenv install python3.10
 pyenv global python3.10 # or don't do this if you want a different version available globally for your system
 ```
 
-Create a virtual env:
+### Install Poetry
+
+This project uses [Poetry](https://python-poetry.org/docs/) to manage dependencies.
+
+Follow the directions on the [Poetry website](https://python-poetry.org/docs/#installation) for installation.
+
+### Create a virtual env (Optional)
+
+By default, Poetry will create its own virtual environment (see [here](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment)), but it will
+also detect and respect an existing virtual environment if you have one activated.
+
+#### Other options:
+
+* Create a virtual environment with `python` and activate it like so:
+  ```
+  python -m venv ~/.virtualenvs/domain-ee # or wherever you want
+  source ~/.virtualenvs/domain-ee/bin/activate
+  ```
+* Use [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv) to create and activate virtual environments with `pyenv`.
+* Use [Poetry](https://python-poetry.org/docs/basic-usage/#activating-the-virtual-environment) to explicitly create and use a virtual environment.
+
+Make sure your python path is set up to pull from your virtualenv:
 
 ```
-python -m venv ~/.virtualenvs/domain-ee # or wherever you want
-source ~/.virtualenvs/domain-ee/bin/activate
+which python
+# /path/to/your/virtualenv/bin/python
 ```
 
-Make sure your python path is set up to pull from your virtualenv:
+### Install dependencies
+
+Use Poetry to run and install all dependencies:
 
 ```
-which python3
-# /Users/<your_username>/.virtualenvs/domain-ee/bin/python
+poetry install
 ```
 
-Install dependencies and run webserver
+### Install pre-commit hooks
+
+This project uses pre-commit hooks to ensure code quality. To install them, run:
+
+```
+poetry run pre-commit install
+```
+
+## Run the server locally
+
+Using Poetry, run the following command from the root of the repository:
 
 ```
-cd disability-max-ratings-api/src
-pip3 install -r dev-requirements.txt
-uvicorn api:app --port 8130 --reload
+poetry run uvicorn src.python_src.api:app --port 8130 --reload
 ```
 
+## Run the server with Docker
+
+TODO: update this to use the new disability-max-ratings-api Docker Compose file - <https://github.com/department-of-veterans-affairs/abd-vro/issues/3833>
+
 ## Testing it all together
 
 Run the Python webserver (uvicorn command above). Now you should be able to make a post request to the `/disability-max-ratings/`
@@ -84,74 +119,26 @@ This should result in a response with the following body:
 * If any entry of the `diagnostic_codes` is not found, the response `ratings` array will not contain the corresponding
   item.
 
-## Unit tests
+## Run Unit tests
 
-Make sure you're in your `.virtualenv`:
+Using Poetry, run the following command from the root of the repository:
 
 ```
-source ~/.virtualenvs/domain-ee/bin/activate
-```
-
-Navigate to `disability-max-ratings-api/`:
-
-```
-cd disability-max-ratings-api
-```
-
-Run the tests:
-
-```
-pytest
+poetry run pytest
 ```
 
 ## Contributing
 
-### Install dev dependencies
-
-```
-# TODO: update this to use the new disability-max-ratings-api
-source ~/.virtualenvs/domain-ee/bin/activate
-pip install -r dev-requirements.txt
-# MAKE SURE you are in adb-vro/domain-ee to get the right pre-commit-config.yaml installed
-pre-commit install
-```
+Follow steps for getting started above, then make your changes and submit a pull request.
 
 ## Building docs
 
-```
-# TODO: update this to use the new disability-max-ratings-api
-source ~/.virtualenvs/domain-ee/bin/activate
-cd ./disability-max-ratings-api
-python3 src/python_src/pull_api_documentation.py
-```
-
-## Docker Stuff
+Swagger docs can be viewed by running the server [locally](#run-the-server-locally) and navigating to `http://localhost:8130/docs`.
 
-### Build the image
-
- TODO: update this to use the new disability-max-ratings-api Docker Compose file - <https://github.com/department-of-veterans-affairs/abd-vro/issues/3833>
-
-Follow steps for
-[Platform Base + API-Gateway](https://github.com/department-of-veterans-affairs/abd-vro/wiki/Docker-Compose#platform-base)
-then run the disability-max-ratings-api with the following command from the `disability-max-ratings-api directory`:
-
-TODO migrate away from gradlew to use a python alternative <https://github.com/department-of-veterans-affairs/abd-vro/issues/3832>
-```
-COMPOSE_PROFILES="all" ./gradlew :domain-ee:dockerComposeUp
-```
-
-### Verify API in API Gateway
-
-Navigate to [Swagger](http://localhost:8060/webjars/swagger-ui/index.html?urls.primaryName=3.%20Max%20CFI%20API)
-
-Try to send a request on the post endpoint with the following request body:
+If desired, the docs can be exported to `openapi.json` by running the following command:
 
 ```
-{
-  "diagnostic_codes": [
-    6260
-  ]
-}
+poetry run python src/python_src/pull_api_documentation.py
 ```
 
 ## Repository History

diff --git a/src/python_src/pull_api_documentation.py b/src/python_src/pull_api_documentation.py
@@ -1,4 +1,5 @@
 import json
+import os
 
 from fastapi import FastAPI
 from fastapi.openapi.utils import get_openapi
@@ -15,5 +16,9 @@ def export_openapi(app: FastAPI, filename: str) -> None:
 if __name__ == '__main__':
     from api import app
 
-    export_openapi(app, 'fastapi.json')
-    print('Done!')
+    if not os.path.exists('build'):
+        os.mkdir('build')
+
+    output_file = os.path.abspath('build/fastapi.json')
+    export_openapi(app, output_file)
+    print(f'OpenAPI specification exported to: {output_file}')