Python API¶
The public API is intentionally small. Most callers should load a plan with
load_plan or load_tasks and then use the CLI or exporters.
Configuration¶
load_plan(path, config=configuration) and load_tasks accept a validated
Configuration object. When omitted, they resolve and load the user file.
write_docx, write_svg, write_pdf, and write_pptx also accept
config=configuration to resolve category and project priority labels. When omitted they load the
standard user configuration. The optional sites and bnrs allowlists
validate effective task values. Task types use the built-in vocabulary.
Unknown classification IDs fail before
replacing output. Use nested ExportOptions.from_mapping selections for new callers.
Legacy low-level option constructors remain supported for compatibility.
Presentation defaults remain independent; pass
configuration.export as export_options to apply configured settings:
config = load_configuration("team-config.yaml")
plan = load_plan("plan.yaml", config=config)
write_docx(plan, "plan.docx", config=config, export_options=config.export)
User configuration, packaged defaults, and configurable plan vocabularies.
- class planner.config.VocabularyEntry(id: str, label: str, description: str, table_entry: str | None = None)¶
- Parameters:
id (str)
label (str)
description (str)
table_entry (str | None)
- class planner.config.IdEntry(id: str)¶
- Parameters:
id (str)
- class planner.config.Configuration(task_priorities: tuple[planner.config.VocabularyEntry, ...], task_categories: tuple[planner.config.VocabularyEntry, ...], export: planner.export_options.ExportOptions, config_version: int = 1, sites: tuple[planner.config.IdEntry, ...] | None = None, bnrs: tuple[planner.config.IdEntry, ...] | None = None, list_options: planner.export_options.ExportOptions | None = None, terminal_colors: dict | None = None, max_width: int = 80, rates_file: pathlib.Path | None = None, labor_costing: str = 'annual')¶
- Parameters:
task_priorities (tuple[VocabularyEntry, ...])
task_categories (tuple[VocabularyEntry, ...])
export (ExportOptions)
config_version (int)
sites (tuple[IdEntry, ...] | None)
bnrs (tuple[IdEntry, ...] | None)
list_options (ExportOptions | None)
terminal_colors (dict | None)
max_width (int)
rates_file (Path | None)
labor_costing (str)
- property types¶
Built-in task types, shared with templates and Word recovery.
- planner.config.initialize_config(path=None)¶
Publish a complete default file exclusively; never overwrite user settings.
- planner.config.load_configuration(path=None, *, ignore_list=False, export_standard=None)¶
Load configuration, optionally bypassing only list-presentation validation.
Initialize only a missing implicit default; classification rules stay active. An export_standard override selects its configured rules without saving it.
Loader¶
Models¶
Activity.code is the optional labor allocation default. Task.code holds
the effective task default after activity inheritance; StaffCost.code records
the actually selected allocation. load_plan supplies activity context
internally. Direct Task.from_mapping callers may supply
activity_codes={"DESIGN": "DEMO_CORE_0000"} alongside their funding resolver.
For plans with project commitments, retain the full plan and pass its dependency definitions when validating or scheduling task collections:
plan = load_plan("plan.yaml", config=config)
schedule = build_schedule(plan.tasks, dependencies=plan.dependencies)
ProjectPlan.dependencies contains Dependency records, while
ProjectPlan.risks contains public ProjectRisk definitions. Task.risks
remains a tuple of private inline Risk records. Task dependency references
remain strings. Exporters receive the complete plan to resolve both namespaces.
- exception planner.models.ValidationError(message, *, filename=None, lineno=None)¶
- class planner.models.Risk(type: 'str', level: 'str', mitigation: 'str', description: 'str' = '')¶
- Parameters:
type (str)
level (str)
mitigation (str)
description (str)
- class planner.models.Task(id: 'str', label: 'str', start: 'str', expected: 'int | None', milestones: 'tuple[str, ...]', priority: 'str', risks: 'tuple[Risk, ...]', status: 'str', description: 'str', dependencies: 'tuple[str, ...]', completed: 'str' = '', bnr: 'str' = '', funding: 'Mapping[str, str]'=<factory>, site: 'str' = '', type: 'str' = '', tags: 'tuple[str, ...]'=(), parent_id: 'str' = '', parent_label: 'str' = '', part_id: 'str' = '', funding_source_id: 'str' = '', activity: 'str' = '', category: 'str' = '', note: 'str' = '', parent_funding: 'Mapping[str, str] | None'=None, source_file: 'str' = '', source_line: 'int | None' = None, funding_line: 'int | None' = None, parent_funding_line: 'int | None' = None, workitems: 'tuple[WorkItem, ...]'=(), part_index: 'int' = 0, deliverables: 'tuple[str, ...]'=(), types: 'tuple[str, ...]'=(), parent_data: 'Mapping[str, object]'=<factory>, code: 'str' = '')¶
- Parameters:
id (str)
label (str)
start (str)
expected (int | None)
milestones (tuple[str, ...])
priority (str)
risks (tuple[Risk, ...])
status (str)
description (str)
dependencies (tuple[str, ...])
completed (str)
bnr (str)
funding (Mapping[str, str])
site (str)
type (str)
tags (tuple[str, ...])
parent_id (str)
parent_label (str)
part_id (str)
funding_source_id (str)
activity (str)
category (str)
note (str)
parent_funding (Mapping[str, str] | None)
source_file (str)
source_line (int | None)
funding_line (int | None)
parent_funding_line (int | None)
workitems (tuple[WorkItem, ...])
part_index (int)
deliverables (tuple[str, ...])
types (tuple[str, ...])
parent_data (Mapping[str, object])
code (str)
- property funding_status: bool¶
Whether the task and its declared coverage sources are funded.
- property funding_total: str¶
Total of this task’s effective fiscal-year funding, in thousands.
- property duration: int | None¶
Expected task duration in fiscal months.
- property duration_label: str¶
Human-readable duration, including an unknown placeholder estimate.
- property funded_years: tuple[str, ...]¶
Fiscal years with positive funding amounts, in time order.
- property schedule_spans: tuple[tuple[str, str], ...]¶
Scheduled fiscal periods; ongoing work has one span per funded year.
- property end: str¶
Last fiscal month, counting the start month as month one.
- class planner.models.Activity(id: 'str', label: 'str', description: 'str', code: 'str' = '')¶
- Parameters:
id (str)
label (str)
description (str)
code (str)
- class planner.models.Deliverable(id: 'str', label: 'str', description: 'str', type: 'str', status: 'str' = 'required', completed: 'str' = '', source_file: 'str' = '', source_line: 'int | None' = None)¶
- Parameters:
id (str)
label (str)
description (str)
type (str)
status (str)
completed (str)
source_file (str)
source_line (int | None)
- property requires_producers: bool¶
Outstanding outputs retain every producer and milestone constraint.
- property reference_label: str¶
Show non-default lifecycle state wherever an output is referenced.
- class planner.models.Milestone(id: 'str', label: 'str', description: 'str', deadline: 'str', deliverables: 'tuple[str, ...]' = (), reporting_level: 'str' = '', source_file: 'str' = '', source_line: 'int | None' = None)¶
- Parameters:
id (str)
label (str)
description (str)
deadline (str)
deliverables (tuple[str, ...])
reporting_level (str)
source_file (str)
source_line (int | None)
- class planner.models.ProjectRisk(type: 'str', level: 'str', mitigation: 'str', description: 'str' = '', id: 'str' = '', label: 'str' = '', source_file: 'str' = '', source_line: 'int | None' = None)¶
- Parameters:
type (str)
level (str)
mitigation (str)
description (str)
id (str)
label (str)
source_file (str)
source_line (int | None)
- class planner.models.Dependency(id: 'str', label: 'str', type: 'str', description: 'str', promised: 'str', risks: 'tuple[str, ...]' = (), source_file: 'str' = '', source_line: 'int | None' = None)¶
- Parameters:
id (str)
label (str)
type (str)
description (str)
promised (str)
risks (tuple[str, ...])
source_file (str)
source_line (int | None)
- class planner.models.ProjectPlan(tasks: 'tuple[Task, ...]', portfolios: 'tuple[str, ...]'=(), project: 'str' = '', managers: 'tuple[str, ...]'=(), pocs: 'tuple[str, ...]'=(), summary: 'str' = '', fiscal_years: 'tuple[str, ...]'=(), execution_description: 'str' = '', activities: 'tuple[Activity, ...]'=(), metadata: 'Mapping[str, object]'=<factory>, milestones: 'tuple[Milestone, ...]'=(), deliverables: 'tuple[Deliverable, ...]'=(), dependencies: 'tuple[Dependency, ...]'=(), stakeholders: 'str' = '', users: 'str' = '', risks: 'tuple[ProjectRisk, ...]'=(), background: 'str' = '', fiscal_current: 'str' = '', planned_value: 'str' = '', rates_sources: 'Mapping[object, bytes]'=<factory>)¶
- Parameters:
tasks (tuple[Task, ...])
portfolios (tuple[str, ...])
project (str)
managers (tuple[str, ...])
pocs (tuple[str, ...])
summary (str)
fiscal_years (tuple[str, ...])
execution_description (str)
activities (tuple[Activity, ...])
metadata (Mapping[str, object])
milestones (tuple[Milestone, ...])
deliverables (tuple[Deliverable, ...])
dependencies (tuple[Dependency, ...])
stakeholders (str)
users (str)
risks (tuple[ProjectRisk, ...])
background (str)
fiscal_current (str)
planned_value (str)
rates_sources (Mapping[object, bytes])
Deadline Assessments¶
Derived output readiness and milestone constraints; never changes schedules.
- class planner.deadlines.DeliverableTiming(producers: tuple[str, ...], ready: str, required_by: str, inferred_complete: bool, actual: bool, status: str = 'required')¶
- Parameters:
producers (tuple[str, ...])
ready (str)
required_by (str)
inferred_complete (bool)
actual (bool)
status (str)
- class planner.deadlines.DeadlineAssessment(deliverables: dict[str, planner.deadlines.DeliverableTiming], task_required_by: dict[str, str], milestone_tasks: dict[str, tuple[str, ...]])¶
- Parameters:
deliverables (dict[str, DeliverableTiming])
task_required_by (dict[str, str])
milestone_tasks (dict[str, tuple[str, ...]])
- planner.deadlines.assess_deadlines(plan)¶
Assess required producers and explicit output completion without changing schedules.
- Parameters:
plan (ProjectPlan)
- Return type:
Export Options¶
- class planner.export_options.TaskTableColumn(attribute: 'str', label: 'str | None' = None, alignment: 'str' = 'center')¶
- Parameters:
attribute (str)
label (str | None)
alignment (str)
- class planner.export_options.ExportOptions(task_table_attributes: 'tuple[str, ...]' = ('site', 'bnr', 'funding', 'type'), task_table_columns: 'tuple[TaskTableColumn, ...]' = (), include_note: 'bool' = False, elements: 'dict | tuple[str, ...] | None' = None, layout: 'tuple[TaskTableColumn, ...]' = (), nested: 'bool' = False, standard: 'str' = 'legacy', headings_underline: 'bool' = False, table_orientation: 'str' = 'portrait', table_fiscal_years: 'tuple[str, ...] | None' = None, header: 'str' = '', spacing: 'str' = 'tight', lines: 'tuple[ExportLine, ...]' = (), instructions: 'tuple[FormatInstruction, ...] | None' = None, definition_instructions: 'dict[str, tuple[FormatInstruction, ...]]' = <factory>, font_size: 'float | None' = None, table_font_size: 'float' = 10, context_colors: 'bool' = True, task_numbering: 'str' = 'numeric', multipart: 'str' = 'expanded', metadata_styles: 'dict' = <factory>, element_spacing: 'dict[str, str]' = <factory>, structure: 'tuple[tuple[str, str | None], ...] | None' = None)¶
- Parameters:
task_table_attributes (tuple[str, ...])
task_table_columns (tuple[TaskTableColumn, ...])
include_note (bool)
elements (dict | tuple[str, ...] | None)
layout (tuple[TaskTableColumn, ...])
nested (bool)
standard (str)
headings_underline (bool)
table_orientation (str)
table_fiscal_years (tuple[str, ...] | None)
header (str)
spacing (str)
lines (tuple[ExportLine, ...])
instructions (tuple[FormatInstruction, ...] | None)
definition_instructions (dict[str, tuple[FormatInstruction, ...]])
font_size (float | None)
table_font_size (float)
context_colors (bool)
task_numbering (str)
multipart (str)
metadata_styles (dict)
element_spacing (dict[str, str])
structure (tuple[tuple[str, str | None], ...] | None)
- spacing_for(element)¶
Resolve an element override through its ancestors to document spacing.
- selection(element)¶
Return a nested selection without discarding its child switches.
- subtotal_selection(name)¶
Explicit task_table subtotal setting; never implied by “select all”.
Subtotals are opt-in, so omitted elements, a bare
task_tableand other whole-branch selections leave them off.
- totals_placement(name)¶
Return top/bottom for a placeable total, or None when disabled.
Exporters¶
Set ExportOptions(elements=("project", "summary", "tasks")) to select
top-level output fields. elements=None selects all; elements=() selects
none. Pass these options through export_options in each plan exporter.
The validated plan remains complete for references and derived calculations.
- planner.exporters.write_pdf(plan_or_tasks, destination, *, export_options=None, config=None)¶
Export the Word plan through Microsoft Word to preserve its page layout.
- Parameters:
plan_or_tasks (ProjectPlan | list[Task])
destination (str | Path)
export_options (ExportOptions | None)
config (Configuration | None)
- Return type:
Path
PowerPoint Plans¶
Editable PowerPoint plan slides, optionally based on a user’s presentation.
- planner.slides.find_template(template=None)¶
Validate an explicit template, or search the configured directory and cwd.
- Parameters:
template (str | Path | None)
- Return type:
Path | None
- planner.slides.write_pptx(plan_or_tasks, destination, *, export_options=None, template=None, config=None)¶
Write paginated, editable plan slides using a template’s theme and layouts.
- Parameters:
plan_or_tasks (ProjectPlan | list[Task])
destination (str | Path)
export_options (ExportOptions | None)
template (str | Path | None)
config (Configuration | None)
- Return type:
Path
Word Import¶
Import visible content from planner-style Word documents into YAML drafts.
- planner.importers.import_docx(source, destination, *, export_options=None, config=None, update=None)¶
Import visible Word content, validate it, and publish a YAML draft.
sourcemust be a planner-style.docxdocument.destinationmust be a new.yamlor.ymlpath; publication is atomic and exclusive. Paths are relative to the current directory, with no planner environment overrides. Optionalexport_optionsidentify custom table headers.Missing task IDs are generated deterministically from labels with numeric collision suffixes; recovered explicit IDs are preserved. Missing forecast timing is inferred from positive annual funding with full-year bounds and review notices, preserving recovered dates/duration. Missing status or unrecoverable required timing becomes planning. Actual completion dates are never inferred. Top-level fields, activities, and task entries retain document order. Labeled comment dividers separate top-level fields; one blank line separates ID-bearing list entries at every nesting level.
Return report lines containing counts and review warnings. Raise
ValidationErrorfor invalid input, ambiguous deliverable references, invalid generated plans, or publication failures.- Parameters:
source (str | Path)
destination (str | Path)
export_options (ExportOptions | None)
config (Configuration | None)
update (str | None)
- Return type:
list[str]
Object Listings¶
Object-scoped list views, relationship filters, and shared terminal rendering.
- class planner.listing.ListFilter(target: str | None, values: tuple[str, ...], partial: bool = False)¶
- Parameters:
target (str | None)
values (tuple[str, ...])
partial (bool)
Gantt Exporters¶
Both Gantt exporters accept optional range_begin and range_end keyword
arguments. Use FY26 for a whole fiscal-year bound or M1Q1FY26 for an
exact fiscal-month bound. The bounds are inclusive.
Fiscal-month Gantt exports for SVG and PowerPoint.
Terminal Planning Documents¶
Full terminal planning documents, independent of export presentation options.
- planner.terminal_document.format_plan_document(plan, *, config, task_ids=None, color=False, parents=False)¶
Render source sections with consistent parent and child heading roles.
Staff Funding¶
Task.funding continues to map fiscal years to resolved annual amounts. Typed
inputs produce ResolvedFunding, with by_type, staff (StaffCost
records) and authored attributes retaining the detail.
load_plan(..., funding_resolver=resolver) and
Task.from_mapping(..., funding_resolver=resolver) accept explicit rates
resolution. For example:
from planner.funding import FundingResolver, RatesCatalog
catalog = RatesCatalog.from_mapping({
"rates": [{"id": "STANDARD", "amount": "$300K"}],
"staff": [{"id": "STAFF_A", "rate": "STANDARD", "fte": "40%"}],
})
resolver = FundingResolver(catalog=catalog, labor_costing="annual")
plan = load_plan("plan.yaml", config=config, funding_resolver=resolver)
An injected catalog bypasses file reads. A resolver holds one rates snapshot;
reuse it only when that snapshot is intentional. Normal load_plan calls
create a fresh resolver. See Funding and Staff Costs for calculation rules.
RatesCatalog.rate_metadata maps rate IDs to RateMetadata records with
optional category and band text. Records are present when either field
is supplied. RatesCatalog.rates continues to contain only resolved monetary
amounts, and staff cost calculations use those amounts.
Coded staff allocations use (staff_id, code) tuple keys in
RatesCatalog.staff and RatesCatalog.fte. Uncoded entries retain string
keys. allocation_key(id, code="") resolves an explicit code, an uncoded
default, or a single unambiguous coded allocation. StaffCost.code records
the selected code, including when a unique coded allocation was selected by ID.
Grouped staff codes lists normalize to the same tuple-keyed catalog as flat
coded entries. The parent rate is inherited by child codes unless overridden;
source mappings are not modified. Staff and task lookup APIs are unchanged.
Task Cost Estimates¶
Task.cost returns a CostEstimate with by_type, total, complete,
known_subtotal and shared_parent. as_mapping() supplies the list
projection, rounding displayed monetary values to whole K with halves up.
by_type, total and known_subtotal keep their exact decimal values;
rounding happens after aggregation. It reads existing resolved annual funding
rather than recalculating staff charges.
load_plan(..., allow_incomplete_funding=True) opts into list-style resolution.
Alternatively, pass a FundingResolver(allow_incomplete=True) explicitly.
Default loading remains strict. IncompleteAmount values retain an exact
known subtotal and reasons; funding_totals and actual/potential values
propagate them instead of converting them to zero. Only missing calculation
inputs are deferred; malformed data and invalid references still raise. An
unavailable rates snapshot remains unavailable for that resolver’s lifetime;
create a new resolver or load the plan again after fixing the file.
Funding range context¶
load_plan resolves typed funding fiscal_range defaults using the plan’s
normalized fiscal years, preserving shorthand in ResolvedFunding.authored.
Direct Task.from_mapping and FundingResolver.resolve callers can supply
fiscal_years=("FY27", "FY28") to provide this context. Explicit year entries
replace the range default for that type/year.
Funding coverage¶
ResolvedFunding.coverage stores FundingCoverage records, separate from
its direct annual dollar mapping. load_plan resolves references only after
all direct budgets exist. share uses Decimal percentage points; amount
and source_amount are in K. An omitted share has no attributed amount.
CostEstimate.by_type and total remain direct costs; coverage carries
included shares, and as_mapping labels its total as direct when necessary.
References to funding owned by another task, without transferring dollars.
- class planner.coverage.FundingCoverage(task: str, kind: str, year: str, id: str = '', code: str = '', share: decimal.Decimal | None = None, amount: decimal.Decimal | planner.budget.IncompleteAmount | None = None, source_amount: decimal.Decimal | planner.budget.IncompleteAmount | None = None, funded: bool = True, resolved: bool = False, raw: dict = <factory>)¶
- Parameters:
task (str)
kind (str)
year (str)
id (str)
code (str)
share (Decimal | None)
amount (Decimal | IncompleteAmount | None)
source_amount (Decimal | IncompleteAmount | None)
funded (bool)
resolved (bool)
raw (dict)
- planner.coverage.resolve_coverage(tasks, *, allow_external=False)¶
Resolve complete-plan coverage after all direct task budgets are known.
Local fragment transforms may retain references outside their visible task collection. Full-plan loading always uses strict reference resolution.
Task-date funding range context¶
Task.from_mapping resolves typed funding range from authored start/end
or start/expected. Plan fiscal metadata is unnecessary. Direct
FundingResolver.resolve callers provide normalized start, expected
and explicit_timing=True. Range expansion and annual/duration cost calculation
remain separate.
With incomplete resolution enabled, ResolvedFunding.unavailable retains
unknown range components by type, alongside known explicit annual amounts.
Unknown ranges have no synthetic fiscal-year keys. Cost and annual funding
aggregation preserve these unknowns; explicit overrides remain known for their
years. Strict callers and exporters reject missing timing. Authored shorthand
remains in ResolvedFunding.authored.
Rates code validation¶
RatesCatalog.from_mapping validates flat staff code and grouped
codes[].id against [A-Z0-9]{4}_[A-Z0-9]{4}_[A-Z0-9]{4}, trimming
surrounding whitespace. Invalid values raise source-aware ValidationError.
Uncoded allocations and the syntax of staff/rate IDs remain unchanged.
Implicit parent attribution¶
Task.from_mapping passes the loader’s multipart funding context to coverage
parsing, allowing child share entries to infer their authoritative parent.
Explicit child-to-parent references use the same resolution and share pool.
Direct FundingResolver.resolve callers can supply coverage_parent when
parsing a child’s budget; complete-plan resolve_coverage still validates
ownership and sources. Child cost estimates retain declared attribution, while
parent summaries and financial aggregation retain the full owned budget.