django-pyrepl-hacks 0.1.0__py3-none-any.whl

django_pyrepl_hacks/__init__.py

@@ -0,0 +1,13 @@
+"""A Django shell that uses the new Python REPL, with pyrepl-hacks key bindings.
+
+Add ``"django_pyrepl_hacks"`` to ``INSTALLED_APPS`` and ``manage.py shell``
+will launch the new Python REPL (``_pyrepl``) with Django's auto-imported
+models and a set of extra key bindings.
+
+Everything is configurable through ``PYREPL_*`` settings.
+See the README for the full list.
+"""
+
+from .bindings import Insert, insert
+
+__all__ = ["Insert", "insert"]

django_pyrepl_hacks/apps.py

@@ -0,0 +1,16 @@
+"""The app config, which exists to register the settings checks."""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+from django.core.checks import register
+
+from .checks import check_settings
+
+
+class PyreplHacksConfig(AppConfig):
+    name = "django_pyrepl_hacks"
+    verbose_name = "Python REPL hacks"
+
+    def ready(self) -> None:
+        register(check_settings)

django_pyrepl_hacks/bindings.py

@@ -0,0 +1,126 @@
+"""Key bindings for the pyrepl-powered Django shell.
+
+Nothing in this module imports ``pyrepl_hacks`` (and therefore ``_pyrepl``) at
+import time.
+Settings modules import ``insert`` from this package, and importing a private
+stdlib module as a side effect of reading settings would be rude.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+
+from django.core.exceptions import ImproperlyConfigured
+
+__all__ = ["DEFAULT_BINDINGS", "Insert", "apply_bindings", "insert", "resolve_bindings"]
+
+
+@dataclass(frozen=True)
+class Insert:
+    """A binding that inserts literal text at the cursor."""
+
+    text: str
+
+
+def insert(text: str) -> Insert:
+    """Return a binding that inserts ``text`` at the cursor.
+
+    Meant for use in the ``PYREPL_BINDINGS`` setting:
+
+        PYREPL_BINDINGS = {"Ctrl+N": insert("[2, 1, 3, 4, 7, 11, 18, 29]")}
+    """
+    return Insert(text)
+
+
+#: A binding target: a command name, literal text to insert, or a function.
+type Binding = str | Insert | Callable[..., None]
+
+
+DEFAULT_BINDINGS: dict[str, Binding] = {
+    "Home": "home",
+    "End": "end",
+    "Alt+M": "move-to-indentation",
+    "Shift+Tab": "dedent",
+    "Alt+Down": "move-line-down",
+    "Alt+Up": "move-line-up",
+    "Ctrl+Up": "previous-history",
+    "Ctrl+Down": "next-history",
+    "Alt+{": "previous-paragraph",
+    "Alt+}": "next-paragraph",
+}
+
+
+def resolve_bindings(
+    overrides: Mapping[str, Binding | None] | None = None,
+    *,
+    use_defaults: bool = True,
+) -> dict[str, Binding]:
+    """Merge ``overrides`` over ``DEFAULT_BINDINGS``.
+
+    A key mapped to ``None`` is removed, which is how a default binding is
+    turned off without turning all of them off.
+    """
+    bindings: dict[str, Binding | None] = dict(DEFAULT_BINDINGS) if use_defaults else {}
+    bindings.update(overrides or {})
+    return {key: target for key, target in bindings.items() if target is not None}
+
+
+def _wants_event(function: Callable[..., None]) -> bool:
+    """Return whether ``function`` expects ``(reader, event_name, event)``."""
+    try:
+        signature = inspect.signature(function)
+    except (TypeError, ValueError):
+        return False
+    parameters = [
+        parameter
+        for parameter in signature.parameters.values()
+        if parameter.kind
+        in (parameter.POSITIONAL_ONLY, parameter.POSITIONAL_OR_KEYWORD)
+    ]
+    return len(parameters) >= 3
+
+
+def _command_name(function: Callable[..., None]) -> str:
+    """Return the REPL command name for ``function``."""
+    name: str | None = getattr(function, "__name__", None)
+    if not name or name == "<lambda>":
+        raise ImproperlyConfigured(
+            "PYREPL_BINDINGS functions need a name: bind a def, not a lambda.",
+        )
+    return name.replace("_", "-")
+
+
+def apply_bindings(bindings: Mapping[str, Binding]) -> None:
+    """Bind every key in ``bindings`` in the current REPL reader."""
+    import pyrepl_hacks as repl
+
+    for keybinding, target in bindings.items():
+        match target:
+            case str():
+                repl.bind(keybinding, target)
+            case Insert(text=text):
+                repl.bind_to_insert(keybinding, text)
+            case _ if callable(target):
+                name = _command_name(target)
+                repl.register_command(name, with_event=_wants_event(target))(target)
+                repl.bind(keybinding, name)
+            case _:
+                raise ImproperlyConfigured(
+                    f"PYREPL_BINDINGS[{keybinding!r}] should be a command name, "
+                    f"an insert(...) value, or a function, not {target!r}.",
+                )
+
+
+def describe(target: Binding) -> str:
+    """Return a short human-readable description of a binding target."""
+    match target:
+        case str():
+            return target
+        case Insert(text=text):
+            return f"insert {text!r}"
+        case _ if callable(target):
+            return _command_name(target)
+        case _:  # pragma: no cover - guarded by apply_bindings
+            return repr(target)

django_pyrepl_hacks/checks.py

@@ -0,0 +1,115 @@
+"""System checks for the ``PYREPL_*`` settings.
+
+These run on ``manage.py check``, which is the only chance to catch a typo in
+a setting before it turns into a traceback in front of the REPL prompt.
+
+Nothing here imports ``pyrepl_hacks``: importing it registers commands, which
+builds a REPL reader, which needs a terminal that a check run may not have.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from django.core.checks import Error, Warning
+from django.core.exceptions import ImproperlyConfigured
+
+from . import conf, repl
+from .bindings import Insert
+
+__all__ = ["check_settings"]
+
+
+# The token names `_colorize.Syntax` accepts, which is what `update_theme`
+# forwards its keyword arguments to.
+THEME_TOKENS = frozenset(
+    {
+        "prompt",
+        "keyword",
+        "keyword_constant",
+        "soft_keyword",
+        "builtin",
+        "comment",
+        "string",
+        "number",
+        "op",
+        "definition",
+        "reset",
+    },
+)
+
+
+def check_settings(**kwargs: Any) -> list[Any]:
+    """Validate every ``PYREPL_*`` setting we understand."""
+    return [
+        *_check_bindings(),
+        *_check_theme(),
+        *_check_setup(),
+    ]
+
+
+def _check_bindings() -> list[Any]:
+    try:
+        bindings = conf.get_bindings()
+    except ImproperlyConfigured as error:
+        return [_error(f"PYREPL_BINDINGS is invalid: {error}", "pyrepl_hacks.E001")]
+    errors: list[Error] = []
+    for key, target in bindings.items():
+        if not isinstance(target, str | Insert) and not callable(target):
+            errors.append(
+                _error(
+                    f"PYREPL_BINDINGS[{key!r}] is {target!r}, which is not a command "
+                    "name, an insert(...) value, or a function.",
+                    "pyrepl_hacks.E002",
+                ),
+            )
+        elif getattr(target, "__name__", None) == "<lambda>":
+            # A command is registered under a name, and a lambda has none.
+            errors.append(
+                _error(
+                    f"PYREPL_BINDINGS[{key!r}] is a lambda, which has no name to "
+                    "register a command under.",
+                    "pyrepl_hacks.E003",
+                    hint="Use a def, or insert(...) if you just want to insert text.",
+                ),
+            )
+    return errors
+
+
+def _check_theme() -> list[Any]:
+    try:
+        theme = conf.get_theme()
+    except ImproperlyConfigured as error:
+        return [_error(f"PYREPL_THEME is invalid: {error}", "pyrepl_hacks.E004")]
+    if theme and sys.version_info < repl.THEME_REQUIRES:
+        return [
+            Warning(
+                "PYREPL_THEME needs Python 3.14 or later, so the shell will "
+                "refuse to start with it set.",
+                hint="Remove the setting to use the REPL's own colors.",
+                id="pyrepl_hacks.W001",
+            ),
+        ]
+    unknown = sorted(set(theme) - THEME_TOKENS)
+    if not unknown:
+        return []
+    return [
+        _error(
+            f"PYREPL_THEME has unknown token names: {', '.join(unknown)}.",
+            "pyrepl_hacks.E005",
+            hint=f"Known tokens: {', '.join(sorted(THEME_TOKENS))}.",
+        ),
+    ]
+
+
+def _check_setup() -> list[Any]:
+    try:
+        conf.get_setup_hooks()
+    except ImproperlyConfigured as error:
+        return [_error(f"PYREPL_SETUP is invalid: {error}", "pyrepl_hacks.E006")]
+    return []
+
+
+def _error(message: str, check_id: str, hint: str | None = None) -> Error:
+    return Error(message, hint=hint, id=check_id)

