Merge branch 'main' into release/2

azure-pipelines.yml

@@ -71,11 +71,10 @@ stages:
         testResultsFiles: '**/test-*.xml'
         testRunTitle: 'Publish test results for Python $(python.version)'
 
-    - task: PublishCodeCoverageResults@1
+    - task: PublishCodeCoverageResults@2
       displayName: 'Publish code coverage report'
       condition: succeededOrFailed()
       inputs:
-        codeCoverageTool: Cobertura
         summaryFileLocation: '$(System.DefaultWorkingDirectory)/coverage.xml'
 
 
@@ -93,7 +92,7 @@ stages:
     - task: UsePythonVersion@0
       displayName: 'Use Python version'
       inputs:
-        versionSpec: '3.11'
+        versionSpec: '3.12'
         architecture: 'x64'
 
     - script: python -m pip install -r requirements-dev.txt
@@ -102,14 +101,11 @@ stages:
     - script: codespell ./docs/ ./wagtailcache/
       displayName: 'CR-QC: Spell check'
 
-    - script: flake8 .
-      displayName: 'CR-QC: Static analysis (flake8)'
+    - script: ruff check .
+      displayName: 'CR-QC: Static analysis (ruff)'
 
-    - script: isort --check .
-      displayName: 'CR-QC: Format check (isort)'
-
-    - script: black --check .
-      displayName: 'CR-QC: Format check (black)'
+    - script: ruff format --check .
+      displayName: 'CR-QC: Format check'
 
     - script: mypy ./wagtailcache/
       displayName: 'CR-QC: Type check (mypy)'
@@ -144,7 +140,7 @@ stages:
     - task: UsePythonVersion@0
       displayName: 'Use Python version'
       inputs:
-        versionSpec: '3.11'
+        versionSpec: '3.12'
         architecture: 'x64'
 
     - script: python -m pip install -r requirements-dev.txt

ci/compare-codecov.ps1

