django-workspaces 0.0.1a1__py3-none-any.whl

django_workspaces/__init__.py

@@ -0,0 +1,80 @@
+"""Django reusable app to manage user workspaces.
+
+'Workspace' in this package is a unit of work. Each session always has one
+active workspace. Anything can be added to a workspace.
+"""
+
+from typing import TYPE_CHECKING, Any, cast
+
+import django_stubs_ext
+from django.apps import apps as django_apps
+from django.conf import settings
+from django.http import Http404, HttpRequest
+from django.shortcuts import aget_object_or_404, get_object_or_404
+
+from .signals import workspace_requested
+from .types import _Workspace, _WorkspaceModel
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import AbstractUser, AnonymousUser
+
+django_stubs_ext.monkeypatch()
+
+__all__ = [
+    "aget_workspace",
+    "get_workspace",
+    "get_workspace_model",
+    "workspace_requested",
+]
+
+SESSION_KEY = "_workspace_id"
+
+
+def get_workspace_model() -> _WorkspaceModel:
+    """Return the workspace model that is active for this project.
+
+    The workspace model defaults to :class:`django_workspaces.models.Workspace`, and can
+    be swapped through the ``WORKSPACE_MODEL`` setting.
+    """
+    workspace_model_name: str = getattr(settings, "WORKSPACE_MODEL", "django_workspaces.Workspace")
+    return django_apps.get_model(workspace_model_name, require_ready=False)
+
+
+def get_workspace(request: HttpRequest) -> _Workspace:
+    """Return the workspace model instance associated with the given request."""
+    Workspace: _WorkspaceModel = get_workspace_model()  # noqa: N806
+    user: AbstractUser | AnonymousUser = request.user
+
+    try:
+        workspace_id = Workspace._meta.pk.to_python(request.session[SESSION_KEY])  # noqa: SLF001
+    except KeyError as exc:
+        responses = workspace_requested.send(Workspace, user=user, request=request)
+        if not responses:
+            msg = "Could not find a workspace"
+            raise Http404(msg) from exc
+
+        _, workspace = cast("tuple[Any, _Workspace]", responses[0])
+    else:
+        workspace = get_object_or_404(Workspace, pk=workspace_id)
+
+    return workspace
+
+
+async def aget_workspace(request: HttpRequest) -> _Workspace:
+    """Async version of :func:`get_workspace`."""
+    Workspace: _WorkspaceModel = get_workspace_model()  # noqa: N806
+    user: AbstractUser | AnonymousUser = await request.auser()
+
+    session_workspace = await request.session.aget(SESSION_KEY)
+    if session_workspace is None:
+        responses = await workspace_requested.asend(Workspace, user=user, request=request)
+        if not responses:
+            msg = "Could not find a workspace"
+            raise Http404(msg)
+
+        _, workspace = cast("tuple[Any, _Workspace]", responses[0])
+    else:
+        workspace_id = Workspace._meta.pk.to_python(session_workspace)  # noqa: SLF001
+        workspace = await aget_object_or_404(Workspace, pk=workspace_id)
+
+    return workspace

django_workspaces/_compat.py

@@ -0,0 +1,17 @@
+import sys
+
+if sys.version_info >= (3, 12):
+    from inspect import iscoroutinefunction, markcoroutinefunction
+else:
+    from asgiref.sync import iscoroutinefunction, markcoroutinefunction
+
+if sys.version_info >= (3, 13):
+    from typing import TypeIs
+else:
+    from typing_extensions import TypeIs
+
+__all__ = [
+    "TypeIs",
+    "iscoroutinefunction",
+    "markcoroutinefunction",
+]

django_workspaces/apps.py

@@ -0,0 +1,12 @@
+"""Read by Django to configure :mod:`django_workspaces`."""
+
+from django.apps import AppConfig
+from django.utils.translation import gettext_lazy as _
+
+
+class WorkspacesConfig(AppConfig):
+    """:mod:`django_workspaces` app configuration."""
+
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_workspaces"
+    verbose_name = _("Workspaces")

django_workspaces/middleware.py

@@ -0,0 +1,39 @@
+"""Workspace middlewares."""
+
+from collections.abc import Awaitable, Callable
+from functools import partial
+from typing import cast
+
+from django.core.exceptions import ImproperlyConfigured
+from django.http import HttpResponseBase
+from django.utils.decorators import sync_and_async_middleware
+from django.utils.functional import SimpleLazyObject
+
+from . import aget_workspace, get_workspace
+from ._compat import iscoroutinefunction, markcoroutinefunction
+from .types import HttpRequest, _Workspace
+
+_Middleware = Callable[[HttpRequest], HttpResponseBase] | Callable[[HttpRequest], Awaitable[HttpResponseBase]]
+
+
+@sync_and_async_middleware
+def workspace_middleware(get_response: _Middleware, /) -> _Middleware:
+    """Django middleware to add the current workspace to every request.
+
+    Adds the property `workspace` to use in sync contexts, and the
+    `aworkspace` corourine function for async contexts.
+    """
+
+    def middleware(request: HttpRequest) -> HttpResponseBase:
+        if not hasattr(request, "user"):
+            msg: str = "The workspace middleware requires Django's authentication middleware"
+            raise ImproperlyConfigured(msg)
+
+        request.workspace = cast("_Workspace", SimpleLazyObject(partial(get_workspace, request)))
+        request.aworkspace = partial(aget_workspace, request)
+        return get_response(request)  # type: ignore[return-value]
+
+    if iscoroutinefunction(get_response):
+        middleware = markcoroutinefunction(middleware)
+
+    return middleware

django_workspaces/migrations/0001_initial.py

