From fba959516cf9af1723fffb9179ce262542d68659 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Gr=C3=B6nholm?= Date: Sat, 30 Jul 2022 18:15:45 +0300 Subject: Made the apscheduler.converters module private --- src/apscheduler/_converters.py | 68 +++++++++++++++++++++++++ src/apscheduler/converters.py | 68 ------------------------- src/apscheduler/events.py | 97 +++++++++++++++++++++++++++++++++--- src/apscheduler/schedulers/async_.py | 2 +- src/apscheduler/structures.py | 2 +- src/apscheduler/workers/async_.py | 2 +- 6 files changed, 161 insertions(+), 78 deletions(-) create mode 100644 src/apscheduler/_converters.py delete mode 100644 src/apscheduler/converters.py (limited to 'src') diff --git a/src/apscheduler/_converters.py b/src/apscheduler/_converters.py new file mode 100644 index 0000000..3518d44 --- /dev/null +++ b/src/apscheduler/_converters.py @@ -0,0 +1,68 @@ +from __future__ import annotations + +from collections.abc import Callable +from datetime import datetime, timedelta +from enum import Enum +from typing import TypeVar +from uuid import UUID + +from . import abc + +TEnum = TypeVar("TEnum", bound=Enum) + + +def as_aware_datetime(value: datetime | str) -> datetime: + """Convert the value from a string to a timezone aware datetime.""" + if isinstance(value, str): + # fromisoformat() does not handle the "Z" suffix + if value.upper().endswith("Z"): + value = value[:-1] + "+00:00" + + value = datetime.fromisoformat(value) + + return value + + +def as_uuid(value: UUID | str) -> UUID: + """Convert a string-formatted UUID to a UUID instance.""" + if isinstance(value, str): + return UUID(value) + + return value + + +def as_timedelta(value: timedelta | float | None) -> timedelta | None: + if isinstance(value, (float, int)): + return timedelta(seconds=value) + + return value + + +def as_enum(enum_class: type[TEnum]) -> Callable[[TEnum | str], TEnum]: + def converter(value: TEnum | str) -> TEnum: + if isinstance(value, str): + return enum_class.__members__[value] + + return value + + return converter + + +def as_async_eventbroker( + value: abc.EventBroker | abc.AsyncEventBroker, +) -> abc.AsyncEventBroker: + if isinstance(value, abc.EventBroker): + from apscheduler.eventbrokers.async_adapter import AsyncEventBrokerAdapter + + return AsyncEventBrokerAdapter(value) + + return value + + +def as_async_datastore(value: abc.DataStore | abc.AsyncDataStore) -> abc.AsyncDataStore: + if isinstance(value, abc.DataStore): + from apscheduler.datastores.async_adapter import AsyncDataStoreAdapter + + return AsyncDataStoreAdapter(value) + + return value diff --git a/src/apscheduler/converters.py b/src/apscheduler/converters.py deleted file mode 100644 index 3518d44..0000000 --- a/src/apscheduler/converters.py +++ /dev/null @@ -1,68 +0,0 @@ -from __future__ import annotations - -from collections.abc import Callable -from datetime import datetime, timedelta -from enum import Enum -from typing import TypeVar -from uuid import UUID - -from . import abc - -TEnum = TypeVar("TEnum", bound=Enum) - - -def as_aware_datetime(value: datetime | str) -> datetime: - """Convert the value from a string to a timezone aware datetime.""" - if isinstance(value, str): - # fromisoformat() does not handle the "Z" suffix - if value.upper().endswith("Z"): - value = value[:-1] + "+00:00" - - value = datetime.fromisoformat(value) - - return value - - -def as_uuid(value: UUID | str) -> UUID: - """Convert a string-formatted UUID to a UUID instance.""" - if isinstance(value, str): - return UUID(value) - - return value - - -def as_timedelta(value: timedelta | float | None) -> timedelta | None: - if isinstance(value, (float, int)): - return timedelta(seconds=value) - - return value - - -def as_enum(enum_class: type[TEnum]) -> Callable[[TEnum | str], TEnum]: - def converter(value: TEnum | str) -> TEnum: - if isinstance(value, str): - return enum_class.__members__[value] - - return value - - return converter - - -def as_async_eventbroker( - value: abc.EventBroker | abc.AsyncEventBroker, -) -> abc.AsyncEventBroker: - if isinstance(value, abc.EventBroker): - from apscheduler.eventbrokers.async_adapter import AsyncEventBrokerAdapter - - return AsyncEventBrokerAdapter(value) - - return value - - -def as_async_datastore(value: abc.DataStore | abc.AsyncDataStore) -> abc.AsyncDataStore: - if isinstance(value, abc.DataStore): - from apscheduler.datastores.async_adapter import AsyncDataStoreAdapter - - return AsyncDataStoreAdapter(value) - - return value diff --git a/src/apscheduler/events.py b/src/apscheduler/events.py index 6aba147..24697fd 100644 --- a/src/apscheduler/events.py +++ b/src/apscheduler/events.py @@ -9,7 +9,7 @@ import attrs from attrs.converters import optional from . import abc -from .converters import as_aware_datetime, as_uuid +from ._converters import as_aware_datetime, as_uuid from .enums import JobOutcome @@ -22,6 +22,12 @@ def serialize(inst, field, value): @attrs.define(kw_only=True, frozen=True) class Event: + """ + Base class for all events. + + :ivar timestamp: the time when the event occurrent + """ + timestamp: datetime = attrs.field( factory=partial(datetime.now, timezone.utc), converter=as_aware_datetime ) @@ -41,43 +47,90 @@ class Event: @attrs.define(kw_only=True, frozen=True) class DataStoreEvent(Event): - pass + """Base class for events originating from a data store.""" @attrs.define(kw_only=True, frozen=True) class TaskAdded(DataStoreEvent): + """ + Signals that a new task was added to the store. + + :ivar task_id: ID of the task that was added + """ + task_id: str @attrs.define(kw_only=True, frozen=True) class TaskUpdated(DataStoreEvent): + """ + Signals that a task was updated in a data store. + + :ivar task_id: ID of the task that was updated + """ + task_id: str @attrs.define(kw_only=True, frozen=True) class TaskRemoved(DataStoreEvent): + """ + Signals that a task was removed from the store. + + :ivar task_id: ID of the task that was removed + """ + task_id: str @attrs.define(kw_only=True, frozen=True) class ScheduleAdded(DataStoreEvent): + """ + Signals that a new schedule was added to the store. + + :ivar schedule_id: ID of the schedule that was added + :ivar next_fire_time: the first run time calculated for the schedule + """ + schedule_id: str next_fire_time: datetime | None = attrs.field(converter=optional(as_aware_datetime)) @attrs.define(kw_only=True, frozen=True) class ScheduleUpdated(DataStoreEvent): + """ + Signals that a schedule has been updated in the store. + + :ivar schedule_id: ID of the schedule that was updated + :ivar next_fire_time: the next time the schedule will run + """ + schedule_id: str next_fire_time: datetime | None = attrs.field(converter=optional(as_aware_datetime)) @attrs.define(kw_only=True, frozen=True) class ScheduleRemoved(DataStoreEvent): + """ + Signals that a schedule was removed from the store. + + :ivar schedule_id: ID of the schedule that was removed + """ + schedule_id: str @attrs.define(kw_only=True, frozen=True) class JobAdded(DataStoreEvent): + """ + Signals that a new job was added to the store. + + :ivar job_id: ID of the job that was added + :ivar task_id: ID of the task the job would run + :ivar schedule_id: ID of the schedule the job was created from + :ivar tags: the set of tags collected from the associated task and schedule + """ + job_id: UUID = attrs.field(converter=as_uuid) task_id: str schedule_id: str | None @@ -86,6 +139,13 @@ class JobAdded(DataStoreEvent): @attrs.define(kw_only=True, frozen=True) class JobRemoved(DataStoreEvent): + """ + Signals that a job was removed from the store. + + :ivar job_id: ID of the job that was removed + + """ + job_id: UUID = attrs.field(converter=as_uuid) @@ -108,7 +168,7 @@ class JobDeserializationFailed(DataStoreEvent): @attrs.define(kw_only=True, frozen=True) class SchedulerEvent(Event): - pass + """Base class for events originating from a scheduler.""" @attrs.define(kw_only=True, frozen=True) @@ -118,6 +178,12 @@ class SchedulerStarted(SchedulerEvent): @attrs.define(kw_only=True, frozen=True) class SchedulerStopped(SchedulerEvent): + """ + Signals that a scheduler has stopped. + + :ivar exception: the exception that caused the scheduler to stop, if any + """ + exception: BaseException | None = None @@ -128,22 +194,33 @@ class SchedulerStopped(SchedulerEvent): @attrs.define(kw_only=True, frozen=True) class WorkerEvent(Event): - pass + """Base class for events originating from a worker.""" @attrs.define(kw_only=True, frozen=True) class WorkerStarted(WorkerEvent): - pass + """Signals that a worker has started.""" @attrs.define(kw_only=True, frozen=True) class WorkerStopped(WorkerEvent): + """ + Signals that a worker has stopped. + + :ivar exception: the exception that caused the worker to stop, if any + """ + exception: BaseException | None = None @attrs.define(kw_only=True, frozen=True) class JobAcquired(WorkerEvent): - """Signals that a worker has acquired a job for processing.""" + """ + Signals that a worker has acquired a job for processing. + + :param job_id: the ID of the job that was acquired + :param worker_id: the ID of the worker that acquired the job + """ job_id: UUID = attrs.field(converter=as_uuid) worker_id: str @@ -151,7 +228,13 @@ class JobAcquired(WorkerEvent): @attrs.define(kw_only=True, frozen=True) class JobReleased(WorkerEvent): - """Signals that a worker has finished processing of a job.""" + """ + Signals that a worker has finished processing of a job. + + :param job_id: the ID of the job that was released + :param worker_id: the ID of the worker that released the job + :param outcome: the outcome of the job + """ job_id: UUID = attrs.field(converter=as_uuid) worker_id: str diff --git a/src/apscheduler/schedulers/async_.py b/src/apscheduler/schedulers/async_.py index 4ad15ac..3e0f96a 100644 --- a/src/apscheduler/schedulers/async_.py +++ b/src/apscheduler/schedulers/async_.py @@ -14,9 +14,9 @@ import attrs from anyio import TASK_STATUS_IGNORED, create_task_group, move_on_after from anyio.abc import TaskGroup, TaskStatus +from .._converters import as_async_datastore, as_async_eventbroker from ..abc import AsyncDataStore, AsyncEventBroker, Job, Schedule, Subscription, Trigger from ..context import current_scheduler -from ..converters import as_async_datastore, as_async_eventbroker from ..datastores.memory import MemoryDataStore from ..enums import CoalescePolicy, ConflictPolicy, JobOutcome, RunState from ..eventbrokers.async_local import LocalAsyncEventBroker diff --git a/src/apscheduler/structures.py b/src/apscheduler/structures.py index 8d1ba89..55d5278 100644 --- a/src/apscheduler/structures.py +++ b/src/apscheduler/structures.py @@ -11,7 +11,7 @@ import tenacity.wait from attrs.validators import instance_of from . import abc -from .converters import as_enum, as_timedelta +from ._converters import as_enum, as_timedelta from .enums import CoalescePolicy, JobOutcome from .marshalling import callable_from_ref, callable_to_ref diff --git a/src/apscheduler/workers/async_.py b/src/apscheduler/workers/async_.py index 0fe632f..51bb25e 100644 --- a/src/apscheduler/workers/async_.py +++ b/src/apscheduler/workers/async_.py @@ -20,9 +20,9 @@ from anyio import ( ) from anyio.abc import CancelScope, TaskGroup +from .._converters import as_async_datastore, as_async_eventbroker from ..abc import AsyncDataStore, AsyncEventBroker, Job from ..context import current_worker, job_info -from ..converters import as_async_datastore, as_async_eventbroker from ..enums import JobOutcome, RunState from ..eventbrokers.async_local import LocalAsyncEventBroker from ..events import JobAdded, WorkerStarted, WorkerStopped -- cgit v1.2.1