@@ -68,7 +68,8 @@ foreach ($cov in $mainCoverageJson.coverageData.coverageStats) {
 
 
 # Get current code coverage from coverage.xml file.
-$coveragePath = Get-ChildItem -Recurse -Filter "coverage.xml" $wd
+# Use the first one, if there are multiple i.e. from multiple runs.
+$coveragePath = (Get-ChildItem -Recurse -Filter "coverage.xml" $wd)[0]
 if (Test-Path -Path $coveragePath) {
     [xml]$BranchXML = Get-Content $coveragePath
 }
@@ -84,7 +85,7 @@ $branchlinerate = [math]::Round([decimal]$BranchXML.coverage.'line-rate' * 100,
 
 
 Write-Output ""
-Write-Output "Dev branch coverage rate:   $mainlinerate%"
+Write-Output "Main branch coverage rate:  $mainlinerate%"
 Write-Output "This branch coverage rate:  $branchlinerate%"
 
 if ($mainlinerate -eq 0) {

docs/contributing.rst

@@ -58,4 +58,4 @@ the ``dist/`` directory.
 
 .. code-block:: console
 
-    $ python setup.py sdist bdist_wheel
+    $ python -m build

docs/getting_started/cache_control.rst

@@ -0,0 +1,185 @@
+Advanced Cache Control
+======================
+
+
+Page-specific cache control
+---------------------------
+
+The ``WagtailCacheMixin`` also gives you the option to add a
+custom Cache-Control header via ``cache_control``, which can be a dynamic
+function or a string:
+
+.. code-block:: python
+
+    from wagtailcache.cache import WagtailCacheMixin
+
+    class MyPage(WagtailCacheMixin, Page):
+
+        cache_control = 'no-cache'
+
+        ...
+
+
+Setting this to contain ``no-cache`` or ``private`` will tell wagtail-cache
+**not** to cache this page. You could also set it to a custom value such as
+"public, max-age=3600". It can also be a function:
+
+.. code-block:: python
+
+    from wagtailcache.cache import WagtailCacheMixin
+
+    class MyPage(WagtailCacheMixin, Page):
+
+        def cache_control(self):
+            return 'no-cache'
+
+        ...
+
+
+Not caching views or URLs
+-------------------------
+
+Across the entire Django site, Wagtail Cache will never cache a response that has a
+``Cache-Control`` header containing ``no-cache`` or ``private``. Adding this
+header to any response will cause it to be skipped.
+
+To explicitly not cache certain views or URL patterns, you could also wrap them
+with the ``nocache_page`` decorator, which adds the ``Cache-Control: no-cache``
+header to all responses of that view or URL pattern. To use with a view:
+
+.. code-block:: python
+
+    from wagtailcache.cache import nocache_page
+
+    @nocache_page
+    def myview(request):
+        ...
+
+Or on a URL pattern:
+
+.. code-block:: python
+
+    from wagtailcache.cache import nocache_page
+
+    ...
+
+    url(r'^url/pattern/$', nocache_page(viewname), name='viewname'),
+
+    ...
+
+When using the Wagtail Cache middleware, the middleware will detect CSRF tokens and will only cache
+those responses on a per-cookie basis. So Wagtail Cache should work well with CSRF tokens 🙂.
+But if you still experience issues with CSRF tokens, use the mixin, the ``nocache_page`` decorator,
+or set the ``Cache-Control`` header to ``no-cache`` on the response to guarantee that it will
+never be cached. If you are using the ``cache_page`` decorator instead of the middleware, you
+**must** use the mixin or set the ``Cache-Control`` header on responses with CSRF tokens to avoid
+getting 403 forbidden errors.
+
+
+Using a separate cache backend
+------------------------------
+
+For complex sites, it may be desirable to use a separate cache backend only for
+the page cache, so that purging the page cache will not affect other caches:
+
+.. code-block:: python
+
+    WAGTAIL_CACHE_BACKEND = 'pagecache'
+
+    CACHES = {
+        'default': {
+            ...
+        },
+        'pagecache': {
+            ...
+        }
+    }
+
+
+Only cache specific views
+-------------------------
+
+The wagtail-cache middleware will attempt to cache ALL responses that appear to be cacheable
+(meaning the response does not contain a 'no-cache'/'private' Cache-Control header, the request method
+is GET or HEAD, the response status code is 200, 301, 302, 404, the response did not set a cookie,
+the page is not in preview mode, a user is not logged in, and many other requirements).
+
+To only cache specific views, remove the middleware and use the ``cache_page`` decorator on views or URLs.
+
+Alternatively, to continue using the middleware but explicitly not cache certain views or URLs, wrap those
+views or URLs with the ``nocache_page`` decorator.
+
+Note that when using the ``cache_page`` decorator, it is not possible to cache Wagtail page 404s or redirects. Only the
+middleware is able to cache those responses.
+
+Caching wagtail pages only
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most likely you will want this on all of your wagtail pages, so you will have to
+replace the inclusion of ``wagtail_urls`` in your project's ``urls.py``. You
+will need to change from this:
+
+.. code-block:: python
+
+    from django.conf.urls import url
+
+    url(r'', include(wagtail_urls)),
+
+To this:
+
+.. code-block:: python
+
+    from django.conf.urls import url
+
+    from django.contrib.auth import views as auth_views
+    from wagtail.urls import serve_pattern, WAGTAIL_FRONTEND_LOGIN_TEMPLATE
+    from wagtail import views as wagtail_views
+    from wagtailcache.cache import cache_page
+
+    # Copied from wagtail.urls:
+    url(r'^_util/authenticate_with_password/(\d+)/(\d+)/$', wagtail_views.authenticate_with_password,
+        name='wagtailcore_authenticate_with_password'),
+    url(r'^_util/login/$', auth_views.LoginView.as_view(template_name=WAGTAIL_FRONTEND_LOGIN_TEMPLATE),
+        name='wagtailcore_login'),
+
+    # Wrap the serve function with wagtail-cache
+    url(serve_pattern, cache_page(wagtail_views.serve), name='wagtail_serve'),
+
+Caching specific wagtail page models only
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also use the decorator on specific wagtail pages. It is helpful in
+Wagtail sites where the requirement is not to cache all pages:
+
+.. code-block:: python
+
+    from django.utils.decorators import method_decorator
+    from wagtailcache.cache import cache_page, WagtailCacheMixin
+
+    @method_decorator(cache_page, name='serve')
+    class MyPage(WagtailCacheMixin, Page):
+        ...
+
+Caching views
+~~~~~~~~~~~~~
+
+You can also use the decorator on views:
+
+.. code-block:: python
+
+    from wagtailcache.cache import cache_page
+
+    @cache_page
+    def myview(request):
+        ...
+
+To use it on class-based views:
+
+.. code-block:: python
+
+    from django.utils.decorators import method_decorator
+    from wagtailcache.cache import cache_page
+
+    @method_decorator(cache_page, name='dispatch')
+    class MyView(TemplateView):
+        ...

docs/getting_started/index.rst

@@ -6,6 +6,7 @@ Getting Started
 
     install
     usage
+    cache_control
     hooks
     django_settings
     supported_backends