python-corekit 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

corekit/api/application.py

@@ -26,16 +26,34 @@ from typing import Any, Sequence
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
 from fastapi.staticfiles import StaticFiles
 from starlette.middleware.trustedhost import TrustedHostMiddleware
 
 from corekit.api.middleware import MiddlewareStack
 from corekit.api.routers import CatchAllRouter, SimpleRouter, router_registry
+from corekit.exceptions import CoreHTTPException
 from corekit.observability.loggable import Loggable
 
 __all__ = ["Application"]
 
 
+def _origin_in_package(router: SimpleRouter, package_name: str) -> bool:
+    """
+    Whether this router was constructed by ``package_name`` or a submodule.
+    """
+    origin = router._origin_module
+    return origin == package_name or origin.startswith(f"{package_name}.")
+
+
+async def _core_http_exception_handler(request: Any, exc: CoreHTTPException) -> JSONResponse:
+    """
+    The same body FastAPI returns for ``HTTPException``.
+    """
+    headers = getattr(exc, "headers", None)
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail}, headers=headers)
+
+
 class Application(FastAPI, Loggable):
     """
     ``FastAPI`` plus router discovery, middleware helpers and static mounting.
@@ -47,6 +65,7 @@ class Application(FastAPI, Loggable):
         """
         FastAPI.__init__(self, *args, **kwargs)
         Loggable.__init__(self)
+        self._register_http_exception_handler()
 
     # ─── Routers ──────────────────────────────────────────────────────────
 
@@ -55,9 +74,12 @@ class Application(FastAPI, Loggable):
         Import every module under ``package`` and mount the routers it defines.
 
         Importing a module is what constructs its routers, so discovery is a
-        walk over ``package`` that lets each one register itself. A router that
-        was included into another router during that walk is skipped -- its
-        parent already owns it -- and any ``CatchAllRouter`` is mounted last.
+        walk over ``package`` that lets each one register itself. Only routers
+        constructed inside that package are mounted: the registry is
+        process-wide, and an unclaimed router from some other import must not
+        ride along. A router that was included into another router is skipped
+        -- its parent already owns it -- and any ``CatchAllRouter`` is mounted
+        last.
 
         Args:
             package: The imported package to search, e.g. ``app.backend.routers``.
@@ -78,11 +100,12 @@ class Application(FastAPI, Loggable):
 
         self._warn_on_unimportable_dirs(package)
 
-        before = len(router_registry)
         scanned = self._import_submodules(package)
-        discovered = len(router_registry) - before
-
-        mountable = router_registry.unclaimed
+        # unclaimed is every top-level router in the process. Mounting that
+        # list would include routers built by some other package that happens
+        # to be imported. Origin is where the instance was constructed, which
+        # is the scanned package for a router that belongs here.
+        mountable = [router for router in router_registry.unclaimed if _origin_in_package(router, name)]
         if not mountable:
             raise ValueError(
                 f"No routers found in '{name}' (scanned {scanned} modules). "
@@ -90,8 +113,9 @@ class Application(FastAPI, Loggable):
                 f"a SimpleRouter or SmartRouter at import time."
             )
 
-        claimed = discovered - len(mountable)
-        self.info(f"  scanned {scanned} modules, found {discovered} routers")
+        in_package = [router for router in router_registry if _origin_in_package(router, name)]
+        claimed = len(in_package) - len(mountable)
+        self.info(f"  scanned {scanned} modules, found {len(in_package)} routers")
         if claimed > 0:
             plural = "s" if claimed != 1 else ""
             self.info(f"  skipped {claimed} sub-router{plural} (already included by a parent)")
@@ -235,3 +259,17 @@ class Application(FastAPI, Loggable):
         self.mount(url_path, StaticFiles(directory=str(path), **kwargs), name=name or url_path.strip("/"))
         self.info(f"  + static {url_path:<24} -> {path}")
         return True
+
+    def _register_http_exception_handler(self) -> None:
+        """
+        Handle the library's HTTP exceptions the same way FastAPI handles its own.
+
+        ``CoreHTTPException`` is already an ``HTTPException``, so Starlette
+        would answer it. Registering the type explicitly keeps that response
+        -- ``{"detail": ...}`` only, never ``message`` or ``error`` -- even
+        if a later change in lookup order would otherwise miss the subclass.
+        A handler the caller already installed is left in place.
+        """
+        if CoreHTTPException in self.exception_handlers:
+            return
+        self.add_exception_handler(CoreHTTPException, _core_http_exception_handler)