@@ -0,0 +1,29 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="Workspace",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                (
+                    "name",
+                    models.CharField(
+                        db_comment="Workspace name",
+                        help_text="Required. 255 characters or fewer.",
+                        max_length=255,
+                        verbose_name="name",
+                    ),
+                ),
+            ],
+            options={
+                "abstract": False,
+                "swappable": "WORKSPACE_MODEL",
+            },
+        ),
+    ]

django_workspaces/models.py

@@ -0,0 +1,33 @@
+"""Workspace models."""
+
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+from django_stubs_ext.db.models import TypedModelMeta
+
+
+class AbstractWorkspace(models.Model):
+    """Abstract base class implementing a workspace.
+
+    Custom workspace models should inherit from this class.
+    """
+
+    name = models.CharField(
+        _("name"),
+        max_length=255,
+        help_text=_("Required. 255 characters or fewer."),
+        db_comment="Workspace name",
+    )
+
+    class Meta(TypedModelMeta):
+        abstract = True
+
+    def __str__(self) -> str:
+        """Return a string representation of the workspace."""
+        return self.name
+
+
+class Workspace(AbstractWorkspace):
+    """Default workspace model."""
+
+    class Meta(AbstractWorkspace.Meta):
+        swappable = "WORKSPACE_MODEL"

django_workspaces/py.typed

@@ -0,0 +1 @@
+PEP-561 marker file

django_workspaces/signals.py

@@ -0,0 +1,17 @@
+"""Dispatched signals."""
+
+from django.dispatch import Signal
+
+workspace_requested = Signal()
+"""Dispatched when a workspace is not found in the current session.
+
+This should look up the user's preferences to get the latest or default workspace.
+
+Args:
+    sender: The current workspace model.
+    user: The user requesting a workspace.
+    request: The current request. Optional.
+
+Returns:
+    A workspace instance if could find a default workspace. None otherwise.
+"""

django_workspaces/types.py

@@ -0,0 +1,23 @@
+"""Type helpers."""
+
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, TypeAlias
+
+from django.http import HttpRequest as DjangoHttpRequest
+
+if TYPE_CHECKING:
+    from .models import AbstractWorkspace
+
+_Workspace: TypeAlias = "AbstractWorkspace"
+"""Placeholder type for the current workspace.
+
+The mypy plugin will refine it someday."""
+
+_WorkspaceModel: TypeAlias = type[_Workspace]  # noqa: PYI047
+
+
+class HttpRequest(DjangoHttpRequest):
+    """HTTP request with workspace."""
+
+    workspace: _Workspace
+    aworkspace: Callable[[], Awaitable[_Workspace]]

django_workspaces-0.0.1a1.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: django-workspaces
+Version: 0.0.1a1
+Summary: Django reusable app to manage user workspaces
+Project-URL: Documentation, https://github.com/hartungstenio/django-workspaces#readme
+Project-URL: Issues, https://github.com/hartungstenio/django-workspaces/issues
+Project-URL: Source, https://github.com/hartungstenio/django-workspaces
+Author-email: Christian Hartung <hartung@live.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+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 :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: django
+Requires-Dist: django-stubs-ext
+Requires-Dist: typing-extensions; python_version < '3.13'
+Description-Content-Type: text/markdown
+
+# django-workspaces
+
+[![PyPI - Version](https://img.shields.io/pypi/v/django-workspaces.svg)](https://pypi.org/project/django-workspaces)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-workspaces.svg)](https://pypi.org/project/django-workspaces)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [License](#license)
+
+## Installation
+
+```console
+pip install django-workspaces
+```
+
+## License
+
+`django-workspaces` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

django_workspaces-0.0.1a1.dist-info/RECORD

@@ -0,0 +1,14 @@
+django_workspaces/__init__.py,sha256=hp5hUNZij9nR2iukGqbZAyxWMZxG2w3LCRxyfvNPG9o,2806
+django_workspaces/_compat.py,sha256=vLgdGvaSApBvHJZ3JK7S-dRk1v_TcFf81zyxHzE6NIE,384
+django_workspaces/apps.py,sha256=z6wVAXJjYHEg2UpyfDZY-YciGc4T46VxcBxHKXyRNkQ,365
+django_workspaces/middleware.py,sha256=-RSe99WOUk2fs32znJ9fuUdFGY-ZZFdzNWreub3WwHg,1504
+django_workspaces/models.py,sha256=EALgPW4gGw6CMMKqzagbzWLPO4I06-u6MLXa6BL_ymM,829
+django_workspaces/py.typed,sha256=Qn1PtAFCQCHxVY6FV1vsRH98Re39dTxwl3lQRksOGpY,20
+django_workspaces/signals.py,sha256=aspua_A38H-QSym7qiZ5SOE7jB50SY3S3m2N4Tzxj5w,471
+django_workspaces/types.py,sha256=JawPN4lIPKDERS4pm83z44sy7ea2MmOUFJbjAwQQ4YA,589
+django_workspaces/migrations/0001_initial.py,sha256=FKwAb9uyrYVhBi6PznmG9skoXLV2bwO0SKw-mUUGfVA,833
+django_workspaces/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_workspaces-0.0.1a1.dist-info/METADATA,sha256=A--DX4jj1QKAc6ssZXfYW0fRHVbUXNLG8QXUkE_6DD8,1930
+django_workspaces-0.0.1a1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+django_workspaces-0.0.1a1.dist-info/licenses/LICENSE.txt,sha256=kw90zQM3KTw6c7cenDnJY8bGSv6MM46DpIXHiU9g_h8,1101
+django_workspaces-0.0.1a1.dist-info/RECORD,,

django_workspaces-0.0.1a1.dist-info/WHEEL

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

django_workspaces-0.0.1a1.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025-present Christian Hartung <hartung@live.com>
+
+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.