targetprocess-py 0.1.0__py3-none-any.whl

targetprocess/_base.py

@@ -0,0 +1,318 @@
+"""Base entity classes, mirroring TargetProcess's own type hierarchy.
+
+TP's ``/meta`` declares a real inheritance chain: most domain types derive from
+``General``, and the work-item types derive from ``Assignable``, which itself
+derives from ``General``. :class:`GeneralEntity` and :class:`AssignableEntity`
+model those two bases, so every field TP defines once is declared once here
+rather than repeated on each concrete type.
+
+:class:`Entity` and :class:`NamedEntity` sit above them and carry no TP
+counterpart - they hold the identity fields every payload shares and the
+``Name`` split, so the types TP exposes outside the ``General`` chain (the
+lookup and join types) have a base too.
+
+The concrete entity models live in the sibling private modules and are
+re-exported by :mod:`targetprocess.models`, which stays the import surface
+callers use.
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from targetprocess._dates import TPDateTime
+from targetprocess._nested import (
+    AssignedUsers,
+    CustomFieldValue,
+    EntityRef,
+    EntityTypeRef,
+    RefWithImportance,
+    UserRef,
+)
+
+
+class Entity(BaseModel):
+    """Base class for all TargetProcess entities.
+
+    Provides the fields common to every TP entity. Entity types that carry no
+    ``Name`` field (``User``, ``Comment``, ``Assignment``, ``TeamAssignment``,
+    ``RoleEffort``, ``Relation``, ``Time``) extend this base directly; types
+    with a display name extend :class:`NamedEntity`, and the ``General`` /
+    ``Assignable`` families extend the two bases below that. Pydantic aliases
+    handle the API's PascalCase format automatically.
+
+    ``CreateDate`` and ``ModifyDate`` are declared here because most types
+    carry them, but TP exposes neither on every type - on a type whose
+    ``/meta`` omits them (the lookup and join types, largely) they simply stay
+    ``None``.
+
+    Undeclared API fields are never silently discarded: ``extra="allow"``
+    preserves them in ``model_extra`` under their wire (PascalCase) names,
+    reachable via attribute access and included by ``model_dump``. TP payload
+    shapes vary by instance and version, so undeclared keys are tolerated
+    rather than rejected - but kept, not dropped. Assigning an undeclared
+    attribute (a mistyped name included) likewise lands in ``model_extra``.
+
+    Attributes:
+        id: Unique identifier for the entity
+        resource_type: Type of the entity (e.g., "UserStory", "Bug", "User")
+        create_date: When the entity was created (optional)
+        modify_date: When the entity was last modified (optional)
+        custom_fields: Custom-field values embedded in the entity's
+            ``CustomFields`` array (present when fetched via ``include=``)
+    """
+
+    model_config = ConfigDict(
+        populate_by_name=True,  # Allow both alias and field name
+        str_strip_whitespace=True,  # Strip whitespace from strings
+        validate_assignment=True,  # Validate on assignment
+        extra="allow",  # Preserve undeclared API fields in model_extra
+    )
+
+    id: int = Field(alias="Id", description="Unique identifier")
+    resource_type: str | None = Field(default=None, alias="ResourceType", description="Entity type")
+    create_date: TPDateTime | None = Field(
+        default=None, alias="CreateDate", description="Creation timestamp"
+    )
+    modify_date: TPDateTime | None = Field(
+        default=None, alias="ModifyDate", description="Modification timestamp"
+    )
+    custom_fields: list[CustomFieldValue] | None = Field(
+        default=None, alias="CustomFields", description="Custom-field values"
+    )
+
+    # Property accessors for PascalCase access
+    @property
+    def Id(self) -> int:
+        """Access id field via PascalCase (API format)."""
+        return self.id
+
+    @property
+    def ResourceType(self) -> str | None:
+        """Access resource_type field via PascalCase (API format)."""
+        return self.resource_type
+
+    @property
+    def CreateDate(self) -> datetime | None:
+        """Access create_date field via PascalCase (API format)."""
+        return self.create_date
+
+    @property
+    def ModifyDate(self) -> datetime | None:
+        """Access modify_date field via PascalCase (API format)."""
+        return self.modify_date
+
+    @property
+    def CustomFields(self) -> list[CustomFieldValue] | None:
+        """Access custom_fields field via PascalCase (API format)."""
+        return self.custom_fields
+
+
+class NamedEntity(Entity):
+    """Base class for TP entities that carry a display Name.
+
+    The common shape - most domain entities have a ``Name``. Which types do
+    not, and why, is stated once on :class:`Entity`.
+
+    Attributes:
+        name: Display name of the entity
+    """
+
+    name: str | None = Field(default=None, alias="Name", description="Display name")
+
+    @property
+    def Name(self) -> str | None:
+        """Access name field via PascalCase (API format)."""
+        return self.name
+
+
+class GeneralEntity(NamedEntity):
+    """TP's ``General`` base - the shape shared by every domain entity.
+
+    ``Project``, ``Team``, ``Release``, ``Iteration``, ``TeamIteration`` and
+    ``TestCase`` derive from this directly; the work-item types reach it
+    through :class:`AssignableEntity`.
+
+    The four ``GeneralUser``-shaped references (``Owner``, ``Creator``,
+    ``LastEditor``, ``LastCommentedUser``) arrive as :class:`UserRef` - TP
+    sends them with ``FirstName``/``LastName``/``Login``/``FullName`` and no
+    ``Name`` key. ``Owner`` records who *created* the entity, not who is
+    working it: for a work item that is the ``Assignment`` collection (see
+    ``client.assignments``).
+
+    Attributes:
+        description: Detailed description
+        start_date: Start date/time
+        end_date: End date/time
+        last_comment_date: When the entity was last commented on
+        tags: Comma-separated tag string (TP stores tags as one string)
+        numeric_priority: TP's global ordering rank (a float, not a Priority)
+        entity_version: Per-record version counter (increments on every edit)
+        is_now: Whether the entity sits in the current time window
+        is_next: Whether the entity sits in the next time window
+        is_previous: Whether the entity sits in the previous time window
+        entity_type: The TP entity type this record is an instance of
+        owner: Who created the entity (TP deprecates this in favour of creator)
+        creator: Who created the entity
+        last_editor: Who last modified the entity
+        last_commented_user: Who last commented on the entity
+        project: Project reference
+        linked_test_plan: Linked test plan reference
+        milestone: Milestone reference
+    """
+
+    # Content
+    description: str | None = Field(
+        default=None, alias="Description", description="Detailed description"
+    )
+    tags: str | None = Field(default=None, alias="Tags", description="Comma-separated tags")
+
+    # Date tracking
+    start_date: TPDateTime | None = Field(
+        default=None, alias="StartDate", description="Start date/time"
+    )
+    end_date: TPDateTime | None = Field(default=None, alias="EndDate", description="End date/time")
+    last_comment_date: TPDateTime | None = Field(
+        default=None, alias="LastCommentDate", description="Last comment date/time"
+    )
+
+    # Ordering / versioning
+    numeric_priority: float | None = Field(
+        default=None, alias="NumericPriority", description="Global ordering rank"
+    )
+    entity_version: int | None = Field(
+        default=None, alias="EntityVersion", description="Per-record version counter"
+    )
+
+    # Time-window flags
+    is_now: bool | None = Field(default=None, alias="IsNow", description="In the current window")
+    is_next: bool | None = Field(default=None, alias="IsNext", description="In the next window")
+    is_previous: bool | None = Field(
+        default=None, alias="IsPrevious", description="In the previous window"
+    )
+
+    # Relationships
+    entity_type: EntityTypeRef | None = Field(
+        default=None, alias="EntityType", description="TP entity type"
+    )
+    owner: UserRef | None = Field(default=None, alias="Owner", description="Creator (deprecated)")
+    creator: UserRef | None = Field(default=None, alias="Creator", description="Creator")
+    last_editor: UserRef | None = Field(
+        default=None, alias="LastEditor", description="Last modifier"
+    )
+    last_commented_user: UserRef | None = Field(
+        default=None, alias="LastCommentedUser", description="Last commenter"
+    )
+    project: EntityRef | None = Field(default=None, alias="Project", description="Project")
+    linked_test_plan: EntityRef | None = Field(
+        default=None, alias="LinkedTestPlan", description="Linked test plan"
+    )
+    milestone: EntityRef | None = Field(default=None, alias="Milestone", description="Milestone")
+
+
+class AssignableEntity(GeneralEntity):
+    """TP's ``Assignable`` base - the work-item shape.
+
+    ``UserStory``, ``Bug``, ``Task``, ``Feature``, ``Epic`` and ``Request``
+    derive from this. It adds the effort/time surface, the planning
+    references, and the workflow state that make a record schedulable.
+
+    Two fields read as a priority and are not interchangeable: ``priority`` is
+    the entity-type-scoped ``Priority`` record (arriving with an
+    ``Importance``), while ``numeric_priority`` on :class:`GeneralEntity` is
+    TP's continuous backlog-ordering rank.
+
+    ``team`` is deprecated upstream - TP's ``/meta`` marks it so, and
+    ``responsible_team`` (a ``TeamAssignment`` reference) is the current
+    surface - but it is still populated and still declared here.
+
+    The numeric fields carry no range constraint. TP computes most of them and
+    documents no bounds, and a constraint on a server-supplied value fails the
+    **whole entity**, not the field: one out-of-range roll-up would abort a
+    whole ``list()`` page with a ``ParseError``. A read model that faithfully
+    reports what TP sent is worth more than one that asserts an invariant the
+    API never promised. Write-side range checks belong where the value
+    originates - see ``times.upsert``, which validates before sending.
+
+    Attributes:
+        effort: Total effort estimate
+        effort_completed: Completed effort
+        effort_todo: Remaining effort
+        progress: Completion ratio TP derives from effort (0.0 - 1.0)
+        time_spent: Hours logged against the item
+        time_remain: Hours still expected
+        units: The unit effort is expressed in (e.g. "h", "pt")
+        lead_time: Days from creation to completion
+        cycle_time: Days from work starting to completion
+        last_state_change_date: When the entity state last changed
+        planned_start_date: Planned start (shadows the assigned iteration)
+        planned_end_date: Planned end (shadows the assigned iteration)
+        forecast_end_date: TP's projected completion date
+        entity_state: Current workflow state reference
+        priority: Priority reference, scoped to this entity type
+        release: Release reference
+        iteration: Iteration reference
+        team_iteration: TeamIteration (team sprint) reference
+        team: Team reference (deprecated upstream)
+        responsible_team: TeamAssignment reference
+        assigned_user: Assigned users
+    """
+
+    # Effort / time tracking
+    effort: float | None = Field(default=None, alias="Effort", description="Total effort")
+    effort_completed: float | None = Field(
+        default=None, alias="EffortCompleted", description="Completed effort"
+    )
+    effort_todo: float | None = Field(
+        default=None, alias="EffortToDo", description="Remaining effort"
+    )
+    time_spent: float | None = Field(default=None, alias="TimeSpent", description="Time spent")
+    time_remain: float | None = Field(
+        default=None, alias="TimeRemain", description="Time remaining"
+    )
+    progress: float | None = Field(default=None, alias="Progress", description="Completion ratio")
+    units: str | None = Field(default=None, alias="Units", description="Effort unit")
+
+    # Flow metrics
+    lead_time: float | None = Field(default=None, alias="LeadTime", description="Lead time (days)")
+    cycle_time: float | None = Field(
+        default=None, alias="CycleTime", description="Cycle time (days)"
+    )
+
+    # Date tracking
+    last_state_change_date: TPDateTime | None = Field(
+        default=None, alias="LastStateChangeDate", description="Last state change"
+    )
+    planned_start_date: TPDateTime | None = Field(
+        default=None, alias="PlannedStartDate", description="Planned start"
+    )
+    planned_end_date: TPDateTime | None = Field(
+        default=None, alias="PlannedEndDate", description="Planned end"
+    )
+    forecast_end_date: TPDateTime | None = Field(
+        default=None, alias="ForecastEndDate", description="Forecast end"
+    )
+
+    # Relationships
+    entity_state: EntityRef | None = Field(
+        default=None, alias="EntityState", description="Workflow state"
+    )
+    priority: RefWithImportance | None = Field(
+        default=None, alias="Priority", description="Priority"
+    )
+    release: EntityRef | None = Field(default=None, alias="Release", description="Release")
+    iteration: EntityRef | None = Field(default=None, alias="Iteration", description="Iteration")
+    team_iteration: EntityRef | None = Field(
+        default=None, alias="TeamIteration", description="Team iteration"
+    )
+    team: EntityRef | None = Field(
+        default=None, alias="Team", description="Team (deprecated upstream)"
+    )
+    responsible_team: EntityRef | None = Field(
+        default=None, alias="ResponsibleTeam", description="Responsible team assignment"
+    )
+
+    # Collections
+    assigned_user: AssignedUsers | None = Field(
+        default=None, alias="AssignedUser", description="Assigned users"
+    )

targetprocess/_content.py

@@ -0,0 +1,287 @@
+"""The types that carry content attached to another entity.
+
+A ``Comment`` and an ``Attachment`` both hang off a ``General``; a
+``CustomField`` describes a field configured on a process rather than a value
+held by an entity. None sits in TP's ``General`` hierarchy.
+
+Re-exported by :mod:`targetprocess.models`, which stays the import surface
+callers use.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from targetprocess._base import Entity, NamedEntity
+from targetprocess._dates import TPDateTime
+from targetprocess._nested import CustomFieldConfig, EntityRef, EntityTypeRef, UserRef
+
+
+class Comment(Entity):
+    """Comment on a TP entity.
+
+    TP comments carry the comment body in ``Description`` and have no Name
+    field. ``General`` is the entity the comment is attached to; ``Owner`` is
+    the commenter. Threaded replies carry a ``ParentId``.
+
+    Attributes:
+        description: Comment body text
+        parent_id: Parent comment id for threaded replies (None at top level)
+        description_modify_date: When the comment body was last edited
+        is_private: Whether the comment is private
+        is_pinned: Whether the comment is pinned
+        general: The entity the comment is attached to
+        owner: The commenter
+        entity_version: TP's per-record version counter (increments on edit)
+    """
+
+    description: str | None = Field(
+        default=None, alias="Description", description="Comment body text"
+    )
+    parent_id: int | None = Field(
+        default=None, alias="ParentId", description="Parent comment id (threaded replies)"
+    )
+    description_modify_date: TPDateTime | None = Field(
+        default=None, alias="DescriptionModifyDate", description="When the body was last edited"
+    )
+    is_private: bool | None = Field(
+        default=None, alias="IsPrivate", description="Whether the comment is private"
+    )
+    is_pinned: bool | None = Field(
+        default=None, alias="IsPinned", description="Whether the comment is pinned"
+    )
+    general: EntityRef | None = Field(
+        default=None, alias="General", description="Attached-to entity"
+    )
+    owner: UserRef | None = Field(default=None, alias="Owner", description="Commenter")
+    entity_version: int | None = Field(
+        default=None, alias="EntityVersion", description="Per-record version counter"
+    )
+
+
+class Attachment(NamedEntity):
+    """File attachment on a TP entity.
+
+    ``Name`` is the display filename; ``UniqueFileName`` is TP's stored name.
+    ``General`` is the entity the file is attached to; ``Owner`` is the
+    uploader. ``Uri`` is the download path for the file's bytes (relative to
+    the instance root, e.g. ``/Attachment.aspx?AttachmentID=1234``) - fetch it
+    via ``client.attachments.download``.
+
+    Attributes:
+        unique_file_name: TP's stored unique filename
+        description: Attachment description
+        date: Upload date/time
+        owner: The uploader
+        general: The entity the file is attached to
+        message: Optional attachment message
+        uri: Download path for the file bytes, relative to the instance root
+        mime_type: MIME type of the stored file
+        size: File size in bytes
+        thumbnail_uri: Download path for the thumbnail (images only)
+    """
+
+    unique_file_name: str | None = Field(
+        default=None, alias="UniqueFileName", description="Stored unique filename"
+    )
+    description: str | None = Field(
+        default=None, alias="Description", description="Attachment description"
+    )
+    date: TPDateTime | None = Field(default=None, alias="Date", description="Upload date/time")
+    owner: UserRef | None = Field(default=None, alias="Owner", description="Uploader")
+    general: EntityRef | None = Field(
+        default=None, alias="General", description="Attached-to entity"
+    )
+    message: EntityRef | None = Field(
+        default=None, alias="Message", description="Attachment message"
+    )
+    uri: str | None = Field(
+        default=None, alias="Uri", description="Download path for the file bytes"
+    )
+    mime_type: str | None = Field(default=None, alias="MimeType", description="MIME type")
+    size: int | None = Field(default=None, alias="Size", ge=0, description="File size in bytes")
+    thumbnail_uri: str | None = Field(
+        default=None, alias="ThumbnailUri", description="Thumbnail download path"
+    )
+
+
+class UploadedFileRef(BaseModel):
+    """A reference nested in an ``/UploadFile.ashx`` response.
+
+    The same three roles :class:`Attachment` names - the uploader, the entity
+    the file landed on, and that entity as an Assignable - but projected by
+    the file endpoint rather than the JSON entity API, so the keys are
+    camelCase and the user shape carries its name fields inline. One
+    permissive model covers all of them: a user reference brings the name
+    fields, an entity reference brings ``name``, and ``extra="allow"`` keeps
+    anything else the endpoint sends.
+
+    Not in ``_nested`` with the other reference shapes on purpose: those
+    project TP's JSON entity API, and this one does not (see
+    :class:`UploadedAttachment`).
+
+    Attributes:
+        resource_type: Type of the referenced record
+        id: Id of the referenced record
+        name: Display name, on an entity reference
+        first_name: Given name, on a user reference
+        last_name: Family name, on a user reference
+        full_name: Display name, on a user reference
+        login: Login, on a user reference
+    """
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        str_strip_whitespace=True,
+        validate_assignment=True,
+        extra="allow",
+    )
+
+    resource_type: str | None = Field(
+        default=None, alias="resourceType", description="Referenced record's type"
+    )
+    id: int | None = Field(default=None, alias="id", description="Referenced record's Id")
+    name: str | None = Field(default=None, alias="name", description="Display name")
+    first_name: str | None = Field(default=None, alias="firstName", description="Given name")
+    last_name: str | None = Field(default=None, alias="lastName", description="Family name")
+    full_name: str | None = Field(default=None, alias="fullName", description="Display name")
+    login: str | None = Field(default=None, alias="login", description="Login")
+
+
+class UploadedAttachment(BaseModel):
+    """The attachment record ``/UploadFile.ashx`` answers an upload with.
+
+    TargetProcess documents neither this endpoint's response body nor its
+    casing. What it actually sends - recorded in the write-path integration
+    suite rather than taken on trust - is
+    ``{"items": [<this shape>]}``: the created Attachment, hydrated much as
+    ``/api/v1/Attachments`` would hydrate it, but in **camelCase** and with
+    two extra fields the entity API does not carry (``persistedMimeType``,
+    ``persistedSize``) alongside their entity-API equivalents. ``date`` is
+    ISO-8601 rather than TP's ``/Date(ms±HHMM)/`` wire format, which
+    :data:`TPDateTime` passes through to pydantic unchanged.
+
+    Deliberately outside ``scripts/check_model_coverage.py``'s ``COLLECTIONS``
+    map: this is one endpoint's response projection, not a queryable entity
+    type, so there is no ``/meta`` to diff it against. The recorded cassette
+    is what pins the shape.
+
+    Attributes:
+        resource_type: Always ``"Attachment"``
+        id: Id of the created attachment record
+        name: Display filename, as sent
+        unique_file_name: TP's stored unique filename
+        description: Attachment description (the filename, by default)
+        date: Upload timestamp
+        persisted_mime_type: MIME type of the stored file
+        persisted_size: Stored size in bytes
+        is_empty: Whether the stored file has no content
+        uri: Absolute download URL for the file bytes
+        thumbnail_uri: Absolute download URL for the thumbnail
+        mime_type: MIME type of the stored file
+        size: File size in bytes
+        owner: The uploader
+        general: The entity the file was attached to
+        message: The message the file was attached to, if any
+        assignable: The attached-to entity as an Assignable, if it is one
+    """
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        str_strip_whitespace=True,
+        validate_assignment=True,
+        extra="allow",
+    )
+
+    resource_type: str | None = Field(default=None, alias="resourceType", description="Record type")
+    id: int = Field(alias="id", description="Created attachment's Id")
+    name: str | None = Field(default=None, alias="name", description="Display filename")
+    unique_file_name: str | None = Field(
+        default=None, alias="uniqueFileName", description="Stored unique filename"
+    )
+    description: str | None = Field(
+        default=None, alias="description", description="Attachment description"
+    )
+    date: TPDateTime | None = Field(default=None, alias="date", description="Upload timestamp")
+    persisted_mime_type: str | None = Field(
+        default=None, alias="persistedMimeType", description="Stored MIME type"
+    )
+    persisted_size: int | None = Field(
+        default=None, alias="persistedSize", ge=0, description="Stored size in bytes"
+    )
+    is_empty: bool | None = Field(
+        default=None, alias="isEmpty", description="Whether the stored file is empty"
+    )
+    uri: str | None = Field(default=None, alias="uri", description="Absolute download URL")
+    thumbnail_uri: str | None = Field(
+        default=None, alias="thumbnailUri", description="Absolute thumbnail URL"
+    )
+    mime_type: str | None = Field(default=None, alias="mimeType", description="MIME type")
+    size: int | None = Field(default=None, alias="size", ge=0, description="File size in bytes")
+    owner: UploadedFileRef | None = Field(default=None, alias="owner", description="Uploader")
+    general: UploadedFileRef | None = Field(
+        default=None, alias="general", description="Attached-to entity"
+    )
+    message: UploadedFileRef | None = Field(
+        default=None, alias="message", description="Attached-to message"
+    )
+    assignable: UploadedFileRef | None = Field(
+        default=None, alias="assignable", description="Attached-to entity as an Assignable"
+    )
+
+
+class CustomField(NamedEntity):
+    """Custom-field definition (the queryable ``/CustomFields`` entity).
+
+    Describes a custom field configured on a Process/EntityType - its type,
+    constraints, and metadata. Actual per-entity values are carried by
+    ``CustomFieldValue`` (embedded in each entity's ``CustomFields`` array),
+    not here.
+
+    Attributes:
+        value: Field value from the definition endpoint (typically a string or
+            None; typed ``object`` to carry any value the endpoint returns)
+        field_type: Field type (e.g. "DropDown", "Text", "Date", "Number")
+        enabled_for_filter: Whether the field is enabled for filtering
+        required: Whether the field is required
+        numeric_priority: Ordering priority
+        is_system: Whether this is a system field
+        description: Field description
+        placeholder: Field placeholder text
+        max_text_length: Maximum text length
+        entity_field_name: Underlying entity field name, where the custom field
+            shadows a built-in one
+        config: Type-specific configuration (default value, units, formatting)
+        entity_type: EntityType the field applies to
+        process: Process the field belongs to
+    """
+
+    value: object = Field(default=None, alias="Value", description="Field value (polymorphic)")
+    field_type: str | None = Field(default=None, alias="FieldType", description="Field type")
+    enabled_for_filter: bool | None = Field(
+        default=None, alias="EnabledForFilter", description="Enabled for filtering"
+    )
+    required: bool | None = Field(default=None, alias="Required", description="Whether required")
+    numeric_priority: float | None = Field(
+        default=None, alias="NumericPriority", description="Ordering priority"
+    )
+    is_system: bool | None = Field(
+        default=None, alias="IsSystem", description="Whether a system field"
+    )
+    description: str | None = Field(
+        default=None, alias="Description", description="Field description"
+    )
+    placeholder: str | None = Field(
+        default=None, alias="Placeholder", description="Placeholder text"
+    )
+    max_text_length: int | None = Field(
+        default=None, alias="MaxTextLength", description="Maximum text length"
+    )
+    entity_field_name: str | None = Field(
+        default=None, alias="EntityFieldName", description="Shadowed entity field name"
+    )
+    config: CustomFieldConfig | None = Field(
+        default=None, alias="Config", description="Type-specific configuration"
+    )
+    entity_type: EntityTypeRef | None = Field(
+        default=None, alias="EntityType", description="Applicable entity type"
+    )
+    process: EntityRef | None = Field(default=None, alias="Process", description="Owning process")