corekit/api/lifespan.py

@@ -108,7 +108,9 @@ class Lifespan(Loggable):
             startup: Called on the way up, in the order steps were added.
             shutdown: Called on the way down, in reverse order. Called only if
                 ``startup`` completed, so it can assume what ``startup`` builds.
-            tags: Free-form labels, for callers that group or filter steps.
+            tags: Labels used by ``for_tags``. Untagged steps always run; a
+                tagged step runs only when one of its tags is selected. With
+                no filter, every step runs.
             always_shutdown: Call ``shutdown`` even when ``startup`` raised.
                 For a startup that acquires something before it can fail -- a
                 connection opened, then a handshake that throws. The hook then
@@ -136,6 +138,25 @@ class Lifespan(Loggable):
         """The registered steps, in the order they will start."""
         return list(self._steps)
 
+    def for_tags(self, *tags: str) -> "Lifespan":
+        """
+        A lifespan that runs the steps matching ``tags``, plus untagged ones.
+
+        An untagged step is ordinary startup and always runs. A tagged step
+        runs only when the caller asked for one of its tags, so a label is a
+        filter rather than decoration. No tags means every step, which is
+        what ``__call__`` does.
+        """
+        if not tags:
+            return self
+
+        wanted = set(tags)
+        selected = Lifespan()
+        for step in self._steps:
+            if not step.tags or wanted.intersection(step.tags):
+                selected._steps.append(step)
+        return selected
+
     @asynccontextmanager
     async def __call__(self, app: Any = None) -> AsyncIterator[None]:
         """
@@ -166,7 +187,8 @@ class Lifespan(Loggable):
         stack.push_async_callback(self._run_shutdown, step)
 
         if step.startup is not None:
-            self.info(f"  ^ {step.name}")
+            label = step.name if not step.tags else f"{step.name} [{', '.join(step.tags)}]"
+            self.info(f"  ^ {label}")
             try:
                 await self._maybe_await(step.startup)
             except Exception:
@@ -192,7 +214,8 @@ class Lifespan(Loggable):
                 self.warning(f"  - {step.name} (skipped: startup did not complete)")
             return
 
-        self.info(f"  v {step.name}")
+        label = step.name if not step.tags else f"{step.name} [{', '.join(step.tags)}]"
+        self.info(f"  v {label}")
         try:
             await self._maybe_await(step.shutdown)
         except Exception:

corekit/concurrency/__init__.py

@@ -2,8 +2,8 @@
 Concurrency primitives: per-thread storage, workers, and parallel mapping.
 """
 
-from corekit.concurrency.decorators import parallelize
+from corekit.concurrency.decorators import allow_sync, parallelize
 from corekit.concurrency.thread_local import ThreadLocalRegistry
 from corekit.concurrency.worker import ThreadWorker
 
-__all__ = ["ThreadLocalRegistry", "ThreadWorker", "parallelize"]
+__all__ = ["ThreadLocalRegistry", "ThreadWorker", "allow_sync", "parallelize"]

corekit/concurrency/decorators.py

@@ -18,19 +18,26 @@ machine rather than an error message.
 
 Results arrive out of order, because they arrive as they complete. Pass
 ``ordered=True`` to get them in the order the inputs were given.
