ScriptPlan
ScriptPlan is a project scheduler. It reads a project written in the .tjp format, works out when each task runs and who does it, and prints the result as JSON or CSV. Times are kept to the minute.
Installation
pip install scriptplan
It needs Python 3.9 or later.
Command line
plan report reads a project file and writes the report to standard output.
plan report project.tjp # JSON
plan report --csv project.tjp # CSV
plan report - < project.tjp # read the project from standard input
cat project.tjp | plan report # the same, from a pipe
plan report project.tjp > plan.json # keep the result
# one id per project in a directory
for f in projects/*.tjp; do
plan report "$f" | jq -r '.report_id'
done
The JSON looks like this:
{
"data": [
{
"id": "project.task1",
"start": "2024-01-01-09:00",
"end": "2024-01-05-17:00"
}
],
"columns": ["id", "start", "end"],
"report_id": "ea3f901dd6426dfa58288d945819c75485fd9ff1875db59def350f219e2d62ca"
}
The columns come from the taskreport in the project file. A file with no report gets
the id, start and end of each task.
Progress messages, warnings and errors go to standard error. The report on standard
output can be piped into jq or saved to a file as it is, and its column names are
lowercase in the JSON. A project that cannot be scheduled exits with a non-zero status
and says why.
report_id is a SHA-256 of the rendered result. The same schedule gives the same id,
and a different schedule gives a different one.
plan report writes nothing to the working directory. Several runs can work at once
because each uses a temporary directory of its own.
Python API
from scriptplan.core.timezones import from_utc
from scriptplan.parser.tjp_parser import ProjectFileParser
parser = ProjectFileParser()
project = parser.parse(open('project.tjp').read())
zone = project['timezone']
# Access scheduled tasks
for task in project.tasks:
if task.leaf():
start = from_utc(task.get('start', 0), zone)
end = from_utc(task.get('end', 0), zone)
print(f"{task.id}: {start} -> {end}")
task.get('start', 0) and task.get('end', 0) return naive datetimes in UTC,
whatever the project's timezone. A task that starts at 00:00 in London in June
reads 23:00 the day before. from_utc gives the time in the project's zone, which
is what the reports print.
Projects can be parsed and scheduled in parallel threads. Messages and the error
count belong to the thread that produced them. Read
get_message_handler_instance().messages in the thread that called schedule().
What it does
Each statement in this section is checked by a probe in audit/evaluations/. A probe
runs ScriptPlan through its API or command line and compares what comes back with the
expected result. The probes run with the test suite, and you can run them against an
installed release:
audit/evaluations/run_all.sh
Time
- Dates in the file are in the project's timezone. Scheduling is done in UTC and the reports convert back.
- A project's working week is Monday to Friday, 09:00 to 17:00, in the project's
timezone.
length,gaplengthand a resource that states no hours use it. - A
workinghoursline replaces the hours of the days it names. The other days stay as they were, andworkinghours fri offcloses a day. A shift starts from the project's week. A resource starts from its parent resource's week, or from the project's when it has no parent. workinghours <shift id>puts a resource on a shift. Its week becomes the shift's, and the shift'sleavesapply to it.- A resource's hours are read in its own
timezonewhen it has one and in the project's when it does not. They stay at the same local time when the clocks change, in spring and in autumn. - An interval that ends at or before its start runs past midnight.
fri 22:00 - 06:00is Friday evening and Saturday morning, and both halves belong to Friday's line. - A global
leavesorvacationcloses the calendar for everyone, for whole days or for part of one, whatever kind of leave it is. - ScriptPlan picks the slot size from the times the project uses.
start 09:30is kept exactly, and a shift of08:13 - 11:59, 13:07 - 17:47gives its true 8h26m a day.timingresolutionsets the slot size outright, and a slot then counts as worked when it starts in working time.
Units
durationandgapdurationare calendar time.effort,lengthandgaplengthare working time, in which a day isdailyworkinghourslong and a year hasyearlyworkingdaysdays.mis months andminis minutes.
Resources
effortis person-time. Two resources working the same hour deliver two hours of it.- A task makes progress only while a
mandatoryresource is available.persistentkeeps the resource that was chosen first, andalternativenames one to fall back on. - Allocating a resource that has members allocates each member.
- A task with a
duration, or with a statedstartandend, books the resources it allocates for the hours they are on shift and free. Its dates stay as stated when they are not free. dailymax,weeklymax,monthlymaxandmaximumstop bookings at the cap, and booking resumes in the next period. Periods are counted in the resource's own calendar and a week runs Monday to Sunday. A cap smaller than one slot is kept exactly.dailymin,weeklymin,monthlyminandminimumare targets, which placing tasks cannot guarantee. A period in which the resource or task was booked for less draws a warning once the schedule is complete.
Scheduling
- A task is scheduled as soon as possible unless
scheduling alapon the task, on a container or on the project says as late as possible. One chain can mix the two. - A task scheduled as late as possible ends by the earliest of its own
end, the start of each task that follows it (less any gap that task asks for) and the project end. With none of these but a follower scheduled as soon as possible that states no start, it is scheduled as soon as possible as well, and a warning says so. depends X { onstart }lets a task start once X has started. It needs a task scheduled as soon as possible, and the file is refused when the task is scheduled as late as possible.precedes Xis how such a task says it must finish before X starts.- When tasks compete for a resource, the higher
priorityis placed first, then the higher criticalness, then the task declared first. A task's criticalness is its effort times how much is asked of the resources it may use, plus that of the heaviest chain of tasks waiting for it. At equal priority this places the larger effort first. - Tasks are placed one at a time in that order. A task ranked higher takes a resource's daily or weekly allowance first, and a lower-ranked task that started earlier can finish later. Raising its priority keeps it going.
- The declared project period is never rewritten. A task that does not fit is reported with its name and the reason, and a date stated outside the period is an error.
- Scheduling the same project twice gives the same dates and the same bookings.
- A stated
startorendthat the schedule cannot keep is an error. So is a task that would start before something it depends on finishes. lengthandgaplengthcount the project's working time. A resource on longer hours does not shorten the gap.maxgapduration,maxstart,minstart,maxendandminendare checked once the schedule is complete, and a violation is an error.maxgaplengthis not part of the syntax and is refused when the file is read.
Errors and warnings
- A dependency cycle is rejected before scheduling, and the message names the cycle.
- An attribute or reference the parser cannot place is an error. Each directive the
grammar accepts has a probe showing that it changes a schedule, is refused or draws a
warning. The few that do none of these are listed, each with the reason, in
audit/evaluations/probe_directive_effect.py. - Warnings are printed to standard error by
plan reportand byscriptplan.
Differences from other schedulers of this format
A file written for another scheduler may behave differently in these places.
- Direction. A task's direction comes from
scheduling. Adependswritten afterscheduling alapdoes not turn the task back to as soon as possible. - Placement order. Where two tasks lead into the same task, ScriptPlan counts that
task towards the criticalness of both. Another scheduler of this format counts it
towards the one declared first. The two can then place tasks of equal priority in a
different order. Of 150 random projects with contended resources, 132 came out the
same in both. Give a task a
priorityto fix its place. - Start of a
lengthtask. Alengthtask with no start of its own is reported as starting at the first working moment it can. Other schedulers report the moment it was released, which may be midnight. The end is the same. - Task references. A reference is looked up from the referring task's scope, one
level up for each
!. When the!s stop at a task, the reference must name one of its children, and!xwith no siblingxis refused. When there are no!s, or they reach the top level and no top-level task matches, the reference binds to the only task in the project with that id.depends !!packinsidedeliveryfindsdelivery.packthis way. When two tasks could be meant, the file is refused and both are named. - Additions.
schedulingin the project block,workinghours <shift id>on a resource,timezoneon a resource and intervals that run past midnight are ScriptPlan's own.
Known limits
include,supplement,leaveallowanceandstatussheetare not implemented.- Output formats are JSON and CSV.
ical,tjp,nikuand MS Project XML are refused when the file is read. - Accounts are parsed and not yet modelled.
chargesetandchargerecord an amount without posting it anywhere. - The value a task or resource gives to a custom attribute declared with
extendis read and not kept. limitsinside anallocateoption block is refused. Put the limits on the task, and add{ resources <id> }to hold them to one resource.onendonprecedesis refused.- Memory grows with the number of resources times the project's length divided by the slot size, because a resource holds one entry per slot for the whole project. Times off the hour make the slots smaller.
Example project
project "Manufacturing" 2025-07-01 +1m {
timezone "Etc/UTC"
timeformat "%Y-%m-%d %H:%M"
scheduling alap
}
shift factory_hours "Factory Hours" {
workinghours mon - fri 08:00 - 16:00
}
resource machine "Press" {
workinghours factory_hours
}
task delivery "Product Launch" {
end 2025-07-18-16:00
task pack "Packaging" {
effort 8h
allocate machine
}
task assemble_b "Body Assembly" {
effort 16h
allocate machine
precedes !!pack
}
task assemble_a "Engine Assembly" {
effort 16h
allocate machine
}
}
task connection_setup "Logic" {
task set_deps "Apply" {
depends !!delivery.assemble_a, !!delivery.assemble_b
precedes !!delivery.pack
}
}
taskreport output "output" {
formats csv
columns id, start, end
timeformat "%Y-%m-%d-%H:%M"
}
The project is scheduled backward from the delivery deadline. Packaging ends at 16:00 on 18 July. Both assemblies have to finish before packaging starts. With one machine they run one after the other, on the four working days before it.
delivery.pack: 2025-07-18-08:00 -> 2025-07-18-16:00
delivery.assemble_a: 2025-07-14-08:00 -> 2025-07-15-16:00
delivery.assemble_b: 2025-07-16-08:00 -> 2025-07-17-16:00
License
Apache-2.0
Acknowledgments
ScriptPlan reads the .tjp project file format. Its parser, its scheduling algorithms and its reports were written for it, and it contains no code from any other scheduler.
Why ScriptPlan?
This scheduler is part of Highway Workflow Engine's worker capacity management system. I decided to open-source it for the community to benefit from its precise scheduling capabilities. Because it reads the established .tjp syntax, users can adopt ScriptPlan without learning a new format.
Yours, Farshid.
Metadata
Release files for scriptplan 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| scriptplan-0.11.0.tar.gz | 326.0 kB | Without provenance | Details for scriptplan-0.11.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| scriptplan-0.11.0-py3-none-any.whl | Python 3 | none | any | Details for scriptplan-0.11.0-py3-none-any.whl |
Total release size: 531.8 kB
Release files / scriptplan-0.11.0.tar.gz
| Download URL | scriptplan-0.11.0.tar.gz |
|---|---|
| Size | 326.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e7d24b8c0f11df42bbb95d7dac0dd1524fa3afc3542c218c5186ac7cf4c20c0d
|
|
BLAKE2b-256 checksum How to use checksums |
4ca939e3cb442a48c77804f1a2d3a51b5582831ef79e77cf5e6598404c95f3a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.7
|
Release files / scriptplan-0.11.0-py3-none-any.whl
| Download URL | scriptplan-0.11.0-py3-none-any.whl |
|---|---|
| Size | 205.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c287803ec025c7146a0029f9cd6a196b228d55cc23704f7a74605ce62d86faff
|
|
BLAKE2b-256 checksum How to use checksums |
e88350f64df63b752bc14922bb913f81d53b3d833f3bb64087b3c2c92be8809d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.7
|
Security for scriptplan 0.11.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.