django-scope 0.1.0__tar.gz

django_scope-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+*.sqlite3
+db.sqlite3
+node_modules/
+frontend/dist/
+.DS_Store
+*.swp
+*.swo
+.idea/
+.vscode/
+*.log
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+htmlcov/
+.coverage

django_scope-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MythicalCosmic
+
+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_scope-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: django-scope
+Version: 0.1.0
+Summary: An elegant debug assistant for Django, inspired by Laravel Telescope
+Author: cosmic
+License-Expression: MIT
+License-File: LICENSE
+Keywords: debug,django,monitoring,profiling,telescope
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 6
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Requires-Dist: build>=1.4.2
+Requires-Dist: channels>=4.0
+Requires-Dist: daphne>=4.2.1
+Requires-Dist: django>=4.2
+Requires-Dist: setuptools>=82.0.1
+Requires-Dist: twine>=6.2.0
+Requires-Dist: wheel>=0.46.3
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-django; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# django-telescope
+
+An elegant debug assistant for Django, inspired by Laravel Telescope.
+
+## Installation
+
+```bash
+pip install django-telescope
+```
+
+Add to your Django settings:
+
+```python
+INSTALLED_APPS = [
+    "daphne",
+    "telescope",
+    # ... your apps
+]
+
+TELESCOPE = {
+    "ENABLED": True,
+}
+```
+
+Add the middleware:
+
+```python
+MIDDLEWARE = [
+    "telescope.middleware.TelescopeMiddleware",
+    # ... other middleware
+]
+```
+
+Add URL routing:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    path("telescope/", include("telescope.urls")),
+]
+```
+
+## Features
+
+- Real-time monitoring via WebSockets
+- 17 watchers: requests, queries, exceptions, models, logs, cache, mail, Redis, views, events, commands, dumps, HTTP client, gates, notifications, schedules, batches
+- N+1 query detection
+- Beautiful Vue.js dashboard with dark/light themes
+- Request-scoped buffering with bulk writes

django_scope-0.1.0/README.md

@@ -0,0 +1,50 @@
+# django-telescope
+
+An elegant debug assistant for Django, inspired by Laravel Telescope.
+
+## Installation
+
+```bash
+pip install django-telescope
+```
+
+Add to your Django settings:
+
+```python
+INSTALLED_APPS = [
+    "daphne",
+    "telescope",
+    # ... your apps
+]
+
+TELESCOPE = {
+    "ENABLED": True,
+}
+```
+
+Add the middleware:
+
+```python
+MIDDLEWARE = [
+    "telescope.middleware.TelescopeMiddleware",
+    # ... other middleware
+]
+```
+
+Add URL routing:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    path("telescope/", include("telescope.urls")),
+]
+```
+
+## Features
+
+- Real-time monitoring via WebSockets
+- 17 watchers: requests, queries, exceptions, models, logs, cache, mail, Redis, views, events, commands, dumps, HTTP client, gates, notifications, schedules, batches
+- N+1 query detection
+- Beautiful Vue.js dashboard with dark/light themes
+- Request-scoped buffering with bulk writes

django_scope-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "django-scope"
+version = "0.1.0"
+description = "An elegant debug assistant for Django, inspired by Laravel Telescope"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "cosmic" }]
+keywords = ["django", "debug", "telescope", "monitoring", "profiling"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Django",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 5.1",
+    "Framework :: Django :: 6",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Debuggers",
+]
+dependencies = [
+    "django>=4.2",
+    "channels>=4.0",
+    "daphne>=4.2.1",
+    "setuptools>=82.0.1",
+    "wheel>=0.46.3",
+    "twine>=6.2.0",
+    "build>=1.4.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-django",
+    "pytest-asyncio",
+    "ruff",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/telescope"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/telescope/**", "LICENSE", "README.md"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = ["src", "."]
+
+[tool.ruff]
+src = ["src"]
+line-length = 120
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-django>=4.12.0",
+]

django_scope-0.1.0/src/telescope/__init__.py

