About cron¶

Cron is a very powerful tool, this project doesn't intend to cover everything that cron can do, as in most cases you don't need all of cron's features.

There are some use cases where this project, Scheduled, would not be the right tool and you should use cron instead.

Cron also has some downsides that this project tries to avoid. Here are some of the reasons behind these ideas.

Why not cron¶

Syntax¶

Cron has a very specific syntax, normally written inside of a string.

It's quite minimal, but not necessarily obvious to everyone. There are many guides and online tools to try to help understand, write, and validate the syntax.

Not everyone can perfectly write or read a cron expression at first sight.

Inline Errors¶

As cron expressions are a custom syntax inside a string, there's no easy way to define what is valid and what not, what parts can go where, etc.

Without very specialized tooling, it's not easy to get inline errors in your editor telling you that the syntax is incorrect while writing cron expressions.

Autocompletion¶

For the same reason of being a custom syntax, it's almost impossible to get autocompletion for cron expressions in your editor.

The syntax is minimal, so autocompletion would probably not be necessary to save typing, but it wouldn't help you know if you are setting the correct values in the correct places to achieve what you need.

Uncertainty¶

In a cron expression you are required to set a specific value for each field.

It would be easy to accidentally make a cron expression run more frequently than you intended, or less frequently than you intended.

Unless you verify it with additional external tools.

Complexity¶

For the vast majority of cases, you would need a very simple schedule, like "run this once per day", or "run this once per month".

In cron syntax, you would still need to define exactly at which minute, hour, day of month, month, and day of week the job should run.

You still need to know and set all these values, even if you don't care about them.

The intention with Scheduled (this project) is to make the simplest use cases the simplest to achieve.

Spikes¶

With cron, even if you only care that a job runs daily, you still have to set the specific time in minutes and hours for each job.

In most cases people would just set to it to zero, as that's the simplest. But this would mean that a cron system would possibly have many jobs that are defined to run exactly at the same time, causing resource spikes.

And in most cases, you don't really need the job to run at that specific time, only to run at a stable time (at the same time each day), with the specific cadence (e.g. every day).

But cron forces you to define the specific time to run a job.

These spikes in resource usage can be a problem for providers and increase costs, which could be transferred to users.

Or it might be that users can hit rate limits in resource usage or external API calls, there's a better chance to avoid them if the provider can distribute the jobs more uniformly across the day when that is possible.

About Scheduled¶

Scheduled objective is to address these points above.

Syntax, inline errors, and autocompletion are handled by using a standard format like TOML, with predefined fields and values.

If you use a modern editor like PyCharm or VS Code (with a TOML extension like Tombi), it already supports the Scheduled format, including autocompletion and inline errors.

Uncertainty is handled by having explicit field names and values that don't allow for ambiguity. For example, every = "month" is probably more obvious than 0 0 1 * *.

Complexity is handled by only requiring the fields that are necessary for the most common use cases. For example, if you want to run a job once per day, you only need to set every = "day".

Spikes are handled by not requiring users to set a specific time for their jobs, but only a cadence. This allows providers to distribute the jobs more uniformly across the day when that is possible, avoiding spikes in resource usage.

Extensions¶

There are potential extensions planned for Scheduled, for example to define intervals like "every 5 minutes".

It will be updated as needed from observing real life use cases and feedback.