Improved the repr() output of schedulers, data stores and event brokers

docs/versionhistory.rst

@@ -56,6 +56,8 @@ APScheduler, see the :doc:`migration section <migration>`.
   synchronous engine
 - Fixed serializers raising their own exceptions instead of ``SerializationError`` and
   ``DeserializationError`` as appropriate
+- Fixed ``repr()`` outputs of schedulers, data stores and event brokers to be much more
+  useful and reasonable
 
 **4.0.0a5**
 

src/apscheduler/_schedulers/async_.py

@@ -59,7 +59,7 @@
     Task,
     TaskDefaults,
 )
-from .._utils import UnsetValue, merge_metadata, unset
+from .._utils import UnsetValue, create_repr, merge_metadata, unset
 from .._validators import non_negative_number
 from ..abc import DataStore, EventBroker, JobExecutor, Subscription, Trigger
 from ..datastores.memory import MemoryDataStore
@@ -85,7 +85,7 @@
 T = TypeVar("T")
 
 
-@attrs.define(eq=False)
+@attrs.define(eq=False, repr=False)
 class AsyncScheduler:
     """
     An asynchronous (AnyIO based) scheduler implementation.
@@ -194,6 +194,9 @@ async def __aexit__(
         await self.stop()
         await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
 
+    def __repr__(self) -> str:
+        return create_repr(self, "identity", "role", "data_store", "event_broker")
+
     async def _ensure_services_initialized(self, exit_stack: AsyncExitStack) -> None:
         """
         Initialize the data store and event broker if this hasn't already been done.

src/apscheduler/_schedulers/sync.py

@@ -19,7 +19,7 @@
 from .._enums import CoalescePolicy, ConflictPolicy, RunState, SchedulerRole
 from .._events import Event, T_Event
 from .._structures import Job, JobResult, MetadataType, Schedule, Task, TaskDefaults
-from .._utils import UnsetValue, unset
+from .._utils import UnsetValue, create_repr, unset
 from ..abc import DataStore, EventBroker, JobExecutor, Subscription, Trigger
 from .async_ import AsyncScheduler, TaskType
 
@@ -29,7 +29,7 @@
     from typing_extensions import Self
 
 
-@attrs.define(init=False)
+@attrs.define(init=False, repr=False)
 class Scheduler:
     """
     A synchronous wrapper for :class:`AsyncScheduler`.
@@ -171,6 +171,9 @@ def _ensure_services_ready(
 
         return self._portal
 
+    def __repr__(self) -> str:
+        return create_repr(self, "identity", "role", "data_store", "event_broker")
+
     def cleanup(self) -> None:
         portal = self._ensure_services_ready()
         return portal.call(self._async_scheduler.cleanup)

src/apscheduler/_utils.py

@@ -89,3 +89,18 @@ def merge_metadata(
         new_metadata.update(metadata)
 
     return new_metadata
+
+
+def create_repr(instance: object, *attrnames: str, **kwargs) -> str:
+    kv_pairs: list[tuple[str, object]] = []
+    for attrname in attrnames:
+        value = getattr(instance, attrname)
+        if value is not unset and value is not None:
+            kv_pairs.append((attrname, value))
+
+    for key, value in kwargs.items():
+        if value is not unset and value is not None:
+            kv_pairs.append((key, value))
+
+    rendered_attrs = ", ".join(f"{key}={value!r}" for key, value in kv_pairs)
+    return f"{instance.__class__.__name__}({rendered_attrs})"

src/apscheduler/datastores/memory.py

@@ -25,12 +25,13 @@
 )
 from .._exceptions import ConflictingIdError, TaskLookupError
 from .._structures import Job, JobResult, Schedule, ScheduleResult, Task
+from .._utils import create_repr
 from .base import BaseDataStore
 
 max_datetime = datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=timezone.utc)
 
 
-@attrs.define(eq=False)
+@attrs.define(eq=False, repr=False)
 class MemoryDataStore(BaseDataStore):
     """
     Stores scheduler data in memory, without serializing it.
@@ -49,6 +50,9 @@ class MemoryDataStore(BaseDataStore):
     _jobs_by_schedule_id: dict[str, set[Job]] = attrs.Factory(partial(defaultdict, set))
     _job_results: dict[UUID, JobResult] = attrs.Factory(dict)
 
+    def __repr__(self) -> str:
+        return create_repr(self)
+
     def _find_schedule_index(self, schedule: Schedule) -> int:
         left_index = bisect_left(self._schedules, schedule)
         right_index = bisect_right(self._schedules, schedule)

src/apscheduler/datastores/mongodb.py

@@ -42,6 +42,7 @@
     TaskLookupError,
 )
 from .._structures import Job, JobResult, Schedule, ScheduleResult, Task
+from .._utils import create_repr
 from ..abc import EventBroker
 from .base import BaseExternalDataStore
 
