API

This part covers some interfaces of Plan.

Plan Object

class plan.Plan(name='main', path=None, environment=None, output=None, user=None)

The central object where you register jobs. One Plan instance should manage a group of jobs.

Parameters:

• name – the unique identity for this plan object, default to be main
• path – the global path you want to run the task on.
• environment – the global crontab job bash environment.
• output – the global crontab job output logfile for this object.
• user – the user you want to run crontab command with.

bootstrap(command_or_commands)

Register bootstrap commands.

Parameters:command_or_commands – One command or a list of commands.

command(*args, **kwargs)

Register one command.

comment_begin

Comment begin content for this object, this will be added before the actual cron syntax jobs content. Different name is used to distinguish different Plan object, so we can locate the cronfile content corresponding to this object.

cron_content

Your schedule jobs converted to cron syntax.

crons

Return a list of registered jobs’s cron syntax content.

job(job)

Register one job.

Parameters:job – one Job instance.

module(*args, **kwargs)

Register one module.

raw(*args, **kwargs)

Register one raw job.

read_crontab()

Get the current working crontab cronfile content.

run(run_type='check')

Use this to do any action on this Plan object.

Parameters:run_type – The running type, one of (“check”, “write”, “update”, “clear”), default to be “check”

run_bootstrap_commands()

Run bootstrap commands.

script(*args, **kwargs)

Register one script.

update_crontab(update_type)

Update the current cronfile, used by run_type update or clear. This will find the block inside cronfile corresponding to this Plan object and replace it.

Parameters:update_type – update or clear, if you choose update, the block corresponding to this plan object will be replaced with the new cron job entries, otherwise, they will be wiped.

write_crontab()

Write the crontab cronfile with this object’s cron content, used by run_type write. This will replace the whole cronfile.

Job Objects

class plan.Job(task, every, at=None, path=None, environment=None, output=None)

The plan job base class.

Parameters:

• task – this is what the job does.
• every – how often does the job run.
• at – when does the job run.
• path – the path you want to run the task on, default to be current working directory.
• environment – the environment you want to run the task under.
• output – the output redirection for the task.

cron

Job in cron syntax.

main_template

The main job template.

parse_at()

Parse at value into (at_type, moment) pairs.

parse_every()

Parse every value.

Returns:every_type.

parse_month(month)

Parses month into month numbers. Month can only occur in every value.

Parameters:month –

this parameter can be the following values:

jan feb mar apr may jun jul aug sep oct nov dec and all of those full month names(case insenstive) or <int:n>.month

parse_time()

Parse every and at into cron time syntax:

# * * * * *  command to execute
# ┬ ┬ ┬ ┬ ┬
# │ │ │ │ │
# │ │ │ │ │
# │ │ │ │ └─── day of week (0 - 7) (0 to 6 are Sunday to Saturday)
# │ │ │ └───── month (1 - 12)
# │ │ └─────── day of month (1 - 31)
# │ └───────── hour (0 - 23)
# └─────────── minute (0 - 59)

parse_week(week)

Parses day of week name into week numbers.

Parameters:week –

this parameter can be the following values:

sun mon tue wed thu fri sat sunday monday tuesday wednesday thursday friday saturday weekday weedend(case insenstive)

preprocess_at(at)

Do preprocess for at value, just modify “12:12” style moment into “hour.12 minute.12” style moment value.

Parameters:at – The at value you want to do preprocess.

process_template(template)

Process template content. Drop multiple spaces in a row and strip it.

produce_frequency_time(frequency, maximum, start=0)

Translate frequency into comma separated times.

task_in_cron_syntax

Cron content task part.

task_template()

The task template. You should implement this in your own job type. The default template is:

'cd {path} && {environment} {task} {output}'

time_in_cron_syntax

Cron content time part.

validate_time()

Validate every and at value.

every can be:

[1-60].minute [1-24].hour [1-31].day
[1-12].month [1].year
jan feb mar apr may jun jul aug sep oct nov dec
sun mon tue wed thu fri sat weekday weekend
or any fullname of month names and day of week names
(case insensitive)

at:

when every is minute, can not be set
when every is hour, can be minute.[0-59]
when every is day of month, can be minute.[0-59], hour.[0-23]
when every is month, can be day.[1-31], day of week,
                     minute.[0-59], hour.[0-23]
when every is day of week, can be minute.[0-59], hour.[0-23]

at can also be multiple at values seperated by one space.

class plan.CommandJob(task, every, at=None, path=None, environment=None, output=None)

The command job.

task_template()

Template:

'{task} {output}'

class plan.ScriptJob(task, every, at=None, path=None, environment=None, output=None)

The script job.

task_template()

Template:

'cd {path} && {environment} %s {task} {output}' % sys.executable

class plan.ModuleJob(task, every, at=None, path=None, environment=None, output=None)

The module job.

task_template()

Template:

'{environment} %s -m {task} {output}' % sys.executable

class plan.RawJob(task, every, at=None, path=None, environment=None, output=None)

The raw job.

task_template()

Template:

'{task}'