aiohttp-ai-chatbot 1.0.0__py3-none-any.whl

aiohttp_ai_chatbot/__init__.py

@@ -0,0 +1,6 @@
+"""Adds the Asyntai AI chat assistant to aiohttp sites."""
+from .middleware import DEFAULT_SKIP_PATHS, asyntai_middleware, setup
+from .snippet import asyntai_widget, widget_snippet
+
+__all__ = ['DEFAULT_SKIP_PATHS', 'asyntai_middleware', 'asyntai_widget', 'setup', 'widget_snippet']
+__version__ = '1.0.0'

aiohttp_ai_chatbot/middleware.py

@@ -0,0 +1,121 @@
+"""Puts the chat widget on every HTML page of an aiohttp site, with no template edit.
+
+The middleware only touches complete web.Response objects that carry an HTML
+page with status 200. Everything else passes through untouched: JSON, files
+from add_static or web.FileResponse, prepared streams, websockets and
+redirects.
+"""
+from aiohttp import web
+
+from .snippet import MARKER, resolve_widget_id, widget_snippet
+from .utils import clean_script_url
+
+BODY_CLOSE = b'</body>'
+
+#: Paths the widget never touches by default. A path that ends in * matches
+#: the path itself and everything below it.
+DEFAULT_SKIP_PATHS = ('/admin*',)
+
+#: The key under which setup() stores its settings on the application.
+APP_KEY = 'aiohttp_ai_chatbot'
+
+
+def path_is_skipped(path, skip_paths):
+    """Answer whether the widget must stay off on this path."""
+    for rule in skip_paths:
+        if rule.endswith('*'):
+            base = rule[:-1].rstrip('/')
+            if path == base or path.startswith(base + '/'):
+                return True
+        elif path == rule:
+            return True
+    return False
+
+
+def insert_snippet(body, snippet, charset='utf-8'):
+    """Return the page with the snippet before the last </body>, or None.
+
+    None means "leave the page as it is": the page has no closing body tag,
+    it already carries the widget, or it is not readable text.
+    """
+    if MARKER.encode() in body or b'data-asyntai-id' in body:
+        return None
+
+    if BODY_CLOSE not in body.lower():
+        return None
+
+    try:
+        html = body.decode(charset)
+        encoded_snippet = snippet.encode(charset)
+    except (UnicodeError, LookupError):
+        return None
+
+    # Split on the last closing tag, so a page that prints the tag inside an
+    # example or a code block is left alone.
+    index = html.lower().rfind('</body>')
+    if index < 0:
+        return None
+    return html[:index].encode(charset) + encoded_snippet + html[index:].encode(charset)
+
+
+def asyntai_middleware(widget_id=None, skip_paths=DEFAULT_SKIP_PATHS, script_url=None):
+    """Return an aiohttp middleware that inserts the widget before </body>.
+
+    widget_id      the ID from the Asyntai dashboard; without it, the
+                   ASYNTAI_WIDGET_ID environment variable (read on every
+                   request, so the ID can change without a code change)
+    skip_paths     paths the widget never touches
+    script_url     change only if Asyntai support asks
+
+        app = web.Application(middlewares=[asyntai_middleware("asyntai_ab12cd34")])
+    """
+    skip = tuple(skip_paths or ())
+
+    @web.middleware
+    async def asyntai_widget_middleware(request, handler):
+        response = await handler(request)
+
+        if request.method == 'HEAD' or path_is_skipped(request.path or '/', skip):
+            return response
+
+        if not resolve_widget_id(widget_id) or not clean_script_url(script_url):
+            return response
+
+        if _can_carry_widget(response):
+            snippet = widget_snippet(widget_id, script_url)
+            new_body = insert_snippet(response.body, snippet, response.charset or 'utf-8') if snippet else None
+            if new_body is not None:
+                # The body setter also sets the new Content-Length.
+                response.body = new_body
+
+        return response
+
+    return asyntai_widget_middleware
+
+
+def setup(app, widget_id=None, skip_paths=DEFAULT_SKIP_PATHS, script_url=None):
+    """Add the widget middleware to an application before it starts.
+
+        from aiohttp_ai_chatbot import setup
+        setup(app, widget_id="asyntai_ab12cd34")
+    """
+    middleware = asyntai_middleware(widget_id=widget_id, skip_paths=skip_paths, script_url=script_url)
+    app.middlewares.append(middleware)
+    return middleware
+
+
+def _can_carry_widget(response):
+    # A FileResponse or a hand-made StreamResponse is not a web.Response,
+    # and a prepared response has already left; neither can change.
+    if not isinstance(response, web.Response) or response.prepared:
+        return False
+
+    if response.status != 200 or response.headers.get('Content-Encoding'):
+        return False
+
+    if response.content_type != 'text/html':
+        return False
+
+    # A body object (a file, a stream) is sent piece by piece; only plain
+    # bytes can be read and changed here.
+    return isinstance(response.body, (bytes, bytearray))