django_pyrepl_hacks/conf.py

@@ -0,0 +1,74 @@
+"""Reading the ``PYREPL_*`` settings.
+
+Every setting is optional, so each accessor here returns a usable default.
+Values are read at call time rather than at import time, so that
+``override_settings`` works and so that importing this package never requires
+configured settings.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.utils.module_loading import import_string
+
+from .bindings import Binding, resolve_bindings
+
+__all__ = [
+    "get_bindings",
+    "get_setup_hooks",
+    "get_theme",
+]
+
+
+def _setting(name: str, default: object) -> object:
+    return getattr(settings, f"PYREPL_{name}", default)
+
+
+def get_bindings() -> dict[str, Binding]:
+    """Return the key bindings to apply, defaults included unless disabled."""
+    overrides = _setting("BINDINGS", {})
+    if not isinstance(overrides, Mapping):
+        raise ImproperlyConfigured("PYREPL_BINDINGS should be a dictionary.")
+    use_defaults = bool(_setting("USE_DEFAULT_BINDINGS", True))
+    return resolve_bindings(overrides, use_defaults=use_defaults)
+
+
+def get_theme() -> dict[str, str]:
+    """Return syntax highlighting colors to pass to ``update_theme``."""
+    theme = _setting("THEME", {})
+    if not isinstance(theme, Mapping):
+        raise ImproperlyConfigured("PYREPL_THEME should be a dictionary.")
+    return dict(theme)
+
+
+def get_setup_hooks() -> list[Callable[[], None]]:
+    """Return the callables configured by ``PYREPL_SETUP``.
+
+    A single callable, a single dotted path, or a sequence of either is
+    accepted, since one hook is the common case and a list is the general one.
+    """
+    configured = _setting("SETUP", [])
+    if configured is None:
+        return []
+    if callable(configured) or isinstance(configured, str):
+        configured = [configured]
+    if not isinstance(configured, Sequence):
+        raise ImproperlyConfigured(
+            "PYREPL_SETUP should be a callable, an import path, or a list of them.",
+        )
+    hooks = []
+    for hook in configured:
+        if isinstance(hook, str):
+            try:
+                hook = import_string(hook)
+            except ImportError as error:
+                raise ImproperlyConfigured(
+                    f"PYREPL_SETUP could not import {hook!r}: {error}",
+                ) from error
+        if not callable(hook):
+            raise ImproperlyConfigured(f"PYREPL_SETUP entry {hook!r} is not callable.")
+        hooks.append(hook)
+    return hooks

django_pyrepl_hacks/management/commands/shell.py

@@ -0,0 +1,72 @@
+"""A ``shell`` command that prefers the new Python REPL."""
+
+from __future__ import annotations
+
+import types
+from typing import Any
+
+from django.core.management.base import CommandError
+from django.core.management.commands.shell import Command as BaseShellCommand
+
+from django_pyrepl_hacks import conf, repl
+from django_pyrepl_hacks.bindings import describe
+
+
+class Command(BaseShellCommand):
+    """Django's shell command, with ``pyrepl`` as the preferred interface."""
+
+    shells = ["pyrepl", "ipython", "bpython", "python"]  # noqa: RUF012
+
+    def add_arguments(self, parser: Any) -> None:
+        super().add_arguments(parser)
+        parser.add_argument(
+            "--show-bindings",
+            action="store_true",
+            help="Print the configured REPL key bindings and exit.",
+        )
+
+    def handle(self, **options: Any) -> None:
+        if options.get("show_bindings"):
+            self.show_bindings()
+            return
+        super().handle(**options)
+
+    def show_bindings(self) -> None:
+        """Write the resolved key bindings to stdout, aligned on the widest key."""
+        bindings = conf.get_bindings()
+        if not bindings:
+            self.stdout.write("No key bindings are configured.")
+            return
+        width = max(len(key) for key in bindings)
+        for key, target in bindings.items():
+            self.stdout.write(f"{key:<{width}}  {describe(target)}")
+
+    def pyrepl(self, options: dict[str, Any]) -> None:
+        """Run the new Python REPL with Django's namespace and our bindings."""
+        usable, reason = repl.can_use_pyrepl()
+        if not usable:
+            # ImportError is how a shell interface declines, which lets Django
+            # move on to the next one in `shells` instead of failing outright.
+            raise ImportError(reason or "the new Python REPL is unavailable")
+        repl.load_pyrepl_hacks()
+
+        from _pyrepl.main import interactive_console
+
+        # Past this point an ImportError is a broken configuration rather than
+        # an unavailable interface, and silently dropping to the plain shell
+        # would hide it. Every one of these is only reachable once the REPL
+        # itself has said it can run.
+        try:
+            repl.setup()
+        except ImportError as error:
+            raise CommandError(f"Could not set up the REPL: {error}") from error
+
+        # A real __main__ module, so that pickling, dataclasses, and anything
+        # else that looks up __module__ behaves the way it does in a REPL.
+        mainmodule = types.ModuleType("__main__")
+        mainmodule.__dict__.update(self.get_namespace(**options))
+
+        interactive_console(
+            mainmodule=mainmodule,
+            pythonstartup=not options.get("no_startup"),
+        )

