====================
flask-ligand-example
====================
|build-status| |pypi-status| |codecov-status| |pre-commit-status|
A simple example project on how to use the `flask-ligand`_ library. This example project is based on the `example`_
from the `flask-smorest`_ project. (Which is a core library that `flask-ligand`_ is built upon)
Quick Start Guide
=================
Follow the instructions below to start exploring this example project!
Prerequisites
-------------
- Python 3.10+
- virtualenvwrapper_
- Docker_ (with `Compose V2`_)
Clone Repo
----------
.. code-block:: bash
$ git clone git@github.com:cowofevil/flask-ligand-example.git
Make Targets
------------
Execute the following command to get a full list of ``make`` targets::
$ make help
Setup Python Environment
------------------------
1. Create a Python virtual environment::
$ mkvirtualenv -p py310 flask-ligand-example
2. Setup develop environment::
$ make develop-venv
3. Setup git pre-commit hooks::
$ make setup-pre-commit
4. Verify that environment is ready for development::
$ make test-tox
Setup Docker Environment
------------------------
The included docker environment used for integration testing can also be used for exploring the example project as well!
1. Setup the Docker environment::
$ make setup-integration
2. Verify that the Docker environment is ready::
$ make check-integration
3. (Optionally) Execute the integration tests::
$ make test-integration
Explore with SwaggerUI Docs
===========================
This example project has all the bells and whistles enabled for the `flask-ligand`_ library which can be explored by
using the included `SwaggerUI`_ documentation. Follow the instructions below to start start running a local Flask server
to serve the `SwaggerUI`_ documentation.
1. Generate a '.env' file to configure Flask server to use the included Docker environment::
$ make gen-local-env-file
2. Initialize the database::
$ make setup-db
3. Generate a JWT access token with admin rights for accessing the included example project endpoints::
$ make gen-admin-access-token
4. Start the local Flask server::
$ make run
5. Open a browser and navigate to 'http://localhost:5000/apidocs'.
6. Click the 'Authorize' button and paste in the JWT access token you created previously.
Now go ahead and start playing around with the API!
Access Keycloak Admin Console
-----------------------------
If you would like to make changes to the `Keycloak`_ IAM clients to explore authentication then you can access the
admin console by navigating to 'http://localhost:8080/admin/master/console/'. The admin credentials can be found in the
'docker/env_files/integration.env/' file.
Flask-Migrate Auto-generation
=============================
For `Flask-Migrate`_ to work well when auto-generating migration scripts it is critical that the ``script.py.mako``
template in the ``migrations`` folder include an import for ``sqlalchemy_utils``. This project already has the template
updated, but if you are using the ``flask-ligand`` library without copying this example project, then it is necessary
you make the appropriate update to the ``script.py.mako`` template before using `Flask-Migrate`_.
Resources
=========
- `Changelog`_
- `Contributing`_
- `License`_
.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/en/latest/
.. _Docker: https://www.docker.com/products/docker-desktop/
.. _Compose V2: https://docs.master.dockerproject.org/compose/#compose-v2-and-the-new-docker-compose-command
.. _flask-ligand: https://flask-ligand.readthedocs.io/en/stable/
.. _flask-smorest: https://flask-smorest.readthedocs.io/en/latest/
.. _`Flask-Migrate`: https://flask-migrate.readthedocs.io/en/latest/
.. _example: https://flask-smorest.readthedocs.io/en/latest/quickstart.html
.. _`SwaggerUI`: https://swagger.io/tools/swagger-ui/
.. _`Keycloak`: https://www.keycloak.org/
.. _`Changelog`: ./CHANGELOG.md
.. _`Contributing`: ./CONTRIBUTING.rst
.. _`License`: ./LICENSE
.. |build-status| image:: https://img.shields.io/github/actions/workflow/status/cowofevil/flask-ligand-example/bump_and_publish_release.yml?branch=main&logo=github
:target: https://github.com/cowofevil/flask-ligand-example/actions/workflows/bump_and_publish_release.yml
:alt: Build
.. |pypi-status| image:: https://img.shields.io/pypi/v/flask-ligand-example?color=blue&logo=pypi
:target: https://pypi.org/project/flask-ligand-example/
:alt: PyPI
.. |codecov-status| image:: https://img.shields.io/codecov/c/gh/cowofevil/flask-ligand-example?color=teal&logo=codecov
:target: https://app.codecov.io/gh/cowofevil/flask-ligand-example
:alt: Codecov
.. |pre-commit-status| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
:target: https://github.com/pre-commit/pre-commit
:alt: pre-commit
Raw data
{
"_id": null,
"home_page": "",
"name": "flask-ligand-example",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "flask",
"author": "Ryan Gard",
"author_email": "ryan@gardiancapitol.com",
"download_url": "https://files.pythonhosted.org/packages/69/5a/6db8b8389ea3889c9883f019349bf4c22f8b352f221309b36c5c91200a95/flask-ligand-example-0.5.2.tar.gz",
"platform": null,
"description": "====================\nflask-ligand-example\n====================\n\n|build-status| |pypi-status| |codecov-status| |pre-commit-status|\n\nA simple example project on how to use the `flask-ligand`_ library. This example project is based on the `example`_\nfrom the `flask-smorest`_ project. (Which is a core library that `flask-ligand`_ is built upon)\n\nQuick Start Guide\n=================\n\nFollow the instructions below to start exploring this example project!\n\nPrerequisites\n-------------\n\n- Python 3.10+\n- virtualenvwrapper_\n- Docker_ (with `Compose V2`_)\n\nClone Repo\n----------\n\n.. code-block:: bash\n\n $ git clone git@github.com:cowofevil/flask-ligand-example.git\n\nMake Targets\n------------\n\nExecute the following command to get a full list of ``make`` targets::\n\n $ make help\n\nSetup Python Environment\n------------------------\n\n1. Create a Python virtual environment::\n\n $ mkvirtualenv -p py310 flask-ligand-example\n\n2. Setup develop environment::\n\n $ make develop-venv\n\n3. Setup git pre-commit hooks::\n\n $ make setup-pre-commit\n\n4. Verify that environment is ready for development::\n\n $ make test-tox\n\nSetup Docker Environment\n------------------------\n\nThe included docker environment used for integration testing can also be used for exploring the example project as well!\n\n1. Setup the Docker environment::\n\n $ make setup-integration\n\n2. Verify that the Docker environment is ready::\n\n $ make check-integration\n\n3. (Optionally) Execute the integration tests::\n\n $ make test-integration\n\nExplore with SwaggerUI Docs\n===========================\n\nThis example project has all the bells and whistles enabled for the `flask-ligand`_ library which can be explored by\nusing the included `SwaggerUI`_ documentation. Follow the instructions below to start start running a local Flask server\nto serve the `SwaggerUI`_ documentation.\n\n\n1. Generate a '.env' file to configure Flask server to use the included Docker environment::\n\n $ make gen-local-env-file\n\n2. Initialize the database::\n\n $ make setup-db\n\n3. Generate a JWT access token with admin rights for accessing the included example project endpoints::\n\n $ make gen-admin-access-token\n\n4. Start the local Flask server::\n\n $ make run\n\n5. Open a browser and navigate to 'http://localhost:5000/apidocs'.\n6. Click the 'Authorize' button and paste in the JWT access token you created previously.\n\nNow go ahead and start playing around with the API!\n\nAccess Keycloak Admin Console\n-----------------------------\n\nIf you would like to make changes to the `Keycloak`_ IAM clients to explore authentication then you can access the\nadmin console by navigating to 'http://localhost:8080/admin/master/console/'. The admin credentials can be found in the\n'docker/env_files/integration.env/' file.\n\nFlask-Migrate Auto-generation\n=============================\n\nFor `Flask-Migrate`_ to work well when auto-generating migration scripts it is critical that the ``script.py.mako``\ntemplate in the ``migrations`` folder include an import for ``sqlalchemy_utils``. This project already has the template\nupdated, but if you are using the ``flask-ligand`` library without copying this example project, then it is necessary\nyou make the appropriate update to the ``script.py.mako`` template before using `Flask-Migrate`_.\n\nResources\n=========\n\n- `Changelog`_\n- `Contributing`_\n- `License`_\n\n.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/en/latest/\n.. _Docker: https://www.docker.com/products/docker-desktop/\n.. _Compose V2: https://docs.master.dockerproject.org/compose/#compose-v2-and-the-new-docker-compose-command\n.. _flask-ligand: https://flask-ligand.readthedocs.io/en/stable/\n.. _flask-smorest: https://flask-smorest.readthedocs.io/en/latest/\n.. _`Flask-Migrate`: https://flask-migrate.readthedocs.io/en/latest/\n.. _example: https://flask-smorest.readthedocs.io/en/latest/quickstart.html\n.. _`SwaggerUI`: https://swagger.io/tools/swagger-ui/\n.. _`Keycloak`: https://www.keycloak.org/\n.. _`Changelog`: ./CHANGELOG.md\n.. _`Contributing`: ./CONTRIBUTING.rst\n.. _`License`: ./LICENSE\n\n.. |build-status| image:: https://img.shields.io/github/actions/workflow/status/cowofevil/flask-ligand-example/bump_and_publish_release.yml?branch=main&logo=github\n :target: https://github.com/cowofevil/flask-ligand-example/actions/workflows/bump_and_publish_release.yml\n :alt: Build\n.. |pypi-status| image:: https://img.shields.io/pypi/v/flask-ligand-example?color=blue&logo=pypi\n :target: https://pypi.org/project/flask-ligand-example/\n :alt: PyPI\n.. |codecov-status| image:: https://img.shields.io/codecov/c/gh/cowofevil/flask-ligand-example?color=teal&logo=codecov\n :target: https://app.codecov.io/gh/cowofevil/flask-ligand-example\n :alt: Codecov\n.. |pre-commit-status| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white\n :target: https://github.com/pre-commit/pre-commit\n :alt: pre-commit\n\n",
"bugtrack_url": null,
"license": "GNU Affero General Public License v3",
"summary": "A simple example project on how to use the flask-ligand library.",
"version": "0.5.2",
"project_urls": {
"Changelog": "https://github.com/cowofevil/flask-ligand-example/blob/main/CHANGELOG.md",
"Source": "https://github.com/cowofevil/flask-ligand-example",
"Tracker": "https://github.com/cowofevil/flask-ligand-example/issues"
},
"split_keywords": [
"flask"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dc58c439a29f610e2db5b8341e3ff4301f8c858164f7a47087d521a5f3f994d7",
"md5": "c3e94226ffd997b19854a4909a8662bb",
"sha256": "1c064fa180de0a11a4a79f4cd10e731bae0e583bbec35b8898472bc6ead5d56d"
},
"downloads": -1,
"filename": "flask_ligand_example-0.5.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3e94226ffd997b19854a4909a8662bb",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.10",
"size": 21950,
"upload_time": "2023-05-18T20:39:48",
"upload_time_iso_8601": "2023-05-18T20:39:48.494944Z",
"url": "https://files.pythonhosted.org/packages/dc/58/c439a29f610e2db5b8341e3ff4301f8c858164f7a47087d521a5f3f994d7/flask_ligand_example-0.5.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "695a6db8b8389ea3889c9883f019349bf4c22f8b352f221309b36c5c91200a95",
"md5": "bd39ae536021731180db9c274d6dafeb",
"sha256": "c25e474d013d4036512b0d8a326887c976ca4ac1913f66b5d42d89f2e60e99c2"
},
"downloads": -1,
"filename": "flask-ligand-example-0.5.2.tar.gz",
"has_sig": false,
"md5_digest": "bd39ae536021731180db9c274d6dafeb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 53304,
"upload_time": "2023-05-18T20:39:50",
"upload_time_iso_8601": "2023-05-18T20:39:50.295828Z",
"url": "https://files.pythonhosted.org/packages/69/5a/6db8b8389ea3889c9883f019349bf4c22f8b352f221309b36c5c91200a95/flask-ligand-example-0.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-18 20:39:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cowofevil",
"github_project": "flask-ligand-example",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "flask-ligand-example"
}
JSON
