{"id":19820030,"url":"https://github.com/freelancer/esapyi","last_synced_at":"2025-05-01T11:33:22.369Z","repository":{"id":53562186,"uuid":"203125838","full_name":"freelancer/esapyi","owner":"freelancer","description":"A dockerized and production ready python API template with no setup required.","archived":false,"fork":false,"pushed_at":"2023-08-25T03:33:40.000Z","size":613,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2023-08-25T05:48:57.154Z","etag":null,"topics":["docker","flask-api","python-template","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/freelancer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-19T07:58:10.000Z","updated_at":"2023-08-25T05:48:57.155Z","dependencies_parsed_at":"2023-01-28T10:30:56.156Z","dependency_job_id":null,"html_url":"https://github.com/freelancer/esapyi","commit_stats":null,"previous_names":[],"tags_count":2,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freelancer%2Fesapyi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freelancer%2Fesapyi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freelancer%2Fesapyi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freelancer%2Fesapyi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/freelancer","download_url":"https://codeload.github.com/freelancer/esapyi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224254360,"owners_count":17281146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","flask-api","python-template","python3"],"created_at":"2024-11-12T10:21:09.475Z","updated_at":"2024-11-12T10:21:10.075Z","avatar_url":"https://github.com/freelancer.png","language":"Python","readme":"# esapyi \u0026middot; [![CI Tests](https://github.com/freelancer/esapyi/actions/workflows/ci.yml/badge.svg)](https://github.com/freelancer/esapyi/actions/workflows/ci.yml)\n\u003cdiv align=\"center\"\u003e\u003cstrong\u003e\u003cem\u003e\nA dockerized and production ready python API template with no setup required.\n\u003c/em\u003e\u003c/strong\u003e\u003c/div\u003e\n\nThis project aims to provide a pre-configured python API server template based on the Flask python framework.\n\n| Table of Contents                                                                           |\n| ------------------------------------------------------------------------------------------- |\n| [Quickstart Guide](#Quickstart-guide)                                                       |\n| [The Hitchhicker's Guide to `api_boilerplate`](#The-Hitchhickers-Guide-to-api_boilerplate)  |\n| [Developer Guide](#Developer-Guide)                                                         |\n\n## Quickstart guide\n\n1. Ensure that you have [docker](https://docs.docker.com/install/) installed on your system.\n2. Clone this repository using `git clone https://github.com/freelancer/esapyi.git`\n3. (Optional) Pick a new name for your project and run `./project_rename.sh \"my_project_name\"`\n4. Start the python server using `./run.sh dev`\n\n## The Hitchhicker's Guide to `api_boilerplate`\nThis section will take you through the following\n\n* [Project Structure](#Project-Structure)\n* Writing versioned APIs (TODO)\n\n### Project Structure\n\n\u003cpre\u003e\u003cfont color=\"#729FCF\"\u003e\u003cb\u003eapi_boilerplate\u003c/b\u003e\u003c/font\u003e\n├── app.py\n├── \u003cfont color=\"#729FCF\"\u003e\u003cb\u003econfig\u003c/b\u003e\u003c/font\u003e\n│   ├── __init__.py\n│   ├── local_development.py\n│   ├── prod.py\n│   └── testing.py\n├── \u003cfont color=\"#729FCF\"\u003e\u003cb\u003eexceptions\u003c/b\u003e\u003c/font\u003e\n├── \u003cfont color=\"#729FCF\"\u003e\u003cb\u003ehandlers\u003c/b\u003e\u003c/font\u003e\n├── \u003cfont color=\"#729FCF\"\u003e\u003cb\u003ehealthcheck\u003c/b\u003e\u003c/font\u003e\n├── \u003cfont color=\"#729FCF\"\u003e\u003cb\u003emodels\u003c/b\u003e\u003c/font\u003e\n├── \u003cfont color=\"#729FCF\"\u003e\u003cb\u003eutils\u003c/b\u003e\u003c/font\u003e\n└── \u003cfont color=\"#729FCF\"\u003e\u003cb\u003ev1\u003c/b\u003e\u003c/font\u003e\n    ├── \u003cfont color=\"#729FCF\"\u003e\u003cb\u003eexceptions\u003c/b\u003e\u003c/font\u003e\n    ├── \u003cfont color=\"#729FCF\"\u003e\u003cb\u003ehandlers\u003c/b\u003e\u003c/font\u003e\n    ├── input_schemas.py\n    ├── output_schemas.py\n\u003c/pre\u003e\n\n## Developer Guide\nThis section goes through the various tools and procedures a developer would need when developing using this setup.\n\n**Contents**\n- [Commands Quickstart](#Commands): Getting the most out of the utility scripts\n- [Linting](#Linting): The linter setup and now to customize it\n- [Testing](#Testing): Getting the most out of the test setup\n- [Database Migrations](#Database-Migrations): How to track and alter the database schema\n- [Production Deployment](#Production-Deployment): The ideal way of running the production server\n\n### Commands Quickstart\nAll of the common development tasks that need to be performed are done through the `run.sh` script located at the root of the project.\n`run.sh` has the following commands\n- `run.sh dev` - start the local db and python development server at port *8080*\n- `run.sh prod` - start the local db and the production [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/) python server at port *8080*\n- `run.sh lint` - lint the entire project\n- `run.sh test` - run the entire test suite for the project\n- `run.sh check` - run the *lint* and *test* command in succession\n- `run.sh dev db` - spin up and connect to the local dev database\n- `run.sh alembic` - proxy to the [alembic](https://alembic.sqlalchemy.org) cli\n\n### Linting\nThis project uses 2 main linting programs\n- [pyright](https://microsoft.github.io/pyright/#/) - a static type-checker\n- [ruff](https://ruff.rs/) - a code quality checker\n\nIf you want to customize the lint configuration, modify the following files\n- [pyproject.toml](pyproject.toml) - to customize the mypy setup\n- [pyproject.toml](pyproject.toml) - to customize the ruff setup\n\n### Testing\nThis project uses the [pytest](https://docs.pytest.org/en/latest/) framework for writing and maintaining unit tests.\n- In order to configure pytest, use the [pytest.ini](pytest.ini) file\n\nThe unit tests also spin up a dockerized MySQL database. Every `run.sh test` call will kill and re-create the database to ensure tests are running in a fresh environment.\n\nThere are 3 base test classes which you should extend when writing tests.\n* [BaseTestCase](tests/conftest.py#L10)\n    * An empty class that extends [unittest.TestCase](https://docs.python.org/3/library/unittest.html#unittest.TestCase)\n* [AppContextTestCase](tests/conftest.py#L14)\n    * A class makes a [flask test client](https://flask.palletsprojects.com/en/1.0.x/testing/#the-testing-skeleton) available at `self.client`\n* [DbContextTestCase](tests/conftest.py#L22)\n    * Waits for the database to become available if it's not\n    * Re-sets the database after every test using [alembic](https://alembic.sqlalchemy.org/en/latest/tutorial.html#downgrading).\n\n### Database Migrations\n\nThis project uses [alembic](https://alembic.sqlalchemy.org/en/latest/) as a database migrations tool. This tool essentially acts as a version control for your database schema. Any changes that need to be made should be tracked and done through alembic.\n\n**Example: Adding a new column**\n\nSay we want to add a new column to our users table - `first_name`.\n\u003cbr/\u003eTo do so, follow these steps\n\n1. Modify the [user model](api_boilerplate/models/user.py) and add the first_name column\n```python\nfirst_name = Column(Text, nullable=False)\n```\n2. Run the alembic command to [autogenerate](https://alembic.sqlalchemy.org/en/latest/autogenerate.html) a revision\n    * This command creates a new file under the migrations/versions folder which contains code to create this new column in the db\n```bash\n./run.sh alembic revision --autogenerate -m\"add_fname_to_user\"\n```\n3. Run the alembic command to upgrade the database\n```bash\n./run.sh alembic upgrade head\n```\n4. That's it! The user table in the local docker database now has a first_name column. Remember to commit the generated migration file to git.\n\n### Production Deployment\n\nIt is recommended that you deploy this API as a docker container on your production server.\nIn order to help build this container there is a production ready [dockerfile](lib/docker/prod_app/Dockerfile) provided.\n\nIn production, the python app is run using [uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/). The configuration for this uWSGI server is in [uwsgi_prod_app_config.ini](uwsgi_prod_app_config.ini).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreelancer%2Fesapyi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreelancer%2Fesapyi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreelancer%2Fesapyi/lists"}