django_pyrepl_hacks/repl.py

@@ -0,0 +1,87 @@
+"""Setting up the REPL itself: bindings, theme, and setup hooks.
+
+The ``pyrepl_hacks`` imports live inside the functions here.
+Importing it builds a REPL reader, which needs a terminal, so it must not
+happen while Django is merely loading apps.
+"""
+
+from __future__ import annotations
+
+import sys
+from types import ModuleType
+
+from django.core.exceptions import ImproperlyConfigured
+
+from . import conf
+from .bindings import apply_bindings
+
+__all__ = ["can_use_pyrepl", "load_pyrepl_hacks", "setup"]
+
+
+def can_use_pyrepl() -> tuple[bool, str]:
+    """Return whether the new REPL can run here, and why not when it cannot.
+
+    ``_pyrepl`` silently falls back to the basic REPL when it cannot run, and
+    that fallback drops the namespace we spent all this effort building.
+    So the shell command asks first and declines the interface instead.
+    """
+    try:
+        from _pyrepl.main import CAN_USE_PYREPL, FAIL_REASON
+    except ImportError as error:  # pragma: no cover - Python 3.12 and earlier
+        return False, str(error)
+    return CAN_USE_PYREPL, FAIL_REASON
+
+
+def load_pyrepl_hacks() -> ModuleType:
+    """Import ``pyrepl_hacks``, translating its failures into ImportError.
+
+    Importing it registers commands, which builds a REPL reader, which needs a
+    terminal. A RuntimeError from that is the same kind of "not here, not now"
+    answer as an ImportError, and only ImportError makes Django try the next
+    interface.
+    """
+    try:
+        import pyrepl_hacks
+    except RuntimeError as error:
+        raise ImportError(f"pyrepl-hacks could not set up the REPL: {error}") from error
+    return pyrepl_hacks
+
+
+#: Syntax highlighting is themeable from Python 3.14 on, when `_colorize`
+#: grew the `Syntax` class that `update_theme` builds a theme out of.
+THEME_REQUIRES = (3, 14)
+
+
+def apply_theme() -> None:
+    """Apply ``PYREPL_THEME`` to the REPL's syntax highlighting."""
+    theme = conf.get_theme()
+    if not theme:
+        return
+    if sys.version_info < THEME_REQUIRES:
+        raise ImproperlyConfigured(
+            "PYREPL_THEME needs Python 3.14 or later. "
+            "Remove the setting to use the REPL's own colors.",
+        )
+
+    import pyrepl_hacks as repl
+
+    try:
+        repl.update_theme(**theme)
+    except (AttributeError, TypeError) as error:
+        # An unknown color name is an AttributeError on _colorize.ANSIColors,
+        # and an unknown token name is a TypeError from Syntax().
+        raise ImproperlyConfigured(f"PYREPL_THEME is invalid: {error}") from error
+
+
+def run_setup_hooks() -> None:
+    """Call everything listed in ``PYREPL_SETUP``."""
+    for hook in conf.get_setup_hooks():
+        hook()
+
+
+def setup() -> None:
+    """Configure the REPL from settings, just before it starts."""
+    load_pyrepl_hacks()
+    apply_bindings(conf.get_bindings())
+    apply_theme()
+    run_setup_hooks()

