{"id":14065081,"url":"https://github.com/keathmilligan/flask-quickstart","last_synced_at":"2025-07-29T19:34:12.390Z","repository":{"id":131358484,"uuid":"70200869","full_name":"keathmilligan/flask-quickstart","owner":"keathmilligan","description":"A quick-start project template for a RESTful Flask-based application feature SQLAlchemy database integration, object marshalling, JWT authentication and pytest unit-tests.","archived":false,"fork":false,"pushed_at":"2022-03-27T18:23:02.000Z","size":707,"stargazers_count":19,"open_issues_count":0,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-08-13T07:08:09.196Z","etag":null,"topics":["flask","python","setuptools"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/keathmilligan.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,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2016-10-06T23:26:42.000Z","updated_at":"2024-07-02T15:29:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"a4356f0b-d121-49e6-96bf-eff366e2d1d4","html_url":"https://github.com/keathmilligan/flask-quickstart","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keathmilligan%2Fflask-quickstart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keathmilligan%2Fflask-quickstart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keathmilligan%2Fflask-quickstart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keathmilligan%2Fflask-quickstart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keathmilligan","download_url":"https://codeload.github.com/keathmilligan/flask-quickstart/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228046059,"owners_count":17861086,"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":["flask","python","setuptools"],"created_at":"2024-08-13T07:04:17.245Z","updated_at":"2024-12-04T04:30:43.044Z","avatar_url":"https://github.com/keathmilligan.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"Flask Application Quick Start Template\n======================================\n\nThis repo provides a quick-start template for creating a stand-alone web application using the [Flask](http://flask.pocoo.org/) micro-framework for Python 3.8+. You can use this template as a basis for an app that will serve HTML and other content or as a starting point for an API-only service that will be paired with an SPA (React, Angular, etc.) or some other type of client.\n\nFeatures:\n* Flask 2.x and blueprints\n* Jinja2 HTML templates\n* SQLAlchemy database models\n* Marshmallow for object marshalling\n* JSON Web Token (JWT) authentication\n* PyTest unit-tests\n* Serve in production with waitress\n* Pylint and Black\n\nSee [RESTful Flask application quick-start](http://keathmilligan.net/restful-flask-application-quick-start/) for more info.\n\n## Getting Started\n\nYou will need Python 3.8 or later. Use the appropriate installation method for your system to install Python and make sure it is in your path. The template currently targets Python 3.10 (recommended).\n\nThis project also uses [pipenv](https://pipenv.pypa.io/en/latest/) to manage dependencies and its virtual environment. You will need to install it if you do not already have it.\n\n### Using the template\n\nTo use the template, click the **Use this template** button in the [Github repository](https://github.com/keathmilligan/flask-quickstart) to create a new project using this code as a basis. Alternatively, you can clone the repository locally.\n\n### Install dependencies\n\n\u003e The template currently expects Python 3.10, if you need to use an older version, you will need to modify the `Pipfile`.\n\nUse [pipenv](https://pipenv.pypa.io/en/latest/) to create a virtual environment and install the dependencies:\n\n```\npipenv install --dev\n```\n\nThe `--dev` option will also install the optional development dependencies such as `pylint` and `pytest`.\n\n## Running\n\n### Create the database\n\nBefore running the app for the first time, you must initialize the database with:\n\nLinux/MacOS:\n```bash\nexport FLASK_APP=sample; pipenv run flask initdb\n```\n\nWindows Powershell\n```powershell\n$env:FLASK_APP = \"sample\"; pipenv run flask initdb\n```\n\n### Running in Development\n\nTo start the development server with automatic reloading, run:\n\nLinux/MacOS:\n```bash\nexport FLASK_APP=sample; pipenv run flask run --debugger --reload --with-threads\n```\n\nWindows Powershell\n```powershell\n$env:FLASK_APP = \"sample\"; pipenv run flask run --debugger --reload --with-threads\n```\n\nThe app will be available with `http://localhost:5000`. Log in with the test user name `user1` and password `1234`:\n![screenshot](/docs/images/screenshot.png)\n\nClick the **Contacts** link to list and create sample data.\n\n![contacts](/docs/images/contacts.png)\n\nEdit a contact:\n\n![edit contact](/docs/images/edit-contact.png)\n\n### Running in Production\n\nTo serve the app with `waitress` for production use, run:\n\n```\npipenv run python -m sample\n```\n\nHit `Ctrl-C` to abort.\n\nThis is just a starting point for production deployment - see the [waitress docs](https://docs.pylonsproject.org/projects/waitress/en/latest/usage.html) for more info.\n\n## Test\n\nRun the `pytest` unit tests with:\n\n```\npipenv run pytest\n```\n\nYou should see something like:\n```\n======================================================= test session starts ========================================================\nplatform darwin -- Python 3.5.2, pytest-3.0.3, py-1.4.31, pluggy-0.4.0\nrootdir: /Users/kmilligan/workspace/flask-quickstart, inifile: \ncollected 11 items \n\ntests/test_auth.py ......\ntests/test_contacts.py .....\n\n==================================================== 11 passed in 2.90 seconds =====================================================\n```\n\n## REST API Usage\n\nUse an HTTP client such as [PostMan](https://www.postman.com/) or the VSCode [Thunder Client](https://marketplace.visualstudio.com/items?itemName=rangav.vscode-thunder-client) extension to experiment with the REST API endpoints:\n\n### Authenticate\n\nBefore you can access secured endpoints, you must obtain a JWT access token. Send a POST request to `http://127.0.0.1:5000/api/login` with the username/password to login and get an access token and a refresh token:\n\n![Authenticate](/docs/images/rest-login.png)\n\nCopy the access token to the clipboard - you will need it for subsequent requests. Also, save the refresh token somewhere, we'll use it later.\n\nTo verify that you have a valid access token, create a new GET request to `http://127.0.0.1:5000/api/auth` and set the \"Authorization\" type to \"Bearer Token\" and paste the access token into the Token field and send the request (alternatively, set the `Authorization` header to \"Bearer `\u003caccess token\u003e`\").\n\n![Verify Authentication](/docs/images/rest-get-auth.png)\n\n### Refresh Access Token\n\nIf the access token has expired or is about to expire, you can obtain a new one by using the `api/refresh` endpoint:\n\n![Refresh Access Token](/docs/images/rest-refresh.png)\n\n### Use Sample Data Endpoints\n\nNow you can use the sample contacts endpoints to list, create, update and delete entries:\n\n![Get Contacts](/docs/images/rest-contacts.png)\n\n## Next Steps\n\n### Delete the stuff you don't need\n\nFor example, if you don't need to serve HTML, you can remove the `templates` directory and the page-oriented views from the blueprints. Alternatively, if you don't need to serve RESTful resources, you can delete the API endpoints.\n\n### Add a real authentication backend\n\nA real application will likely use some external service to lookup users, validate passwords, control access, etc. Enhance the `auth.py` module with your own authentication/authorization logic.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeathmilligan%2Fflask-quickstart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeathmilligan%2Fflask-quickstart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeathmilligan%2Fflask-quickstart/lists"}