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' = '', funding_inherited: 'bool' = False, funding_file: 'str' = '', parent_funding_file: '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)
funding_inherited (bool)
funding_file (str)
parent_funding_file (str)
- property funding_excluded: bool¶
Historical context tasks do not participate in current funding.
- 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.
RatesCatalog.staff_labels maps staff IDs to non-empty display labels.
staff_label(id) returns the label or the ID when none is set. Labels apply
across allocations without changing staff lookup or costs.
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. Task.funding_excluded is true for
complete and closed tasks; their costs and current funding totals are zero.
Completed funding retains its authored input without resolving it. Closed
funding is validated but excluded from calculations. Funding projections mark
both statuses as excluded.
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.
Staff Subscription¶
staff_subscription(plan, catalog, year=None, month=None) builds a read-only
StaffReport of monthly StaffSubscription rows for every catalog
allocation. Use the same rates snapshot/catalog that resolved the plan’s funding.
staff_demands(tasks) supplies canonical direct budget-owner claims and is
also used by overcommitment validation. Plan validation uses the loaded catalog
to compare those claims with the same monthly person capacity as the report.
StaffReport.person returns a
PersonSubscription named tuple: subscription, availability,
allocated, proposed, complete and proposed_complete. Configured
capacity sums coded allocations or uses the uncoded allocation. If both exist,
use the larger alternative pool, not their sum. Person availability subtracts
total subscription from configured capacity and is unknown when capacity or
demand is unknown. It is not a balance against an assumed 100% FTE.
In StaffSubscription code rows, available, used, remaining and
proposed retain their Decimal FTE meanings (allocated, subscribed, available
and proposed effort). subscription is the code-allocation percentage.
Text output names the FTE value Subscribed and the remaining FTE Available. CSV uses explicit allocated_fte, subscription_fte,
availability_fte and code_subscription_percent column names.
complete and proposed_complete describe demand completeness. Unknown
availability or incomplete demand yields remaining=None and
subscription=None; zero availability also has no subscription ratio.
used and proposed retain known subtotals when demand is incomplete.
format_staff_subscription provides terminal output;
staff_subscription_csv provides monthly CSV. Display filters do not mutate
the full report or change person totals.