django_pyrepl_hacks-0.1.0.dist-info/METADATA

@@ -0,0 +1,409 @@
+Metadata-Version: 2.4
+Name: django-pyrepl-hacks
+Version: 0.1.0
+Summary: A Django shell that uses the new Python REPL, with pyrepl-hacks key bindings.
+Keywords: django,repl,shell,pyrepl,keyboard,shortcuts
+Author: Trey Hunner
+Author-email: Trey Hunner <trey@treyhunner.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
+Requires-Dist: django>=5.2
+Requires-Dist: pyrepl-hacks>=0.5.0
+Requires-Python: >=3.13, <3.15
+Project-URL: Documentation, https://github.com/treyhunner/django-pyrepl-hacks#readme
+Project-URL: Changelog, https://github.com/treyhunner/django-pyrepl-hacks/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/treyhunner/django-pyrepl-hacks/issues
+Project-URL: Source, https://github.com/treyhunner/django-pyrepl-hacks
+Description-Content-Type: text/markdown
+
+# django-pyrepl-hacks 🐍
+
+[![PyPI][pypi-badge]][pypi]
+[![CI][ci-badge]][ci]
+[![Coverage][coverage-badge]][coverage]
+
+A Django `shell` that uses the new Python REPL, with [pyrepl-hacks][] key bindings.
+
+Django's shell tries IPython, then bpython, then `code.interact`.
+None of those is the REPL that ships with Python 3.13 and later, so `manage.py shell` gives you a worse REPL than `python` does.
+This package adds a `pyrepl` interface and puts it first.
+
+You get syntax highlighting, multi-line editing, and history search, plus Django's auto-imported models and a handful of extra key bindings.
+
+
+## ⚠️ WARNING: here be dragons 🐉
+
+This builds on [pyrepl-hacks][], which relies on the `_pyrepl` module.
+As the `_` prefix implies, that module is not designed for public use, and a new Python release may break it.
+
+So this package pins its supported Python versions to the ones known to work.
+
+
+## Installing 💾
+
+This needs Python 3.13 or 3.14 and Django 5.2 or later.
+
+```console
+uv add django-pyrepl-hacks
+```
+
+Or with pip:
+
+```console
+python -m pip install django-pyrepl-hacks
+```
+
+Then add it to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    "django_pyrepl_hacks",
+    # ...
+]
+```
+
+That's the whole setup.
+`manage.py shell` will now use the new REPL:
+
+```console
+$ ./manage.py shell
+14 objects imported automatically (use -v 2 for details).
+
+>>>
+```
+
+The other interfaces are still there, so `manage.py shell -i ipython` works as before.
+So does everything else the shell command does: `-c`, piped stdin, `--no-imports`, and `--no-startup`.
+
+### A note on dependency groups
+
+`INSTALLED_APPS` is read wherever Django starts, so this belongs with your regular dependencies rather than in a dev-only group.
+A dev-only install plus an unconditional `INSTALLED_APPS` entry means production cannot start at all.
+
+If you would rather keep it out of production, gate the entry too:
+
+```python
+if DEBUG:
+    INSTALLED_APPS += ["django_pyrepl_hacks"]
+```
+
+Production then falls back to Django's own shell, which means a production shell loses the auto-imported models as well.
+Shipping it is usually the smaller cost: the package is pure Python and depends on nothing but Django and [pyrepl-hacks][].
+
+
+## Default key bindings ⌨️
+
+| Key         | Command               | What it does                              |
+| ----------- | --------------------- | ----------------------------------------- |
+| `Home`      | `home`                | Move to the first character in the input   |
+| `End`       | `end`                 | Move to the last character in the input    |
+| `Alt+M`     | `move-to-indentation` | Move to the first non-space in the line    |
+| `Shift+Tab` | `dedent`              | Dedent the whole input                     |
+| `Alt+Down`  | `move-line-down`      | Swap the current line with the next one    |
+| `Alt+Up`    | `move-line-up`        | Swap the current line with the previous one |
+| `Ctrl+Up`   | `previous-history`    | Move to the previous history entry         |
+| `Ctrl+Down` | `next-history`        | Move to the next history entry             |
+| `Alt+{`     | `previous-paragraph`  | Move to the previous blank line            |
+| `Alt+}`     | `next-paragraph`      | Move to the next blank line                |
+
+To see what is actually bound in your project, including your own additions:
+
+```console
+./manage.py shell --show-bindings
+```
+
+
+## Settings ⚙️
+
+Every setting is optional.
+
+
+### `PYREPL_BINDINGS`
+
+A dictionary mapping a key to the thing that key should do, layered over the defaults above.
+
+The keys are human-readable: `"Ctrl+K"`, `"Alt+Up"`, `"Shift+Tab"`, `"F4"`, `"Home"`, `"PageUp"`, or a sequence like `"Ctrl+X Ctrl+R"`.
+
+The values come in four flavors.
+
+**1. A string is the name of a REPL command that already exists.**
+
+```python
+PYREPL_BINDINGS = {
+    "Ctrl+K": "kill-line",  # Delete from the cursor to end of line
+    "Alt+D": "kill-word",  # Delete the word after the cursor
+    "Ctrl+L": "clear-screen",
+    "Alt+<": "first-history",  # Jump to the oldest history entry
+    "Alt+>": "last-history",  # Jump to the newest
+    "Ctrl+O": "operate-and-get-next",  # Run this line, then offer the next one
+}
+```
+
+There are about 50 of these built in.
+`show-history`, `paste-mode`, `transpose-characters`, `yank`, `yank-pop`, `unix-word-rubout`, `backward-word`, `forward-word`, and `history-search-backward` are some of the more useful ones.
+[pyrepl-hacks][] adds `dedent`, `move-line-up`, `move-line-down`, `move-to-indentation`, `previous-paragraph`, and `next-paragraph`.
+
+**2. `insert(text)` types some text for you.**
+
+```python
+from django_pyrepl_hacks import insert
+
+PYREPL_BINDINGS = {
+    "Ctrl+N": insert("User.objects.filter("),
+    "F5": insert("from django.test import Client\nc = Client()\n"),
+    "F9": insert("connection.queries[-1]['sql']"),
+}
+```
+
+**3. A function becomes a new REPL command.**
+
+It is registered under its own name, with underscores turned into hyphens, so `sql_of_last_query` becomes the command `sql-of-last-query`.
+It is called with the reader, which is the object holding the text you are editing:
+
+```python
+# myproject/repl.py
+def sql_of_last_query(reader):
+    """Type out the SQL of the most recent query."""
+    from django.db import connection
+
+    if connection.queries:
+        reader.insert(connection.queries[-1]["sql"])
+```
+
+```python
+from myproject.repl import sql_of_last_query
+
+PYREPL_BINDINGS = {"F9": sql_of_last_query}
+```
+
+A function taking three arguments is called with the event too, the way [pyrepl-hacks][] `with_event=True` commands are.
+That is what you need to move the cursor, since the movement commands take the event:
+
+```python
+import pyrepl_hacks as repl
+
+
+def filter_call(reader, event_name, event):
+    """Type `User.objects.filter()` and park the cursor inside the parens."""
+    reader.insert("User.objects.filter()")
+    repl.commands.left(reader, event_name, event)
+```
+
+Lambdas are rejected, because a command has to be registered under a name.
+`manage.py check` tells you so rather than waiting until you press the key.
+
+**4. `None` turns off one of the defaults.**
+
+```python
+PYREPL_BINDINGS = {
+    "Home": None,  # Give Home back to beginning-of-line
+    "Ctrl+Up": None,
+}
+```
+
+Putting it together:
+
+```python
+from django_pyrepl_hacks import insert
+from myproject.repl import sql_of_last_query
+
+PYREPL_BINDINGS = {
+    "Ctrl+K": "kill-line",
+    "Ctrl+N": insert("User.objects.filter("),
+    "F9": sql_of_last_query,
+    "Home": None,
+}
+```
+
+```console
+$ ./manage.py shell --show-bindings
+End        end
+Alt+M      move-to-indentation
+Shift+Tab  dedent
+Alt+Down   move-line-down
+Alt+Up     move-line-up
+Ctrl+Up    previous-history
+Ctrl+Down  next-history
+Alt+{      previous-paragraph
+Alt+}      next-paragraph
+Ctrl+K     kill-line
+Ctrl+N     insert 'User.objects.filter('
+F9         sql-of-last-query
+```
+
+
+### `PYREPL_USE_DEFAULT_BINDINGS`
+
+Set to `False` to start from nothing instead of from the default bindings.
+`PYREPL_BINDINGS` is then the whole set.
+
+
+### `PYREPL_THEME`
+
+Syntax highlighting colors for the code you type at the prompt.
+The REPL colors your input as you type it, and this changes which color each kind of token gets.
+
+The keys are the eleven token types the REPL knows about, and the values are colors:
+
+```python
+PYREPL_THEME = {
+    "string": "green",
+    "number": "intense blue",
+    "comment": "grey",
+    "keyword": "bold magenta",
+    "prompt": "bold green",
+}
+```
+
+The token types:
+
+| Token              | What it colors                          |
+| ------------------ | --------------------------------------- |
+| `prompt`           | The `>>>` and `...` prompts             |
+| `keyword`          | `def`, `if`, `for`, `import`, `return`  |
+| `keyword_constant` | `None`, `True`, `False`                 |
+| `soft_keyword`     | `match`, `case`, `type`                 |
+| `builtin`          | `len`, `print`, `sorted`                |
+| `comment`          | `# like this`                           |
+| `string`           | `"like this"`                           |
+| `number`           | `42`, `3.14`                            |
+| `op`               | `+`, `-`, `=`, `(`, `,`                 |
+| `definition`       | The name in `def name` or `class Name`  |
+| `reset`            | Everything else, and the default style  |
+
+The colors are `black`, `blue`, `cyan`, `green`, `grey`, `magenta`, `red`, `white`, and `yellow`, each of which can be prefixed:
+
+| Specification              | Example                     |
+| -------------------------- | --------------------------- |
+| plain                      | `"red"`                     |
+| `bold`                     | `"bold red"`                |
+| `intense`                  | `"intense red"`             |
+| `background`               | `"background red"`          |
+| `intense background`       | `"intense background red"`  |
+| combined with a comma      | `"background black, bold white"` |
+| nothing at all             | `"reset"`                   |
+
+So a low-contrast theme that leaves keywords loud:
+
+```python
+PYREPL_THEME = {
+    "keyword": "bold magenta",
+    "keyword_constant": "bold magenta",
+    "soft_keyword": "bold magenta",
+    "builtin": "cyan",
+    "string": "green",
+    "number": "green",
+    "comment": "intense black",
+    "op": "reset",
+    "definition": "bold blue",
+}
+```
+
+Anything you leave out keeps the REPL's own color.
+
+Named themes (`PYREPL_THEME = "solarized-light"`) are not implemented yet.
+A string is not a valid value today, so they can be added without breaking a dictionary you have already written.
+
+This setting needs Python 3.14 or later, since that is when the REPL's theme became something a program could set.
+`manage.py check` warns when it is set on an older Python, and the shell refuses to start rather than pretending it worked.
+
+
+### `PYREPL_SETUP`
+
+A callable, an import path, or a list of either, called once the REPL is configured and just before it starts.
+
+This is the escape hatch: the one place to put code that should run when the REPL starts and nowhere else.
+Settings modules will not do: they are imported by every management command and by your web server too.
+
+```python
+PYREPL_SETUP = "myproject.repl.setup"
+```
+
+Here's how you'd use the full [pyrepl-hacks][] API to register a command, rather than going through `PYREPL_BINDINGS`:
+
+```python
+# myproject/repl.py
+import pyrepl_hacks as repl
+
+
+def setup():
+    @repl.bind("Ctrl+X Ctrl+Q", with_event=True)
+    def insert_query(reader, event_name, event):
+        """Insert a queryset skeleton and park the cursor inside it."""
+        reader.insert("User.objects.filter()")
+        repl.commands.left(reader, event_name, event)
+```
+
+Import `pyrepl_hacks` inside the hook rather than at module level: importing it builds a REPL reader, which needs a terminal.
+
+The hook is also where the settings this package deliberately does not have go.
+
+**A prompt that tells you which environment you are in.**
+The REPL only sets `sys.ps1` and `sys.ps2` if it finds them missing, so setting them in the hook means it leaves yours alone:
+
+```python
+def setup():
+    import sys
+    from django.conf import settings
+
+    if not settings.DEBUG:
+        sys.ps1, sys.ps2 = "prod>>> ", "prod... "
+```
+
+Worth setting up before the day you run a quick query in what turns out to be production.
+A prompt is on every line, so unlike a banner it does not scroll away.
+
+**A banner above the prompt.**
+
+```python
+def setup():
+    import django
+    from django.db import connections
+
+    database = connections["default"].settings_dict["NAME"]
+    print(f"Django {django.get_version()} | {database}")
+```
+
+
+## When the REPL cannot run 🚧
+
+The new REPL needs a terminal, and it refuses to start under `PYTHON_BASIC_REPL` or on an old Windows.
+When that happens the `pyrepl` interface steps aside and Django moves on to IPython, bpython, or `code.interact`, exactly as it would if this package were not installed.
+
+A mistake in your own configuration is a different thing: the shell reports it rather than quietly falling back to a plain REPL.
+
+
+## Checks ✅
+
+`manage.py check` validates every `PYREPL_*` setting, so a typo turns up before you are staring at a broken prompt.
+
+
+## Contributing 🤝
+
+See [CONTRIBUTING.md][].
+
+[pyrepl-hacks]: https://github.com/treyhunner/pyrepl-hacks
+[CONTRIBUTING.md]: CONTRIBUTING.md
+[pypi-badge]: https://img.shields.io/pypi/v/django-pyrepl-hacks.svg
+[pypi]: https://pypi.org/project/django-pyrepl-hacks/
+[ci-badge]: https://github.com/treyhunner/django-pyrepl-hacks/actions/workflows/ci.yml/badge.svg
+[ci]: https://github.com/treyhunner/django-pyrepl-hacks/actions/workflows/ci.yml
+[coverage-badge]: https://codecov.io/gh/treyhunner/django-pyrepl-hacks/branch/main/graph/badge.svg
+[coverage]: https://codecov.io/gh/treyhunner/django-pyrepl-hacks

