Metadata-Version: 2.1
Name: zgw-consumers
Version: 0.26.2
Summary: Configuration for service (OpenAPI 3 or other) consumers
Home-page: https://github.com/maykinmedia/zgw-consumers
Author: Maykin Media
Author-email: support@maykinmedia.nl
License: MIT
Project-URL: Documentation, https://zgw-consumers.readthedocs.io/en/latest/
Project-URL: Changelog, https://github.com/maykinmedia/zgw-consumers/blob/main/changelog.rst
Project-URL: Bug Tracker, https://github.com/maykinmedia/zgw-consumers/issues
Project-URL: Source Code, https://github.com/maykinmedia/zgw-consumers
Keywords: ZGW,Common Ground,VNG,API,OpenAPI,OAS,mTLS
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: db
Provides-Extra: drf
Provides-Extra: tests
Provides-Extra: pep8
Provides-Extra: coverage
Provides-Extra: docs
Provides-Extra: release
License-File: LICENSE

.. zgw_consumers documentation master file, created by startproject.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to ZGW Consumers' documentation!
========================================

:Version: 0.26.2
:Source: https://github.com/maykinmedia/zgw-consumers
:Keywords: OpenAPI, Zaakgericht Werken, Common Ground, NLX
:PythonVersion: 3.7, 3.8, 3.9

|build-status| |coverage| |linting| |docs|

|python-versions| |django-versions| |pypi-version|

Manage your external API's to consume.

.. contents::

.. section-numbering::

Features
========

* Store services with their configuration in the database
* Integrate with OpenAPI 3.0 specifications
* NLX support
* Declare data/domain objects as modern Python dataclasses

Installation
============

Requirements
------------

* Python 3.6 or newer
* setuptools 30.3.0 or newer
* Django 2.2 or newer


Install
-------

1. Install from PyPI

.. code-block:: bash

    pip install zgw-consumers

2. Add ``zgw_consumers`` to the ``INSTALLED_APPS`` setting.

3. Optionally override ``ZGW_CONSUMERS_CLIENT_CLASS`` to a custom client class.

4. Optionally specify ``ZGW_CONSUMERS_OAS_CACHE`` to point to a separate django cache.
   Defaults to ``django.core.cache.DEFAULT_CACHE_ALIAS``, which is ``default`` in
   practice. For performance reasons we highly recommend to use a real cache backend
   like Redis or Memcache.


Usage
=====

In the Django admin, you can create ``Service`` instances to define your external APIs.

**Client**

To get a client for a given resource, you can use:

.. code-block:: python

    from zgw_consumers.models import Service

    client = Service.get_client(some_url)

Or, to just retrieve the auth header(s):

.. code-block:: python

    from zgw_consumers.models import Service

    auth = Service.get_auth_header(some_url)

**Data model**

Use ``zgw_consumers.api_models.base.factory`` to turn raw JSON responses into instances
of domain models:

.. code-block:: python

    from zgw_consumers.api_models.base import factory
    from zgw_consumers.api_models.zaken import Zaak

    results = client.list("zaak")["results"]

    return factory(Zaak, results)


It works for both collections and scalar values, and takes care of the camel-case to
snake case conversion.


You can also define your own data models, take a look at the ``zgw_consumers.api_models``
package for inspiration.

.. |build-status| image:: https://github.com/maykinmedia/zgw-consumers/workflows/Run%20CI/badge.svg
    :target: https://github.com/maykinmedia/zgw-consumers/actions?query=workflow%3A%22Run+CI%22
    :alt: Run CI

.. |linting| image:: https://github.com/maykinmedia/zgw-consumers/workflows/Code%20quality%20checks/badge.svg
    :target: https://github.com/maykinmedia/zgw-consumers/actions?query=workflow%3A%22Code+quality+checks%22
    :alt: Code linting

.. |coverage| image:: https://codecov.io/gh/maykinmedia/zgw-consumers/branch/main/graph/badge.svg
    :target: https://codecov.io/gh/maykinmedia/zgw-consumers
    :alt: Coverage status

.. |docs| image:: https://readthedocs.org/projects/zgw-consumers/badge/?version=latest
    :target: https://zgw-consumers.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. |python-versions| image:: https://img.shields.io/pypi/pyversions/zgw_consumers.svg

.. |django-versions| image:: https://img.shields.io/pypi/djversions/zgw_consumers.svg

.. |pypi-version| image:: https://img.shields.io/pypi/v/zgw_consumers.svg
    :target: https://pypi.org/project/zgw_consumers/
