Data Models¶

Pydantic models for task data validation and serialization.

TaskInputDTO¶

Used for creating and modifying tasks.

`TaskInputDTO` ¶

Bases: BaseModel

Data Transfer Object for creating and updating tasks.

This model is used when adding new tasks or modifying existing ones. All fields are optional, excepted description when creating a task (optional when updating a task).

Attributes:

Name	Type	Description
`description`	`str \| None`	Task description.
`priority`	`Priority \| None`	Task priority level (H, M, L, or None).
`due`	`str \| None`	Due date/time. Accepts ISO format or TaskWarrior expressions like "tomorrow", "friday", "eom" (end of month).
`project`	`str \| None`	Project name. Supports hierarchical projects like "work.reports".
`tags`	`list[str]`	List of tags to assign to the task.
`depends`	`UUIDList`	List of UUIDs of tasks this task depends on.
`parent`	`UUID \| None`	UUID of the parent recurring task template.
`recur`	`RecurrencePeriod \| str \| None`	Recurrence period for recurring tasks.
`scheduled`	`str \| None`	Earliest date/time the task can be started.
`wait`	`str \| None`	Date until which the task is hidden from pending list.
`until`	`str \| None`	Expiration date for recurring task instances.
`annotations`	`list[str]`	List of annotation strings to add to the task.
`udas`	`AnyDict`	Dictionary of User Defined Attribute values (e.g., {"severity": "high"}).

Example

Create a simple task::

task = TaskInputDTO(description="Buy milk")

Create a task with full details::

task = TaskInputDTO(
    description="Finish project report",
    priority=Priority.HIGH,
    project="work.reports",
    tags=["urgent", "q1"],
    due="friday",
    scheduled="tomorrow",
)

Create a task with UDAs::

task = TaskInputDTO(
    description="Fix critical bug",
    udas={"severity": "critical", "estimate": 2.5}
)

`description_must_not_be_empty(v)` `classmethod` ¶

Validate that task description is not empty.

Parameters:

Name	Type	Description	Default
`v`	`str \| None`	The description value to validate.	required

Returns:

Type	Description
`str \| None`	The stripped description string.

Raises:

Type	Description
`TaskValidationError`	If the description is empty or whitespace-only.

TaskOutputDTO¶

Returned when retrieving tasks from TaskWarrior.

`TaskOutputDTO` ¶

Bases: BaseModel

Data Transfer Object for task retrieval results.

This model represents a task as returned by TaskWarrior. It includes all input fields plus read-only fields set by TaskWarrior.

Attributes:

Name	Type	Description
`description`	`str`	Task description.
`index`	`int`	Task ID number in the working set (alias: "id").
`uuid`	`UUID`	Unique identifier for the task.
`status`	`TaskStatus`	Current task status (pending, completed, deleted, etc.).
`priority`	`Priority \| None`	Task priority level.
`due`	`datetime \| None`	Due date/time as datetime object.
`entry`	`datetime \| None`	Task creation timestamp (read-only).
`start`	`datetime \| None`	Timestamp when task was started (read-only).
`end`	`datetime \| None`	Timestamp when task was completed (read-only).
`modified`	`datetime \| None`	Last modification timestamp (read-only).
`tags`	`list[str]`	List of tags assigned to the task.
`project`	`str \| None`	Project the task belongs to.
`depends`	`UUIDList`	List of UUIDs of dependency tasks.
`parent`	`UUID \| None`	UUID of parent recurring task template.
`recur`	`RecurrencePeriod \| None`	Recurrence period if recurring.
`scheduled`	`datetime \| None`	Scheduled start date/time.
`wait`	`datetime \| None`	Date until which task is hidden.
`until`	`datetime \| None`	Expiration date for recurring instances.
`urgency`	`float \| None`	Calculated urgency score (read-only).
`annotations`	`AnnotationList`	List of annotation objects with timestamps.
`udas`	`AnyDict`	Dictionary of User Defined Attribute values.
`imask`	`str \| int \| None`	Mask for recurring tasks or instance number.
`rtype`	`str \| None`	Type of recurring task.

Example

Retrieve and inspect a task::

task = tw.get_task(uuid)
print(f"Task #{task.index}: {task.description}")
print(f"Status: {task.status}")
print(f"Urgency: {task.urgency}")

Access UDA values::

severity = task.get_uda("severity")
estimate = task.get_uda("estimate", default=0)

`extract_udas_from_extra_fields(data)` `classmethod` ¶

Extract unknown fields from TaskWarrior JSON into the udas dict.

TaskWarrior returns UDA values as top-level fields in the JSON. This validator captures any field not defined in the model and moves it to the 'udas' dictionary.

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	The raw input data dictionary.	required

