tuxfan-planner 0.2.0__tar.gz

tuxfan_planner-0.2.0/PKG-INFO

@@ -0,0 +1,401 @@
+Metadata-Version: 2.4
+Name: tuxfan-planner
+Version: 0.2.0
+Summary: Simple text-driven project planning system
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: docs
+Requires-Dist: Sphinx>=7.2; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+
+# Project Planner
+
+A small planning system that lets you define project plans and tasks in either YAML or Python.
+
+A plan can include optional top-level project metadata:
+
+- `portfolio`: portfolio or parent program name.
+- `project`: high-level project name.
+- `managers`: list of manager names.
+- `pocs`: list of point-of-contact names.
+- `summary`: high-level plan summary.
+- `fiscal_range_begin` and `fiscal_range_end`: optional fiscal year range covered by the plan, for example `27` through `31`.
+- `execution`: execution metadata. It can be a mapping with `overview` text and `sections`, where each section has `label`, `description`, and an optional stable `id` for task links. The older flat list of sections is still accepted.
+
+Each task supports these fields:
+
+- `id`: required string task id. Must contain only letters, numbers, or underscores, with no spaces.
+- `label`: required string display name for the task.
+- `site`: optional site or institution label.
+- `bnr`: optional budget and reporting identifier.
+- `cost`: optional task cost label, for example `$100K`.
+- `funding status` or `funding_status`: optional funding state label.
+- `type`: optional task type label.
+- `tags`: optional comma-separated string or list of task tags.
+- `project`: required string project name.
+- `execution_section`: optional ID of a section under `execution.sections`. Linked tasks use that section's label and position for activity headings and task numbers in exports. An unknown ID is rejected.
+- `description`: required string describing the task.
+- `start`: required fiscal period string in `M{month}Q{quarter}FY{year}` format, where `month` is `1` to `3` within the quarter.
+- `deadline`: required fiscal period string in `M{month}Q{quarter}FY{year}` format, where `month` is `1` to `3` within the quarter.
+- `completed`: optional fiscal period string for work that is already complete. A task with `status: complete` and `completed` may omit planning-only fields: `start`, `deadline`, `expected duration`, `milestone`, `priority`, `dependencies`, and `risk`. Without `completed`, these fields are required.
+- `expected duration` or `expected_duration`: required positive whole number of months.
+- `milestone`: required string milestone name.
+- `priority`: required string priority label such as `low`, `medium`, `high`, or `urgent`.
+- `status`: required string status. Allowed values are `pending`, `active`, `ongoing`, `blocked`, and `complete`.
+- `dependencies`: required list of task ids. Each dependency must reference another task `id`.
+- `risk`: required risk entry or list of risk entries. Each entry has `type`, `level`, and `mitigation`, and may include `description`; `level` must be `low`, `medium`, `high`, or `extreme`.
+- `funding`: optional mapping of fiscal year to funding level, for example `fy27: 50K`. A task is treated as unfunded for fiscal years not present in this mapping.
+
+A task can also be a multi-part task by using `parts` instead of the per-task
+schedule fields on the parent. Parent fields such as `project`, `execution_section`, `site`, `bnr`,
+`type`, `tags`, and `funding` are inherited by each part, while each part
+provides its own `id`, `label`, `description`, `start`, `deadline`,
+`expected duration`, `milestone`, `priority`, `status`, `dependencies`, and
+`risk`. Part ids are expanded as `{parent_id}_{part_id}`. Dependencies inside a
+multi-part task can reference sibling part ids, and dependencies from other
+tasks can reference the parent id to depend on all expanded parts. Parent-level
+funding inherited by multiple parts is counted once in fiscal-year totals.
+
+## Quick start
+
+Run from this directory:
+
+```bash
+planner validate planner/examples/tasks.yaml
+planner list planner/examples/tasks.yaml
+planner summary planner/examples/tasks.yaml
+planner schedule planner/examples/tasks.yaml
+planner export-docx planner/examples/tasks.yaml /tmp/plan.docx
+planner export-svg planner/examples/tasks.yaml /tmp/plan.svg
+```
+
+If you set `TUXFAN_PLANNER_DATAFILE`, the CLI uses that file by default:
+
+```bash
+export TUXFAN_PLANNER_DATAFILE=planner/examples/tasks.yaml
+planner validate
+planner list
+planner export-docx /tmp/plan.docx
+planner export-svg /tmp/plan.svg
+```
+
+If you set `TUXFAN_PLANNER_EXPORT_OPTIONS`, the export commands use that file by default:
+
+```bash
+export TUXFAN_PLANNER_EXPORT_OPTIONS=planner/examples/export-options.yaml
+planner export-docx planner/examples/tasks.yaml /tmp/plan.docx
+```
+
+You can also install it locally:
+
+```bash
+python3 -m pip install -e .
+planner list planner/examples/tasks.yaml
+```
+
+The legacy `tuxfan-planner` command remains available as an alias.
+Run `planner --help` to see the current values of both planner environment
+variables alongside the command help.
+
+## Shell completion
+
+The CLI can print completion scripts for `bash`, `zsh`, and `fish`:
+
+```bash
+planner completion bash
+planner completion zsh
+planner completion fish
+```
+
+For a one-session bash setup:
+
+```bash
+source <(planner completion bash)
+```
+
+The generated completion supports the basic planner subcommands, the
+`tuxfan-planner` alias, file path completion for task and output arguments, and
+`--export-options` for export commands.
+
+## Documentation
+
+Sphinx documentation lives in `docs/`. See the
+[developer setup and checks](DEVELOPER.md) for the current dependency and HTML
+build commands.
+
+On GitHub, the `Documentation` workflow builds the same Sphinx output and
+publishes it to the `gh-pages` branch. Configure the repository Pages settings
+to serve from the `gh-pages` branch root.
+
+## Updating the virtual environment
+
+Follow [Install or upgrade dependencies](DEVELOPER.md#install-or-upgrade-dependencies)
+in the developer guide to update the root `.venv` and check the result.
+
+## YAML format
+
+Top-level can be either a list of tasks or a mapping with a `tasks` key. The mapping form can also include plan-level metadata such as `portfolio`, `project`, `managers`, `pocs`, `summary`, `fiscal_range_begin`, `fiscal_range_end`, and `execution`.
+
+```yaml
+portfolio: Advanced Simulation and Computing
+project: Task-Parallel Project
+managers:
+  - Alice Example
+pocs:
+  - Casey Example, PI
+summary: >
+  High-level planning context for the task collection.
+fiscal_range_begin: 27
+fiscal_range_end: 29
+execution:
+  overview: >
+    Overall execution context for the plan.
+  sections:
+    - id: deliverable_a
+      label: Deliverable A
+      description: >
+        Narrative execution detail for this deliverable.
+
+tasks:
+  - id: DraftArchitecture
+    label: Draft architecture
+    bnr: DP1518130
+    cost: $100K
+    funding status: funded
+    site: LANL
+    type: labor
+    tags:
+      - architecture
+    project: Planning System
+    execution_section: deliverable_a
+    description: Produce the first architecture draft.
+    start: M1Q3FY26
+    deadline: M2Q3FY26
+    expected duration: 2
+    milestone: Design
+    priority: high
+    status: complete
+    dependencies: []
+    risk:
+      - type: scope
+        level: medium
+        description: Integration requirements may change during implementation.
+        mitigation: Review the architecture with stakeholders before implementation starts.
+    funding:
+      fy27: 50K
+      fy29: 100K
+
+  - id: BuildParser
+    label: Build parser
+    project: Planning System
+    description: Load task definitions from YAML and Python files.
+    start: M2Q3FY26
+    deadline: M2Q3FY26
+    expected_duration: 1
+    milestone: Implementation
+    priority: high
+    status: pending
+    dependencies:
+      - DraftArchitecture
+    risk:
+      - type: integration
+        level: medium
+        mitigation: Add schema validation tests for both YAML and Python task sources.
+
+  - id: MultiYearDelivery
+    label: Multi-year delivery
+    site: LANL
+    project: Planning System
+    funding:
+      fy27: 50K
+      fy28: 100K
+    parts:
+      - id: A
+        label: First phase
+        description: Complete the first phase.
+        start: M1Q1FY27
+        deadline: M3Q2FY27
+        expected duration: 6
+        milestone: Phase A
+        priority: high
+        status: active
+        dependencies: []
+        risk:
+          - type: schedule
+            level: low
+            mitigation: Review progress monthly.
+      - id: B
+        label: Second phase
+        description: Complete the second phase.
+        start: M1Q3FY27
+        deadline: M3Q4FY28
+        expected duration: 18
+        milestone: Phase B
+        priority: medium
+        status: pending
+        dependencies:
+          - A
+        risk:
+          - type: technical
+            level: medium
+            mitigation: Keep integration tests current.
+```
+
+## Python format
+
+Define `PLAN` or `plan` in a `.py` file for metadata plus tasks. The legacy `TASKS` or `tasks` list still works.
+
+```python
+PLAN = {
+    "portfolio": "Advanced Simulation and Computing",
+    "project": "Task-Parallel Project",
+    "managers": ["Alice Example"],
+    "pocs": ["Casey Example, PI"],
+    "summary": "High-level planning context for the task collection.",
+    "fiscal_range_begin": 27,
+    "fiscal_range_end": 29,
+    "execution": {
+        "overview": "Overall execution context for the plan.",
+        "sections": [
+            {
+                "id": "deliverable_a",
+                "label": "Deliverable A",
+                "description": "Narrative execution detail for this deliverable.",
+            }
+        ],
+    },
+    "tasks": [
+        {
+            "id": "DraftArchitecture",
+            "label": "Draft architecture",
+            "bnr": "DP1518130",
+            "cost": "$100K",
+            "funding_status": "funded",
+            "site": "LANL",
+            "type": "labor",
+            "tags": ["architecture"],
+            "project": "Planning System",
+            "execution_section": "deliverable_a",
+            "description": "Produce the first architecture draft.",
+            "start": "M1Q3FY26",
+            "deadline": "M2Q3FY26",
+            "expected_duration": 2,
+            "milestone": "Design",
+            "priority": "high",
+            "status": "complete",
+            "dependencies": [],
+            "risk": [
+                {
+                    "type": "scope",
+                    "level": "medium",
+                    "mitigation": "Review the architecture with stakeholders before implementation starts.",
+                }
+            ],
+            "funding": {"fy27": "50K", "fy29": "100K"},
+        }
+    ],
+}
+```
+
+## Status values
+
+Use one of:
+
+- `pending`
+- `active`
+- `ongoing`
+- `blocked`
+- `complete`
+
+## Fiscal period values
+
+`start` and `deadline` must use `M{month}Q{quarter}FY{year}`:
+
+- `month` is `1` to `3` within the quarter
+- `quarter` is `1` to `4`
+- `year` is a 2-digit fiscal year, for example `FY26`
+
+Fiscal years begin on October 1:
+
+- `Q1` = October through December
+- `Q2` = January through March
+- `Q3` = April through June
+- `Q4` = July through September
+
+Examples:
+
+- `M1Q1FY26` = October 2025
+- `M2Q3FY26` = May 2026
+- `M3Q4FY26` = September 2026
+
+## Commands
+
+- `validate`: checks required fields, invalid status values, invalid fiscal period or duration values, invalid ids, duplicate ids, missing dependencies, and dependency cycles
+- `list`: prints task details in deadline order by default, including fiscal start and deadline values and expected duration in months
+- `summary`: groups tasks by project and milestone and prints funding totals when task funding is present
+- `schedule`: prints tasks in dependency order and marks them as `READY`, `BLOCKED`, `ACTIVE`, or `COMPLETE`
+- `export-docx`: generates a Word document with the schedule and a detailed task table. Use `--export-options PATH` or `TUXFAN_PLANNER_EXPORT_OPTIONS` to control which optional task attributes appear in the summary table and in the per-task narrative metadata. The table starts on a new page with its section headings. When fiscal years are configured, it includes one column per fiscal year with each task's funding level or a blank cell when the task is not funded in that year, plus a final total row.
+- `export-svg`: generates a graphical SVG plan with the same activity letters and task numbers as Word. It shows configured fiscal-year funding totals, completion years, and dependency task numbers. Fill color reflects status, border color uses the Word risk colors, and an accent bar reflects priority. Export options select which optional task attributes appear on cards; custom column labels and alignment apply only to Word.
+
+## Export options
+
+Export options files can be YAML, YML, or Python. The current supported settings are `task_table_attributes` and `task_table_columns`, which control the optional task attribute columns included in the Word export summary table and the attributes shown on SVG task cards. Custom labels and alignment apply only to Word. The `.docx` table always starts with an unlabeled column containing generated task numbers; it does not include a Project column. An `Activity A`, `Activity B`, etc. row precedes each activity's tasks, which appear in numeric task order. When tasks link to execution sections, the activity row includes the section label and its letter follows section order (for example, `Activity B: Specialization Work` with `Task B.1`). Unlinked tasks follow in project-based groups; plans without links keep their existing project-based grouping. Each activity label occupies one left-aligned cell spanning the table. The column header repeats only when the table continues onto another page; Activity rows appear at their normal group transitions. All table cells center their content vertically. Fiscal-year columns are added automatically when plan fiscal years are configured, with a final `Total Funding` row that sums each year and counts inherited multipart funding once. For completed tasks, those columns become one green-filled cell labeled with the completion year (for example, `Completed FY26`) when a `completed` period is available, or `Completed` otherwise; the other cells remain black on white. The other task metadata columns and per-task attribute narrative are limited to the attributes listed here.
+
+In the Word risk mitigation section, the bold risk label is green for `low`, yellow for `medium`, orange for `high`, and deep red for `extreme`. Mitigation text remains black.
+
+Top-level Word section labels, including `Tasks:`, are bold and underlined.
+
+Supported attribute names:
+
+- `bnr`
+- `cost`
+- `funding` or `funding_status`
+- `site`
+- `type`
+- `tags`
+
+Simple YAML:
+
+```yaml
+task_table_attributes:
+  - site
+  - bnr
+  - funding
+  - tags
+```
+
+Shorthand YAML with custom labels:
+
+```yaml
+task_table_attributes:
+  - bnr: BNR
+  - funding: Status
+  - tags: Keywords
+```
+
+Recommended explicit YAML when you need labels or alignment:
+
+```yaml
+task_table_columns:
+  - attribute: bnr
+    label: BNR
+  - attribute: funding
+    label: Status
+  - attribute: tags
+    label: Keywords
+```
+
+Supported column alignment values:
+
+- `left`
+- `center`
+- `right`
+
+`alignment` is optional and defaults to `center`.
+
+Example CLI usage:
+
+```bash
+planner export-docx planner/examples/tasks.yaml /tmp/plan.docx --export-options planner/examples/export-options.yaml
+```