@@ -0,0 +1,35 @@
+default_app_config = "telescope.apps.TelescopeConfig"
+
+
+def dump(value, *, label=None):
+    """Public API: record a dump entry from user code."""
+    import inspect
+    from .entry_type import EntryType
+    from .recorder import Recorder
+
+    frame = inspect.currentframe().f_back
+    caller = f"{frame.f_code.co_filename}:{frame.f_lineno}"
+
+    Recorder.record(
+        entry_type=EntryType.DUMP,
+        content={
+            "dump": repr(value),
+            "label": label,
+            "caller": caller,
+        },
+    )
+
+
+def notify(notification_class, recipient, channels=None):
+    """Public API: record a notification entry."""
+    from .entry_type import EntryType
+    from .recorder import Recorder
+
+    Recorder.record(
+        entry_type=EntryType.NOTIFICATION,
+        content={
+            "notification": notification_class.__name__ if isinstance(notification_class, type) else str(notification_class),
+            "recipient": str(recipient),
+            "channels": channels or [],
+        },
+    )

django_scope-0.1.0/src/telescope/apps.py

@@ -0,0 +1,15 @@
+from django.apps import AppConfig
+
+
+class TelescopeConfig(AppConfig):
+    name = "telescope"
+    default_auto_field = "django.db.models.BigAutoField"
+    verbose_name = "Django Telescope"
+
+    def ready(self):
+        from .settings import get_config
+
+        if get_config("ENABLED"):
+            from .watchers import WatcherRegistry
+
+            WatcherRegistry.register_all()

django_scope-0.1.0/src/telescope/backends/cache_backend.py

@@ -0,0 +1,97 @@
+import time
+
+from django.core.cache.backends.locmem import LocMemCache
+
+
+class TelescopeCacheBackend(LocMemCache):
+    """Wrapping cache backend that records all cache operations."""
+
+    def __init__(self, server, params):
+        # The actual backend class to wrap can be specified in OPTIONS
+        self._telescope_alias = params.get("telescope_alias", "default")
+        actual_backend = params.pop("TELESCOPE_BACKEND", None)
+
+        if actual_backend:
+            # Dynamically instantiate the real backend
+            from django.utils.module_loading import import_string
+
+            backend_cls = import_string(actual_backend)
+            self._real_cache = backend_cls(server, params)
+        else:
+            super().__init__(server, params)
+            self._real_cache = None
+
+    def _get_backend(self):
+        return self._real_cache if self._real_cache else self
+
+    def get(self, key, default=None, version=None):
+        start = time.perf_counter()
+        backend = self._get_backend()
+        if backend is self:
+            value = super().get(key, default, version)
+        else:
+            value = backend.get(key, default, version)
+        duration_ms = (time.perf_counter() - start) * 1000
+
+        from ..watchers.cache_watcher import CacheWatcher
+
+        CacheWatcher.record_operation(
+            operation="get",
+            key=key,
+            value=value,
+            hit=value is not default,
+            duration_ms=duration_ms,
+            backend_alias=self._telescope_alias,
+        )
+        return value
+
+    def set(self, key, value, timeout=None, version=None):
+        start = time.perf_counter()
+        backend = self._get_backend()
+        if backend is self:
+            result = super().set(key, value, timeout, version)
+        else:
+            result = backend.set(key, value, timeout, version)
+        duration_ms = (time.perf_counter() - start) * 1000
+
+        from ..watchers.cache_watcher import CacheWatcher
+
+        CacheWatcher.record_operation(
+            operation="set",
+            key=key,
+            value=value,
+            duration_ms=duration_ms,
+            backend_alias=self._telescope_alias,
+        )
+        return result
+
+    def delete(self, key, version=None):
+        start = time.perf_counter()
+        backend = self._get_backend()
+        if backend is self:
+            result = super().delete(key, version)
+        else:
+            result = backend.delete(key, version)
+        duration_ms = (time.perf_counter() - start) * 1000
+
+        from ..watchers.cache_watcher import CacheWatcher
+
+        CacheWatcher.record_operation(
+            operation="delete",
+            key=key,
+            duration_ms=duration_ms,
+            backend_alias=self._telescope_alias,
+        )
+        return result
+
+    def clear(self):
+        backend = self._get_backend()
+        if backend is self:
+            result = super().clear()
+        else:
+            result = backend.clear()
+
+        from ..watchers.cache_watcher import CacheWatcher
+
+        CacheWatcher.record_operation(operation="clear", key="*")
+        return result

django_scope-0.1.0/src/telescope/backends/mail_backend.py

