django-huddle 0.1.0__tar.gz

django_huddle-0.1.0/.editorconfig

@@ -0,0 +1,37 @@
+# https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{html,css,js,json,sh,yml,yaml}]
+indent_size = 2
+
+[*.bat]
+indent_style = tab
+end_of_line = crlf
+
+[LICENSE]
+insert_final_newline = false
+
+[justfile]
+indent_style = space
+indent_size = 4
+
+# Ignore binary or generated files
+[*.{png,jpg,gif,ico,woff,woff2,ttf,eot,svg,pdf}]
+charset = unset
+end_of_line = unset
+indent_style = unset
+indent_size = unset
+trim_trailing_whitespace = unset
+insert_final_newline = unset
+max_line_length = unset
+
+[*.{diff,patch}]
+trim_trailing_whitespace = false

django_huddle-0.1.0/.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "07:00"
+      timezone: Europe/London
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 5
+
+  # Cooldown matches exclude-newer in pyproject.toml, so uv can always lock it.
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "07:00"
+      timezone: Europe/London
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 5

django_huddle-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+## What
+
+<!-- 1-3 sentences. Link the issue if there is one. -->
+
+## AI Provenance
+
+<!-- Remove this section for human-authored PRs. -->
+
+- **Tool:** <!-- Claude Code, Cursor, Copilot, Codex, etc. -->
+- **Model:** <!-- Claude Opus 4.6, GPT-4o, etc. -->
+- **Prompt/thread:** <!-- Paste your prompt or a link to the thread. -->
+
+## Checklist
+
+- [ ] Addresses exactly one issue or feature
+- [ ] New or changed behavior has test coverage
+- [ ] Diff contains only changes for this task

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

@@ -0,0 +1,120 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+  type-check:
+    name: Type check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+
+      - name: Type check with mypy
+        run: uv run mypy src/ tests/ example/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+
+      - name: Run tox envs for Python ${{ matrix.python-version }}
+        run: uvx --with tox-uv tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
+
+      - name: Upload coverage data
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: .coverage.*
+          include-hidden-files: true
+          if-no-files-found: error
+
+  coverage:
+    name: Coverage
+    needs: [test]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+
+      - name: Download coverage data
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: coverage-*
+          merge-multiple: true
+
+      - name: Combine coverage
+        run: uv run coverage combine
+
+      - name: Coverage report
+        run: |
+          echo '## Coverage Report' >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          uv run coverage report | tee -a $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+
+  all-checks-pass:
+    name: All checks pass
+    if: always()
+    needs: [lint, type-check, test, coverage]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check job results
+        uses: re-actors/alls-green@b5b5b37504aa4183270bd3d855c52a67f212be35 # v1.3.0
+        with:
+          jobs: ${{ toJSON(needs) }}

django_huddle-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,34 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 6 * * 1'
+
+permissions: {}
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+        with:
+          languages: python  # Add c-cpp, go, java-kotlin, or swift if needed
+          build-mode: none   # Switch to autobuild for compiled languages
+          queries: security-extended
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9

django_huddle-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions: {}
+
+concurrency:
+  group: publish
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      # Cache disabled to prevent cache-poisoning attacks on release artifacts.
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: false
+
+      - name: Build
+        run: uv build
+
+      - name: Upload distribution
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      attestations: write
+    # Needs Settings > Environments > pypi: reviewers + v* tag restriction.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/django-huddle
+    steps:
+      - name: Download distribution
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-path: "dist/*"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

django_huddle-0.1.0/.github/workflows/zizmor.yml

