pavics/magpie repository overview

.. explicit references must be used in this file (not references.rst) to ensure they are directly rendered on Github

⁠====================================== Magpie: A RestFul AuthN/AuthZ service

Magpie (the smart-bird) a very smart bird who knows everything about you.

Magpie is service for AuthN/AuthZ accessible via a REST API_ implemented with the Pyramid_ web framework. It allows you to manage User/Group/Service/Resource/Permission with a PostgreSQL_ database. Behind the scene, it uses Ziggurat-Foundations_ and Authomatic_.

.. start-badges

.. list-table:: :header-rows: 0 :stub-columns: 1 :widths: 10,90

* - dependencies
  - | |py_ver_recommend| |py_ver_support| |py_ver_legacy| |dependencies|
* - tests status
  - | |github_latest| |github_tagged| |coverage| |codacy|
* - docker status
  - | |docker_build_mode| |docker_build_status| |docker_latest_tag| |docker_semver_tag|
* - releases
  - | |version| |commits-since|

.. list-table:: :header-rows: 1 :widths: 15,85

* - Python Versions
  - Description
* - *Legacy*
  - Older versions could still work, but maintenance is dropped.
* - *Supported*
  - Tested by the CI and maintained for backward compatibility.
* - *Recommended*
  - Preferred minimal version to use for latest security updates and performance enhancements.

.. |py_ver_legacy| image:: https://img.shields.io/badge/python%20%28legacy%29-3.5%20%2D%2D%203.9-orange.svg⁠ :alt: Python 3.5+ supported (legacy) :target: https://www.python.org/getit⁠

.. |py_ver_support| image:: https://img.shields.io/badge/python%20%28supported%29-3.10%2B-yellow.svg⁠ :alt: Python 3.10+ supported :target: https://www.python.org/getit⁠

.. |py_ver_recommend| image:: https://img.shields.io/badge/python%20%28recommended%29-3.11%2B-blue.svg⁠ :alt: Python 3.11+ recommended :target: https://www.python.org/getit⁠

.. |commits-since| image:: https://img.shields.io/github/commits-since/Ouranosinc/Magpie/5.1.1.svg⁠ :alt: Commits since latest release :target: https://github.com/Ouranosinc/Magpie/compare/5.1.1...master⁠

.. |version| image:: https://img.shields.io/badge/tag-5.1.1-blue.svg?style=flat⁠ :alt: Latest Tag :target: https://github.com/Ouranosinc/Magpie/tree/5.1.1⁠

.. |dependencies| image:: https://pyup.io/repos/github/Ouranosinc/Magpie/shield.svg⁠ :alt: Dependencies Status :target: https://pyup.io/account/repos/github/Ouranosinc/Magpie/⁠

.. |github_latest| image:: https://img.shields.io/github/actions/workflow/status/Ouranosinc/Magpie/tests.yml?label=master&branch=master⁠ :alt: Github Actions CI Build Status (master branch) :target: https://github.com/Ouranosinc/Magpie/actions?query=workflow%3ATests+branch%3Amaster⁠

.. |github_tagged| image:: https://img.shields.io/github/actions/workflow/status/Ouranosinc/Magpie/tests.yml?label=5.1.1&branch=5.1.1⁠ :alt: Github Actions CI Build Status (latest tag) :target: https://github.com/Ouranosinc/Magpie/actions?query=workflow%3ATests+branch%3A5.1.1⁠

.. |readthedocs| image:: https://img.shields.io/readthedocs/pavics-magpie⁠ :alt: Readthedocs Build Status (master branch) :target: readthedocs_

.. |coverage| image:: https://img.shields.io/codecov/c/gh/Ouranosinc/Magpie.svg?label=coverage⁠ :alt: Travis-CI CodeCov Coverage :target: https://codecov.io/gh/Ouranosinc/Magpie⁠

.. |codacy| image:: https://app.codacy.com/project/badge/Grade/0dd500de5e3c4bdf84093eaa64cf9a81⁠ :alt: Codacy Badge :target: https://app.codacy.com/gh/Ouranosinc/Magpie/dashboard⁠

.. |docker_build_mode| image:: https://img.shields.io/docker/automated/pavics/magpie.svg?label=build⁠ :alt: Docker Build Status (latest tag) :target: https://hub.docker.com/r/pavics/magpie/builds⁠

.. |docker_build_status| image:: https://img.shields.io/docker/cloud/build/pavics/magpie.svg?label=status⁠ :alt: Docker Build Status (latest tag) :target: https://hub.docker.com/r/pavics/magpie/builds⁠

.. |docker_latest_tag| image:: https://img.shields.io/docker/v/pavics/magpie?label=last%20build⁠ :alt: Docker Latest Tag :target: https://hub.docker.com/r/pavics/magpie/tags?page=1&ordering=last_updated&name=latest⁠

.. |docker_semver_tag| image:: https://img.shields.io/docker/v/pavics/magpie?label=version&sort=semver⁠ :alt: Docker Version Tag :target: https://hub.docker.com/r/pavics/magpie/tags?page=1&ordering=last_updated&name=5.1.1⁠

.. end-badges

⁠Documentation

The REST API documentation is auto-generated and served under {MAGPIE_URL}/api/ using Swagger-UI with tag latest.

| More ample details about installation, configuration and usage are provided on |readme_readthedocs|. | These are generated from corresponding information provided in |github_docs| directory.

⁠Configuration and Usage

| Multiple configuration options exist for Magpie application. | Please refer to |readme_configuration|_ section for details. | See |readme_usage|_ section for details.

⁠Change History

Addressed features, changes and bug fixes per version tag are available in |readme_changes|_.

⁠Docker Images

Following most recent variants are available:

.. |br| raw:: html

<br>

.. list-table:: :header-rows: 1

* - Magpie
  - Twitcher |br|
    (with integrated ``MagpieAdapter``)
* - ``pavics/magpie:5.1.1``
  - ``pavics/twitcher:magpie-5.1.1``
* - ``pavics/magpie:latest``
  - ``pavics/twitcher:magpie-latest``

Notes:

• Older tags the are also available: Magpie Docker Images_
• Twitcher_ image with integrated MagpieAdapter are only available for Magpie >=1.0.0

.. these reference must be left direct (not included with 'docs/references.rst') to allow pretty rendering on Github .. |readme_changes| replace:: CHANGES .. _readme_changes: CHANGES.rst .. |readme_configuration| replace:: Configuration .. _readme_configuration: docs/configuration.rst .. |readme_usage| replace:: Usage .. _readme_usage: docs/usage.rst .. |readme_readthedocs| replace:: ReadTheDocs .. _readme_readthedocs: https://pavics-magpie.readthedocs.io⁠ .. |github_docs| replace:: docs .. _github_docs: https://github.com/Ouranosinc/Magpie/tree/master/docs⁠

.. REST API redoc reference is auto-generated by sphinx from magpie cornice-swagger definitions .. _REST API: https://pavics-magpie.readthedocs.io/en/latest/api.html⁠ .. _Authomatic: https://authomatic.github.io/authomatic/⁠ .. _PostgreSQL: https://www.postgresql.org/⁠ .. _Pyramid: https://docs.pylonsproject.org/projects/pyramid/⁠ .. _Ziggurat-Foundations: https://github.com/ergo/ziggurat_foundations⁠ .. _Magpie Docker Images: https://hub.docker.com/r/pavics/magpie/tags⁠ .. _Twitcher: https://github.com/bird-house/twitcher⁠