django-deacon 1.0.0__tar.gz

django_deacon-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deacon
+
+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.

django_deacon-1.0.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: django-deacon
+Version: 1.0.0
+Summary: Django app that adds Deacon, an AI support chat that answers from your docs, to every page.
+Keywords: django,deacon,chat widget,support,ai,chatbot,ai-chatbot,ask-ai,support-chat
+Author: Deacon
+Author-email: Deacon <hello@heydeacon.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: django>=5.2
+Requires-Python: >=3.11
+Project-URL: Homepage, https://heydeacon.com
+Project-URL: Repository, https://github.com/heydeacon/django-deacon
+Project-URL: Issues, https://github.com/heydeacon/django-deacon/issues
+Description-Content-Type: text/markdown
+
+# django-deacon
+
+[Deacon](https://heydeacon.com) is an AI support agent that answers questions from your own docs and content, and says when it doesn't know. This app adds its chat widget to every page of a Django site.
+
+You need a Deacon account, and there's a free plan.
+
+## Install
+
+```sh
+pip install django-deacon
+```
+
+## Set it up
+
+Add the app and your key to `settings.py`:
+
+```python
+INSTALLED_APPS = [
+    # ...the rest of your apps
+    "django_deacon",
+]
+
+DEACON_KEY = "pk_your_widget_key"
+```
+
+Then load the tag in the `<head>` of your base template:
+
+```django
+{% load deacon %}
+<head>
+  {# ...the rest of your head #}
+  {% deacon_widget %}
+</head>
+```
+
+To find your key, open Install from the button at the top of the Deacon dashboard. The snippet there has it in `data-key`, and it starts with `pk_`. It isn't a secret, since every visitor's browser reads it, but you can read it from the environment like any setting: `DEACON_KEY = os.environ.get("DEACON_KEY")`. If the key is missing, the tag prints nothing and logs a warning that says why, so your pages still render. A setting of the wrong type raises `ImproperlyConfigured`, which says why.
+
+Deacon only runs on the sites listed on Install. A listed domain covers its subdomains, so `example.com` covers `app.example.com`. If your site lives somewhere else, such as `example.fly.dev`, add that address on Install too.
+
+When you run `python manage.py runserver`, Install notices the widget on `127.0.0.1:8000` and lets you add it in one click. Chats on a development address don't count towards your plan.
+
+If you tell Deacon who is signed in, with the `window.deaconUser` script from [Deacon's install guide](https://heydeacon.com/agent/install.md), put that script above `{% deacon_widget %}` in the head, because the widget reads it as it starts.
+
+## Options
+
+| Setting             | Type    | Default  | What it does |
+| ------------------- | ------- | -------- | ------------ |
+| `DEACON_KEY`        | str     | none     | Your Deacon key. Without it the tag prints nothing and logs a warning. |
+| `DEACON_CONTEXT`    | dict    | none     | Details Deacon takes into account when it answers, the same on every page, such as `{"product": "api", "docs_version": "3.2"}`. Up to 12 keys, each value a string, number or boolean. Anyone can read them in the page's HTML, so never put a secret here. |
+| `DEACON_PAGE_VIEWS` | bool    | `True`   | The same script counts visits for Deacon's website analytics. Set this to `False` to send no page views or JavaScript errors from your site. Chat still works. |
+
+```python
+DEACON_KEY = "pk_your_widget_key"
+DEACON_CONTEXT = {"product": "api", "docs_version": "3.2"}
+DEACON_PAGE_VIEWS = False
+```
+
+## Content Security Policy
+
+If your site sends a Content Security Policy with a nonce, the tag carries the request's nonce. It reads it from Django's own CSP support (Django 6.0 and later), which needs the `django.template.context_processors.csp` context processor, or from [django-csp](https://pypi.org/project/django-csp/)'s `request.csp_nonce`, which needs `django.template.context_processors.request`.
+
+The policy also needs Deacon's address, `https://heydeacon.com`, in `script-src`, `connect-src` and `frame-src`, and `'unsafe-inline'` in `style-src`, because the widget writes its styles where a nonce can't reach. Keep the nonce out of `style-src`, since a nonce there makes browsers ignore `'unsafe-inline'`:
+
+```python
+from django.utils.csp import CSP
+
+SECURE_CSP = {
+    "default-src": [CSP.SELF],
+    "script-src": [CSP.SELF, CSP.NONCE, "https://heydeacon.com"],
+    "style-src": [CSP.SELF, CSP.UNSAFE_INLINE],
+    "connect-src": [CSP.SELF, "https://heydeacon.com"],
+    "frame-src": ["https://heydeacon.com"],
+}
+```
+
+## Opening the chat from your own button
+
+The widget comes with its own button. To use one of yours instead, hide Deacon's in Appearance in the dashboard and call `window.Deacon.open()` from your button or link. `Deacon.close()` and `Deacon.toggle()` work too.
+
+## What it adds
+
+The tag prints the same tag Install gives you:
+
+```html
+<script src="https://heydeacon.com/widget/v1/loader.js" data-key="pk_your_widget_key" async></script>
+```
+
+It loads in the background without holding up the page. Works with Django 5.2 and later, on Python 3.11 and later.
+
+## License
+
+MIT

django_deacon-1.0.0/README.md

@@ -0,0 +1,92 @@
+# django-deacon
+
+[Deacon](https://heydeacon.com) is an AI support agent that answers questions from your own docs and content, and says when it doesn't know. This app adds its chat widget to every page of a Django site.
+
+You need a Deacon account, and there's a free plan.
+
+## Install
+
+```sh
+pip install django-deacon
+```
+
+## Set it up
+
+Add the app and your key to `settings.py`:
+
+```python
+INSTALLED_APPS = [
+    # ...the rest of your apps
+    "django_deacon",
+]
+
+DEACON_KEY = "pk_your_widget_key"
+```
+
+Then load the tag in the `<head>` of your base template:
+
+```django
+{% load deacon %}
+<head>
+  {# ...the rest of your head #}
+  {% deacon_widget %}
+</head>
+```
+
+To find your key, open Install from the button at the top of the Deacon dashboard. The snippet there has it in `data-key`, and it starts with `pk_`. It isn't a secret, since every visitor's browser reads it, but you can read it from the environment like any setting: `DEACON_KEY = os.environ.get("DEACON_KEY")`. If the key is missing, the tag prints nothing and logs a warning that says why, so your pages still render. A setting of the wrong type raises `ImproperlyConfigured`, which says why.
+
+Deacon only runs on the sites listed on Install. A listed domain covers its subdomains, so `example.com` covers `app.example.com`. If your site lives somewhere else, such as `example.fly.dev`, add that address on Install too.
+
+When you run `python manage.py runserver`, Install notices the widget on `127.0.0.1:8000` and lets you add it in one click. Chats on a development address don't count towards your plan.
+
+If you tell Deacon who is signed in, with the `window.deaconUser` script from [Deacon's install guide](https://heydeacon.com/agent/install.md), put that script above `{% deacon_widget %}` in the head, because the widget reads it as it starts.
+
+## Options
+
+| Setting             | Type    | Default  | What it does |
+| ------------------- | ------- | -------- | ------------ |
+| `DEACON_KEY`        | str     | none     | Your Deacon key. Without it the tag prints nothing and logs a warning. |
+| `DEACON_CONTEXT`    | dict    | none     | Details Deacon takes into account when it answers, the same on every page, such as `{"product": "api", "docs_version": "3.2"}`. Up to 12 keys, each value a string, number or boolean. Anyone can read them in the page's HTML, so never put a secret here. |
+| `DEACON_PAGE_VIEWS` | bool    | `True`   | The same script counts visits for Deacon's website analytics. Set this to `False` to send no page views or JavaScript errors from your site. Chat still works. |
+
+```python
+DEACON_KEY = "pk_your_widget_key"
+DEACON_CONTEXT = {"product": "api", "docs_version": "3.2"}
+DEACON_PAGE_VIEWS = False
+```
+
+## Content Security Policy
+
+If your site sends a Content Security Policy with a nonce, the tag carries the request's nonce. It reads it from Django's own CSP support (Django 6.0 and later), which needs the `django.template.context_processors.csp` context processor, or from [django-csp](https://pypi.org/project/django-csp/)'s `request.csp_nonce`, which needs `django.template.context_processors.request`.
+
+The policy also needs Deacon's address, `https://heydeacon.com`, in `script-src`, `connect-src` and `frame-src`, and `'unsafe-inline'` in `style-src`, because the widget writes its styles where a nonce can't reach. Keep the nonce out of `style-src`, since a nonce there makes browsers ignore `'unsafe-inline'`:
+
+```python
+from django.utils.csp import CSP
+
+SECURE_CSP = {
+    "default-src": [CSP.SELF],
+    "script-src": [CSP.SELF, CSP.NONCE, "https://heydeacon.com"],
+    "style-src": [CSP.SELF, CSP.UNSAFE_INLINE],
+    "connect-src": [CSP.SELF, "https://heydeacon.com"],
+    "frame-src": ["https://heydeacon.com"],
+}
+```
+
+## Opening the chat from your own button
+
+The widget comes with its own button. To use one of yours instead, hide Deacon's in Appearance in the dashboard and call `window.Deacon.open()` from your button or link. `Deacon.close()` and `Deacon.toggle()` work too.
+
+## What it adds
+
+The tag prints the same tag Install gives you:
+
+```html
+<script src="https://heydeacon.com/widget/v1/loader.js" data-key="pk_your_widget_key" async></script>
+```
+
+It loads in the background without holding up the page. Works with Django 5.2 and later, on Python 3.11 and later.
+
+## License
+
+MIT

django_deacon-1.0.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "django-deacon"
+version = "1.0.0"
+description = "Django app that adds Deacon, an AI support chat that answers from your docs, to every page."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = ["Django>=5.2"]
+keywords = [
+    "django",
+    "deacon",
+    "chat widget",
+    "support",
+    "ai",
+    "chatbot",
+    "ai-chatbot",
+    "ask-ai",
+    "support-chat",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[[project.authors]]
+name = "Deacon"
+email = "hello@heydeacon.com"
+
+[project.urls]
+Homepage = "https://heydeacon.com"
+Repository = "https://github.com/heydeacon/django-deacon"
+Issues = "https://github.com/heydeacon/django-deacon/issues"
+
+[dependency-groups]
+dev = [
+    "django-csp>=4.0",
+    "pytest>=9.1",
+    "pytest-django>=4.14",
+    "ruff>=0.17.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = ["."]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

django_deacon-1.0.0/pyproject.toml.orig

@@ -0,0 +1,62 @@
+[project]
+name = "django-deacon"
+version = "1.0.0"
+description = "Django app that adds Deacon, an AI support chat that answers from your docs, to every page."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Deacon", email = "hello@heydeacon.com" }]
+requires-python = ">=3.11"
+dependencies = ["Django>=5.2"]
+keywords = [
+    "django",
+    "deacon",
+    "chat widget",
+    "support",
+    "ai",
+    "chatbot",
+    "ai-chatbot",
+    "ask-ai",
+    "support-chat",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.urls]
+Homepage = "https://heydeacon.com"
+Repository = "https://github.com/heydeacon/django-deacon"
+Issues = "https://github.com/heydeacon/django-deacon/issues"
+
+[dependency-groups]
+dev = [
+    "django-csp>=4.0",
+    "pytest>=9.1",
+    "pytest-django>=4.14",
+    "ruff>=0.17.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = ["."]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

django_deacon-1.0.0/src/django_deacon/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class DeaconConfig(AppConfig):
+    name = "django_deacon"
+    verbose_name = "Deacon"

django_deacon-1.0.0/src/django_deacon/templatetags/deacon.py

@@ -0,0 +1,96 @@
+import json
+import logging
+
+from django import template
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.utils.html import escape
+from django.utils.safestring import mark_safe
+
+register = template.Library()
+logger = logging.getLogger("django_deacon")
+
+LOADER_SRC = "https://heydeacon.com/widget/v1/loader.js"
+
+MISSING_KEY = (
+    "django-deacon: the DEACON_KEY setting is missing, so the page has no Deacon widget. In "
+    "Deacon, open Install (the button at the top of the dashboard) and copy the data-key value "
+    "from the snippet. It starts with pk_."
+)
+
+
+@register.simple_tag(takes_context=True)
+def deacon_widget(context):
+    """
+    The tag Install gives, with the key from the DEACON_KEY setting. With no key it prints
+    nothing and logs a warning, so a missing setting never takes a page down.
+    """
+    key = str(getattr(settings, "DEACON_KEY", None) or "").strip()
+
+    if key == "":
+        logger.warning(MISSING_KEY)
+        return ""
+
+    deacon_context = getattr(settings, "DEACON_CONTEXT", None)
+    page_views = getattr(settings, "DEACON_PAGE_VIEWS", True)
+    _check_context(deacon_context)
+    _check_page_views(page_views)
+
+    attributes = {"data-key": key}
+    if deacon_context is not None:
+        attributes["data-context"] = json.dumps(
+            deacon_context, separators=(",", ":"), ensure_ascii=False
+        )
+    if page_views is False:
+        attributes["data-no-page-views"] = True
+
+    return _loader_tag(attributes, _csp_nonce(context))
+
+
+def _csp_nonce(context):
+    """
+    The request's Content Security Policy nonce: from Django's own CSP support (6.0 and
+    later, through its csp context processor), else from django-csp's request.csp_nonce, or
+    None when the project has no nonce.
+    """
+    nonce = context.get("csp_nonce")
+    if nonce is None:
+        nonce = getattr(context.get("request"), "csp_nonce", None)
+
+    return None if nonce is None else str(nonce)
+
+
+def _check_context(deacon_context):
+    """A wrong type is a mistake in the project's settings, so it raises."""
+    if deacon_context is None:
+        return
+
+    if not isinstance(deacon_context, dict) or not all(
+        isinstance(value, str | int | float | bool) for value in deacon_context.values()
+    ):
+        raise ImproperlyConfigured(
+            "django-deacon: the DEACON_CONTEXT setting must be a dict whose values are strings, "
+            "numbers or booleans."
+        )
+
+
+def _check_page_views(page_views):
+    if not isinstance(page_views, bool):
+        raise ImproperlyConfigured(
+            "django-deacon: the DEACON_PAGE_VIEWS setting must be True or False."
+        )
+
+
+def _loader_tag(attributes, nonce):
+    """
+    The tag Install gives, with any of its other attributes between the key and async, and
+    the nonce after them. An attribute that is True is written with no value, as async is.
+    """
+    rendered = "".join(
+        f" {name}" if value is True else f' {name}="{escape(value)}"'
+        for name, value in attributes.items()
+    )
+
+    nonce_attribute = "" if nonce is None else f' nonce="{escape(nonce)}"'
+
+    return mark_safe(f'<script src="{LOADER_SRC}"{rendered} async{nonce_attribute}></script>')