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:
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' = '', funding_inherited: 'bool' = False)
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)

  • funding_inherited (bool)

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])

planner.models.build_schedule(tasks, dependencies=())

Order task edges; project commitments remain unconfirmed readiness gates.

Parameters:

tasks (Iterable[Task])

Return type:

list[tuple[int, str, Task]]

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:

DeadlineAssessment

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_table and 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:
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:
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.

source must be a planner-style .docx document. destination must be a new .yaml or .yml path; publication is atomic and exclusive. Paths are relative to the current directory, with no planner environment overrides. Optional export_options identify 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 ValidationError for 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() retains the aggregate direct-cost mapping, rounding monetary values to whole K with halves up. Terminal list output uses the separate planner.cost_display.cost_view projection for annual amounts, staff details and covered attribution. It groups exact matching values before rounding and never changes resolved funding or CostEstimate values. 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. Resolved share uses Decimal percentage points; amount and source_amount are in K. remainder records explicit or implicit for authored remainder attribution, or automatic for a derived child split; share_description supplies the display label. Before complete-plan resolution, an explicit remainder may retain the string "remainder" in share. External omitted shares remain unquantified; a sole child-to-parent omitted share is inferred after numeric claims. Complete-plan pools are resolved before filtering without mutating ResolvedFunding.authored. Remainder claims preserve existing authoritative parent ownership, annual totals and source availability/completeness rules. CostEstimate.by_type and total remain direct costs; coverage carries included shares, and as_mapping labels its total as direct when necessary.

load_plan tracks whether a child’s funding was inherited with Task.funding_inherited. Complete-plan coverage resolution populates ResolvedFunding.inferred_coverage with read-only equal remainder splits for unallocated children, independently of authored coverage and annual amounts. funding_coverage(budget) combines both kinds for presentation. Cost display uses these attributions without changing CostEstimate aggregate APIs, financial totals, schedules or authored mappings. Re-running resolution replaces inferred records rather than counting them as new claims. Stable child IDs place any non-terminating division’s sub-cent residual deterministically; exact split amounts sum to the remaining source amount. Automatic percentages may be abbreviated with an approximation marker for presentation.

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 | str | 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>, remainder: str = '')
Parameters:
  • task (str)

  • kind (str)

  • year (str)

  • id (str)

  • code (str)

  • share (Decimal | str | None)

  • amount (Decimal | IncompleteAmount | None)

  • source_amount (Decimal | IncompleteAmount | None)

  • funded (bool)

  • resolved (bool)

  • raw (dict)

  • remainder (str)

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.

Monetary display and parent categories

planner.budget.display_funding rounds monetary presentation to whole K with halves up. money_text, task funding, funding_totals, project budget values and staff/coverage amounts retain exact values for calculations and API callers. List/export renderers apply rounding at their boundaries after aggregation, including incomplete known subtotals. Budget comparison colors are selected before display rounding.

For a derived ParentSummary, category is the common scalar ID or a tuple of distinct child IDs in authored part order. categories always returns a tuple. Canonical source Task.category remains scalar. Classification helpers render each parent category through the active vocabulary; table values use newline-separated codes and each Word/PDF paragraph retains column alignment.

Monthly staff costs

RatesCatalog retains scalar values or normalized EffectiveHistory and FTEProfile records for authored histories. StaffCost.monthly contains StaffMonth records with the canonical fiscal period, available FTE, selected rate ID and annual full-time rate used for each costed month. Annual funding remains rounded once per staff/code/year. StaffCost.fte and annual_rate are None when their monthly values vary; rate_id is empty when multiple rate IDs apply. Constant profiles retain the previous summary values.