targetprocess/_dates.py

@@ -0,0 +1,70 @@
+"""TP ``/Date(ms±HHMM)/`` wire-format date handling.
+
+The public names here (``TPDateTime``, ``parse_tp_date``, ``format_tp_date``)
+are re-exported by :mod:`targetprocess.models`, which remains the import
+surface callers use.
+"""
+
+import re
+from datetime import UTC, datetime, timedelta, timezone
+from typing import Annotated
+
+from pydantic import BeforeValidator
+
+_TP_DATE_RE = re.compile(r"^/Date\((-?\d+)(?:([+-])(\d{2})(\d{2}))?\)/$")
+
+
+def parse_tp_date(value: object) -> object:
+    """Convert TP's ``/Date(ms±HHMM)/`` wire format to datetime.
+
+    Non-matching values (datetime, ISO strings, None) pass through for
+    pydantic's own datetime handling.
+    """
+    if isinstance(value, str):
+        m = _TP_DATE_RE.match(value)
+        if m:
+            ms = int(m.group(1))
+            if m.group(2):
+                sign = 1 if m.group(2) == "+" else -1
+                tz = timezone(sign * timedelta(hours=int(m.group(3)), minutes=int(m.group(4))))
+            else:
+                tz = UTC
+            return datetime.fromtimestamp(ms / 1000, tz=tz)
+    return value
+
+
+TPDateTime = Annotated[datetime, BeforeValidator(parse_tp_date)]
+
+_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
+
+
+def format_tp_date(value: datetime) -> str:
+    """Encode a timezone-aware datetime as TP's ``/Date(ms±HHMM)/`` wire format.
+
+    The inverse of :func:`parse_tp_date`. The offset written is the one the
+    datetime carries, so the caller decides which offset TP records.
+
+    Args:
+        value: Timezone-aware datetime to encode.
+
+    Returns:
+        The TP wire representation, e.g. ``/Date(1718366400000+0200)/``.
+
+    Raises:
+        ValueError: ``value`` is naive, so no offset can be written.
+        ValueError: ``value``'s offset is not a whole number of minutes, so
+            it cannot be represented in TP's ``±HHMM`` wire format.
+    """
+    offset = value.utcoffset()
+    if offset is None:
+        raise ValueError("format_tp_date requires a timezone-aware datetime")
+    if offset.total_seconds() % 60 != 0:
+        raise ValueError(f"format_tp_date requires a whole-minute UTC offset, got {offset}")
+    # Floor-divide two timedeltas rather than scaling ``timestamp()``: that
+    # returns a float, and int() truncates toward zero, which is wrong for
+    # pre-epoch instants.
+    milliseconds = (value - _EPOCH) // timedelta(milliseconds=1)
+    total_minutes = int(offset.total_seconds() // 60)
+    sign = "+" if total_minutes >= 0 else "-"
+    hours, minutes = divmod(abs(total_minutes), 60)
+    return f"/Date({milliseconds}{sign}{hours:02d}{minutes:02d})/"