Merge branch 'master' into stable/1.0.x

.bumpversion.cfg

@@ -1,7 +1,7 @@
 [bumpversion]
 commit = False
 tag = False
-current_version = 1.0.52
+current_version = 1.5.6
 
 [bumpversion:file:setup.cfg]
 

.travis.yml

@@ -1,19 +1,27 @@
 language: python
 cache: pip
 
-sudo: false
+services:
+  - postgresql
 
 python:
   - "3.6"
+  - "3.7"
 
 env:
-  - DJANGO=2.2
+  global:
+    - PGUSER=postgres
+    - PGDATABASE=postgres
+    - PGPASSWORD=
+  matrix:
+    - DJANGO=2.2
 
 matrix:
   fast_finish: true
   include:
     - { python: "3.6", env: TOXENV=isort }
     - { python: "3.6", env: TOXENV=docs }
+    - { python: "3.6", env: TOXENV=black }
 
 install:
   - pip install tox-travis

CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to vng-api-common
+
+Hi! First of all, thank you for your interest in contributing to this project,
+you can do this in a number of ways :-)
+
+* [Reporting issues](#reporting-issues)
+* [Submitting pull requests](#submitting-pull-requests)
+* [Code and commit style](#code-and-commit-style)
+
+## Versioning
+
+vng-api-common is used as shared library in various downstream projects, which
+each have their own versions (currently they are all in 1.0.0 release
+candidate) status.
+
+The versioning of vng-api-common is semantic and follows the downstream
+versioning. This means that the current latest version can accept new features,
+i.e. things that make the API look different, in non-breaking ways, such as
+adding API resource field attributes.
+
+Current branches/versions:
+
+* `master` is the latest version, currently tracking `1.1.x` versions.
+* `stable/1.0.x` is input for the 1.0.0 release candidate versions.
+
+## Reporting issues
+
+If you're running into a bug or desired feature, you can
+[submit an issue](https://github.com/VNG-Realisatie/vng-api-common/issues/new).
+
+**Feature requests**
+
+When you're submitting a feature request, please use the label *enhancement*.
+
+**Submitting a bug report**
+
+When submitting a bug report, please state:
+
+1. Which API this occurred in (ZRC, DRC, ...)
+2. What the expected behaviour was
+3. What the observed behaviour is
+
+If the issue affects older versions, please apply those tags (e.g. *1.0.x*)
+
+## Submitting pull requests
+
+Code contributions are valued, but we request some quality control!
+
+**Tests**
+
+Please make sure the tests pass. You can run the test suite by running `tox`.
+While developing, you can also run the tests using `pytest` in the root of the
+project. See the Tox and Pytest documentation for advanced usage.
+
+You can also refer to the `.travis.yml` setup to see which system requirements
+are relevant, such as a working Postgres database.
+
+Bugfixes require a test that shows the errant behaviour and proves the bug was
+fixed.
+
+New features should be accompanied by tests that show the interface/desired
+behaviour.
+
+## Code and commit style
+
+**Imports**
+
+We sort imports using [isort](https://pypi.org/project/isort/). The tests
+have an `isort` check, which you can run using `tox -e isort`.
+
+**Code formatting**
+
+Python code should be [black](https://github.com/psf/black) formatted, this
+leaves no discussion about formatting.
+
+**Commit messages**
+
+Please use meaningful commit messages, and rebase them if you can. For example,
+we'd expect a commit for adding a regression test and a second commit with
+the fix.
+
+We encourage use of [gitmoji](https://gitmoji.carloscuesta.me/) to quickly
+identify the type of change in the commit. This also helps you keep your
+commits atomic - if multiple gitmoji are applicable, perhaps your commit should
+be split in multiple atomic commits.
+
+Where applicable, please refer to the reported issue.
+
+Commit message template:
+
+```
+:bug: Fixes #123 -- fixed URL resolution
+
+<elaborate description describing what happened in the commit>
+```

README.rst

@@ -2,7 +2,7 @@
 VNG-API-common - Tooling voor RESTful APIs
 ==========================================
 
-|build-status| |coverage| |docs|
+|build-status| |coverage| |docs| |black|
 
 |python-versions| |django-versions| |pypi-version|
 
@@ -84,4 +84,7 @@ Features
 .. |pypi-version| image:: https://img.shields.io/pypi/v/vng-api-common.svg
     :target: https://pypi.org/project/vng-api-common/
 
+.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+
 .. _documentatie: https://vng-api-common.readthedocs.io/en/latest/?badge=latest

docs/conf.py

@@ -23,6 +23,7 @@
 
 settings.configure(
     INSTALLED_APPS=[
+        "django.contrib.sites",
         "rest_framework",
         "django_filters",
         "vng_api_common",

docs/ref/http_caching.rst

@@ -0,0 +1,75 @@
+============
+HTTP Caching
+============
+
+HTTP caching is a mechanism that shines in RESTful APIs. A ``GET`` or ``HEAD``
+response on a detail resource can be augmented with the ``ETag`` header, which
+essentially is a "version" of a resource. Every modification of the resource
+leads to a new version.
+
+This can be leveraged in combination with the ``If-None-Match`` request header,
+kwown as conditional requests.
+
+The client includes the ``ETag`` value(s) in this header, and if the current
+version of the resource has the same ``ETag`` value, then the server replies
+with an ``HTTP 304`` response, indicating that the content has not changed.
+
+This allows consumers to send less data over the wire without having to
+perform extra requests if they keep resources in their own cache.
+
+See the `ETag on MDN`_ documentation for the full specification.
+
+Implementing conditional requests
+=================================
+
+Two actions are needed to implement this in API implementations:
+
+Add the model mixin to save the ETag value
+------------------------------------------
+
+This enables us to perform fast lookups and avoid calculating the ETag value
+over and over again. It happens automatically on ``save`` of a model instance.
+
+.. code-block:: python
+    :linenos:
+
+    from vng_api_common.caching import ETagMixin
+
+
+    class MyModel(ETagMixin, models.Model):
+        pass
+
+.. note:: If you're doing ``queryset.update`` or ``bulk_create`` operations,
+   you need to take care of setting/calculating the value yourself.
+
+Decorate the viewset
+--------------------
+
+Decorating the viewset retrieve ensures that the ``ETag`` header is set,
+the conditional request handling (HTTP 200 vs. HTTP 304) is performed and the
+extra methods/headers show up in the generated API schema.
+
+.. code-block:: python
+    :linenos:
+
+    from rest_framework import viewsets
+    from vng_api_common.caching import conditional_retrieve
+
+    from .models import MyModel
+    from .serializers import MyModelSerializer
+
+
+    @conditional_retrieve()
+    class MyModelViewSet(viewsets.ReadOnlyViewSet):
+        queryset = MyModel.objects.all()
+        serializer_class = MyModelSerializer
+
+
+Public API
+==========
+
+.. automodule:: vng_api_common.caching
+    :members:
+
+
+.. _ETag on MDN: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag

docs/ref/index.rst

@@ -13,6 +13,7 @@ Modules reference
    exceptions
    middleware
    viewset-mixins
+   http_caching
    database
    geo
    polymorphism