@@ -123,7 +124,7 @@ async def create(cls, func: Callable[..., Cursor[T]]) -> AsyncCursor[T]:
         return AsyncCursor(cursor)
 
 
-@attrs.define(eq=False)
+@attrs.define(eq=False, repr=False)
 class MongoDBDataStore(BaseExternalDataStore):
     """
     Uses a MongoDB server to store data.
@@ -194,6 +195,10 @@ def __attrs_post_init__(self) -> None:
         self._jobs = database["jobs"]
         self._jobs_results = database["job_results"]
 
+    def __repr__(self) -> str:
+        server_descriptions = self._client.topology_description.server_descriptions()
+        return create_repr(self, host=list(server_descriptions))
+
     def _initialize(self) -> None:
         with self._client.start_session() as session:
             if self.start_from_scratch:

src/apscheduler/datastores/sqlalchemy.py

@@ -76,6 +76,7 @@
     TaskLookupError,
 )
 from .._structures import Job, JobResult, Schedule, ScheduleResult, Task
+from .._utils import create_repr
 from ..abc import EventBroker
 from .base import BaseExternalDataStore
 
@@ -121,7 +122,7 @@ class _JobDiscard:
     exception: Exception | None = None
 
 
-@attrs.define(eq=False)
+@attrs.define(eq=False, repr=False)
 class SQLAlchemyDataStore(BaseExternalDataStore):
     """
     Uses a relational database to store data.
@@ -189,6 +190,9 @@ def __attrs_post_init__(self) -> None:
         self._t_jobs = self._metadata.tables[prefix + "jobs"]
         self._t_job_results = self._metadata.tables[prefix + "job_results"]
 