+
+``allow_sync`` wraps an async function so a script can call it directly, while
+an already-running event loop still gets a coroutine to await.
 """
 
+import asyncio
 import functools
+import logging
+from collections.abc import Awaitable, Callable
 from concurrent.futures import Future, ThreadPoolExecutor, as_completed
-from typing import Any, Callable, Iterable, Iterator
+from typing import Any, Iterable, Iterator, ParamSpec, TypeVar
 
 from corekit.config import get_settings
-from corekit.observability import Loggable
 
-__all__ = ["parallelize"]
+__all__ = ["parallelize", "allow_sync"]
+
+_logger = logging.getLogger("parallelize")
 
-_logger = Loggable()
-_logger.logger = _logger.logger.getChild("parallelize")
+P = ParamSpec("P")
+R = TypeVar("R")
 
 
 def parallelize(
@@ -70,3 +77,23 @@ def parallelize(
         return wrapper
 
     return decorator
+
+
+def allow_sync(async_func: Callable[P, Awaitable[R]]) -> Callable[P, R | Awaitable[R]]:
+    """
+    Call an async function from sync code, or return its coroutine if a loop is running.
+
+    A script gets the result back immediately. Inside an async app the wrapper
+    returns the coroutine, so the caller must await it — calling the wrapper
+    and ignoring the result will not run the function.
+    """
+
+    @functools.wraps(async_func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R | Awaitable[R]:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(async_func(*args, **kwargs))
+        return async_func(*args, **kwargs)
+
+    return wrapper

corekit/concurrency/thread_local.py

@@ -19,7 +19,7 @@ import threading
 from typing import Any
 
 from corekit.observability.loggable import Loggable
-from corekit.registry import SmartRegistry
+from corekit.registry import normalize_key
 
 __all__ = ["ThreadLocalRegistry"]
 
@@ -59,7 +59,7 @@ class ThreadLocalRegistry(threading.local, Loggable):
         turn SQLConnection into "sqlconnection" rather than "sql_connection".
         """
         name = key.__name__ if isinstance(key, type) else str(key)
-        return SmartRegistry.__normalize_key__(name).replace("-", "_")
+        return normalize_key(name).replace("-", "_")
 
     def get(self, key: Any, fallback: Any = None) -> Any:
         """

corekit/concurrency/worker.py

@@ -5,6 +5,15 @@ import time
 
 
 class ThreadWorker(threading.Thread):
+    """
+    A daemon thread that waits for ``can_start``, then calls ``process`` once.
+
+    ``timeout`` and ``loop`` are stored for a subclass that wants them.
+    ``run`` does not enforce ``timeout`` and does not drive ``loop``.
+    ``stop`` sets ``running`` so a subclass of ``process`` can notice it; it
+    does not interrupt a thread already inside ``process``.
+    """
+
     def __init__(
         self,
         can_start: threading.Event,

corekit/config/loader.py

@@ -9,6 +9,8 @@ settings know only their own shape.
 from pathlib import Path
 from typing import Any
 
+from pydantic import ValidationError
+
 from corekit.config.settings import ENV_PREFIX, CorekitSettings
 from corekit.config.sources import ConfigFileSource, ConfigSource, EnvironmentSource, PyprojectSource
 from corekit.observability import Loggable
@@ -72,11 +74,12 @@ class SettingsLoader(Loggable):
         """
         Read every source and construct the settings.
 
-        Invalid configuration falls back to defaults rather than raising:
-        corekit has to remain importable, and a library that refuses to load
-        because of a stray value in a file is worse than one that logs the
-        problem and carries on. The log line is the difference between this and
-        silently ignoring it.
+        Invalid configuration drops the bad section and keeps the rest.
+        A bad thread count must not discard a valid salt or serialization
+        key that arrived from another section or the environment. If what
+        remains still will not validate, the last resort is defaults --
+        corekit has to remain importable. The log line is the difference
+        between this and silently ignoring it.
         """
         values: dict[str, Any] = {}
         for source in self.sources():
@@ -84,10 +87,44 @@ class SettingsLoader(Loggable):
 
         try:
             return CorekitSettings(**values)
+        except ValidationError as exc:
+            cleaned, dropped = self._without_invalid_sections(values, exc)
+            if dropped:
+                self.error(
+                    f"Invalid corekit configuration in {', '.join(dropped)}; "
+                    f"those sections fall back to defaults: {exc}"
+                )
+                try:
+                    return CorekitSettings(**cleaned)
+                except ValidationError as retry_exc:
+                    self.error(f"Invalid corekit configuration, falling back to defaults: {retry_exc}")
+                    return CorekitSettings()
+            self.error(f"Invalid corekit configuration, falling back to defaults: {exc}")
+            return CorekitSettings()
         except Exception as exc:
             self.error(f"Invalid corekit configuration, falling back to defaults: {exc}")
             return CorekitSettings()
 
+    @staticmethod
+    def _without_invalid_sections(values: dict[str, Any], exc: ValidationError) -> tuple[dict[str, Any], list[str]]:
+        """
+        Drop each section named in a validation error, leaving the others.
+
+        A section is the first element of the error location. A failure that
+        names no section cannot be isolated, so nothing is dropped and the
+        caller falls back to defaults.
+        """
+        dropped: list[str] = []
+        for error in exc.errors():
+            loc = error.get("loc") or ()
+            if not loc:
+                continue
+            section = str(loc[0])
+            if section not in dropped:
+                dropped.append(section)
+        cleaned = {key: value for key, value in values.items() if key not in dropped}
+        return cleaned, dropped
+
     @staticmethod
     def _merge(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
         """

