diff --git a/docs/guides/scheduling.md b/docs/guides/scheduling.md index 7750fb8c..e4579042 100644 --- a/docs/guides/scheduling.md +++ b/docs/guides/scheduling.md @@ -297,7 +297,7 @@ These are covered more extensively in our [events reference](../reference/schedu from amltk._doc import doc_print; doc_print(print, scheduler, output="html", fontsize="small") # markdown-exec: hide ``` -=== "`limit=`" +=== "`max_calls=`" Limit the number of times a callback can be called, after which, the callback will be ignored. @@ -316,7 +316,7 @@ These are covered more extensively in our [events reference](../reference/schedu def submit_calculations() -> None: scheduler.submit(expensive_function, 2) - @scheduler.on_future_result(limit=3) + @scheduler.on_future_result(max_calls=3) def print_result(future, result) -> None: scheduler.submit(expensive_function, 2) diff --git a/src/amltk/scheduling/events.py b/src/amltk/scheduling/events.py index fdb8a8ed..516d7616 100644 --- a/src/amltk/scheduling/events.py +++ b/src/amltk/scheduling/events.py @@ -75,7 +75,7 @@ def on_start(): from amltk._doc import doc_print; doc_print(print, scheduler, fontsize="small") # markdown-exec: hide ``` - === "`on('event', limit=...)`" + === "`on('event', max_calls=...)`" Limit the number of times a callback can be called, after which, the callback will be ignored. @@ -94,7 +94,7 @@ def expensive_function(x: int) -> int: def submit_calculations() -> None: scheduler.submit(expensive_function, 2) - @scheduler.on_future_result(limit=3) + @scheduler.on_future_result(max_calls=3) def print_result(future, result) -> None: scheduler.submit(expensive_function, 2) @@ -355,7 +355,7 @@ def callback(a: int, b: str) -> None: emitter: Emitter event: Event[P] when: Callable[[], bool] | None = None - limit: int | None = None + max_calls: int | None = None repeat: int = 1 every: int = 1 @@ -370,7 +370,7 @@ def __call__( callback: None = None, *, when: Callable[[], bool] | None = ..., - limit: int | None = ..., + max_calls: int | None = ..., repeat: int = ..., every: int = ..., ) -> partial[Callable[P, Any]]: @@ -382,7 +382,7 @@ def __call__( callback: Callable[P, Any], *, when: Callable[[], bool] | None = ..., - limit: int | None = ..., + max_calls: int | None = ..., repeat: int = ..., every: int = ..., hidden: bool = ..., @@ -394,7 +394,7 @@ def __call__( callback: Callable[P, Any] | None = None, *, when: Callable[[], bool] | None = None, - limit: int | None = None, + max_calls: int | None = None, repeat: int = 1, every: int = 1, hidden: bool = False, @@ -406,7 +406,7 @@ def __call__( when: A predicate that must be satisfied for the callback to be called. every: The callback will be called every `every` times the event is emitted. repeat: The callback will be called `repeat` times successively. - limit: The maximum number of times the callback can be called. + max_calls: The maximum number of times the callback can be called. hidden: Whether to hide the callback in visual output. This is mainly used to facilitate Plugins who act upon events but don't want to be seen, primarily @@ -420,7 +420,7 @@ def __call__( return partial( self.__call__, when=when, - limit=limit, + max_calls=max_calls, repeat=repeat, every=every, ) # type: ignore @@ -429,7 +429,7 @@ def __call__( self.event, callback, when=when, - limit=limit, + max_calls=max_calls, repeat=repeat, every=every, hidden=hidden, @@ -454,7 +454,7 @@ class Handler(Generic[P]): every: int = 1 n_calls_to_handler: int = 0 n_calls_to_callback: int = 0 - limit: int | None = None + max_calls: int | None = None repeat: int = 1 registered_at: int = field(default_factory=time.time_ns) hidden: bool = False @@ -471,9 +471,9 @@ def __call__(self, *args: P.args, **kwargs: P.kwargs) -> None: if self.when is not None and not self.when(): return - limit = self.limit if self.limit is not None else math.inf + max_calls = self.max_calls if self.max_calls is not None else math.inf for _ in range(self.repeat): - if self.n_calls_to_callback >= limit: + if self.n_calls_to_callback >= max_calls: return logger.debug(f"Calling: {callstring(self.callback)}") @@ -602,7 +602,7 @@ def subscriber( when: Callable[[], bool] | None = None, every: int = 1, repeat: int = 1, - limit: int | None = None, + max_calls: int | None = None, ) -> Subscriber[P]: """Create a subscriber for an event. @@ -611,18 +611,18 @@ def subscriber( when: A predicate that must be satisfied for the callback to be called. every: The callback will be called every `every` times the event is emitted. repeat: The callback will be called `repeat` times successively. - limit: The maximum number of times the callback can be called. + max_calls: The maximum number of times the callback can be called. """ if event not in self.handlers: self.handlers[event] = [] return Subscriber( self, - event, + event, # type: ignore when=when, every=every, repeat=repeat, - limit=limit, + max_calls=max_calls, ) def on( @@ -633,7 +633,7 @@ def on( when: Callable[[], bool] | None = None, every: int = 1, repeat: int = 1, - limit: int | None = None, + max_calls: int | None = None, hidden: bool = False, ) -> None: """Register a callback for an event. @@ -644,7 +644,7 @@ def on( when: A predicate that must be satisfied for the callback to be called. every: The callback will be called every `every` times the event is emitted. repeat: The callback will be called `repeat` times successively. - limit: The maximum number of times the callback can be called. + max_calls: The maximum number of times the callback can be called. hidden: Whether to hide the callback in visual output. This is mainly used to facilitate Plugins who act upon events but don't want to be seen, primarily @@ -668,7 +668,7 @@ def on( when=when, every=every, repeat=repeat, - limit=limit, + max_calls=max_calls, hidden=hidden, ), ) diff --git a/src/amltk/scheduling/task.py b/src/amltk/scheduling/task.py index bbda044c..a6550666 100644 --- a/src/amltk/scheduling/task.py +++ b/src/amltk/scheduling/task.py @@ -230,7 +230,7 @@ def on( callback: None = None, *, when: Callable[[], bool] | None = ..., - limit: int | None = ..., + max_calls: int | None = ..., repeat: int = ..., every: int = ..., ) -> Subscriber[P2]: @@ -243,7 +243,7 @@ def on( callback: None = None, *, when: Callable[[], bool] | None = ..., - limit: int | None = ..., + max_calls: int | None = ..., repeat: int = ..., every: int = ..., ) -> Subscriber[...]: @@ -256,7 +256,7 @@ def on( callback: Callable, *, when: Callable[[], bool] | None = ..., - limit: int | None = ..., + max_calls: int | None = ..., repeat: int = ..., every: int = ..., ) -> None: @@ -268,7 +268,7 @@ def on( callback: Callable[P2, Any] | None = None, *, when: Callable[[], bool] | None = None, - limit: int | None = None, + max_calls: int | None = None, repeat: int = 1, every: int = 1, hidden: bool = False, @@ -280,7 +280,7 @@ def on( callback: The callback to call when the event is emitted. If not specified, what is returned can be used as a decorator. when: A predicate to determine whether to call the callback. - limit: The number of times to call the callback. + max_calls: The maximum number of times to call the callback. repeat: The number of times to repeat the subscription. every: The number of times to wait between repeats. hidden: Whether to hide the callback in visual output. @@ -304,7 +304,7 @@ def on( subscriber = self.emitter.subscriber( _e, # type: ignore when=when, - limit=limit, + max_calls=max_calls, repeat=repeat, every=every, ) @@ -331,7 +331,8 @@ def submit(self, *args: P.args, **kwargs: P.kwargs) -> Future[R] | None: **kwargs: The keyword arguments to call the task with. Returns: - The future of the task, or `None` if the limit was reached. + The future of the task, or `None` if it was rejected for either reaching + some max call limit or a plugin prevented if from being submitted. Raises: SchedulerNotRunningError: If the scheduler is not running.