django_pyrepl_hacks-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+django_pyrepl_hacks/__init__.py,sha256=P-yANqP5Nc64s2DHbQ3q-ECDL9hV5JCj4VwMlt79skw,439
+django_pyrepl_hacks/apps.py,sha256=WVv9PicqWt4uAjQ1qOQGb4y02aGmglZuftQJoiCPnag,388
+django_pyrepl_hacks/bindings.py,sha256=kc7KFD9ei_iGr4QkwvVmy5p49DoeRfot-4tXZiRnUk0,4086
+django_pyrepl_hacks/checks.py,sha256=NQXkXwypuujfcOlYnU9xRfCLOU9Qr5eO8JfYvpzktjE,3541
+django_pyrepl_hacks/conf.py,sha256=ARh6l5dIv5Fjni574t9E0BQ6tIeztoRiKt38F8w6BJk,2562
+django_pyrepl_hacks/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_pyrepl_hacks/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_pyrepl_hacks/management/commands/shell.py,sha256=rRSfPWv7tPNygG6Mwu1SO8x7HjTe0yHF_hsmrLvZPxk,2772
+django_pyrepl_hacks/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_pyrepl_hacks/repl.py,sha256=HN_EZZPfnjDrGov3IIiY1pa14yopf6u5E-RgacD9DYQ,2861
+django_pyrepl_hacks-0.1.0.dist-info/licenses/LICENSE.txt,sha256=Oyi3NXRJXSTm0P52rdsbqY-R2swOxbUg0CM7NZqw5N0,1076
+django_pyrepl_hacks-0.1.0.dist-info/WHEEL,sha256=4OL6Foqnnp3xRY5wMkjgc25_i5YJC6dKsC6LPcjqEoU,80
+django_pyrepl_hacks-0.1.0.dist-info/METADATA,sha256=Ks4vh_kV36YmByHaeR-ES-MUt5qdBAYvL8EEF96FP6s,14354
+django_pyrepl_hacks-0.1.0.dist-info/RECORD,,

django_pyrepl_hacks-0.1.0.dist-info/WHEEL

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

django_pyrepl_hacks-0.1.0.dist-info/licenses/LICENSE.txt

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