@@ -0,0 +1,13 @@
+from django.core.mail.backends.smtp import EmailBackend
+
+
+class TelescopeMailBackend(EmailBackend):
+    """Wrapping mail backend that records all sent emails."""
+
+    def send_messages(self, email_messages):
+        from ..watchers.mail_watcher import MailWatcher
+
+        for message in email_messages:
+            MailWatcher.record_mail(message)
+
+        return super().send_messages(email_messages)

django_scope-0.1.0/src/telescope/consumers/telescope_consumer.py

@@ -0,0 +1,39 @@
+import json
+import logging
+
+from channels.generic.websocket import AsyncJsonWebsocketConsumer
+
+logger = logging.getLogger("telescope.consumers")
+
+
+class TelescopeConsumer(AsyncJsonWebsocketConsumer):
+    """WebSocket consumer for real-time telescope entry updates."""
+
+    async def connect(self):
+        await self.channel_layer.group_add("telescope", self.channel_name)
+        await self.accept()
+        logger.debug("Telescope WebSocket connected: %s", self.channel_name)
+
+    async def disconnect(self, close_code):
+        await self.channel_layer.group_discard("telescope", self.channel_name)
+        logger.debug("Telescope WebSocket disconnected: %s", self.channel_name)
+
+    async def receive_json(self, content, **kwargs):
+        # Client can send filter preferences
+        msg_type = content.get("type")
+        if msg_type == "filter":
+            # Store filter preferences on the consumer instance
+            self._filters = content.get("filters", {})
+
+    async def telescope_entry(self, event):
+        """Handle new telescope entry broadcast."""
+        entry = event.get("entry", {})
+
+        # Apply client-side filters if set
+        if hasattr(self, "_filters") and self._filters:
+            entry_type = entry.get("type_slug")
+            allowed_types = self._filters.get("types")
+            if allowed_types and entry_type not in allowed_types:
+                return
+
+        await self.send_json({"type": "entry", "data": entry})

django_scope-0.1.0/src/telescope/context.py

@@ -0,0 +1,37 @@
+import uuid
+from contextvars import ContextVar
+
+# Unique ID grouping all entries from the same request/command
+batch_id_var: ContextVar[str | None] = ContextVar("telescope_batch_id", default=None)
+
+# Buffer of entries to be flushed at end of request
+buffer_var: ContextVar[list | None] = ContextVar("telescope_buffer", default=None)
+
+# Whether recording is active for this scope
+recording_var: ContextVar[bool] = ContextVar("telescope_recording", default=True)
+
+
+def start_scope():
+    """Begin a new telescope scope (called at request start)."""
+    batch_id_var.set(str(uuid.uuid4()))
+    buffer_var.set([])
+    recording_var.set(True)
+
+
+def end_scope():
+    """End the current telescope scope."""
+    batch_id_var.set(None)
+    buffer_var.set(None)
+    recording_var.set(True)
+
+
+def get_batch_id():
+    return batch_id_var.get()
+
+
+def get_buffer():
+    return buffer_var.get()
+
+
+def is_recording():
+    return recording_var.get()

django_scope-0.1.0/src/telescope/db_router.py

@@ -0,0 +1,31 @@
+from .settings import get_config
+
+APP_LABEL = "telescope"
+
+
+class TelescopeRouter:
+    """Routes telescope models to a separate database if configured."""
+
+    def _db(self):
+        return get_config("DB_CONNECTION")
+
+    def db_for_read(self, model, **hints):
+        if model._meta.app_label == APP_LABEL:
+            return self._db()
+        return None
+
+    def db_for_write(self, model, **hints):
+        if model._meta.app_label == APP_LABEL:
+            return self._db()
+        return None
+
+    def allow_relation(self, obj1, obj2, **hints):
+        if obj1._meta.app_label == APP_LABEL or obj2._meta.app_label == APP_LABEL:
+            return True
+        return None
+
+    def allow_migrate(self, db, app_label, model_name=None, **hints):
+        target = self._db() or "default"
+        if app_label == APP_LABEL:
+            return db == target
+        return None

django_scope-0.1.0/src/telescope/entry_type.py

