Skip to content


Esmerald internally uses Asyncz to perform its tasks if need and the main object used is the EsmeraldScheduler.

Can you use this externally? Very unlikely. This serves only for the purpose of explaining how and what the object does as internally, by the time of this writting, Esmerald does not allow to pass specific schedulers, instead, uses this one out of the box.


The object that is instantiated when an Esmerald application is created and the scheduler is enabled.

Esmerald also defaults the scheduler_class to the Asyncz AsyncIOScheduler if nothing is provided.


By the time this document was written, Esmerald was in version 0.5.0 and it did not allow passing different EsmeraldScheduler instance on instantiation time but that might change in the future. In other words, this is just an explanation of how does the object work internally.


  • app - Esmerald instance.
  • scheduler_class - An instance of a scheduler.
  • tasks - A dictinary str, str mapping the tasks of the application to be executed.
  • timezone - The timezone instance.
  • configurations - A dictionary with extra configurations to be passed to the scheduler.


This is how Esmerald usually works. Let us assume:

  • You have some tasks living inside a file src/accounts/
  • You want to pass some extra configurations to the scheduler.
from esmerald import Esmerald
from loguru import logger

from asyncz.contrib.esmerald.decorator import scheduler
from asyncz.schedulers import AsyncIOScheduler
from asyncz.triggers import IntervalTrigger

# Run every 2 minutes
def send_message():"Message sent after 2 minutes")

# Run every 20 minutes
def send_longer_message():"Message sent after 20 minutes")

# Create the extra configurations
configurations = (
        "asyncz.stores.mongo": {"type": "mongodb"},
        "asyncz.stores.default": {"type": "redis", "database": "0"},
        "asyncz.executors.threadpool": {
            "max_workers": "20",
            "class": "asyncz.executors.threadpool:ThreadPoolExecutor",
        "asyncz.executors.default": {"class": "asyncz.executors.asyncio::AsyncIOExecutor"},
        "asyncz.task_defaults.coalesce": "false",
        "asyncz.task_defaults.max_instances": "3",
        "asyncz.task_defaults.timezone": "UTC",

# Start Esmerald with the scheduler
# Pass the configurations
# Enable the scheduler
# AsyncIOScheduler Is the default scheduler of Esmerald but
# we pass here for example purposes
app = Esmerald(
        "send_message": "src.accounts.tasks",
        "send_longer_message": "src.accounts.tasks",

As stated above, this is just an illustration on how Esmerald operates with Asyncz (from the version 0.5.0 onwards) and shows how you can use your usual configurations of Asyncz directly with the framework


EsmeraldScheduler does the heavy lifting for you.

  • Registers the tasks in the Asyncz scheduler based on the tasks parameters.
  • Registers the Esmerald events startup and shutdown automatically on app instantiation.