aiohttp_ai_chatbot/snippet.py

@@ -0,0 +1,82 @@
+"""The HTML that loads the chat widget, for the middleware and for templates."""
+import os
+from html import escape
+
+from .utils import clean_script_url, clean_widget_id
+
+#: Text that only this package writes. The middleware looks for it, so the
+#: widget is never added twice.
+MARKER = 'asyntai-widget-config'
+
+_TEMPLATE = (
+    '<div class="' + MARKER + '" data-asyntai-widget="__WIDGET_ID__" '
+    'data-asyntai-src="__SCRIPT_URL__" style="display: none"></div>\n'
+    '<script>\n'
+    '    // Loads the Asyntai chat widget after the page has finished loading,\n'
+    '    // so the site draws first and page speed does not change. The two\n'
+    '    // values arrive on a data attribute, so nothing is ever written into\n'
+    '    // the script itself.\n'
+    '    (function () {\n'
+    "        var config = document.querySelector('." + MARKER + "');\n"
+    '        if (!config) { return; }\n'
+    '\n'
+    "        var widgetId = config.getAttribute('data-asyntai-widget') || '';\n"
+    "        var scriptUrl = config.getAttribute('data-asyntai-src') || '';\n"
+    "        if (!widgetId || scriptUrl.indexOf('https://') !== 0) { return; }\n"
+    '\n'
+    '        var load = function () {\n'
+    "            if (document.querySelector('script[data-asyntai-id]')) { return; }\n"
+    '\n'
+    "            var script = document.createElement('script');\n"
+    '            script.src = scriptUrl;\n'
+    '            script.async = true;\n'
+    "            script.setAttribute('data-asyntai-id', widgetId);\n"
+    '            document.head.appendChild(script);\n'
+    '        };\n'
+    '\n'
+    "        if (document.readyState === 'complete') {\n"
+    '            load();\n'
+    '        } else {\n'
+    "            window.addEventListener('load', load);\n"
+    '        }\n'
+    '    }());\n'
+    '</script>\n'
+)
+
+
+def resolve_widget_id(widget_id=None):
+    """The given ID, or the ASYNTAI_WIDGET_ID environment variable."""
+    if widget_id is None:
+        widget_id = os.environ.get('ASYNTAI_WIDGET_ID', '')
+    return clean_widget_id(widget_id)
+
+
+def widget_snippet(widget_id=None, script_url=None):
+    """Return the widget HTML, or an empty string when the chat must stay off.
+
+    Without a widget_id, the ASYNTAI_WIDGET_ID environment variable is used.
+    """
+    clean_id = resolve_widget_id(widget_id)
+    clean_url = clean_script_url(script_url)
+    if not clean_id or not clean_url:
+        return ''
+
+    return (_TEMPLATE
+            .replace('__WIDGET_ID__', escape(clean_id, quote=True))
+            .replace('__SCRIPT_URL__', escape(clean_url, quote=True)))
+
+
+def asyntai_widget(widget_id=None, script_url=None):
+    """Template helper: the same HTML, marked safe for Jinja2.
+
+    With aiohttp-jinja2, register it once, then write {{ asyntai_widget() }}
+    before </body>:
+
+        aiohttp_jinja2.get_env(app).globals['asyntai_widget'] = asyntai_widget
+    """
+    html = widget_snippet(widget_id, script_url)
+    try:
+        from markupsafe import Markup
+    except ImportError:  # Jinja2 is optional.
+        return html
+    return Markup(html)

