asyncz 0.8.3__tar.gz → 0.10.0__tar.gz

{asyncz-0.8.3 → asyncz-0.10.0}/.gitignore

@@ -1,5 +1,6 @@
 # folders
 *.egg-info/
+*.sqlite3
 .hypothesis/
 .idea/
 .mypy_cache/

{asyncz-0.8.3 → asyncz-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: asyncz
-Version: 0.8.3
+Version: 0.10.0
 Summary: The scheduler that nobody wants but every application needs.
 Project-URL: Homepage, https://github.com/dymmond/asyncz
 Project-URL: Documentation, https://asyncz.dymmond.com/
@@ -10,7 +10,7 @@ Project-URL: Source, https://github.com/dymmond/asyncz
 Author-email: Tiago Silva <tiago.arasilva@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
-Keywords: api,apscheduler,asgi,asyncz,cron,fastapi,framework,http,machine learning,ml,openapi,pydantic,rest,scheduler,starlette,websocket
+Keywords: apscheduler,asgi,asyncz,cron,fastapi,framework,pydantic,scheduler,starlette
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Web Environment
 Classifier: Framework :: AnyIO
@@ -38,19 +38,24 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Requires-Dist: backports-zoneinfo; python_version < '3.9'
+Requires-Dist: cryptography
 Requires-Dist: loguru<0.8.0,>=0.7.0
 Requires-Dist: pydantic<3.0.0,>=2.5.3
 Requires-Dist: tzlocal<6.0,>=4.0
 Provides-Extra: testing
 Requires-Dist: esmerald; extra == 'testing'
+Requires-Dist: httpx; extra == 'testing'
+Requires-Dist: lilya; extra == 'testing'
 Requires-Dist: mypy<2.0.0,>=0.982; extra == 'testing'
 Requires-Dist: pymongo<5.0.0,>=4.3.3; extra == 'testing'
-Requires-Dist: pytest-asyncio<1.0.0,>=0.19.0; extra == 'testing'
+Requires-Dist: pytest-asyncio<1.0.0,>=0.23.0; extra == 'testing'
 Requires-Dist: pytest-cov<6.0.0,>=2.12.0; extra == 'testing'
 Requires-Dist: pytest-loguru<1,>=0.2.0; extra == 'testing'
 Requires-Dist: pytest<9.0.0,>=7.1.3; extra == 'testing'
 Requires-Dist: pytz>=2022.6; extra == 'testing'
 Requires-Dist: redis<6.0.0,>=4.4.0; extra == 'testing'
+Requires-Dist: sqlalchemy; extra == 'testing'
+Requires-Dist: starlette; extra == 'testing'
 Description-Content-Type: text/markdown
 
 # Asyncz
@@ -207,12 +212,94 @@ fun 😁🎉.
 
 ## ASGI support
 
-Asyncz currently supports the [Esmerald framework](https://asyncz.dymmond.com/contrib/esmerald/index.md)
-and brings some batteries that are currently used by the framework and leveraging Asyncz.
+Asyncz currently supports ASGI, the [Esmerald framework](https://asyncz.dymmond.com/contrib/esmerald/)
+and brings some batteries that are currently used by Esmerald and leveraging Asyncz.
 
-If you wish to have support to any other framework such as FastAPI, Starlite, Starlette or
-literally any other, check the [contributing](https://asyncz.dymmond.com/contributing.md) section and see how you can
-do it.
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+...
+
+# handle_lifespan is optional, set to True if you don't want to pass it down because the underlying app doesn't support it
+# this is true for django
+application = AsyncIOScheduler().asgi(application, handle_lifespan=False)
+# or more simple (please do not use both together)
+application = AsyncIOScheduler().asgi()(application)
+```
+
+Using with lilya:
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+# Lilya middleware doesn't pass lifespan events
+
+app = AsyncIOScheduler().asgi(Lilya(
+    routes=[...],
+))
+
+```
+
+Or manually:
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+scheduler = AsyncIOScheduler()
+
+app = Lilya(
+    routes=[...],
+    on_startup=[scheduler.start],
+    on_shutdown=[scheduler.shutdown],
+)
+
+```
+
+
+## Contextmanager support
+
+Use as sync contextmanager
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+with AsyncIOScheduler() as scheduler:
+    ...
+```
+
+Use as async contextmanager
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+async with AsyncIOScheduler() as scheduler:
+    ...
+```
+
+For using with lifespan of starlette:
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+async lifespan(app):
+    with AsyncIOScheduler() as scheduler:
+        yield
+        # or yield a state
+app = Starlette(
+    lifespan=lifespan,
+)
+
+```
+
+## Security
+
+You should use store encryption for security reasons.
+
+All standard stores except MemoryStore support the environment variable `ASYNCZ_STORE_ENCRYPTION_KEY`.
+If set and non-empty the hash of the value is used for AESGCM encrypting the elements before sending them
+to the store.
+This way store entries are encrypted and authentificated so there is no security hole.
+This is highly recommended! Because if someone can inject store entries he can execute code.
 
 ## Sponsors
 

{asyncz-0.8.3 → asyncz-0.10.0}/README.md

@@ -152,12 +152,94 @@ fun 😁🎉.
 
 ## ASGI support
 
-Asyncz currently supports the [Esmerald framework](https://asyncz.dymmond.com/contrib/esmerald/index.md)
-and brings some batteries that are currently used by the framework and leveraging Asyncz.
+Asyncz currently supports ASGI, the [Esmerald framework](https://asyncz.dymmond.com/contrib/esmerald/)
+and brings some batteries that are currently used by Esmerald and leveraging Asyncz.
 
-If you wish to have support to any other framework such as FastAPI, Starlite, Starlette or
-literally any other, check the [contributing](https://asyncz.dymmond.com/contributing.md) section and see how you can
-do it.
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+...
+
+# handle_lifespan is optional, set to True if you don't want to pass it down because the underlying app doesn't support it
+# this is true for django
+application = AsyncIOScheduler().asgi(application, handle_lifespan=False)
+# or more simple (please do not use both together)
+application = AsyncIOScheduler().asgi()(application)
+```
+
+Using with lilya:
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+# Lilya middleware doesn't pass lifespan events
+
+app = AsyncIOScheduler().asgi(Lilya(
+    routes=[...],
+))
+
+```
+
+Or manually:
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+scheduler = AsyncIOScheduler()
+
+app = Lilya(
+    routes=[...],
+    on_startup=[scheduler.start],
+    on_shutdown=[scheduler.shutdown],
+)
+
+```
+
+
+## Contextmanager support
+
+Use as sync contextmanager
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+with AsyncIOScheduler() as scheduler:
+    ...
+```
+
+Use as async contextmanager
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+async with AsyncIOScheduler() as scheduler:
+    ...
+```
+
+For using with lifespan of starlette:
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+async lifespan(app):
+    with AsyncIOScheduler() as scheduler:
+        yield
+        # or yield a state
+app = Starlette(
+    lifespan=lifespan,
+)
+
+```
+
+## Security
+
+You should use store encryption for security reasons.
+
+All standard stores except MemoryStore support the environment variable `ASYNCZ_STORE_ENCRYPTION_KEY`.
+If set and non-empty the hash of the value is used for AESGCM encrypting the elements before sending them
+to the store.
+This way store entries are encrypted and authentificated so there is no security hole.
+This is highly recommended! Because if someone can inject store entries he can execute code.
 
 ## Sponsors
 

asyncz-0.10.0/asyncz/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.10.0"

{asyncz-0.8.3 → asyncz-0.10.0}/asyncz/datastructures.py

@@ -57,7 +57,7 @@ class CronState(BaseDatastructureState):
     jitter: Optional[int] = None
 
 
-class TaskState(BaseDatastructureState):
+class TaskState(BaseDatastructureState):  # type: ignore
     id: Optional[str] = None
     name: Optional[str] = None
     fn: Optional[Union[Callable[..., Any], str]] = None
@@ -69,7 +69,7 @@ class TaskState(BaseDatastructureState):
     executor: Optional[str] = None
     mistrigger_grace_time: Optional[int] = None
     max_instances: Optional[int] = None
-    next_run_time: Optional[datetime]
+    next_run_time: Optional[datetime] = None
     scheduler: Optional[Any] = None
     store_alias: Optional[str] = None
     store: Optional[Union[str, StoreType]] = None

{asyncz-0.8.3 → asyncz-0.10.0}/asyncz/enums.py

@@ -1,12 +1,12 @@
-from enum import Enum
+from enum import Enum, IntEnum
 
 
-class SchedulerState(Enum):
+class SchedulerState(IntEnum):
     STATE_STOPPED = 0
     STATE_RUNNING = 1
     STATE_PAUSED = 2
 
 
-class PluginInstance(Enum):
+class PluginInstance(str, Enum):
     EXECUTOR = "executor"
     STORE = "store"

{asyncz-0.8.3 → asyncz-0.10.0}/asyncz/events/base.py

@@ -30,8 +30,8 @@ class TaskEvent(SchedulerEvent):
         store: The alias given to a store.
     """
 
-    task_id: Union[str, int]
-    store: Union[str, Any] = None
+    task_id: str
+    store: Optional[str] = None
 
 
 class TaskSubmissionEvent(TaskEvent):

{asyncz-0.8.3 → asyncz-0.10.0}/asyncz/exceptions.py

@@ -30,7 +30,7 @@ class BaseLookupError(LookupError):
 
     detail = "Not found."
 
-    def __init__(self, detail: Optional[str] = None):
+    def __init__(self, detail: Optional[str] = None) -> None:
         if not detail:
             detail = self.detail
         super().__init__(detail)
@@ -47,7 +47,7 @@ class AsynczLookupError(BaseLookupError):
 class SchedulerLookupError(BaseLookupError):
     detail = "No schedule with the id {schedule_id} has been found."
 
-    def __init__(self, schedule_id: str):
+    def __init__(self, schedule_id: str) -> None:
         detail = self.detail.format(schedule_id=schedule_id)
         super().__init__(detail=detail)
 
@@ -55,7 +55,7 @@ class SchedulerLookupError(BaseLookupError):
 class TaskLookupError(BaseLookupError):
     detail = "No task with the id {task_id} has been found."
 
-    def __init__(self, task_id: str):
+    def __init__(self, task_id: Optional[str]) -> None:
         detail = self.detail.format(task_id=task_id)
         super().__init__(detail=detail)
 
@@ -63,7 +63,7 @@ class TaskLookupError(BaseLookupError):
 class ConflictError(KeyError):
     detail = "This data store already contains a schedule with the identifier {schedule_id}."
 
-    def __init__(self, schedule_id: str):
+    def __init__(self, schedule_id: str) -> None:
         detail = self.detail.format(schedule_id=schedule_id)
         super().__init__(detail)
 
@@ -71,7 +71,7 @@ class ConflictError(KeyError):
 class ConflictIdError(KeyError):
     detail = "Task identifier ({task_id}) conflicts with an existing task."
 
-    def __init__(self, task_id: str):
+    def __init__(self, task_id: Optional[str]) -> None:
         detail = self.detail.format(task_id=task_id)
         super().__init__(detail)
 
@@ -83,7 +83,7 @@ class MaxInterationsReached(AsynczException):
 class MaximumInstancesError(AsynczException):
     detail = "The task by the id of {id} reached its maximum number of instances {total}."
 
-    def __init__(self, _id: Union[UUID, str, int], total: int):
+    def __init__(self, _id: Union[UUID, str, int], total: int) -> None:
         detail = self.detail.format(id=_id, total=total)
         super().__init__(detail=detail)
 

{asyncz-0.8.3 → asyncz-0.10.0}/asyncz/executors/asyncio.py

@@ -1,6 +1,6 @@
-from typing import TYPE_CHECKING, Any, Union
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, List, Set
 
-from asyncz.exceptions import AsynczException
 from asyncz.executors.base import BaseExecutor, run_coroutine_task, run_task
 from asyncz.utils import iscoroutinefunction_partial
 
@@ -10,7 +10,8 @@ if TYPE_CHECKING:
 
 class AsyncIOExecutor(BaseExecutor):
     """
-    Executor used for AsyncIO, typically can also be plugged into any ASGI framework as well, for example, Esmerald, Starlite, FastAPI...
+    Executor used for AsyncIO, typically can also be plugged into any ASGI framework as well,
+    for example, Esmerald, Starlite, FastAPI...
 
     Runs the task in the default executor event loop.
 
@@ -19,36 +20,34 @@ class AsyncIOExecutor(BaseExecutor):
     executor which is usually a thread pool.
     """
 
-    def start(self, scheduler: Any, alias: str):
+    def start(self, scheduler: Any, alias: str) -> None:
         super().start(scheduler, alias)
         self.event_loop = scheduler.event_loop
-        self.pending_futures = set()
+        self.pending_futures: Set[Any] = set()
 
-    def shutdown(self, wait: bool = True):
+    def shutdown(self, wait: bool = True) -> None:
         for f in self.pending_futures:
             if not f.done():
                 f.cancel()
 
         self.pending_futures.clear()
 
-    def do_send_task(self, task: "TaskType", run_times: Union[int, str]):
-        def callback(fn):
+    def do_send_task(self, task: "TaskType", run_times: List[datetime]) -> None:
+        task_id = task.id
+        assert task_id is not None, "Cannot send decorator type task"
+
+        def callback(fn: Any) -> None:
             self.pending_futures.discard(fn)
             try:
                 events = fn.result()
             except BaseException:
-                self.run_task_error(task.id)
+                self.run_task_error(task_id)
             else:
-                self.run_task_success(task.id, events)
+                self.run_task_success(task_id, events)
 
         if iscoroutinefunction_partial(task.fn):
-            if run_coroutine_task is not None:
-                coroutine = run_coroutine_task(task, task.store_alias, run_times, self.logger)
-                fn = self.event_loop.create_task(coroutine)
-            else:
-                raise AsynczException(
-                    detail="Executing coroutine based tasks is not supported with Trollius."
-                )
+            coroutine = run_coroutine_task(task, task.store_alias, run_times, self.logger)  # type: ignore
+            fn = self.event_loop.create_task(coroutine)
         else:
             fn = self.event_loop.run_in_executor(
                 None, run_task, task, task.store_alias, run_times, self.logger

{asyncz-0.8.3 → asyncz-0.10.0}/asyncz/executors/base.py

@@ -1,11 +1,11 @@
 import sys
 import traceback
-from abc import ABC, abstractmethod
 from collections import defaultdict
 from datetime import datetime, timedelta
 from datetime import timezone as tz
+from threading import RLock
 from traceback import format_tb
-from typing import TYPE_CHECKING, Any, List, Optional, Union
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, cast
 
 from loguru import logger
 from loguru._logger import Logger
@@ -13,24 +13,25 @@ from loguru._logger import Logger
 from asyncz.events import TaskExecutionEvent
 from asyncz.events.constants import TASK_ERROR, TASK_EXECUTED, TASK_MISSED
 from asyncz.exceptions import MaximumInstancesError
+from asyncz.executors.types import ExecutorType
 from asyncz.state import BaseStateExtra
 
 if TYPE_CHECKING:
     from asyncz.tasks.types import TaskType
 
 
-class BaseExecutor(BaseStateExtra, ABC):
+class BaseExecutor(BaseStateExtra, ExecutorType):
     """
     Base model for the executors. It defines the interface for all the executors used by the Asyncz.
 
     Asyncz uses loguru for its logging as it is more descriptive and intuitive.
     """
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs: Any) -> None:
         super().__init__(**kwargs)
-        self.instances = defaultdict(lambda: 0)
+        self.instances: Dict[str, int] = defaultdict(lambda: 0)
 
-    def start(self, scheduler: Any, alias: str):
+    def start(self, scheduler: Any, alias: str) -> None:
         """
         Called by the scheduler when the scheduler is being started or when the executor is being
         added to an already running scheduler.
@@ -40,11 +41,11 @@ class BaseExecutor(BaseStateExtra, ABC):
             alias - The alias of this executor as it was assigned to the scheduler.
         """
         self.scheduler = scheduler
-        self.lock = scheduler.create_lock()
-        self.logger = logger
+        self.lock: RLock = scheduler.create_lock()
+        self.logger: Any = logger
         self.logger.bind(logger_name=f"asyncz.executors.{alias}")
 
-    def shutdown(self, wait: bool = True):
+    def shutdown(self, wait: bool = True) -> None:
         """
         Shuts down the executor.
 
@@ -52,15 +53,16 @@ class BaseExecutor(BaseStateExtra, ABC):
             wait - Boolean indicating to wait until all submitted tasks have been executed.
         """
 
-    def send_task(self, task: "TaskType", run_times: List[datetime]):
+    def send_task(self, task: "TaskType", run_times: List[datetime]) -> None:
         """
         Sends the task for execution.
 
         Args:
-            task: A Task instanceyo execute.
+            task: A Task instance to execute.
             run_times: A list of datetimes specifying when the task should have been run.
         """
         assert self.lock is not None, "This executor has not been started yet."
+        assert task.id is not None, "The task is in decorator mode."
         with self.lock:
             if self.instances[task.id] >= task.max_instances:
                 raise MaximumInstancesError(task.id, task.max_instances)
@@ -68,14 +70,7 @@ class BaseExecutor(BaseStateExtra, ABC):
             self.do_send_task(task, run_times)
             self.instances[task.id] += 1
 
-    @abstractmethod
-    def do_send_task(self, task: "TaskType", run_times: List[datetime]) -> Any:
-        """
-        Executes the actual task of scheduling `run_task` to be called.
-        """
-        ...
-
-    def run_task_success(self, task_id: Union[str, int], events: List[int]) -> Any:
+    def run_task_success(self, task_id: str, events: List[TaskExecutionEvent]) -> None:
         """
         Called by the executor with the list of generated events when the function run_task has
         been successfully executed.
@@ -88,7 +83,7 @@ class BaseExecutor(BaseStateExtra, ABC):
         for event in events or []:
             self.scheduler.dispatch_event(event)
 
-    def run_task_error(self, task_id: Union[str, int]) -> Any:
+    def run_task_error(self, task_id: str) -> None:
         """
         Called by the executor with the exception if there is an error calling the run_task.
         """
@@ -104,8 +99,8 @@ def run_task(
     task: "TaskType",
     store_alias: str,
     run_times: List[datetime],
-    _logger: Optional["Logger"] = None,
-):
+    _logger: Optional[Any] = None,
+) -> List[TaskExecutionEvent]:
     """
     Called by executors to run the task. Returns a list of scheduler events to be dispatched by the
     scheduler.
@@ -117,9 +112,10 @@ def run_task(
 
     events = []
     for run_time in run_times:
-        if getattr(task, "mistrigger_grace_time", None) is not None:
+        mistrigger_grace_time = task.mistrigger_grace_time
+        if mistrigger_grace_time is not None:
             difference = datetime.now(tz.utc) - run_time
-            grace_time = timedelta(seconds=task.mistrigger_grace_time)
+            grace_time = timedelta(seconds=mistrigger_grace_time)
             if difference > grace_time:
                 events.append(
                     TaskExecutionEvent(
@@ -134,9 +130,9 @@ def run_task(
 
         _logger.info(f'Running task "{task}" (scheduled at {run_time})')
         try:
-            return_value = task.fn(*task.args, **task.kwargs)
-        except BaseException:
-            exc, trace_back = sys.exc_info()[1:]
+            return_value = cast(Callable[..., Any], task.fn)(*task.args, **task.kwargs)
+        except Exception as exc:
+            trace_back = sys.exc_info()[2]
             formatted_trace_back = "".join(format_tb(trace_back))
             events.append(
                 TaskExecutionEvent(
@@ -169,7 +165,7 @@ async def run_coroutine_task(
     store_alias: str,
     run_times: List[datetime],
     _logger: Optional["Logger"] = None,
-):
+) -> List[TaskExecutionEvent]:
     """
     Called by executors to run the task. Returns a list of scheduler events to be dispatched by the
     scheduler.
@@ -177,13 +173,14 @@ async def run_coroutine_task(
     The run task is made to run in async mode.
     """
     if not _logger:
-        _logger = logger
+        _logger = logger  # type: ignore
 
     events = []
     for run_time in run_times:
-        if getattr(task, "mistrigger_grace_time", None) is not None:
+        mistrigger_grace_time = task.mistrigger_grace_time
+        if mistrigger_grace_time is not None:
             difference = datetime.now(tz.utc) - run_time
-            grace_time = timedelta(seconds=task.mistrigger_grace_time)
+            grace_time = timedelta(seconds=mistrigger_grace_time)
             if difference > grace_time:
                 events.append(
                     TaskExecutionEvent(
@@ -193,14 +190,14 @@ async def run_coroutine_task(
                         scheduled_run_time=run_time,
                     )
                 )
-                _logger.warning(f"Run time of task '{task}' was missed by {difference}")
+                _logger.warning(f"Run time of task '{task}' was missed by {difference}")  # type: ignore
                 continue
 
-        _logger.info(f'Running task "{task}" (scheduled at {run_time})')
+        _logger.info(f'Running task "{task}" (scheduled at {run_time})')  # type: ignore
         try:
-            return_value = await task.fn(*task.args, **task.kwargs)
-        except BaseException:
-            exc, trace_back = sys.exc_info()[1:]
+            return_value = await cast(Callable[..., Any], task.fn)(*task.args, **task.kwargs)
+        except Exception as exc:
+            trace_back = sys.exc_info()[2]
             formatted_trace_back = "".join(format_tb(trace_back))
             events.append(
                 TaskExecutionEvent(
@@ -224,6 +221,6 @@ async def run_coroutine_task(
                     return_value=return_value,
                 )
             )
-            _logger.info(f"Task '{task}' executed successfully")
+            _logger.info(f"Task '{task}' executed successfully")  # type: ignore
 
     return events

{asyncz-0.8.3 → asyncz-0.10.0}/asyncz/executors/debug.py

@@ -1,4 +1,5 @@
-from typing import TYPE_CHECKING, Union
+from datetime import datetime
+from typing import TYPE_CHECKING, List
 
 from asyncz.executors.base import BaseExecutor, run_task
 
@@ -15,14 +16,12 @@ class DebugExecutor(BaseExecutor):
     def do_send_task(
         self,
         task: "TaskType",
-        run_times: Union[
-            int,
-            str,
-        ],
-    ):
+        run_times: List[datetime],
+    ) -> None:
+        assert task.id is not None, "Cannot send decorator type task"
         try:
-            events = run_task(task, task.store_alias, run_times, self.logger)
-        except BaseException:
+            events = run_task(task, task.store_alias, run_times, self.logger)  # type: ignore
+        except Exception:
             self.run_task_error(task.id)
         else:
             self.run_task_success(task.id, events)