Returns:

Type	Description
`dict[str, Any]`	The data dictionary with extra fields moved to 'udas'.

`parse_datetime_field(value)` `classmethod` ¶

Parse datetime fields from TaskWarrior format.

Handles both TaskWarrior's compact format (20260101T193139Z) and standard ISO format.

Parameters:

Name	Type	Description	Default
`value`	`str \| datetime \| None`	The datetime value to parse, either as string or datetime.	required

Returns:

Type	Description
`datetime \| None`	A datetime object with timezone info, or None if value is None.

`get_uda(name, default=None)` ¶

Get a User Defined Attribute value by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the UDA to retrieve.	required
`default`	`Any`	Value to return if the UDA is not set. Defaults to None.	`None`

Returns:

Type	Description
`Any`	The UDA value if set, otherwise the default value.

Example

task = tw.get_task(uuid) severity = task.get_uda("severity") estimate = task.get_uda("estimate", default=0)

AnnotationDTO¶

Represents a task annotation.

`AnnotationDTO` ¶

Bases: BaseModel

Data Transfer Object for task annotations.

Annotations are timestamped notes attached to tasks. Each annotation records when it was added and its content.

Attributes:

Name	Type	Description
`entry`	`datetime`	Timestamp when the annotation was created.
`description`	`str`	The annotation text content.

Example

Annotations are typically retrieved as part of a task::

task = tw.get_task(uuid)
for annotation in task.annotations:
    print(f"{annotation.entry}: {annotation.description}")

`parse_entry_date(value)` `classmethod` ¶

Parse the entry date from TaskWarrior format.

Parameters:

Name	Type	Description	Default
`value`	`str \| datetime`	The date value, either as string or datetime.	required

Returns:

Type	Description
`datetime`	A datetime object with timezone info.

ContextDTO¶

Represents a TaskWarrior context.

`ContextDTO` ¶

Bases: BaseModel

Data Transfer Object for task contexts.

Contexts allow you to define named filters that can be applied globally. When a context is active, all task queries are automatically filtered by the context's read_filter, and new tasks inherit the write_filter constraints.

Attributes:

Name	Type	Description
`name`	`str`	The unique name of the context.
`read_filter`	`str`	TaskWarrior filter applied when reading/listing tasks.
`write_filter`	`str`	TaskWarrior filter applied when creating/modifying tasks.
`active`	`bool`	Whether this context is currently active.

Example

List and inspect contexts::

contexts = tw.get_contexts()
for ctx in contexts:
    print(f"{ctx.name}: read={ctx.read_filter} write={ctx.write_filter}")

UdaConfig¶

Represents a User Defined Attribute.

`UdaConfig` ¶

Bases: BaseModel

Data Transfer Object for User Defined Attributes (UDAs).

UDAs extend TaskWarrior with custom fields. Each UDA has a name, uda_type, and optional configuration like allowed values or defaults.

Attributes:

Name	Type	Description
`name`	`str`	Unique name for the UDA (used as the field name).
`uda_type`	`UdaType`	Data type of the UDA value.
`label`	`str \| None`	Human-readable label for display in reports.
`values`	`list[str] \| None`	List of allowed values (for string type with enumeration).
`default`	`str \| None`	Default value when not specified.
`coefficient`	`float \| None`	Urgency coefficient. Positive values increase urgency, negative values decrease it.

Example

Define a severity UDA with allowed values::

uda = UdaConfig(
    name="severity",
    uda_type=UdaType.STRING,
    label="Severity",
    values=["low", "medium", "high", "critical"],
    default="medium",
    coefficient=1.5
)
tw.uda_service.define_uda(uda)

Data Models¶

TaskInputDTO¶

TaskInputDTO ¶

description_must_not_be_empty(v) classmethod ¶

TaskOutputDTO¶

TaskOutputDTO ¶

extract_udas_from_extra_fields(data) classmethod ¶

parse_datetime_field(value) classmethod ¶

get_uda(name, default=None) ¶

AnnotationDTO¶

AnnotationDTO ¶

parse_entry_date(value) classmethod ¶

ContextDTO¶

ContextDTO ¶

UdaConfig¶

UdaConfig ¶

`TaskInputDTO` ¶

`description_must_not_be_empty(v)` `classmethod` ¶

`TaskOutputDTO` ¶

`extract_udas_from_extra_fields(data)` `classmethod` ¶

`parse_datetime_field(value)` `classmethod` ¶

`get_uda(name, default=None)` ¶

`AnnotationDTO` ¶

`parse_entry_date(value)` `classmethod` ¶

`ContextDTO` ¶

`UdaConfig` ¶