django-huddle 0.1.0__py3-none-any.whl

django_huddle-0.1.0.dist-info/METADATA

@@ -0,0 +1,278 @@
+Metadata-Version: 2.5
+Name: django-huddle
+Version: 0.1.0
+Summary: Slack-style team chat for Django: channels, direct messages, threads and @mentions over Django Channels.
+Project-URL: bugs, https://github.com/Streamlined-Analytics/django-huddle/issues
+Project-URL: changelog, https://github.com/Streamlined-Analytics/django-huddle/releases
+Project-URL: homepage, https://github.com/Streamlined-Analytics/django-huddle
+Author-email: Ben Atkinson <ben@streamlinedanalytics.co.uk>
+Maintainer-email: Ben Atkinson <ben@streamlinedanalytics.co.uk>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: channels>=4.2
+Requires-Dist: django>=6
+Provides-Extra: api
+Requires-Dist: djangorestframework>=3.16; extra == 'api'
+Description-Content-Type: text/markdown
+
+# django-huddle
+
+Slack-style team chat for Django: **channels, direct messages, threads and
+@mentions**, live over [Django Channels](https://channels.readthedocs.io/).
+
+- **Channels and DMs.** Public and private named channels, plus one-to-one and
+  group direct messages (one conversation per group of people).
+- **Threads.** Reply to any message in a side thread, as in Slack. Threads
+  are one level deep and track reply counts, followers and read state.
+- **@mentions.** Autocomplete offers only people who can read the channel.
+  Mentions are stored by user id, so renaming someone never breaks old messages.
+- **Live.** New messages, edits, deletions, thread replies and unread badges
+  arrive over a websocket.
+- **Your permissions.** One policy class decides every visibility and action
+  check. Attach channels to your own objects (projects, teams) and say who can
+  see them.
+- **Bring your own frontend, or don't.** It ships a working htmx UI whose every
+  piece is an overridable template. There's also a REST API, and a JSON
+  websocket mode for React, mobile or anything else.
+
+> **Status:** alpha. The public API may change before 1.0.
+
+## Requirements
+
+- Python 3.12+
+- Django 6.0+
+- Django Channels 4.2+ with a channel layer (Redis in production)
+- Optional: Django REST Framework 3.16+ for the REST API
+
+## Install
+
+```bash
+pip install django-huddle          # HTML UI + websocket
+pip install "django-huddle[api]"   # plus the REST API
+```
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    # ...
+    "channels",
+    "rest_framework",  # only for the REST API
+    "huddle",
+]
+ASGI_APPLICATION = "myproject.asgi.application"
+CHANNEL_LAYERS = {
+    "default": {
+        "BACKEND": "channels_redis.core.RedisChannelLayer",
+        "CONFIG": {"hosts": ["redis://localhost:6379/1"]},
+    },
+}
+HUDDLE_BASE_TEMPLATE = "base.html"  # must define {% block content %} and load htmx + htmx-ext-ws
+```
+
+```python
+# urls.py
+urlpatterns = [
+    path("chat/", include("huddle.urls")),
+    path("api/chat/", include("huddle.api.urls")),  # optional
+]
+```
+
+```python
+# asgi.py
+from channels.auth import AuthMiddlewareStack
+from channels.routing import ProtocolTypeRouter, URLRouter
+from channels.security.websocket import AllowedHostsOriginValidator
+from huddle.routing import websocket_urlpatterns
+
+application = ProtocolTypeRouter(
+    {
+        "http": django_asgi_app,
+        "websocket": AllowedHostsOriginValidator(AuthMiddlewareStack(URLRouter(websocket_urlpatterns))),
+    }
+)
+```
+
+Then run `python manage.py migrate`.
+
+## Permissions: the chat policy
+
+Every decision goes through one `huddle.policy.ChatPolicy`. The default allows:
+
+- public unscoped channels for every signed-in user;
+- private channels and DMs for their members;
+- **scoped channels for nobody**, until you say otherwise.
+
+To attach channels to your own objects, subclass the policy:
+
+```python
+from django.db.models import Q
+from huddle.policy import ChatPolicy
+
+
+class ProjectChatPolicy(ChatPolicy):
+    def scope_q(self, user):
+        projects = Project.objects.visible_to(user).values("pk")
+        return Q(scope_content_type__isnull=True) | self.scopes_q(Project, projects)
+
+    def can_create_channel(self, user, scope):
+        return scope is not None and user.has_perm("projects.manage", scope)
+
+    def mentionable_users(self, channel):
+        if channel.is_private or channel.scope is None:
+            return super().mentionable_users(channel)
+        return channel.scope.members.filter(is_active=True)
+
+    def direct_message_candidates(self, user):
+        return User.objects.filter(projects__in=Project.objects.visible_to(user)).exclude(pk=user.pk).distinct()
+```
+
+```python
+HUDDLE_POLICY = "myapp.chat.ProjectChatPolicy"
+```
+
+Every lookup (HTML, API and websocket) goes through
+`Channel.objects.visible_to(user)`, so a channel someone can't see returns a
+**404**, never a 403 that would confirm it exists. Every websocket event is
+re-checked for each viewer before it is sent, so losing access takes effect
+immediately.
+
+Overridable methods: `scope_q`, `filter_visible`, `can_view`, `can_post`,
+`can_create_channel`, `can_manage_channel`, `can_edit_message`,
+`can_delete_message`, `mentionable_users`, `direct_message_candidates`.
+
+## Writing from your own code
+
+```python
+from huddle.services import ChatService
+
+chat = ChatService()
+channel = chat.create_channel(user, "site-visits", scope=project)
+message = chat.post_message(user, channel, "Booked for Tuesday @Ann Lee", mentioned=[ann])
+chat.post_message(ann, channel, "Thanks!", parent=message)  # a thread reply
+dm = chat.open_direct(user, [ann, bob])
+```
+
+The service enforces the policy and raises
+`huddle.exceptions.ChatPermissionDeniedError` (and friends). Each exception
+has a `.context` dict for structured logging.
+
+## Signals: notifications and integrations
+
+Signals are sent **after the transaction commits**:
+
+| Signal | Arguments |
+|---|---|
+| `huddle.signals.message_posted` | `message`, `channel`, `author` |
+| `huddle.signals.user_mentioned` | `message`, `user` (once per newly mentioned user, including on edit) |
+| `huddle.signals.thread_replied` | `message`, `thread`, `recipients` (the thread's followers, minus the author) |
+
+```python
+@receiver(user_mentioned)
+def notify_mention(sender, message, user, **kwargs):
+    notify([user], "chat.mention", target=message)
+```
+
+## Customising the UI
+
+Every fragment is its own template under `huddle/components/`, and pages
+extend `huddle/layout.html`. To restyle one piece, override one file in your
+project's templates directory:
+
+| Template | What it draws |
+|---|---|
+| `huddle/components/message.html` | One message, with its actions and thread summary |
+| `huddle/components/composer.html`, `composer_fields.html` | The message box and @mention autocomplete |
+| `huddle/components/sidebar.html`, `sidebar_entry.html` | Channel and DM list, unread badges |
+| `huddle/components/thread.html` | The thread side panel |
+| `huddle/components/channel_pane.html` | Channel header, timeline and composer |
+| `huddle/layout.html` | The three-column chat layout |
+
+Each message template receives a `message_view` with `message`,
+`author_name`, `html` (safe, escaped), `can_edit`, `can_delete` and `is_own`.
+
+The default stylesheet (`huddle/huddle.css`) is plain CSS with custom
+properties (`--huddle-accent`, `--huddle-border`, …) for theming.
+
+## REST API (`django-huddle[api]`)
+
+| Method and path | Purpose |
+|---|---|
+| `GET /channels/` | Your channels and DMs (`?browse=true`: every visible named channel) |
+| `POST /channels/` | Create a channel `{name, topic, is_private}` |
+| `GET /channels/{id}/` | One channel, with `is_member` and `unread_count` |
+| `POST /channels/direct/` | Open a DM `{user_ids: [...]}` |
+| `POST /channels/{id}/join/` · `leave/` · `read/` | Membership and read state |
+| `GET /channels/{id}/messages/?before=&limit=` | A page of top-level messages, oldest first |
+| `POST /channels/{id}/messages/` | Post `{text, mention_ids, parent_id}` |
+| `GET /channels/{id}/mentionable/?q=` | People who can be @mentioned |
+| `GET`, `PATCH`, `DELETE /messages/{id}/` | Read, edit `{text, mention_ids}`, delete |
+| `GET /messages/{id}/replies/` · `POST read/` | A thread, and marking it read |
+
+Messages come back with `body` (stored tokens), `text` (editable, with
+`@Name`), `html` (rendered and safe), `mention_ids`, `author`, the timestamps,
+`reply_count`, and per-viewer `can_edit`, `can_delete` and `is_own`. To
+attach API-created channels to your own objects, subclass
+`huddle.api.views.ChannelViewSet` and override `get_scope()`.
+
+## Websocket
+
+Connect to `/ws/huddle/` (`HUDDLE_WEBSOCKET_URL`) and send
+`{"subscribe": <channel id>}` / `{"unsubscribe": <channel id>}`.
+
+- **HTML mode** (the default) sends htmx out-of-band swaps; the bundled UI
+  needs no client-side rendering.
+- **JSON mode** (`/ws/huddle/?format=json`) sends
+  `{"type": "message.created" | "message.updated" | "message.deleted", "message": {...}}`
+  and `{"type": "channel.updated", "channel": {...}}`, in the same shapes as
+  the REST API.
+
+If you already run your own consumer (for example, one socket per page that
+also carries notifications), mix in `huddle.consumers.HuddleConsumerMixin`,
+then call `huddle_connect()`, `huddle_receive(content)` and
+`huddle_disconnect()`.
+
+## Message format
+
+Bodies are stored as plain text with tokens: `<@user-pk>` for mentions, and
+`<#kind:id>` reserved for future references to your own objects. Rendering
+escapes everything else, so there's no HTML sanitiser to keep patched.
+
+## Settings
+
+| Setting | Default |
+|---|---|
+| `HUDDLE_POLICY` | `"huddle.policy.ChatPolicy"` |
+| `HUDDLE_BASE_TEMPLATE` | `"huddle/base.html"` (loads htmx from unpkg; replace it in production) |
+| `HUDDLE_PAGE_SIZE` | `50` |
+| `HUDDLE_MAX_MESSAGE_LENGTH` | `10000` |
+| `HUDDLE_WEBSOCKET_URL` | `"/ws/huddle/"` |
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run mypy src/ tests/ example/
+uv run ruff check . && uv run ruff format --check .
+uv run python manage.py migrate && uv run daphne example.asgi:application   # the example project
+```
+
+Design decisions are recorded in [`docs/adr/`](docs/adr/).
+
+## License
+
+MIT

django_huddle-0.1.0.dist-info/RECORD

@@ -0,0 +1,55 @@
+huddle/__init__.py,sha256=0HLLBdNuEpKpJJsHORyk6eeva8MLf-xrhJ6Gn6PQhrE,175
+huddle/apps.py,sha256=awGuyjNHR8aPFwZslIOQ06sL_H3Dvd553C63TVUGqUo,501
+huddle/conf.py,sha256=7WxuOCoNuUBuRF_SJQurxsxdsOon1obl-5pxVkZ1fT4,1724
+huddle/consumers.py,sha256=-MP0IMMIaBcaSxETRxC1x0UiXCwRgtzevvCQIdOQlXw,7501
+huddle/exceptions.py,sha256=naM--Tjh7WiRzLITdCKmUAKdrUh69pb-6YLNvWgk5Ik,1757
+huddle/forms.py,sha256=0VicA3Eh3W-8isM93FNYpgjX_qAiBFEEU0j5WAHH4Us,3216
+huddle/markup.py,sha256=oA7Jj7u8DaoIiDOPiS-guy5y2suEy-9u9fiBhnaVxM4,3959
+huddle/models.py,sha256=ZNAsfZD4lJLNLmhT0stv0taeUZ9QtSbqilw0Jc6ElvE,6999
+huddle/payloads.py,sha256=Ee5JGf0yibkuMbH4AJorjcf7sF4LEZFGi_6-CT2LeuI,3431
+huddle/policy.py,sha256=Q1xkMAJ6HIsTkdaAYhJuFSNjjcg-Hc1HtCR1bpXKvfE,5528
+huddle/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+huddle/querysets.py,sha256=D1B2YfuhZDyPB-KQyQ1fyC4Du-nAEtu7cwyBXfh5cek,4869
+huddle/realtime.py,sha256=G28KUaLsniXujBl7oxNEevmpU4lxVS5x5iPwBkQgQGg,2084
+huddle/rendering.py,sha256=_1JwZFOJI-mNdTIQDvdg2-KafC1tDRtbSr_i9WXqFp0,4433
+huddle/routing.py,sha256=DTXcszSpl4I2ra1BhU8fvd1jQEHxsYZ1A87LEAl_MsQ,282
+huddle/services.py,sha256=EGVp582ZojyBu4z7wcQXI-g07m6AZuIhQMdD-X1A-rs,11695
+huddle/signals.py,sha256=5IxESwrRm9Zi-JQHWq2RrW_e_vT6jYhGh0myN7wTlas,600
+huddle/urls.py,sha256=7YHjLyenX8Z6lRs3Ni6YgA7FdduisMLECQaIeZWi26U,1439
+huddle/views.py,sha256=mzFeoyaTeMDfEt7QHZdaOAKhZxZe6KptHfWvVW-35wE,17427
+huddle/api/__init__.py,sha256=52Bz6ZQrzIV41nwSLK_Itq1ZbmRxe1K2IQF549Ti9tA,157
+huddle/api/serializers.py,sha256=91WUN3kuuQ94H1u5b4MWA2MDXkY_wYX3mjDfbE07yVY,2025
+huddle/api/urls.py,sha256=LJ-X9ry0qdhc0eKcR3KWeS0ebd0jvR6MDA0s-PYWQWo,466
+huddle/api/views.py,sha256=ZKIzHIUTMjN_F7QiY27cNYmZcL87hqxNMDDT-eA_c0o,11319
+huddle/migrations/0001_initial.py,sha256=LxqwISpxUvbLo2pBuxw_9NdJuB3JiWdZ-ju0psub46M,6684
+huddle/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+huddle/static/huddle/huddle.css,sha256=MNG1kl9-bwzjXc4BHPEyURZxzqL2s_PNfEJ8PDvesZw,4312
+huddle/static/huddle/huddle.js,sha256=9tl9hCSz7hdRagV4xdUbcSs-VZbAjvGr67hHELsLFWU,4103
+huddle/templates/huddle/base.html,sha256=5hY4_i8zw_lwiQqJH3nQAszlnUHeawce1185yeuOoes,404
+huddle/templates/huddle/browse_page.html,sha256=gfigG55XgzkwtG3YtrVNuaPsyXCE_AhIxkSl9l4_DiM,123
+huddle/templates/huddle/channel_page.html,sha256=3FhkrA_8pdJFQetfuIM27Ftsdz3y-tMePb0nIDLyw6s,124
+huddle/templates/huddle/create_channel_page.html,sha256=f5iJGeFev07oO9VeXAqCJB7VogOQKoePVqJLjT2E64o,363
+huddle/templates/huddle/home_page.html,sha256=tdGm31Sy-mufBGDf0CesWMM6KpraUVrQ9QdQ1fStzHE,481
+huddle/templates/huddle/layout.html,sha256=vAAij05sxmHApYZSz-m9jgGCvmqv9ejeimL83S3kHnw,567
+huddle/templates/huddle/new_direct_page.html,sha256=-cgHHSumn7Oedk5381CL5H34Z-PTUs7JTmd-t-CD_L0,373
+huddle/templates/huddle/components/browse_list.html,sha256=5QrEVoDe9SZK05OV8rxeOk_geNC_RcSDS7JE6XDRmpg,830
+huddle/templates/huddle/components/channel_pane.html,sha256=gaeFqfYzcqrbcoBP7W6rzSCflU094Ou3G7xrxGR4B2A,1000
+huddle/templates/huddle/components/composer.html,sha256=7rq855PbzHmwAiIYGZIyIQabYlMO7gXLoeaZpYSwvE0,325
+huddle/templates/huddle/components/composer_fields.html,sha256=ifK5pDkK72Dag993v5k9Bkzda8D3GdKMdVfZYuNgsrY,266
+huddle/templates/huddle/components/edit_form.html,sha256=7ujbf3huH-xoXuCPmVAgVBlG-vVtEfpLb1W1Co9jQuw,565
+huddle/templates/huddle/components/mention_results.html,sha256=MGWu5ANa3Wl2vUFSgmPIe_4rt37kIfEYDxO08TSS9D8,316
+huddle/templates/huddle/components/message.html,sha256=QmCLe-oZiArB-mruH_wwTaiP8NpuDzAeLxhvZFbQQPw,1996
+huddle/templates/huddle/components/posted.html,sha256=vAf2MnjgyhP6Qhl8i9Z8eWPUdB7TC33m6Zq5wcwC1M8,164
+huddle/templates/huddle/components/replied.html,sha256=E2-17SnWbjcouqXgqL03yGVKEN5Lx7CUR3RLH3qmn-w,175
+huddle/templates/huddle/components/reply_composer.html,sha256=rHCyZa_di3KpaZNkh-7QTH1SY9VdcYfrcjMMJ8WnX4U,378
+huddle/templates/huddle/components/sidebar.html,sha256=lbTq273pwLozUF9bcDroUIgWRrUAFDQugfz2i2IaQns,1089
+huddle/templates/huddle/components/sidebar_entry.html,sha256=px_Pxf8P-nEeF6PAz8qLYfZxsSFF-m595mq78qz4E_Q,537
+huddle/templates/huddle/components/thread.html,sha256=XmB_y1WYYwUfyX4gkMHkfJqD0ycvY2GYQzM1vwj6ums,711
+huddle/templates/huddle/components/thread_summary.html,sha256=u-BZ2f8DzZmFp-VVvHnZYGWKiSGoPj1XYie48Kd6B-k,461
+huddle/templates/huddle/components/timeline_page.html,sha256=w8rqev1OGWBs2UJ8bpAiqehYBM-ddX_BfuvY17ylQ44,453
+huddle/templates/huddle/components/ws_message.html,sha256=VwaC_42RkuSjlw_EGahPBLA4k-yAFLm1UVajLySk3Vc,661
+huddle/templates/huddle/components/ws_sidebar_entry.html,sha256=WmcA-rtVu3jbNNlNwCbiW7Ro3j4cXkgaFrGz1PDsd9Q,180
+django_huddle-0.1.0.dist-info/METADATA,sha256=nW05LGW-g36qyoZy-yiJT8vfgQsHWy1C1ywjAahS05s,10504
+django_huddle-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+django_huddle-0.1.0.dist-info/licenses/LICENSE,sha256=p7fI6PkctPIJ79gN-RSAMlxnM4r3vtf3-r6dOEjXyA8,1070
+django_huddle-0.1.0.dist-info/RECORD,,

django_huddle-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

django_huddle-0.1.0.dist-info/licenses/LICENSE

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

huddle/__init__.py

@@ -0,0 +1,6 @@
+"""Slack-style team chat for Django: channels, direct messages, threads and @mentions."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

huddle/api/__init__.py

@@ -0,0 +1,4 @@
+"""Optional REST API for custom frontends. Needs ``pip install django-huddle[api]``.
+
+Include it with ``path("api/chat/", include("huddle.api.urls"))``.
+"""

huddle/api/serializers.py

@@ -0,0 +1,50 @@
+"""Input serializers for the REST API.
+
+Responses are built by :class:`~huddle.payloads.ChatPayloads` (shared with the
+websocket JSON mode); these serializers only validate what clients send.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rest_framework import serializers
+
+from huddle.conf import get_setting
+from huddle.forms import ChannelForm
+
+
+class MessageInputSerializer(serializers.Serializer[Any]):
+    """A new or edited message. ``mention_ids`` are the users the client chose to @mention."""
+
+    text = serializers.CharField(trim_whitespace=True)
+    mention_ids = serializers.ListField(child=serializers.CharField(), required=False, default=list)
+    parent_id = serializers.IntegerField(required=False, allow_null=True, default=None)
+
+    def validate_text(self, value: str) -> str:
+        """Enforce ``HUDDLE_MAX_MESSAGE_LENGTH``."""
+        limit = get_setting("HUDDLE_MAX_MESSAGE_LENGTH")
+        if len(value) > limit:
+            raise serializers.ValidationError(f"Ensure this field has no more than {limit} characters.")
+        return value
+
+
+class ChannelInputSerializer(serializers.Serializer[Any]):
+    """A new named channel. Names are normalised the same way as in the HTML form."""
+
+    name = serializers.CharField(max_length=80)
+    topic = serializers.CharField(max_length=250, required=False, allow_blank=True, default="")
+    is_private = serializers.BooleanField(required=False, default=False)
+
+    def validate_name(self, value: str) -> str:
+        """Normalise to Slack style via :class:`~huddle.forms.ChannelForm`."""
+        form = ChannelForm({"name": value, "topic": ""})
+        if not form.is_valid() and "name" in form.errors:
+            raise serializers.ValidationError([str(error) for error in form.errors["name"]])
+        return str(form.cleaned_data["name"])
+
+
+class DirectInputSerializer(serializers.Serializer[Any]):
+    """The other people in a direct message."""
+
+    user_ids = serializers.ListField(child=serializers.CharField(), min_length=1)

huddle/api/urls.py

@@ -0,0 +1,16 @@
+"""REST API routes. Include with ``path("api/chat/", include("huddle.api.urls"))``."""
+
+from __future__ import annotations
+
+from rest_framework.routers import SimpleRouter
+
+from huddle.api.views import ChannelViewSet
+from huddle.api.views import MessageViewSet
+
+app_name = "huddle-api"
+
+router = SimpleRouter()
+router.register("channels", ChannelViewSet, basename="channel")
+router.register("messages", MessageViewSet, basename="message")
+
+urlpatterns = router.urls