corekit/config/settings.py

@@ -35,6 +35,10 @@ class StandardsSettings(BaseModel):
 
     Off by default. These are conventions, not library invariants, and crashing
     a consumer's application over a missing docstring would be hostile.
+
+    ``strict_mode`` makes a ``SmartRegistry`` refuse a second write to a
+    normalized key instead of warning and replacing. It does not imply
+    ``require_handler_docstrings``; that check stays its own flag.
     """
 
     require_handler_docstrings: bool = False
@@ -80,7 +84,13 @@ class ConcurrencySettings(BaseModel):
     @staticmethod
     def cpu_default() -> int:
         """
-        A reasonable thread count for this machine, for callers that want one.
+        A machine-sized thread count, for a caller that asks for one.
+
+        Not what ``resolve`` or ``parallelize`` use when the caller is silent.
+        Those use ``default_threads``. Pass this in when the work should
+        scale with the machine::
+
+            parallelize(num_threads=ConcurrencySettings.cpu_default())
         """
         return min(32, (os.cpu_count() or 1) * 5)
 

corekit/connections/__init__.py

@@ -17,7 +17,12 @@ implementations of the abstraction directly above them, and there is no useful
 way to think about one without the other.
 """
 
-from corekit.connections.connectable import Connectable, ConnectableType, ConnectionPreference
+from corekit.connections.connectable import (
+    Connectable,
+    ConnectableType,
+    ConnectionPreference,
+    ReadOnlyConnectionError,
+)
 from corekit.connections.decorators import connect
 from corekit.connections.registry import ConnectionRegistry, registry
 
@@ -26,6 +31,7 @@ __all__ = [
     "ConnectableType",
     "ConnectionPreference",
     "ConnectionRegistry",
+    "ReadOnlyConnectionError",
     "connect",
     "registry",
 ]

corekit/connections/connectable.py

@@ -21,22 +21,40 @@ class without importing it directly.
 from abc import ABC, abstractmethod
 from typing import Any
 
+from corekit.exceptions import InternalCoreException, Retryability
 from corekit.observability.loggable import Loggable
 from corekit.registry import SmartRegistry
 from corekit.schemas.enum import StringEnum
 
-__all__ = ["Connectable", "ConnectableType", "ConnectionPreference"]
+__all__ = ["Connectable", "ConnectableType", "ConnectionPreference", "ReadOnlyConnectionError"]
 
 
 class ConnectionPreference(StringEnum):
     """
-    Whether a connection should prefer its sync or async path when both exist.
+    A stored hint for which path a caller prefers.
+
+    The base class records this and does not consult it. ``connect`` and
+    ``async_connect`` follow the method the caller invoked, and ``@connect``
+    always opens with ``with``. A subclass may read the hint; nothing here
+    switches paths because of it.
     """
 
     ASYNC = "async"
     SYNC = "sync"
 
 
+class ReadOnlyConnectionError(InternalCoreException):
+    """
+    Raised when a write is attempted on a connection opened read-only.
+    """
+
+    def __init__(self, connection: str) -> None:
+        super().__init__(
+            message=f"{connection} is read-only",
+            retryable=Retryability.NON_RETRYABLE,
+        )
+
+
 class Connectable(Loggable, ABC):
     """
     Base class for anything with a connection lifecycle.
@@ -97,10 +115,20 @@ class Connectable(Loggable, ABC):
     @property
     def connection_preference(self) -> ConnectionPreference:
         """
