django-heckle 0.1.0__tar.gz

django_heckle-0.1.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]

django_heckle-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+        django: ["5.2", "6.0", "6.1"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --group dev
+      - run: uv pip install "django~=${{ matrix.django }}.0"
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync ruff format --check .
+      - run: uv run --no-sync pytest
+      - name: No model changes without a migration
+        run: uv run --no-sync django-admin makemigrations heckle --check --dry-run --settings=tests.settings --pythonpath=.
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - run: uvx twine check --strict dist/*

django_heckle-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+# Publishes a release to PyPI when a tag such as v0.2.0 is pushed, by trusted
+# publishing (no token is stored): on PyPI, the project's publisher is this
+# repository, this workflow (release.yml) and the environment "pypi".
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - name: The tag matches the version in pyproject.toml
+        run: test "v$(uv version --short)" = "$GITHUB_REF_NAME"
+      - run: uv build
+      - run: uv publish --trusted-publishing always

django_heckle-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[co]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

django_heckle-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (11 November 2026)
+
+The first release.
+
+- Comments on any object whose `comments_open` attribute is true, without an account, in Markdown cleaned of anything harmful.
+- Pre-moderation from a signed link in the moderators' email (which gives the commenter's email address), and in Django's and Wagtail's admins; comments by staff approved at once and marked *Author*.
+- Replies, one level deep by default (`HECKLE_MAX_DEPTH`).
+- A honeypot field, a signed timestamp, a rate limit, a signed target, optional Cloudflare Turnstile, and a limit on links.
+- Pictures for commenters drawn from a keyed hash of their email address, in four styles: Lissajous figure, atom, snowflake and emission spectrum.

django_heckle-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Christian Hill
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

django_heckle-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: django-heckle
+Version: 0.1.0
+Summary: Moderated comments for Django sites: anyone may comment, without an account; every comment waits for approval; bots are kept out.
+Project-URL: Homepage, https://github.com/xnx/django-heckle
+Project-URL: Changelog, https://github.com/xnx/django-heckle/blob/main/CHANGELOG.md
+Author: Christian Hill
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: blog,comments,django,moderation,wagtail
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Framework :: Wagtail
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: Message Boards
+Requires-Python: >=3.12
+Requires-Dist: django>=5.2
+Requires-Dist: markdown>=3.5
+Requires-Dist: nh3>=0.2.14
+Provides-Extra: wagtail
+Requires-Dist: wagtail>=7.0; extra == 'wagtail'
+Description-Content-Type: text/markdown
+
+# django-heckle
+
+The django-heckle package adds comments to the pages of a Django site. Anyone can comment, without an account; each comment waits for a moderator's approval, which is given from a link in an email. Bots and spam are kept out by a honeypot field, a signed timestamp, a rate limit and, optionally, Cloudflare Turnstile, with no tracking by a third party. Each commenter gets a picture drawn from a hash of their email address, in one of four scientific styles (a Lissajous figure, an atom, a snowflake or an emission spectrum). The name comes from *heckling*: interrupting a speaker with comments from the audience.
+
+The package needs Python 3.12 or later and Django 5.2 or later, and works with or without Wagtail. It runs on the blog of https://scipython.com.
+
+## Installation
+
+```bash
+pip install django-heckle            # or "django-heckle[wagtail]"
+```
+
+Add the app to `INSTALLED_APPS`, include its URLs and migrate:
+
+```python
+INSTALLED_APPS = [
+    ...,
+    "heckle",
+]
+```
+
+```python
+urlpatterns = [
+    ...,
+    path("comments/", include("heckle.urls")),
+]
+```
+
+The site must be able to send email (Django's `MAILERS`, or `EMAIL_BACKEND` before Django 6.1, and `DEFAULT_FROM_EMAIL`), and should have a shared cache (such as Redis or the database cache) if it runs several processes, since the rate limit is kept in the cache.
+
+## Usage
+
+Comments can be attached to an instance of any model, but only one whose `comments_open` attribute is true takes them, so a model opts in with a field such as
+
+```python
+comments_open = models.BooleanField(default=True)
+```
+
+A page's template shows its approved comments and the form for a new one with
+
+```django
+{% load heckle_tags %}
+{% heckle_comments post %}
+```
+
+and `{% heckle_count post %}` gives the number of approved comments (on an index of posts, for example). Each comment links to itself (`#comment-<id>`), and the section to `#comments`. If `comments_open` is false, the approved comments are still shown, with the form replaced by "Comments are closed."
+
+## Moderation
+
+A new comment is *pending*, and the moderators (`HECKLE_MODERATORS`, or the site's `MANAGERS`) are emailed its text, the commenter's name and email address (if given, also as the email's Reply-To), the page, and a link at which to approve it, reject it or mark it as spam. The link is signed, so it works without logging in, and it expires after `HECKLE_MODERATION_LINK_DAYS`. Opening it changes nothing until a button is pressed, which makes it safe from mail scanners that follow links.
+
+Comments are also moderated in Django's admin and, on a Wagtail site, in Wagtail's admin under *Comments*. A comment posted by a logged-in member of staff (`is_staff`) is approved at once and marked *Author*.
+
+A reply is a comment with a parent. Replies go one level deep by default (replies to comments, but not to replies); `HECKLE_MAX_DEPTH` allows more. Only an approved comment can be replied to.
+
+## Defences against spam
+
+- A *honeypot*: a field hidden from people, which bots fill in.
+- A signed timestamp: a form sent back sooner than `HECKLE_MIN_SECONDS` after it was shown, or later than `HECKLE_MAX_FORM_AGE`, is refused.
+- A rate limit of `HECKLE_RATE_LIMIT_PER_HOUR` comments per hour from each IP address (stored only as a hash).
+- A signed target: the form names the object it belongs to in a signed token, so it cannot be pointed at another.
+- [Cloudflare Turnstile](https://developers.cloudflare.com/turnstile/), if both of its keys are set.
+- A comment with more than `HECKLE_MAX_LINKS` links is kept as spam, and nobody is emailed.
+
+Comments are written in Markdown, of which only paragraphs, emphasis, links, lists, quotations and code are kept: the HTML is cleaned with [nh3](https://github.com/messense/nh3), and links are marked `rel="nofollow ugc noopener"`, which tells search engines not to credit them.
+
+Staff are exempt from the rate limit and from Turnstile. The client's IP address is taken from `REMOTE_ADDR`, so a site behind a proxy must set it from the proxy's header (with middleware or the server's configuration).
+
+## Avatars
+
+The picture beside each comment is drawn from an HMAC (a hash keyed with the site's `SECRET_KEY`) of the commenter's email address, or of their name if they gave none. The same commenter always gets the same picture but, unlike a [Gravatar](https://gravatar.com)'s hash, the key reveals nothing about the address. `HECKLE_AVATAR` chooses the style:
+
+- `"lissajous"`: a *Lissajous figure*, the curve traced by two oscillations at right angles, as on an oscilloscope;
+- `"atom"`: a nucleus with one, two or three electron orbits;
+- `"snowflake"`: a six-fold dendrite;
+- `"spectrum"`: the bright lines of an emission spectrum, a commenter's "fingerprint".
+
+It can also be the dotted path of a function that takes the key (32 bytes) and returns an SVG image, or `None` for no pictures.
+
+## Settings
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `HECKLE_MODERATORS` | `[]` | The addresses emailed about each comment awaiting approval; the site's `MANAGERS` if empty |
+| `HECKLE_FROM_EMAIL` | `""` | The address those emails are sent from; `DEFAULT_FROM_EMAIL` if empty |
+| `HECKLE_MODERATION_LINK_DAYS` | `14` | How long the link in a moderator's email works, in days |
+| `HECKLE_MAX_DEPTH` | `1` | How deep replies may go (1: replies to comments, but not to replies) |
+| `HECKLE_MAX_LENGTH` | `5000` | The longest comment, in characters |
+| `HECKLE_MAX_LINKS` | `3` | The most links a comment may have before it is kept as spam |
+| `HECKLE_RATE_LIMIT_PER_HOUR` | `5` | Comments that each IP address may post per hour |
+| `HECKLE_MIN_SECONDS` | `3` | The shortest time, in seconds, between showing a form and its being sent back |
+| `HECKLE_MAX_FORM_AGE` | `86400` | The longest time, in seconds, for which a form can be sent back |
+| `HECKLE_TURNSTILE_SITE_KEY`, `HECKLE_TURNSTILE_SECRET_KEY` | `""` | Cloudflare Turnstile's keys; it is used if both are set |
+| `HECKLE_AVATAR` | `"lissajous"` | The style of picture (see "Avatars") |
+
+## Templates and styles
+
+The comments are drawn by `heckle/comments.html`, which includes `heckle/_comment.html` for each comment and `heckle/_form.html` for the form; the note under the form about what happens to an email address is `heckle/_privacy.html`. Any of these can be overridden. The pages of the app's own (a comment that could not be posted, and moderation) extend `heckle/page.html`, which by default is a page of its own. A site overrides it to put them inside its own pages:
+
+```django
+{% extends "base.html" %}
+{% block title %}{% block heckle_title %}{% endblock %}{% endblock %}
+{% block content %}{% block heckle_content %}{% endblock %}{% endblock %}
+```
+
+The app has its own stylesheet, with no dependence on a CSS framework. Its colours follow the page's text colour and `color-scheme` (light or dark), unless the site sets these custom properties on `.heckle`: `--heckle-ink`, `--heckle-muted`, `--heckle-line`, `--heckle-surface`, `--heckle-input`, `--heckle-accent` and `--heckle-accent-on`.
+
+## Signals
+
+`heckle.signals.comment_posted` is sent with `comment` and `request` when a comment has been posted (whatever its status), and `comment_moderated` with `comment` when a moderator has changed its status from the emailed link.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+## Licence
+
+BSD 3-Clause; see `LICENSE`.

django_heckle-0.1.0/README.md

@@ -0,0 +1,122 @@
+# django-heckle
+
+The django-heckle package adds comments to the pages of a Django site. Anyone can comment, without an account; each comment waits for a moderator's approval, which is given from a link in an email. Bots and spam are kept out by a honeypot field, a signed timestamp, a rate limit and, optionally, Cloudflare Turnstile, with no tracking by a third party. Each commenter gets a picture drawn from a hash of their email address, in one of four scientific styles (a Lissajous figure, an atom, a snowflake or an emission spectrum). The name comes from *heckling*: interrupting a speaker with comments from the audience.
+
+The package needs Python 3.12 or later and Django 5.2 or later, and works with or without Wagtail. It runs on the blog of https://scipython.com.
+
+## Installation
+
+```bash
+pip install django-heckle            # or "django-heckle[wagtail]"
+```
+
+Add the app to `INSTALLED_APPS`, include its URLs and migrate:
+
+```python
+INSTALLED_APPS = [
+    ...,
+    "heckle",
+]
+```
+
+```python
+urlpatterns = [
+    ...,
+    path("comments/", include("heckle.urls")),
+]
+```
+
+The site must be able to send email (Django's `MAILERS`, or `EMAIL_BACKEND` before Django 6.1, and `DEFAULT_FROM_EMAIL`), and should have a shared cache (such as Redis or the database cache) if it runs several processes, since the rate limit is kept in the cache.
+
+## Usage
+
+Comments can be attached to an instance of any model, but only one whose `comments_open` attribute is true takes them, so a model opts in with a field such as
+
+```python
+comments_open = models.BooleanField(default=True)
+```
+
+A page's template shows its approved comments and the form for a new one with
+
+```django
+{% load heckle_tags %}
+{% heckle_comments post %}
+```
+
+and `{% heckle_count post %}` gives the number of approved comments (on an index of posts, for example). Each comment links to itself (`#comment-<id>`), and the section to `#comments`. If `comments_open` is false, the approved comments are still shown, with the form replaced by "Comments are closed."
+
+## Moderation
+
+A new comment is *pending*, and the moderators (`HECKLE_MODERATORS`, or the site's `MANAGERS`) are emailed its text, the commenter's name and email address (if given, also as the email's Reply-To), the page, and a link at which to approve it, reject it or mark it as spam. The link is signed, so it works without logging in, and it expires after `HECKLE_MODERATION_LINK_DAYS`. Opening it changes nothing until a button is pressed, which makes it safe from mail scanners that follow links.
+
+Comments are also moderated in Django's admin and, on a Wagtail site, in Wagtail's admin under *Comments*. A comment posted by a logged-in member of staff (`is_staff`) is approved at once and marked *Author*.
+
+A reply is a comment with a parent. Replies go one level deep by default (replies to comments, but not to replies); `HECKLE_MAX_DEPTH` allows more. Only an approved comment can be replied to.
+
+## Defences against spam
+
+- A *honeypot*: a field hidden from people, which bots fill in.
+- A signed timestamp: a form sent back sooner than `HECKLE_MIN_SECONDS` after it was shown, or later than `HECKLE_MAX_FORM_AGE`, is refused.
+- A rate limit of `HECKLE_RATE_LIMIT_PER_HOUR` comments per hour from each IP address (stored only as a hash).
+- A signed target: the form names the object it belongs to in a signed token, so it cannot be pointed at another.
+- [Cloudflare Turnstile](https://developers.cloudflare.com/turnstile/), if both of its keys are set.
+- A comment with more than `HECKLE_MAX_LINKS` links is kept as spam, and nobody is emailed.
+
+Comments are written in Markdown, of which only paragraphs, emphasis, links, lists, quotations and code are kept: the HTML is cleaned with [nh3](https://github.com/messense/nh3), and links are marked `rel="nofollow ugc noopener"`, which tells search engines not to credit them.
+
+Staff are exempt from the rate limit and from Turnstile. The client's IP address is taken from `REMOTE_ADDR`, so a site behind a proxy must set it from the proxy's header (with middleware or the server's configuration).
+
+## Avatars
+
+The picture beside each comment is drawn from an HMAC (a hash keyed with the site's `SECRET_KEY`) of the commenter's email address, or of their name if they gave none. The same commenter always gets the same picture but, unlike a [Gravatar](https://gravatar.com)'s hash, the key reveals nothing about the address. `HECKLE_AVATAR` chooses the style:
+
+- `"lissajous"`: a *Lissajous figure*, the curve traced by two oscillations at right angles, as on an oscilloscope;
+- `"atom"`: a nucleus with one, two or three electron orbits;
+- `"snowflake"`: a six-fold dendrite;
+- `"spectrum"`: the bright lines of an emission spectrum, a commenter's "fingerprint".
+
+It can also be the dotted path of a function that takes the key (32 bytes) and returns an SVG image, or `None` for no pictures.
+
+## Settings
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `HECKLE_MODERATORS` | `[]` | The addresses emailed about each comment awaiting approval; the site's `MANAGERS` if empty |
+| `HECKLE_FROM_EMAIL` | `""` | The address those emails are sent from; `DEFAULT_FROM_EMAIL` if empty |
+| `HECKLE_MODERATION_LINK_DAYS` | `14` | How long the link in a moderator's email works, in days |
+| `HECKLE_MAX_DEPTH` | `1` | How deep replies may go (1: replies to comments, but not to replies) |
+| `HECKLE_MAX_LENGTH` | `5000` | The longest comment, in characters |
+| `HECKLE_MAX_LINKS` | `3` | The most links a comment may have before it is kept as spam |
+| `HECKLE_RATE_LIMIT_PER_HOUR` | `5` | Comments that each IP address may post per hour |
+| `HECKLE_MIN_SECONDS` | `3` | The shortest time, in seconds, between showing a form and its being sent back |
+| `HECKLE_MAX_FORM_AGE` | `86400` | The longest time, in seconds, for which a form can be sent back |
+| `HECKLE_TURNSTILE_SITE_KEY`, `HECKLE_TURNSTILE_SECRET_KEY` | `""` | Cloudflare Turnstile's keys; it is used if both are set |
+| `HECKLE_AVATAR` | `"lissajous"` | The style of picture (see "Avatars") |
+
+## Templates and styles
+
+The comments are drawn by `heckle/comments.html`, which includes `heckle/_comment.html` for each comment and `heckle/_form.html` for the form; the note under the form about what happens to an email address is `heckle/_privacy.html`. Any of these can be overridden. The pages of the app's own (a comment that could not be posted, and moderation) extend `heckle/page.html`, which by default is a page of its own. A site overrides it to put them inside its own pages:
+
+```django
+{% extends "base.html" %}
+{% block title %}{% block heckle_title %}{% endblock %}{% endblock %}
+{% block content %}{% block heckle_content %}{% endblock %}{% endblock %}
+```
+
+The app has its own stylesheet, with no dependence on a CSS framework. Its colours follow the page's text colour and `color-scheme` (light or dark), unless the site sets these custom properties on `.heckle`: `--heckle-ink`, `--heckle-muted`, `--heckle-line`, `--heckle-surface`, `--heckle-input`, `--heckle-accent` and `--heckle-accent-on`.
+
+## Signals
+
+`heckle.signals.comment_posted` is sent with `comment` and `request` when a comment has been posted (whatever its status), and `comment_moderated` with `comment` when a moderator has changed its status from the emailed link.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+## Licence
+
+BSD 3-Clause; see `LICENSE`.

django_heckle-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "django-heckle"
+version = "0.1.0"
+description = "Moderated comments for Django sites: anyone may comment, without an account; every comment waits for approval; bots are kept out."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "Christian Hill" }]
+requires-python = ">=3.12"
+keywords = ["django", "wagtail", "comments", "moderation", "blog"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
+    "Framework :: Wagtail",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content :: Message Boards",
+]
+dependencies = [
+    "django>=5.2",
+    "markdown>=3.5",
+    "nh3>=0.2.14",
+]
+
+[project.optional-dependencies]
+wagtail = ["wagtail>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/xnx/django-heckle"
+Changelog = "https://github.com/xnx/django-heckle/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["pytest", "pytest-django", "ruff"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/heckle"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = ["."]
+testpaths = ["tests"]
+# A warning raised in the package's own code, such as of a deprecation, fails.
+filterwarnings = ["error:::heckle"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+src = ["src", "."]
+extend-exclude = ["*/migrations/*"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "DJ"]
+ignore = ["E501"]  # line length is left to `ruff format`

django_heckle-0.1.0/src/heckle/__init__.py

@@ -0,0 +1 @@
+"""Moderated comments for Django sites."""

django_heckle-0.1.0/src/heckle/admin.py

@@ -0,0 +1,39 @@
+"""Moderation in Django's admin. (On a Wagtail site, wagtail_hooks.py adds comments
+to Wagtail's admin too.)"""
+
+from django.contrib import admin
+
+from .models import Comment
+
+
+@admin.register(Comment)
+class CommentAdmin(admin.ModelAdmin):
+    list_display = ["__str__", "name", "email", "target", "status", "created"]
+    list_filter = ["status"]
+    search_fields = ["name", "email", "body"]
+    readonly_fields = [
+        "content_type",
+        "object_pk",
+        "parent",
+        "user",
+        "by_staff",
+        "created",
+    ]
+    actions = ["approve", "reject", "mark_as_spam"]
+
+    def _set(self, queryset, status):
+        for comment in queryset:
+            comment.status = status
+            comment.save(update_fields=["status"])
+
+    @admin.action(description="Approve")
+    def approve(self, request, queryset):
+        self._set(queryset, Comment.Status.APPROVED)
+
+    @admin.action(description="Reject")
+    def reject(self, request, queryset):
+        self._set(queryset, Comment.Status.REJECTED)
+
+    @admin.action(description="Mark as spam")
+    def mark_as_spam(self, request, queryset):
+        self._set(queryset, Comment.Status.SPAM)

django_heckle-0.1.0/src/heckle/antispam.py

@@ -0,0 +1,68 @@
+"""Keeping bots out: a signed timestamp, a limit per visitor, and Cloudflare
+Turnstile. (The honeypot is a form field: see forms.py.)"""
+
+import hashlib
+import json
+import time
+import urllib.parse
+import urllib.request
+
+from django.core import signing
+from django.core.cache import cache
+
+from .conf import setting
+
+TURNSTILE_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify"
+
+
+def client_ip(request):
+    """The visitor's address: the first in X-Forwarded-For (set by the proxy in
+    front of the site), else the connection's."""
+    forwarded = request.META.get("HTTP_X_FORWARDED_FOR", "")
+    return forwarded.split(",")[0].strip() or request.META.get("REMOTE_ADDR", "")
+
+
+def issued():
+    """A signed timestamp for a new form."""
+    return signing.dumps(time.time(), salt="heckle.issued")
+
+
+def form_age(token):
+    """The seconds since the form was issued, or None if the token is forged or
+    too old."""
+    try:
+        when = signing.loads(
+            token, salt="heckle.issued", max_age=setting("MAX_FORM_AGE")
+        )
+    except signing.BadSignature:
+        return None
+    return time.time() - float(when)
+
+
+def rate_limited(ip):
+    """Counts this comment from the address; True once over the limit for the
+    hour. The address itself is not kept, only a hash of it, in the cache."""
+    key = "heckle:" + hashlib.sha256(ip.encode()).hexdigest()
+    cache.add(key, 0, timeout=60 * 60)
+    try:
+        count = cache.incr(key)
+    except ValueError:
+        count = 1
+    return count > setting("RATE_LIMIT_PER_HOUR")
+
+
+def turnstile_enabled():
+    return bool(setting("TURNSTILE_SITE_KEY") and setting("TURNSTILE_SECRET_KEY"))
+
+
+def turnstile_passed(token, ip):
+    """Whether Cloudflare accepts the widget's token. If Cloudflare cannot be
+    reached, the comment is refused (the visitor can try again)."""
+    data = urllib.parse.urlencode(
+        {"secret": setting("TURNSTILE_SECRET_KEY"), "response": token, "remoteip": ip}
+    ).encode()
+    try:
+        with urllib.request.urlopen(TURNSTILE_URL, data=data, timeout=5) as response:
+            return bool(json.load(response).get("success"))
+    except (OSError, ValueError):
+        return False

django_heckle-0.1.0/src/heckle/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class HeckleConfig(AppConfig):
+    name = "heckle"
+    verbose_name = "Comments"
+    # Set here, so that the app's migrations do not depend on the site's setting.
+    default_auto_field = "django.db.models.BigAutoField"