+    def __repr__(self) -> str:
+        return create_repr(self, url=repr(self._engine.url), schema=self.schema)
+
     def _retry(self) -> tenacity.AsyncRetrying:
         def after_attempt(retry_state: tenacity.RetryCallState) -> None:
             self._logger.warning(

src/apscheduler/eventbrokers/asyncpg.py

@@ -19,13 +19,14 @@
 
 from .._events import Event
 from .._exceptions import SerializationError
+from .._utils import create_repr
 from .base import BaseExternalEventBroker
 
 if TYPE_CHECKING:
     from sqlalchemy.ext.asyncio import AsyncEngine
 
 
-@attrs.define(eq=False)
+@attrs.define(eq=False, repr=False)
 class AsyncpgEventBroker(BaseExternalEventBroker):
     """
     An asynchronous, asyncpg_ based event broker that uses a PostgreSQL server to
@@ -80,6 +81,9 @@ def from_async_sqla_engine(
         dsn = engine.url.render_as_string(hide_password=False).replace("+asyncpg", "")
         return cls(dsn, options or {}, **kwargs)
 
+    def __repr__(self) -> str:
+        return create_repr(self, "dsn")
+
     @property
     def _temporary_failure_exceptions(self) -> tuple[type[Exception], ...]:
         return OSError, InterfaceError

src/apscheduler/eventbrokers/local.py

@@ -3,10 +3,11 @@
 import attrs
 
 from .._events import Event
+from .._utils import create_repr
 from .base import BaseEventBroker
 
 
-@attrs.define(eq=False)
+@attrs.define(eq=False, repr=False)
 class LocalEventBroker(BaseEventBroker):
     """
     Asynchronous, local event broker.
@@ -17,5 +18,8 @@ class LocalEventBroker(BaseEventBroker):
     Does not serialize events.
     """
 
+    def __repr__(self) -> str:
+        return create_repr(self)
+
     async def publish(self, event: Event) -> None:
         await self.publish_local(event)

src/apscheduler/eventbrokers/mqtt.py

@@ -15,12 +15,13 @@
 from paho.mqtt.enums import CallbackAPIVersion
 
 from .._events import Event
+from .._utils import create_repr
 from .base import BaseExternalEventBroker
 
 ALLOWED_TRANSPORTS = ("mqtt", "mqtts", "ws", "wss", "unix")
 
 
-@attrs.define(eq=False)
+@attrs.define(eq=False, repr=False)
 class MQTTEventBroker(BaseExternalEventBroker):
     """
     An event broker that uses an MQTT (v3.1 or v5) broker to broadcast events.
@@ -80,6 +81,9 @@ def __attrs_post_init__(self) -> None:
         elif self.ssl:
             self._client.tls_set()
 
+    def __repr__(self) -> str:
+        return create_repr(self, "host", "port", "transport")
+
     async def start(self, exit_stack: AsyncExitStack, logger: Logger) -> None:
         await super().start(exit_stack, logger)
         self._portal = await exit_stack.enter_async_context(BlockingPortal())

src/apscheduler/eventbrokers/psycopg.py

@@ -18,6 +18,7 @@
 
 from .._events import Event
 from .._exceptions import SerializationError
+from .._utils import create_repr
 from .._validators import positive_number
 from .base import BaseExternalEventBroker
 
@@ -29,7 +30,7 @@ def convert_options(value: Mapping[str, Any]) -> dict[str, Any]:
     return dict(value, autocommit=True)
 
 
-@attrs.define(eq=False)
+@attrs.define(eq=False, repr=False)
 class PsycopgEventBroker(BaseExternalEventBroker):
     """
     An asynchronous, psycopg_ based event broker that uses a PostgreSQL server to
@@ -91,6 +92,9 @@ def from_async_sqla_engine(
         )
         return cls(conninfo, options or {}, **kwargs)
 
+    def __repr__(self) -> str:
+        return create_repr(self, "conninfo")
+
     @property
     def _temporary_failure_exceptions(self) -> tuple[type[Exception], ...]:
         return OSError, InterfaceError

src/apscheduler/eventbrokers/redis.py

@@ -15,10 +15,11 @@
 from redis.asyncio.connection import ConnectionPool
 
 from .._events import Event
+from .._utils import create_repr
 from .base import BaseExternalEventBroker
 
 
-@attrs.define(eq=False)
+@attrs.define(eq=False, repr=False)
 class RedisEventBroker(BaseExternalEventBroker):
     """
     An event broker that uses a Redis server to broadcast events.
@@ -55,6 +56,9 @@ def __attrs_post_init__(self) -> None:
         else:
             self._client = self.client_or_url
 
+    def __repr__(self) -> str:
+        return create_repr(self, "client_or_url")
+
     def _retry(self) -> tenacity.AsyncRetrying:
         def after_attempt(retry_state: tenacity.RetryCallState) -> None:
             self._logger.warning(

tests/test_datastores.py

@@ -4,6 +4,7 @@
 from contextlib import AsyncExitStack, asynccontextmanager
 from datetime import datetime, timedelta, timezone
 from logging import Logger
+from pathlib import Path
 from typing import TYPE_CHECKING, AsyncGenerator
 from unittest.mock import Mock
 
@@ -32,6 +33,9 @@
 from apscheduler._structures import ScheduleResult
 from apscheduler.abc import DataStore, EventBroker, Serializer
 from apscheduler.datastores.base import BaseExternalDataStore
+from apscheduler.datastores.memory import MemoryDataStore
+from apscheduler.datastores.mongodb import MongoDBDataStore
+from apscheduler.datastores.sqlalchemy import SQLAlchemyDataStore
 from apscheduler.triggers.date import DateTrigger
 
 if TYPE_CHECKING:
@@ -819,3 +823,24 @@ async def test_acquire_jobs_deserialization_failure(
 
     # This should not yield any jobs
     assert await datastore.acquire_jobs("scheduler_id", timedelta(seconds=30), 1) == []
+
+
+class TestRepr:
+    async def test_memory(self, memory_store: MemoryDataStore) -> None:
+        assert repr(memory_store) == "MemoryDataStore()"
+
+    async def test_aiosqlite(
+        self, aiosqlite_store: SQLAlchemyDataStore, tmp_path: Path
+    ) -> None:
+        assert repr(aiosqlite_store) == (
+            f"SQLAlchemyDataStore(url='sqlite+aiosqlite:///{tmp_path}/test.db')"
+        )
+
+    async def test_psycopg(self, psycopg_async_store: SQLAlchemyDataStore) -> None:
+        assert repr(psycopg_async_store) == (
+            "SQLAlchemyDataStore(url='postgresql+psycopg://postgres:***@localhost/"
+            "testdb', schema='psycopg_async')"
+        )
+
+    async def test_mongodb(self, mongodb_store: MongoDBDataStore) -> None:
+        assert repr(mongodb_store) == "MongoDBDataStore(host=[('localhost', 27017)])"

tests/test_schedulers.py

@@ -133,6 +133,13 @@ def __call__(self) -> int:
 
 
 class TestAsyncScheduler:
+    def test_repr(self) -> None:
+        scheduler = AsyncScheduler(identity="my identity")
+        assert repr(scheduler) == (
+            "AsyncScheduler(identity='my identity', role=<SchedulerRole.both: 3>, "
+            "data_store=MemoryDataStore(), event_broker=LocalEventBroker())"
+        )
+
     async def test_use_before_initialized(self) -> None:
         scheduler = AsyncScheduler()
         with pytest.raises(
@@ -1057,6 +1064,13 @@ def test_interface_parity(self) -> None:
                         args == sync_args[kind]
                     ), f"Parameter mismatch for {attrname}(): {args} != {sync_args[kind]}"
 
+    def test_repr(self) -> None:
+        scheduler = Scheduler(identity="my identity")
+        assert repr(scheduler) == (
+            "Scheduler(identity='my identity', role=<SchedulerRole.both: 3>, "
+            "data_store=MemoryDataStore(), event_broker=LocalEventBroker())"
+        )
+
     def test_configure(self) -> None:
         executor = ThreadPoolJobExecutor()
         task_defaults = TaskDefaults(job_executor="executor1")