@@ -0,0 +1,36 @@
+name: Workflow security analysis
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/**"
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
+    paths:
+      - ".github/workflows/**"
+
+permissions: {}
+
+jobs:
+  zizmor:
+    name: Run zizmor
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Run zizmor
+        uses: zizmorcore/zizmor-action@70fb788f84895a7701f5643d103d587e460b5c99 # v0.6.3
+        with:
+          inputs: ./.github/

django_huddle-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+build/
+dist/
+eggs/
+.eggs/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+coverage.xml
+.hypothesis/
+.pytest_cache/
+
+# Environments
+.env
+.envrc
+.venv
+
+# uv
+#   Generally recommended to include uv.lock in version control for
+#   reproducibility. Uncomment for libraries where you want consumers
+#   to resolve their own dependencies.
+# uv.lock
+
+# Ruff
+.ruff_cache/
+
+# Type checkers
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# Example project local database
+example/db.sqlite3
+
+# Documentation build output
+site/
+
+# IDE files
+# .idea/
+# .vscode/
+
+# Local agent guidance (not a committed team convention)
+CLAUDE.md
+example/db.sqlite3
+.venv/
+site/

django_huddle-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,45 @@
+ci:
+  autoupdate_schedule: monthly
+  skip: [mypy]
+
+default_language_version:
+  python: python3.13
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c  # frozen: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/tox-dev/pyproject-fmt
+    rev: 3b42b9776870badc9eaffdef9a4a0834b764d87c  # frozen: v2.29.3
+    hooks:
+      - id: pyproject-fmt
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 321478e58f4938179c6b86e4ddfa923d1547a49b  # frozen: v0.16.6
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/adamchainz/django-upgrade
+    rev: e668ea858b908d23a9702b24214f4fc5d07ed50f  # frozen: 1.32.0
+    hooks:
+      - id: django-upgrade
+        args: [--target-version, "6.0"]
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy src/ tests/ example/
+        language: system
+        types: [python]
+        pass_filenames: false

django_huddle-0.1.0/AGENTS.md

@@ -0,0 +1,44 @@
+# django-huddle — agent guidance
+
+A public, MIT-licensed Django package providing Slack-style chat (channels, DMs,
+threads, @mentions) over Django Channels. Other projects depend on it, so the
+**public API is a maintenance promise**.
+
+## Commands
+
+```bash
+uv run pytest                                  # quick run
+uvx --with tox-uv tox run -f py314             # Django 6.0 + 6.1 matrix
+uv run ruff format . && uv run ruff check --fix .
+uv run mypy src/ tests/ example/
+pre-commit run --all-files                     # before every commit
+```
+
+## Invariants
+
+1. **Every permission decision goes through `ChatPolicy`** (ADR-0002). Never add
+   an inline `if user ...` access check in a view, API view or consumer. Add or
+   extend a policy method instead.
+2. **Invisible means 404.** Look channels and messages up through
+   `Channel.objects.visible_to(user)`.
+3. **Every write goes through `ChatService`.** It keeps counters and read state
+   consistent and sends signals and broadcasts on commit.
+4. **Websocket events carry ids, never HTML** (ADR-0003). Each connection
+   re-checks and re-renders for its own user.
+5. **Three outputs, two builders** (ADR-0005). Templates use `ChatRenderer`
+   view models; the REST API and websocket JSON use `ChatPayloads`. Keep them in
+   step.
+6. **Stored bodies are tokens plus plain text** (ADR-0004). Never store HTML.
+
+## Style
+
+- Django 6+, Python 3.12+, `from __future__ import annotations`, mypy strict.
+- Query logic lives on QuerySets (`querysets.py`), with docstrings saying what
+  each method selects and where it's used.
+- Guard clauses, max nesting depth 2, intention-revealing names.
+- Docstrings carry the why. `#` comments are one line at most. No comments in
+  templates, JS or CSS unless essential.
+- Each failure mode gets its own exception under `HuddleError`, carrying
+  `context`.
+- One template per UI component under `templates/huddle/components/`.
+- Every PR carries an ADR in `docs/adr/` for each distinct decision.

django_huddle-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First release.
+
+- Channels (public and private), direct and group messages, one-level threads, @mentions.
+- `ChatPolicy` permission hook with scoped channels.
+- `ChatService` for every write, with `message_posted`, `user_mentioned` and `thread_replied` signals.
+- htmx UI built from overridable component templates.
+- Websocket consumer (HTML or JSON mode) and `HuddleConsumerMixin`.
+- Optional REST API (`django-huddle[api]`).

django_huddle-0.1.0/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.