-        Whether this connection prefers its sync or async path.
+        The path hint recorded at construction. Not used to open the connection.
         """
         return self._connection_preference
 
+    def require_writable(self) -> None:
+        """
+        Raise if this connection was opened for reading only.
+
+        Corekit's own write methods call this. The base class does not wrap
+        every method, so a subclass with its own writes should call it too.
+        """
+        if self._read_only:
+            raise ReadOnlyConnectionError(type(self).__name__)
+
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(connected={self.is_connected})"
 
@@ -190,11 +218,24 @@ class Connectable(Loggable, ABC):
         self.debug(f"Terminating {self.__class__.__name__} connection")
         self._disconnect()
 
+    def _async_is_open(self) -> bool:
+        """
+        Whether the async path is already up.
+
+        ``is_connected`` is the sync flag. Redis keeps a process-wide sync pool
+        and a separate async client, so a sync pool must not stand in for the
+        async client. Classes without ``is_async_connected`` use ``is_connected``.
+        """
+        for cls in type(self).mro():
+            if "is_async_connected" in cls.__dict__:
+                return bool(self.is_async_connected)
+        return self.is_connected
+
     async def async_connect(self, force_reconnect: bool = False) -> None:
         """
         Connect asynchronously if not already connected.
         """
-        if self.is_connected and not force_reconnect:
+        if self._async_is_open() and not force_reconnect:
             return
 
         self.debug(f"Establishing async {self.__class__.__name__} connection")

corekit/connections/redis/connection.py

@@ -23,6 +23,7 @@ from redis import asyncio as aioredis
 
 from corekit.config import get_settings
 from corekit.connections import Connectable
+from corekit.exceptions import InternalCoreException, Retryability
 
 __all__ = ["RedisConnection", "RedisNotConnectedError"]
 
@@ -31,11 +32,14 @@ logger = logging.getLogger(__name__)
 DEFAULT_URL = "redis://localhost:6379/0"
 
 
-class RedisNotConnectedError(RuntimeError):
+class RedisNotConnectedError(InternalCoreException):
     """
     Raised when a client is used before its connection is opened.
     """
 
+    def __init__(self, message: str, *, error: str | None = None) -> None:
+        super().__init__(message, retryable=Retryability.NON_RETRYABLE, error=error)
+
 
 def _encode(value: Any) -> str:
     """
@@ -65,14 +69,15 @@ class RedisConnection(Connectable):
     """
     A Connectable wrapper over a Redis client.
 
-    The sync client is shared per URL for the life of the process, because a
+    The sync client is shared per URL for the life of its holders, because a
     Redis client is a connection pool and building one per caller defeats it.
-    ``_disconnect`` is therefore a no-op: one caller finishing must not close a
-    pool others are still using. Async clients are per-instance, since they are
-    bound to a running event loop.
+    Each ``connect`` takes a hold; ``disconnect`` releases it and closes the
+    pool only when no holder remains. Async clients are per-instance, since they
+    are bound to a running event loop.
     """
 
     _shared_clients: dict[str, Any] = {}
+    _shared_refs: dict[str, int] = {}
 
     def __init__(self, url: str | None = None, safe: bool = False, **kwargs: Any) -> None:
         """
@@ -83,6 +88,7 @@ class RedisConnection(Connectable):
         self._url = url or get_settings().redis.url or DEFAULT_URL
         self._safe = safe
         self._async_client: Any = None
+        self._holds_shared = False
 
     @property
     def url(self) -> str:
@@ -93,7 +99,7 @@ class RedisConnection(Connectable):
 
     @property
     def is_connected(self) -> bool:
-        return RedisConnection._shared_clients.get(self._url) is not None
+        return self._holds_shared
 
     @property
     def is_async_connected(self) -> bool:
@@ -102,8 +108,10 @@ class RedisConnection(Connectable):
     @property
     def client(self) -> Any:
         """
-        The sync client, raising if the connection was never opened.
+        The sync client, raising if this instance has not connected.
         """
+        if not self._holds_shared:
+            raise RedisNotConnectedError("RedisConnection is not connected. Call connect() or use a with block.")
         existing = RedisConnection._shared_clients.get(self._url)
         if existing is None:
             raise RedisNotConnectedError("RedisConnection is not connected. Call connect() or use a with block.")
@@ -135,11 +143,29 @@ class RedisConnection(Connectable):
         if RedisConnection._shared_clients.get(self._url) is None:
             self.info(f"Creating shared Redis client for {self._url}")
             RedisConnection._shared_clients[self._url] = self._build(is_async=False)
+            RedisConnection._shared_refs[self._url] = 0
+        if not self._holds_shared:
+            RedisConnection._shared_refs[self._url] = RedisConnection._shared_refs.get(self._url, 0) + 1
+            self._holds_shared = True
 
     def _disconnect(self) -> None:
         """