@@ -0,0 +1,34 @@
+from enum import IntEnum
+
+
+class EntryType(IntEnum):
+    REQUEST = 1
+    QUERY = 2
+    EXCEPTION = 3
+    MODEL = 4
+    LOG = 5
+    CACHE = 6
+    REDIS = 7
+    MAIL = 8
+    VIEW = 9
+    EVENT = 10
+    COMMAND = 11
+    DUMP = 12
+    CLIENT_REQUEST = 13
+    GATE = 14
+    NOTIFICATION = 15
+    SCHEDULE = 16
+    BATCH = 17
+
+    @property
+    def label(self):
+        return self.name.replace("_", " ").title()
+
+    @property
+    def slug(self):
+        return self.name.lower().replace("_", "-")
+
+    @classmethod
+    def from_slug(cls, slug):
+        name = slug.upper().replace("-", "_")
+        return cls[name]

django_scope-0.1.0/src/telescope/filtering.py

@@ -0,0 +1,56 @@
+from django.db.models import Q
+
+from .entry_type import EntryType
+from .models import TelescopeEntry
+
+
+def apply_filters(queryset, params):
+    """Apply query filters from request parameters."""
+
+    # Filter by entry type
+    entry_type = params.get("type")
+    if entry_type:
+        try:
+            et = EntryType.from_slug(entry_type)
+            queryset = queryset.filter(type=et.value)
+        except (KeyError, ValueError):
+            pass
+
+    # Filter by tag
+    tag = params.get("tag")
+    if tag:
+        queryset = queryset.filter(tags__tag=tag)
+
+    # Filter by batch_id
+    batch_id = params.get("batch_id")
+    if batch_id:
+        queryset = queryset.filter(batch_id=batch_id)
+
+    # Filter by family_hash
+    family_hash = params.get("family_hash")
+    if family_hash:
+        queryset = queryset.filter(family_hash=family_hash)
+
+    # Search in content (JSON contains)
+    search = params.get("search")
+    if search:
+        queryset = queryset.filter(
+            Q(content__icontains=search) | Q(tags__tag__icontains=search)
+        ).distinct()
+
+    # Cursor-based pagination (before=<id>)
+    before = params.get("before")
+    if before:
+        try:
+            queryset = queryset.filter(id__lt=int(before))
+        except (ValueError, TypeError):
+            pass
+
+    # Limit
+    limit = params.get("limit", 50)
+    try:
+        limit = min(int(limit), 100)
+    except (ValueError, TypeError):
+        limit = 50
+
+    return queryset[:limit]

django_scope-0.1.0/src/telescope/management/commands/telescope_clear.py

@@ -0,0 +1,29 @@
+from django.core.management.base import BaseCommand
+
+from telescope.entry_type import EntryType
+from telescope.pruning import clear_entries
+
+
+class Command(BaseCommand):
+    help = "Clear all telescope entries"
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--type",
+            type=str,
+            default=None,
+            help="Only clear entries of this type (e.g. 'request', 'query')",
+        )
+
+    def handle(self, *args, **options):
+        entry_type = None
+        type_slug = options["type"]
+        if type_slug:
+            try:
+                entry_type = EntryType.from_slug(type_slug).value
+            except (KeyError, ValueError):
+                self.stderr.write(self.style.ERROR(f"Invalid type: {type_slug}"))
+                return
+
+        count = clear_entries(entry_type=entry_type)
+        self.stdout.write(self.style.SUCCESS(f"Cleared {count} telescope entries"))

django_scope-0.1.0/src/telescope/management/commands/telescope_prune.py

@@ -0,0 +1,21 @@
+from django.core.management.base import BaseCommand
+
+from telescope.pruning import prune_entries
+from telescope.settings import get_config
+
+
+class Command(BaseCommand):
+    help = "Prune old telescope entries"
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--hours",
+            type=int,
+            default=None,
+            help=f"Delete entries older than N hours (default: {get_config('ENTRY_LIFETIME_HOURS')})",
+        )
+
+    def handle(self, *args, **options):
+        hours = options["hours"]
+        count = prune_entries(hours=hours)
+        self.stdout.write(self.style.SUCCESS(f"Pruned {count} telescope entries"))

django_scope-0.1.0/src/telescope/middleware/__init__.py

@@ -0,0 +1,3 @@
+from .telescope_middleware import TelescopeMiddleware
+
+__all__ = ["TelescopeMiddleware"]