Add TaskStage API support with models, resource, tests and examples

[TanyaSingh369-svg]

Description

This PR adds support for Task Stages APIs in the Python TFE client, aligned with the go-tfe implementation.

Task stages represent different phases of a Terraform run and capture execution status, policy checks, and run task results. This PR enables users to retrieve a task stage by ID, list task stages for a run, and override a task stage when permitted.

The implementation follows existing repository patterns for resources and models, and includes proper handling of relationships and forward references between TaskStage, TaskResult, and PolicyEvaluation to avoid circular dependencies.

Changes

• Implemented TaskStages resource with the following methods:
  • read() – Retrieve a task stage by ID
  • list() – List all task stages associated with a run
  • override() – Override a task stage when permissions allow
• Added corresponding models:
  • TaskStage
  • TaskResult
  • Added supporting enums and nested models:
    - Stage
    - TaskStageStatus
    - TaskStageStatusTimestamps
    - Permissions
    - Actions
    - TaskResultStatus
    - TaskResultStatusTimestamps
    - TaskEnforcementLevel
• Implemented relationships between models (e.g., task results and policy evaluations within a task stage)
• Updated TFEClient to expose the task_stages service
• Added example (examples/task_stage_example.py) demonstrating:
  • Fetching a task stage by ID
  • Listing task stages for a given run
  • Overriding a task stage

Testing

• Added unit tests for TaskStages resource:
  - Verified service availability on the client
  - Verified method presence (read, list, override)
  - Tested validation for invalid inputs (e.g., missing or invalid IDs)
  - Mocked HTTP transport layer to validate request construction and payloads
  - Verified override behavior with and without optional comment
• Ensured:
  - All unit tests pass successfully (pytest)
  - Code formatting and linting checks pass (ruff, mypy)
• Manually tested functionality using a real Task Stage ID:
  - Successfully retrieved task stage details via read()
  - Verified response fields and structure match expected API output

Output

Run the unit test

Run the examples

[isivaselvan]

Could you update the correct model for run, instead of dict

[TanyaSingh369-svg]

Updated run to use the proper Run model instead of dict.

[isivaselvan]

all the relationship were mapped as dict instead w.r.t models (Run, task_result, policy_evaluions)

[TanyaSingh369-svg]

Updated the relationship parsing and aligned it with the API relationship response structure.