-        Deliberately a no-op: the sync client is a process-wide pool.
+        Release this instance's hold on the shared pool; close it when last.
         """
+        if not self._holds_shared:
+            return
+        self._holds_shared = False
+        refs = RedisConnection._shared_refs.get(self._url, 1) - 1
+        if refs <= 0:
+            client = RedisConnection._shared_clients.pop(self._url, None)
+            RedisConnection._shared_refs.pop(self._url, None)
+            if client is not None:
+                try:
+                    client.close()
+                except Exception as exc:
+                    self.debug(f"Error closing Redis client for {self._url}: {exc}")
+        else:
+            RedisConnection._shared_refs[self._url] = refs
 
     async def _async_connect(self) -> None:
         self._async_client = self._build(is_async=True)
@@ -166,6 +192,7 @@ class RedisConnection(Connectable):
             except Exception as exc:
                 logger.debug("Error closing Redis client for %s: %s", url, exc)
             del cls._shared_clients[url]
+        cls._shared_refs.clear()
 
     # ------------------------------------------------------------------
     # Sync API
@@ -175,9 +202,11 @@ class RedisConnection(Connectable):
         return _decode(self.client.get(key))
 
     def set(self, key: str, value: Any, **kwargs: Any) -> None:
+        self.require_writable()
         self.client.set(key, _encode(value), **kwargs)
 
     def delete(self, *keys: str) -> None:
+        self.require_writable()
         self.client.delete(*keys)
 
     def ping(self) -> bool:
@@ -187,15 +216,18 @@ class RedisConnection(Connectable):
         return bool(self.client.exists(key))
 
     def expire(self, key: str, seconds: int) -> None:
+        self.require_writable()
         self.client.expire(key, seconds)
 
     def ttl(self, key: str) -> int:
         return self.client.ttl(key)
 
     def incr(self, key: str, amount: int = 1) -> int:
+        self.require_writable()
         return self.client.incr(key, amount)
 
     def decr(self, key: str, amount: int = 1) -> int:
+        self.require_writable()
         return self.client.decr(key, amount)
 
     def keys(self, pattern: str = "*") -> list[Any]:
@@ -205,13 +237,19 @@ class RedisConnection(Connectable):
         return _decode(self.client.hget(key, field))
 
     def hset(self, key: str, field: str, value: Any) -> None:
+        self.require_writable()
         self.client.hset(key, field, _encode(value))
 
     def hdel(self, key: str, *fields: str) -> None:
+        self.require_writable()
         self.client.hdel(key, *fields)
 
     def publish(self, channel: str, message: Any) -> int:
-        return self.client.publish(channel, _encode(message))
+        self.require_writable()
+        # Pre-serialized pub/sub payloads (JSON strings, bytes) pass through;
+        # structured values are encoded the same way as cache writes.
+        payload = message if isinstance(message, (str, bytes, bytearray)) else _encode(message)
+        return self.client.publish(channel, payload)
 
     def pubsub(self) -> Any:
         return self.client.pubsub()
@@ -224,16 +262,21 @@ class RedisConnection(Connectable):
         return _decode(await self.async_client.get(key))
 
     async def aset(self, key: str, value: Any, **kwargs: Any) -> None:
+        self.require_writable()
         await self.async_client.set(key, _encode(value), **kwargs)
 
     async def asetex(self, key: str, seconds: int, value: Any) -> None:
+        self.require_writable()
         await self.async_client.setex(key, seconds, _encode(value))
 
     async def adelete(self, *keys: str) -> None:
+        self.require_writable()
         await self.async_client.delete(*keys)
 
     async def akeys(self, pattern: str = "*") -> list[Any]:
         return await self.async_client.keys(pattern)
 
     async def apublish(self, channel: str, message: Any) -> int:
-        return await self.async_client.publish(channel, _encode(message))
+        self.require_writable()
+        payload = message if isinstance(message, (str, bytes, bytearray)) else _encode(message)
+        return await self.async_client.publish(channel, payload)