aiohttp_ai_chatbot/utils.py

@@ -0,0 +1,57 @@
+"""Reading and checking the two values the widget needs.
+
+Every decision the package makes about a configured value lives here, so the
+tests can run it on its own.
+"""
+import re
+
+DEFAULT_SCRIPT_URL = 'https://widget.asyntai.com/static/js/chat-widget.js'
+
+#: Shape of a widget identifier from the Asyntai dashboard.
+ID_PATTERN = re.compile(r'^asyntai_[A-Za-z0-9]{6,64}$')
+
+#: The identifier inside a pasted snippet.
+SNIPPET_PATTERN = re.compile(r'data-asyntai-id\s*=\s*["\']([^"\']+)["\']')
+
+_HTTPS_PATTERN = re.compile(r'^https://[^\s"\'<>]+$', re.IGNORECASE)
+
+
+def clean_widget_id(raw):
+    """Return a usable widget identifier, or an empty string.
+
+    Accepts a bare identifier or the whole snippet from the Asyntai
+    dashboard, because people paste the snippet. An empty string means the
+    chat stays off, which is how you switch it off again.
+    """
+    if not isinstance(raw, str):
+        return ''
+
+    value = raw.strip()
+    if not value:
+        return ''
+
+    match = SNIPPET_PATTERN.search(value)
+    if match:
+        value = match.group(1).strip()
+
+    return value if ID_PATTERN.match(value) else ''
+
+
+def clean_script_url(raw):
+    """Return the script address, or an empty string when the value is bad.
+
+    Only an https address is accepted, so a bad value can never put a
+    javascript: URL on every page of the site. No value means the Asyntai
+    address.
+    """
+    if raw is None:
+        return DEFAULT_SCRIPT_URL
+
+    if not isinstance(raw, str):
+        return ''
+
+    value = raw.strip()
+    if not value:
+        return DEFAULT_SCRIPT_URL
+
+    return value if _HTTPS_PATTERN.match(value) else ''

