commentail 0.1.0__tar.gz

commentail-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+Initial Commentail release candidate for Wagtail 7.4 LTS.
+
+- Template-based Page integration and adapters for ordinary Django models.
+- Site/Page configuration, moderation queue, group permissions and CSV rules.
+- Verified guests, replaceable CAPTCHA and Site-scoped rate limits.
+- Threaded replies, inline author revisions and protected guest actions.
+- Database email outbox, direct-reply notifications and unsubscribe.
+- Schema.org Comment microdata and JSON-LD, with per-site output selection.
+- Theme inheritance, template overrides, Python hooks and English/Russian UI.
+
+See [release notes](docs/releases/0.1.0.md) and [setup guides](docs/wiki/Home.md).

commentail-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Commentail contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

commentail-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+recursive-include tests *.py *.html *.js
+recursive-include example *.py *.html *.md
+include requirements-test.txt
+recursive-include tools *.py
+include CHANGELOG.md
+recursive-include docs/wiki *.md
+recursive-include docs/releases *.md
+include docs/assets/commentail-preview.png
+include docs/assets/support-qr.png

commentail-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: commentail
+Version: 0.1.0
+Summary: Self-hosted Wagtail comments with moderation, verified guests and threaded replies
+License-Expression: MIT
+Project-URL: Source, https://github.com/hardcodd/Commentail
+Project-URL: Issues, https://github.com/hardcodd/Commentail/issues
+Project-URL: Documentation, https://github.com/hardcodd/Commentail/wiki
+Project-URL: Changelog, https://github.com/hardcodd/Commentail/blob/main/CHANGELOG.md
+Project-URL: Funding, https://pay.cloudtips.ru/p/f92ee349
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Wagtail
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django<5.3,>=5.2
+Requires-Dist: Wagtail<7.5,>=7.4.3
+Requires-Dist: regex>=2026.9.29
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.3.6; extra == "postgres"
+Dynamic: license-file
+
+<div align="center">
+
+# Commentail
+
+**Self-hosted comments for Wagtail CMS**
+
+Moderated discussions, verified guests and inline replies — styled by your site.
+
+[![Tests and distributions](https://github.com/hardcodd/Commentail/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/hardcodd/Commentail/actions/workflows/tests.yml)
+
+[Get started](#quick-start) · [Documentation](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Home.md) · [Wiki](https://github.com/hardcodd/Commentail/wiki) · [Support](#support-commentail)
+
+<img src="https://raw.githubusercontent.com/hardcodd/Commentail/main/docs/assets/commentail-preview.png" alt="Commentail — a blue bird perched on a comment bubble" width="100%">
+
+</div>
+
+Commentail is a Django comments library built for **Wagtail 7.4 LTS**. Add a
+Django template tag to an article, moderate discussions inside Wagtail, and keep
+content, accounts and email delivery in your own application.
+
+The widget inherits your site's typography and colors. CSS custom properties,
+replaceable templates and Python callbacks let you adapt it without a frontend
+framework or an external comments platform.
+
+> Wagtail 8.0 is not supported by 0.1.0.
+
+## Why Commentail?
+
+| For readers | For editors | For developers |
+| --- | --- | --- |
+| Guest email verification or existing site accounts | Four moderation policies | One template tag for Pages and registered objects |
+| Inline replies and author editing | Site defaults and Page overrides | CSS properties and template overrides |
+| Direct-reply email with unsubscribe | Word/phrase rules and CSV import/export | Replaceable avatars, names and CAPTCHA |
+| Responsive layout and plain HTML fallbacks | Site-scoped group permissions | Database outbox; no Redis/Celery requirement |
+
+Comments are plain text with an adjustable 5000-character default. Optional
+clickable HTTP(S) links use safe attributes. Replies can address any visible
+message while keeping one visual nesting level. Moderators approve, reject,
+hide, restore or erase text; they never rewrite another author's words.
+
+Published comments include **Schema.org Comment microdata and JSON-LD**, using
+the visible text and author name. Choose either format or disable output in Python.
+[Structured-data guide →](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Structured-data.md)
+
+## Compatibility
+
+| Component | Version / requirement |
+| --- | --- |
+| Python | 3.12–3.14 |
+| Wagtail | >=7.4.3, <7.5 |
+| Django | >=5.2, <5.3 |
+| Database | SQLite or PostgreSQL; CI covers PostgreSQL 14 |
+| UI languages | English and Russian |
+| Frontend | Django templates, optional progressive JavaScript |
+| License | [MIT](https://github.com/hardcodd/Commentail/blob/main/LICENSE) |
+
+Guest comments require configured SMTP and the scheduled worker. Registered
+users can comment without an email address, but receive no mail. Your site
+provides login and registration. No required external CDN or CAPTCHA service.
+
+## Quick start
+
+### 1. Install
+
+In your site's virtual environment, install the release:
+
+```sh
+python -m pip install commentail==0.1.0
+```
+
+For the optional PostgreSQL driver, use `python -m pip install 'commentail[postgres]==0.1.0'`.
+You can also install a downloaded wheel directly, or extract the source distribution
+and run `python -m pip install .` in its root.
+
+### 2. Connect Django and Wagtail
+
+- Add `commentail` and `wagtail.contrib.settings` to your existing `INSTALLED_APPS`.
+- Insert `commentail.middleware.CapabilityHeadersMiddleware` before CSRF middleware.
+- Retain the host session/authentication/messages middleware and template request context processor.
+- Include Commentail URLs **before** Wagtail's catch-all:
+
+```python
+path("commentail/", include("commentail.urls")),
+```
+
+Run `python manage.py migrate`, `python manage.py check` and your normal static
+collection. See the [complete installation guide](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Installation.md)
+for settings, URL imports, CSRF draft recovery and deployment details.
+
+### 3. Add the widget
+
+```django
+{% load commentail_tags %}
+{% commentail_css %}
+{% commentail_js %}
+{% commentail page %}
+```
+
+Put the resource tags once in the base template and the widget in the article.
+The template controls where Page comments are available; the corresponding Page
+editor receives a Comments tab. Configure site defaults, then inherit or override
+on individual Pages. **Review all** is the initial moderation policy.
+
+### 4. Enable email and cleanup
+
+Configure Django's SMTP settings and schedule this once per minute:
+
+```sh
+python manage.py process_commentail
+```
+
+It sends the database outbox and removes expired transient records. Guests confirm
+email before moderation. Public submissions with an email are automatically
+subscribed to direct-reply notifications when mail is enabled; each reply email
+includes per-comment unsubscribe. [Email setup and behavior →](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Email-and-worker.md)
+
+## Make it yours
+
+The widget has a transparent surface and inherits the container's font and text
+color, following your site's light/dark theme. Load overrides after its stylesheet:
+
+```css
+.commentail {
+  --commentail-color-accent: var(--brand-link, #245a86);
+  --commentail-border-radius: .5rem;
+  --commentail-max-width: 100%;
+}
+```
+
+Use `GET_AVATAR` to return a profile image URL, or return `None` for generated
+initials. Register ordinary Django models through `OBJECT_ADAPTERS`. Technical
+settings use a single `COMMENTAIL` dictionary with `default` and hostname overrides.
+
+## Documentation by task
+
+The [Wiki](https://github.com/hardcodd/Commentail/wiki) and the [versioned guides](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Home.md)
+cover the same topics. Start with the task you need:
+
+| Area | Guides |
+| --- | --- |
+| Connect | [Installation](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Installation.md) · [Runnable example](https://github.com/hardcodd/Commentail/blob/main/example/README.md) |
+| Configure | [Site, Page and Python settings](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Configuration.md) · [Moderation](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Moderation.md) · [CSV rules](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Rules-and-CSV.md) |
+| Reader behavior | [Guests](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Guest-comments.md) · [Replies and editing](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Replies-and-editing.md) |
+| Customize | [CSS and themes](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Styling.md) · [Templates and email](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Templates.md) · [Python callbacks](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Callbacks.md) · [Django model adapters](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Object-adapters.md) |
+| Operate | [SMTP and worker](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Email-and-worker.md) · [Deployment](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Deployment.md) · [Security and privacy](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Security-and-privacy.md) |
+| Diagnose | [Troubleshooting / FAQ](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Troubleshooting.md) · [Example and testing](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Example-and-testing.md) |
+
+## Release scope and verification
+
+[0.1.0 release notes](https://github.com/hardcodd/Commentail/blob/main/docs/releases/0.1.0.md) describe the initial feature set and
+limits. The source distribution includes the runnable Wagtail example, tests and
+guides; the wheel includes the runtime, translations, templates and static assets.
+
+CI checks six Python/database combinations, JavaScript, lint, migration drift,
+translations and source/wheel installation. Browser checks covered installed Safari,
+Chrome, Yandex Browser and Firefox with and without JS, plus selected VoiceOver
+scenarios and a phone. Previous major browser versions remain unverified; this is
+not an exhaustive accessibility or device certification.
+
+There is no separate REST API, rich-text editor, uploads, likes, reports or live
+updates in 0.1.0. SMTP retries can duplicate mail after an uncertain delivery result.
+Host-specific themes, access rules and email delivery need their own acceptance checks.
+
+## Support Commentail
+
+If Commentail helps your project, you can support maintenance, documentation and
+compatibility work. Contributions are optional.
+
+**[Support via CloudTips](https://pay.cloudtips.ru/p/f92ee349)**
+
+<a href="https://pay.cloudtips.ru/p/f92ee349"><img src="https://raw.githubusercontent.com/hardcodd/Commentail/main/docs/assets/support-qr.png" alt="Scan to support Commentail via CloudTips" width="180"></a>
+
+For questions and reproducible bugs, check the [FAQ](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Troubleshooting.md)
+then open a [GitHub issue](https://github.com/hardcodd/Commentail/issues). Do not
+include credentials, private comments or protected email links.

commentail-0.1.0/README.md

@@ -0,0 +1,175 @@
+<div align="center">
+
+# Commentail
+
+**Self-hosted comments for Wagtail CMS**
+
+Moderated discussions, verified guests and inline replies — styled by your site.
+
+[![Tests and distributions](https://github.com/hardcodd/Commentail/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/hardcodd/Commentail/actions/workflows/tests.yml)
+
+[Get started](#quick-start) · [Documentation](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Home.md) · [Wiki](https://github.com/hardcodd/Commentail/wiki) · [Support](#support-commentail)
+
+<img src="https://raw.githubusercontent.com/hardcodd/Commentail/main/docs/assets/commentail-preview.png" alt="Commentail — a blue bird perched on a comment bubble" width="100%">
+
+</div>
+
+Commentail is a Django comments library built for **Wagtail 7.4 LTS**. Add a
+Django template tag to an article, moderate discussions inside Wagtail, and keep
+content, accounts and email delivery in your own application.
+
+The widget inherits your site's typography and colors. CSS custom properties,
+replaceable templates and Python callbacks let you adapt it without a frontend
+framework or an external comments platform.
+
+> Wagtail 8.0 is not supported by 0.1.0.
+
+## Why Commentail?
+
+| For readers | For editors | For developers |
+| --- | --- | --- |
+| Guest email verification or existing site accounts | Four moderation policies | One template tag for Pages and registered objects |
+| Inline replies and author editing | Site defaults and Page overrides | CSS properties and template overrides |
+| Direct-reply email with unsubscribe | Word/phrase rules and CSV import/export | Replaceable avatars, names and CAPTCHA |
+| Responsive layout and plain HTML fallbacks | Site-scoped group permissions | Database outbox; no Redis/Celery requirement |
+
+Comments are plain text with an adjustable 5000-character default. Optional
+clickable HTTP(S) links use safe attributes. Replies can address any visible
+message while keeping one visual nesting level. Moderators approve, reject,
+hide, restore or erase text; they never rewrite another author's words.
+
+Published comments include **Schema.org Comment microdata and JSON-LD**, using
+the visible text and author name. Choose either format or disable output in Python.
+[Structured-data guide →](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Structured-data.md)
+
+## Compatibility
+
+| Component | Version / requirement |
+| --- | --- |
+| Python | 3.12–3.14 |
+| Wagtail | >=7.4.3, <7.5 |
+| Django | >=5.2, <5.3 |
+| Database | SQLite or PostgreSQL; CI covers PostgreSQL 14 |
+| UI languages | English and Russian |
+| Frontend | Django templates, optional progressive JavaScript |
+| License | [MIT](https://github.com/hardcodd/Commentail/blob/main/LICENSE) |
+
+Guest comments require configured SMTP and the scheduled worker. Registered
+users can comment without an email address, but receive no mail. Your site
+provides login and registration. No required external CDN or CAPTCHA service.
+
+## Quick start
+
+### 1. Install
+
+In your site's virtual environment, install the release:
+
+```sh
+python -m pip install commentail==0.1.0
+```
+
+For the optional PostgreSQL driver, use `python -m pip install 'commentail[postgres]==0.1.0'`.
+You can also install a downloaded wheel directly, or extract the source distribution
+and run `python -m pip install .` in its root.
+
+### 2. Connect Django and Wagtail
+
+- Add `commentail` and `wagtail.contrib.settings` to your existing `INSTALLED_APPS`.
+- Insert `commentail.middleware.CapabilityHeadersMiddleware` before CSRF middleware.
+- Retain the host session/authentication/messages middleware and template request context processor.
+- Include Commentail URLs **before** Wagtail's catch-all:
+
+```python
+path("commentail/", include("commentail.urls")),
+```
+
+Run `python manage.py migrate`, `python manage.py check` and your normal static
+collection. See the [complete installation guide](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Installation.md)
+for settings, URL imports, CSRF draft recovery and deployment details.
+
+### 3. Add the widget
+
+```django
+{% load commentail_tags %}
+{% commentail_css %}
+{% commentail_js %}
+{% commentail page %}
+```
+
+Put the resource tags once in the base template and the widget in the article.
+The template controls where Page comments are available; the corresponding Page
+editor receives a Comments tab. Configure site defaults, then inherit or override
+on individual Pages. **Review all** is the initial moderation policy.
+
+### 4. Enable email and cleanup
+
+Configure Django's SMTP settings and schedule this once per minute:
+
+```sh
+python manage.py process_commentail
+```
+
+It sends the database outbox and removes expired transient records. Guests confirm
+email before moderation. Public submissions with an email are automatically
+subscribed to direct-reply notifications when mail is enabled; each reply email
+includes per-comment unsubscribe. [Email setup and behavior →](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Email-and-worker.md)
+
+## Make it yours
+
+The widget has a transparent surface and inherits the container's font and text
+color, following your site's light/dark theme. Load overrides after its stylesheet:
+
+```css
+.commentail {
+  --commentail-color-accent: var(--brand-link, #245a86);
+  --commentail-border-radius: .5rem;
+  --commentail-max-width: 100%;
+}
+```
+
+Use `GET_AVATAR` to return a profile image URL, or return `None` for generated
+initials. Register ordinary Django models through `OBJECT_ADAPTERS`. Technical
+settings use a single `COMMENTAIL` dictionary with `default` and hostname overrides.
+
+## Documentation by task
+
+The [Wiki](https://github.com/hardcodd/Commentail/wiki) and the [versioned guides](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Home.md)
+cover the same topics. Start with the task you need:
+
+| Area | Guides |
+| --- | --- |
+| Connect | [Installation](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Installation.md) · [Runnable example](https://github.com/hardcodd/Commentail/blob/main/example/README.md) |
+| Configure | [Site, Page and Python settings](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Configuration.md) · [Moderation](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Moderation.md) · [CSV rules](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Rules-and-CSV.md) |
+| Reader behavior | [Guests](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Guest-comments.md) · [Replies and editing](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Replies-and-editing.md) |
+| Customize | [CSS and themes](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Styling.md) · [Templates and email](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Templates.md) · [Python callbacks](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Callbacks.md) · [Django model adapters](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Object-adapters.md) |
+| Operate | [SMTP and worker](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Email-and-worker.md) · [Deployment](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Deployment.md) · [Security and privacy](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Security-and-privacy.md) |
+| Diagnose | [Troubleshooting / FAQ](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Troubleshooting.md) · [Example and testing](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Example-and-testing.md) |
+
+## Release scope and verification
+
+[0.1.0 release notes](https://github.com/hardcodd/Commentail/blob/main/docs/releases/0.1.0.md) describe the initial feature set and
+limits. The source distribution includes the runnable Wagtail example, tests and
+guides; the wheel includes the runtime, translations, templates and static assets.
+
+CI checks six Python/database combinations, JavaScript, lint, migration drift,
+translations and source/wheel installation. Browser checks covered installed Safari,
+Chrome, Yandex Browser and Firefox with and without JS, plus selected VoiceOver
+scenarios and a phone. Previous major browser versions remain unverified; this is
+not an exhaustive accessibility or device certification.
+
+There is no separate REST API, rich-text editor, uploads, likes, reports or live
+updates in 0.1.0. SMTP retries can duplicate mail after an uncertain delivery result.
+Host-specific themes, access rules and email delivery need their own acceptance checks.
+
+## Support Commentail
+
+If Commentail helps your project, you can support maintenance, documentation and
+compatibility work. Contributions are optional.
+
+**[Support via CloudTips](https://pay.cloudtips.ru/p/f92ee349)**
+
+<a href="https://pay.cloudtips.ru/p/f92ee349"><img src="https://raw.githubusercontent.com/hardcodd/Commentail/main/docs/assets/support-qr.png" alt="Scan to support Commentail via CloudTips" width="180"></a>
+
+For questions and reproducible bugs, check the [FAQ](https://github.com/hardcodd/Commentail/blob/main/docs/wiki/Troubleshooting.md)
+then open a [GitHub issue](https://github.com/hardcodd/Commentail/issues). Do not
+include credentials, private comments or protected email links.

commentail-0.1.0/commentail/__init__.py

@@ -0,0 +1 @@
+"""Commentail: a Wagtail comments application under active development."""

commentail-0.1.0/commentail/admin_urls.py

@@ -0,0 +1,28 @@
+from django.urls import path
+
+from . import admin_views as views
+
+app_name = "commentail_admin"
+urlpatterns = [
+    path("objects/", views.objects_list, name="objects"),
+    path("objects/<int:identifier>/", views.object_settings, name="object_settings"),
+    path("", views.index, name="list"),
+    path("bulk/", views.bulk, name="bulk"),
+    path("rules/", views.rules, name="rules"),
+    path("rules/import/", views.rules_import, name="rules_import"),
+    path("rules/export/", views.rules_export, name="rules_export"),
+    path("rules/add/", views.rule_edit, name="rule_add"),
+    path("rules/<int:identifier>/", views.rule_edit, name="rule_edit"),
+    path("access/", views.access, name="access"),
+    path("settings/<int:site_id>/", views.settings_view, name="settings"),
+    path(
+        "settings/<int:site_id>/<int:page_id>/",
+        views.settings_view,
+        name="page_settings",
+    ),
+    path("mail/", views.mail_queue, name="mail"),
+    path("mail/<int:identifier>/retry/", views.retry_mail, name="retry"),
+    path("<int:identifier>/", views.detail, name="detail"),
+    path("<int:identifier>/action/", views.action, name="action"),
+    path("<int:identifier>/revision/", views.revision_action, name="revision"),
+]