Welcome to the Comet API!

The goal of this project is to provide a Python-based starter API, which comes pre-configured with tools supporting the accelerated development of both Comet as well as general python APIs. Some of these tools are as follows:

• Platform: Python
• Web Framework: Fast API
• Database: SQLite, Alembic
• ORM: SQLAlchemy
• Data Validation: Pydantic
• Unit Testing: PyTest
• Code Quality: Ruff, PyLint, Black, isort
• Authentication support: JWT
• Documentation: Swagger and ReDoc

Table of Contents

1. Running the Project Locally
2. Running Unit Tests
3. Running Code Quality Checks
4. Running Code Formatting
5. Publishing Updated Docs
6. Contributing
7. Next Steps

Running the Project Locally

1. To create an environment, run the following:

virtualenv -p python3 venv
source venv/bin/activate

2. To install dependencies, run the following:

pip install -r requirements.txt

3. To prepare your environment, add a file called .env to the comet-api directory. Copy and paste the template below and replace the placeholder values with your own:

DATABASE_URL=[SOME_URL] # Ex: 'sqlite:///./db.sqlite3'
OIDC_CONFIG_URL=[SOME_URL] # Ex: 'https://token.actions.githubusercontent.com/.well-known/openid-configuration'

4. To start the app, run the following:

uvicorn app.main:app --reload --host=0.0.0.0 --port=5000

5. Access the swagger docs by navigating to: http://0.0.0.0:5000/docs

Running Unit Tests

1. To run unit tests, run the following:

pytest

2. To run unit tests with code coverage, run the following:

coverage run -m pytest && coverage html

Running Code Quality Checks

1. To run code quality checks, run the following:

ruff check .

Running Code Formatting

1. To run code formatting, run the following:

ruff format .

Publishing Updated Docs

1. Access the swagger ReDocs by navigating to: http://0.0.0.0:5000/redoc

2. Download the OpenAPI spec, click the Download button

3. Navigate to https://editor.swagger.io/#/

4. Upload the spec, click File >> Import File and select the spec file previously downloaded

5. Download the converted spec, click Generate Client >> openapi-yaml

6. Copy the downloaded file into the comet-api/docs directory

7. Convert the yaml into html run the following:

npx redoc-cli bundle docs/openapi.yaml

8. Copy the generated html to the docs directory, run the following:

mv redoc-static.html docs/index.html

9. Commit the spec and html files and merge into main to publish docs

Contributing

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature_a)
3. Commit your Changes (git commit -m 'Added new feature_a')
4. Push to the Branch (git push origin feature_a)
5. Open a Pull Request

Next Steps

The following provides a short list of tasks which are potential next steps for this project. These could be steps in making use of this baseline or they could be for learning purposes.

• Add/Update existing endpoints with more applicable entities and/or columns
• Update applicable endpoints to require JWT
• Add Admin endpoints to support password reset
• Replace default database with external database (Ex. Postgres)
• Deploy to cloud infrastructure
• Automate doc publishing process