aiohttp_ai_chatbot-1.0.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: aiohttp-ai-chatbot
+Version: 1.0.0
+Summary: Adds the Asyntai AI chat assistant to aiohttp sites. It answers visitor questions from your own content, in more than 80 languages.
+Author-email: Asyntai <hello@asyntai.com>
+License-Expression: MIT
+Project-URL: Homepage, https://asyntai.com
+Project-URL: Documentation, https://asyntai.com/documentation/integrations/aiohttp/
+Project-URL: Source, https://github.com/asyntai/aiohttp-ai-chatbot
+Project-URL: Issues, https://github.com/asyntai/aiohttp-ai-chatbot/issues
+Keywords: aiohttp,asyncio,middleware,chatbot,ai,ai-chatbot,live-chat,customer-support,widget
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: aiohttp
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.8
+Dynamic: license-file
+
+# aiohttp-ai-chatbot
+
+Adds the [Asyntai](https://asyntai.com) AI chat assistant to an aiohttp site.
+The assistant answers visitor questions from your own content, day and night,
+in more than 80 languages.
+
+Free and open source. Works on every Asyntai plan, including the free plan.
+
+- Requires Python 3.9 or newer and aiohttp 3.8 or newer
+- Documentation: https://asyntai.com/documentation/integrations/aiohttp/
+
+## Install
+
+```
+pip install aiohttp-ai-chatbot
+```
+
+```python
+from aiohttp import web
+from aiohttp_ai_chatbot import setup
+
+app = web.Application()
+app.router.add_get("/", index)
+setup(app, widget_id="asyntai_ab12cd34")
+
+web.run_app(app)
+```
+
+Or pass the middleware yourself:
+
+```python
+from aiohttp_ai_chatbot import asyntai_middleware
+
+app = web.Application(middlewares=[asyntai_middleware("asyntai_ab12cd34")])
+```
+
+You get the widget ID from the Install page of your
+[Asyntai dashboard](https://asyntai.com/dashboard). You can paste the whole
+snippet; the package keeps only the ID.
+
+That is all. The chat button appears on every HTML page of the site. JSON,
+files, streams, websockets and redirects pass through untouched.
+
+## Options
+
+```python
+setup(
+    app,
+    widget_id="asyntai_ab12cd34",   # without it: the ASYNTAI_WIDGET_ID environment variable
+    skip_paths=["/admin*"],         # the default
+)
+```
+
+- Leave out `widget_id` to read the `ASYNTAI_WIDGET_ID` environment variable.
+  It is read on every request, so you can change it without a code change.
+  An empty value switches the chat off.
+- `skip_paths` lists paths that never get the widget. A path that ends in `*`
+  also matches everything below it, so `/admin*` covers `/admin` and
+  `/admin/users`, but not `/administrator`.
+
+The middleware changes complete `web.Response` pages with status 200 and the
+`text/html` content type. A response that uses `enable_compression()` still
+gets the widget, because aiohttp compresses the body after the middleware.
+Files from `add_static` or `web.FileResponse` and responses that you prepare
+and stream yourself are sent as they are.
+
+## Placing the widget by hand
+
+With aiohttp-jinja2, register the helper once:
+
+```python
+import aiohttp_jinja2
+from aiohttp_ai_chatbot import asyntai_widget
+
+env = aiohttp_jinja2.setup(app, loader=...)
+env.globals["asyntai_widget"] = asyntai_widget
+```
+
+Then put it before the closing body tag:
+
+```html
+{{ asyntai_widget() }}
+</body>
+```
+
+`widget_snippet()` returns the same HTML as a plain string. The middleware
+never adds a second copy to a page that already has one.
+
+## How it loads
+
+The widget script loads after the page has finished loading, so your page
+draws first and page speed does not change.
+
+## License
+
+MIT

aiohttp_ai_chatbot-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+aiohttp_ai_chatbot/__init__.py,sha256=sXwrQBkalN0n0wqTe_OXm3Wah6UtecHkSQDze-5QO5E,304
+aiohttp_ai_chatbot/middleware.py,sha256=3Bh_iLXxZqOp76xnpDIWlxDOPlAELzlxuTOJO2Q09CM,4362
+aiohttp_ai_chatbot/snippet.py,sha256=GTBLZlQxKCqtO2zwyRYZOhYJ4b8Sqvh-yzJGMIis0ik,3083
+aiohttp_ai_chatbot/utils.py,sha256=FngblF1xb0fteWP-08pvPV6GbZVrysLKeRI-nKh2yKA,1632
+aiohttp_ai_chatbot-1.0.0.dist-info/licenses/LICENSE,sha256=jGsodKzosaT2Pr7P3ahTkLrMTHQ6uvf111OMRXeGYUM,1064
+aiohttp_ai_chatbot-1.0.0.dist-info/METADATA,sha256=5cIzj1osrKRnXQkCyxAkf7O7q6R7EXHfHYHVnPzjY_k,4251
+aiohttp_ai_chatbot-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+aiohttp_ai_chatbot-1.0.0.dist-info/top_level.txt,sha256=51JcIn0ocvmFD2iVau7M_371V3XHQxL2MiVFoVJrkIw,19
+aiohttp_ai_chatbot-1.0.0.dist-info/RECORD,,

aiohttp_ai_chatbot-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aiohttp_ai_chatbot-1.0.0.dist-info/licenses/LICENSE

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

aiohttp_ai_chatbot-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aiohttp_ai_chatbot