ScriptPlan
A precise project scheduling engine with minute-level accuracy for resource allocation and dependency management. It reads projects written in the .tjp format.
Installation
pip install scriptplan
Quick Start
Report Generation (Unix-style)
# Generate JSON report to stdout
plan report project.tjp
# Generate CSV report
plan report --csv project.tjp
# Save to file
plan report project.tjp > output.json
plan report --csv project.tjp > output.csv
# Read from stdin
cat project.tjp | plan report
plan report - < project.tjp
# Pipe to other tools
plan report project.tjp | jq '.data[0]'
plan report --csv project.tjp | csvkit
# Process multiple files
for f in projects/*.tjp; do
plan report "$f" | jq -r '.report_id'
done
Output Format (JSON):
{
"data": [
{
"id": "project.task1",
"start": "2024-01-01-09:00",
"end": "2024-01-05-17:00"
}
],
"columns": ["id", "start", "end"],
"report_id": "ea3f901dd6426dfa58288d945819c75485fd9ff1875db59def350f219e2d62ca"
}
Features:
- Output to stdout (Unix philosophy)
- Messages to stderr
- SHA256
report_idover the rendered result, so it changes when the schedule does - Lowercase column names
- No HTML metadata
- No file pollution (uses temp directories)
- Separate processes do not collide: temporary files and directories are unique per run
Python API
from scriptplan.parser.tjp_parser import ProjectFileParser
parser = ProjectFileParser()
project = parser.parse(open('project.tjp').read())
# Access scheduled tasks
for task in project.tasks:
if task.leaf():
start = task.get('start', 0)
end = task.get('end', 0)
print(f"{task.id}: {start} -> {end}")
Projects can be parsed and scheduled in parallel threads. Messages and the error
count belong to the thread that produced them, so read
get_message_handler_instance().messages in the thread that called schedule().
What is verified
Each behaviour below has a probe in audit/evaluations/ that drives ScriptPlan
through its own API or CLI and asserts the result. They run as part of the test
suite, and can be run on their own against an installed release:
audit/evaluations/run_all.sh
Time
- Dates are read in the project's timezone and scheduled in UTC; reports convert back.
- Resource shifts follow their own timezone across daylight-saving changes in both directions.
- A working-hours interval that crosses midnight applies to the following day.
- The project's
workinghoursis the calendar thatlength,gaplengthand a resource with no hours of its own use. Without one it is Monday to Friday, 09:00-17:00, in the project's timezone. - A global
leavesorvacationcloses that calendar for everyone, whatever the leave is called, for whole days or part of one. A shift'sleavesholds for every resource on the shift. - Slot size is derived from the times a project uses, so
start 09:30is honoured exactly and a shift of08:13 - 11:59, 13:07 - 17:47yields its true 8h26m a day.timingresolutionoverrides this.
Units
- Calendar time (
duration,gapduration) and working time (effort,length,gaplength) are distinguished, with working time derived fromdailyworkinghoursandyearlyworkingdays.mmeans months;minmeans minutes.
Resources
effortis person-time: two resources available in a slot contribute two slots of it.mandatoryrequires a resource for the task to progress at all;persistentkeeps the one first chosen;alternativefalls back.- Allocating a resource that has members allocates every member.
- A task with a
duration, or with a statedstartandend, books the resources it allocates for the hours they are on shift and free. It keeps its dates when they are not. dailymax,weeklymax,monthlymaxandmaximumblock at the cap and release in the next period. Periods are counted in the resource's own calendar, a week runs Monday to Sunday, and a cap smaller than one slot is honoured 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
- ASAP and ALAP, including chains that mix the two.
- A task scheduled as late as possible ends by the earliest of its own
end, the start of each successor (less any gap that successor asks for) and the project end. With none of these but a successor scheduled as soon as possible that states no start, it is scheduled as soon as possible instead, with a warning. - Contention is resolved by priority, then criticalness, then declaration order. 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 that follow it, so at equal priority the larger effort is placed first. Tasks are placed one at a time in that order, so 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. A date stated outside the period is an error.
- Scheduling the same project twice produces the same dates and the same bookings.
- A stated
startorendthat the schedule cannot keep, and a task that would start before something it depends on finishes, are errors. lengthandgaplengthcount the project's working time, not a resource's: 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 parsed.)
Honesty
- A project that cannot be scheduled exits non-zero and says why. A dependency cycle is rejected before scheduling, naming the cycle.
- An attribute or reference the parser cannot place is an error, never a silent
drop. Each directive the grammar accepts has a probe showing that it changes a
schedule, is refused or draws a warning, and the few that do none of these are
listed in
audit/evaluations/probe_directive_effect.pywith the reason. - Warnings are printed to stderr by
plan reportas well as byscriptplan. report_idis a SHA-256 of the rendered result, so it differs when the schedule differs.
Known limits
include,supplement,leaveallowanceandstatussheetare not implemented.- Output formats are JSON and CSV.
ical,tjp,nikuand MS Project XML are rejected at parse time rather than silently producing nothing. - Accounts are parsed but not yet modelled, so
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, with{ resources <id> }to hold them to one resource.- The
workinghourslines of one block (project, shift or resource) state its whole week: a day no line names is not worked, and two lines naming the same day add up. Other schedulers of this format keep the inherited hours on a day a line does not name. Name every day you mean. - A
lengthtask with no start of its own is reported as starting at the first working moment it can, where other schedulers report the moment it was released, which may be midnight. The end is the same. - Each resource holds one entry per slot for the whole project, so memory grows
with resources times the project's length divided by the slot size. Times off
the hour make the slots smaller;
timingresolutionsets the size outright. - A task 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:!xwith no siblingxis refused. When there are no!s, or they reach the top level of the project and no top-level task matches, the reference binds to the only task in the project with that id, sodepends !!packinsidedeliveryfindsdelivery.pack. When two tasks could be meant, the file is refused and both are named. onstarton a dependency means start-to-start for a task scheduled as soon as possible: it may start once the predecessor starts. For a task scheduled as late as possible it means the task must finish before the predecessor starts, which is ScriptPlan's own reading.
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
depends !!pack { onstart }
}
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"
}
This project schedules backward from the delivery deadline (ALAP mode). The scheduler:
- Anchors packaging to end at 16:00 on July 18
- Schedules both assembly tasks to complete before packaging starts
- Resolves resource contention (single machine) by sequencing assemblies back-to-back
- Respects weekend boundaries (Mon-Fri working hours)
Result:
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. It contains no code from any other scheduler: the parser, the scheduling algorithms and the reports are its own.
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.10.3
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.10.3.tar.gz | 316.9 kB | Without provenance | Details for scriptplan-0.10.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| scriptplan-0.10.3-py3-none-any.whl | Python 3 | none | any | Details for scriptplan-0.10.3-py3-none-any.whl |
Total release size: 520.5 kB
Release files / scriptplan-0.10.3.tar.gz
| Download URL | scriptplan-0.10.3.tar.gz |
|---|---|
| Size | 316.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aabbcc042c826b7b2934550f9f8bbbd837f8553d1d4cfd02704919d826b02472
|
|
BLAKE2b-256 checksum How to use checksums |
d5d4a1abf270c61feb0c8f4347fc1a45c00ab5963fbb895b9611ebb34f10f9cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / scriptplan-0.10.3-py3-none-any.whl
| Download URL | scriptplan-0.10.3-py3-none-any.whl |
|---|---|
| Size | 203.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
76a9216ecbfe543076f174721f8a12f9194ea9aaef64e67504c33bf369ac1279
|
|
BLAKE2b-256 checksum How to use checksums |
08b052d07a32d5959e6c2f200034e2a72c9edc79e28ee7efd6a628a2b304125b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Security for scriptplan 0.10.3
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.