targetprocess-py 0.1.0__py3-none-any.whl

targetprocess/_entity_types.py

@@ -0,0 +1,33 @@
+"""Entity type name validation, shared by every layer that interpolates one."""
+
+import re
+
+_ENTITY_TYPE_RE = re.compile(r"[A-Za-z][A-Za-z0-9_]*")
+
+
+def require_entity_type(entity_type: str) -> None:
+    """Refuse an entity type name that is not a plain TP identifier.
+
+    An entity type name is interpolated straight into a request path (and,
+    in ``priorities.for_entity_type``, into a ``where=`` filter). On the
+    generic ``entities`` resource it is caller-supplied at runtime - often
+    echoing a server-returned ``ResourceType`` - so anything beyond a bare
+    identifier changes what the request does: ``"UserStories/57731"`` turns
+    a create into an update of that entity, and a trailing slash or stray
+    whitespace slips past a name-keyed guard. TP collection names are plain
+    identifiers, so that is all that is accepted - the same stance as
+    ``RequestHandler._require_instance_path``: enforced, not merely
+    documented.
+
+    Args:
+        entity_type: The entity type name to check
+
+    Raises:
+        ValueError: ``entity_type`` is not letters, digits and underscores
+            starting with a letter.
+    """
+    if not _ENTITY_TYPE_RE.fullmatch(entity_type):
+        raise ValueError(
+            "entity_type must be a TP entity type name (letters, digits, "
+            f"underscore): {entity_type!r}"
+        )

targetprocess/_generals.py

@@ -0,0 +1,324 @@
+"""The ``General`` types that are not work items.
+
+``Project``, ``Team``, ``Release``, ``Iteration``, ``TeamIteration`` and
+``TestCase`` derive from TP's ``General`` base but not from ``Assignable``, so
+they inherit :class:`targetprocess._base.GeneralEntity` and declare their own
+effort and planning fields rather than the assignable set.
+
+Several carry ``Effort``/``EffortCompleted``/``EffortToDo``/``Progress``/
+``Units`` as roll-ups of the work items inside them, identically. They are
+repeated per class rather than hoisted into a shared mixin because TP declares
+no such base: the grouping would be this library's invention, and the next type
+to gain or lose one of the five would have to be pulled back out of it. The
+repetition is the cost of each class listing exactly what its own ``/meta``
+declares, which is the property ``scripts/check_model_coverage.py`` checks.
+
+Re-exported by :mod:`targetprocess.models`, which stays the import surface
+callers use.
+"""
+
+from pydantic import Field
+
+from targetprocess._base import GeneralEntity
+from targetprocess._dates import TPDateTime
+from targetprocess._nested import AssignedUsers, EntityRef, RefWithImportance
+
+
+class Project(GeneralEntity):
+    """Project entity for organisational structure.
+
+    The container every other entity hangs off. Carries its own workflow state
+    and process, the effort roll-up of the work inside it, and the branding
+    fields TP renders in the project picker.
+
+    Attributes:
+        effort: Rolled-up effort
+        effort_completed: Rolled-up completed effort
+        effort_todo: Rolled-up remaining effort
+        progress: Completion ratio derived from effort (0.0 - 1.0)
+        units: The unit effort is expressed in (e.g. "h", "pt")
+        is_active: Whether the project is active
+        is_product: Whether the project is a product rather than a project
+        is_private: Whether the project is hidden from non-members
+        abbreviation: Short code TP renders in compact views
+        mail_reply_address: Address inbound request email is accepted on
+        color: Project colour TP renders in the UI
+        planned_start_date: Planned start date/time
+        planned_end_date: Planned end date/time
+        last_state_change_date: When the entity state last changed
+        forecast_end_date: TP's projected completion date
+        anticipated_end_date: Manually anticipated completion date
+        lead_time: Days from creation to completion
+        cycle_time: Days from work starting to completion
+        entity_state: Current workflow state reference
+        process: Process (workflow definition) reference
+        program: Program reference
+        company: Company reference
+    """
+
+    # Effort roll-up
+    effort: float | None = Field(default=None, alias="Effort", description="Rolled-up 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"
+    )
+    progress: float | None = Field(default=None, alias="Progress", description="Completion ratio")
+    units: str | None = Field(default=None, alias="Units", description="Effort unit")
+
+    # Flags and branding
+    is_active: bool | None = Field(default=None, alias="IsActive", description="Active status")
+    is_product: bool | None = Field(default=None, alias="IsProduct", description="Is a product")
+    is_private: bool | None = Field(default=None, alias="IsPrivate", description="Is private")
+    abbreviation: str | None = Field(
+        default=None, alias="Abbreviation", description="Short project code"
+    )
+    mail_reply_address: str | None = Field(
+        default=None, alias="MailReplyAddress", description="Inbound mail address"
+    )
+    color: str | None = Field(default=None, alias="Color", description="Display colour")
+
+    # Date tracking
+    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"
+    )
+    last_state_change_date: TPDateTime | None = Field(
+        default=None, alias="LastStateChangeDate", description="Last state change"
+    )
+    forecast_end_date: TPDateTime | None = Field(
+        default=None, alias="ForecastEndDate", description="Forecast end"
+    )
+    anticipated_end_date: TPDateTime | None = Field(
+        default=None, alias="AnticipatedEndDate", description="Anticipated end"
+    )
+
+    # 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)"
+    )
+
+    # Relationships
+    entity_state: EntityRef | None = Field(
+        default=None, alias="EntityState", description="Workflow state"
+    )
+    process: EntityRef | None = Field(default=None, alias="Process", description="Process")
+    program: EntityRef | None = Field(default=None, alias="Program", description="Program")
+    company: EntityRef | None = Field(default=None, alias="Company", description="Company")
+
+
+class Team(GeneralEntity):
+    """Team entity for organisational structure.
+
+    A bare ``General`` upstream - TP adds only the activity flag and the
+    identity TP renders in team pickers.
+
+    Attributes:
+        is_active: Whether the team is active
+        abbreviation: Short code TP renders in compact views
+        emoji_icon: Emoji shorthand TP renders beside the team name
+        icon_uri: Path to the team's icon image
+        icon: Legacy icon field (deprecated upstream; prefer icon_uri)
+    """
+
+    is_active: bool | None = Field(default=None, alias="IsActive", description="Active status")
+    abbreviation: str | None = Field(
+        default=None, alias="Abbreviation", description="Short team code"
+    )
+    emoji_icon: str | None = Field(default=None, alias="EmojiIcon", description="Emoji icon")
+    icon_uri: str | None = Field(default=None, alias="IconUri", description="Icon image path")
+    icon: str | None = Field(
+        default=None, alias="Icon", description="Legacy icon (deprecated upstream)"
+    )
+
+
+class Release(GeneralEntity):
+    """Release entity for planning and tracking releases.
+
+    A dated window grouping iterations, with the effort roll-up of everything
+    scheduled into it. ``start_date`` and ``end_date`` are required upstream.
+
+    Attributes:
+        effort: Rolled-up effort
+        effort_completed: Rolled-up completed effort
+        effort_todo: Rolled-up remaining effort
+        progress: Completion ratio derived from effort (0.0 - 1.0)
+        units: The unit effort is expressed in (e.g. "h", "pt")
+        is_current: Whether this is the current release
+        forecast_end_date: TP's projected completion date
+        process: Process (workflow definition) reference
+    """
+
+    effort: float | None = Field(default=None, alias="Effort", description="Rolled-up 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"
+    )
+    progress: float | None = Field(default=None, alias="Progress", description="Completion ratio")
+    units: str | None = Field(default=None, alias="Units", description="Effort unit")
+    is_current: bool | None = Field(
+        default=None, alias="IsCurrent", description="Is the current release"
+    )
+    forecast_end_date: TPDateTime | None = Field(
+        default=None, alias="ForecastEndDate", description="Forecast end"
+    )
+    process: EntityRef | None = Field(default=None, alias="Process", description="Process")
+
+
+class Iteration(GeneralEntity):
+    """Iteration entity for agile sprints.
+
+    A project-level sprint inside a ``Release``. TP scopes iterations to the
+    release, not to a team - the team-scoped equivalent is
+    :class:`TeamIteration`.
+
+    Attributes:
+        effort: Rolled-up effort
+        effort_completed: Rolled-up completed effort
+        effort_todo: Rolled-up remaining effort
+        progress: Completion ratio derived from effort (0.0 - 1.0)
+        units: The unit effort is expressed in (e.g. "h", "pt")
+        velocity: Effort completed per unit time
+        duration: Iteration length in days
+        is_current: Whether this is the current iteration
+        can_be_finished: Whether TP will allow the iteration to be closed
+        forecast_end_date: TP's projected completion date
+        release: Release reference
+    """
+
+    effort: float | None = Field(default=None, alias="Effort", description="Rolled-up 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"
+    )
+    progress: float | None = Field(default=None, alias="Progress", description="Completion ratio")
+    units: str | None = Field(default=None, alias="Units", description="Effort unit")
+    velocity: float | None = Field(default=None, alias="Velocity", description="Velocity")
+    duration: int | None = Field(default=None, alias="Duration", description="Length in days")
+    is_current: bool | None = Field(
+        default=None, alias="IsCurrent", description="Is the current iteration"
+    )
+    can_be_finished: bool | None = Field(
+        default=None, alias="CanBeFinished", description="Can be closed"
+    )
+    forecast_end_date: TPDateTime | None = Field(
+        default=None, alias="ForecastEndDate", description="Forecast end"
+    )
+    release: EntityRef | None = Field(default=None, alias="Release", description="Release")
+
+    # Not declared in TP's /meta for Iteration and rejected by include= there;
+    # kept because removing a published field would break callers. The
+    # team-scoped sprint is TeamIteration.
+    team: EntityRef | None = Field(
+        default=None, alias="Team", description="Team (absent upstream; prefer TeamIteration)"
+    )
+
+
+class TeamIteration(GeneralEntity):
+    """Team-specific iteration (sprint) entity.
+
+    In TP each team owns its own iterations; a TeamIteration carries the
+    team's sprint window, effort/velocity/capacity, and its Release.
+
+    Attributes:
+        effort: Rolled-up effort
+        effort_completed: Rolled-up completed effort
+        effort_todo: Rolled-up remaining effort
+        progress: Completion ratio derived from effort (0.0 - 1.0)
+        units: The unit effort is expressed in (e.g. "h", "pt")
+        velocity: Effort completed per unit time
+        capacity: Effort the team can absorb in the window
+        duration: Iteration length in days
+        is_current: Whether this is the team's current iteration
+        can_be_finished: Whether TP will allow the iteration to be closed
+        forecast_end_date: TP's projected completion date
+        team: Team reference
+        release: Release reference
+    """
+
+    effort: float | None = Field(default=None, alias="Effort", description="Rolled-up 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"
+    )
+    progress: float | None = Field(default=None, alias="Progress", description="Completion ratio")
+    units: str | None = Field(default=None, alias="Units", description="Effort unit")
+    velocity: float | None = Field(default=None, alias="Velocity", description="Team velocity")
+    capacity: float | None = Field(default=None, alias="Capacity", description="Team capacity")
+    duration: int | None = Field(default=None, alias="Duration", description="Length in days")
+    is_current: bool | None = Field(
+        default=None, alias="IsCurrent", description="Is the current iteration"
+    )
+    can_be_finished: bool | None = Field(
+        default=None, alias="CanBeFinished", description="Can be closed"
+    )
+    forecast_end_date: TPDateTime | None = Field(
+        default=None, alias="ForecastEndDate", description="Forecast end"
+    )
+    team: EntityRef | None = Field(default=None, alias="Team", description="Team")
+    release: EntityRef | None = Field(default=None, alias="Release", description="Release")
+
+
+class TestCase(GeneralEntity):
+    """TestCase entity for quality assurance.
+
+    A ``General`` rather than an ``Assignable``: a test case has no effort, no
+    iteration and no workflow state - its status is the outcome of its last
+    run.
+
+    Attributes:
+        last_run_status: Outcome of the most recent run (e.g. "Passed")
+        last_run_date: When the test case was last run
+        last_failure_comment: Comment recorded against the last failure
+        last_status: Legacy boolean pass flag (deprecated; prefer last_run_status)
+        steps: Legacy free-text steps (deprecated upstream)
+        success: Legacy free-text expected result (deprecated upstream)
+        priority: Priority reference, scoped to this entity type
+        user_story: Parent user story reference (deprecated upstream)
+    """
+
+    last_run_status: str | None = Field(
+        default=None, alias="LastRunStatus", description="Last run outcome"
+    )
+    last_run_date: TPDateTime | None = Field(
+        default=None, alias="LastRunDate", description="Last run date/time"
+    )
+    last_failure_comment: str | None = Field(
+        default=None, alias="LastFailureComment", description="Last failure comment"
+    )
+    last_status: bool | None = Field(
+        default=None, alias="LastStatus", description="Legacy pass flag (deprecated upstream)"
+    )
+    steps: str | None = Field(
+        default=None, alias="Steps", description="Legacy steps (deprecated upstream)"
+    )
+    success: str | None = Field(
+        default=None, alias="Success", description="Legacy expected result (deprecated upstream)"
+    )
+    priority: RefWithImportance | None = Field(
+        default=None, alias="Priority", description="Priority"
+    )
+    user_story: EntityRef | None = Field(
+        default=None,
+        alias="UserStory",
+        description="Parent user story (deprecated upstream)",
+    )
+
+    # Neither is declared in TP's /meta for TestCase, and include= rejects both
+    # there; kept because removing a published field would break callers.
+    entity_state: EntityRef | None = Field(
+        default=None, alias="EntityState", description="Workflow state (absent upstream)"
+    )
+    assigned_user: AssignedUsers | None = Field(
+        default=None, alias="AssignedUser", description="Assigned users (absent upstream)"
+    )

targetprocess/_joins.py

@@ -0,0 +1,217 @@
+"""The join entities that connect two records rather than describing one.
+
+``Assignment``, ``TeamAssignment``, ``RoleEffort``, ``Relation`` and ``Time``
+each pair an ``Assignable`` with a user, team, role or another entity. None
+carries a ``Name``, and none sits in TP's ``General`` hierarchy, so all extend
+:class:`targetprocess._base.Entity` directly.
+
+Re-exported by :mod:`targetprocess.models`, which stays the import surface
+callers use.
+"""
+
+from pydantic import Field
+
+from targetprocess._base import Entity
+from targetprocess._dates import TPDateTime
+from targetprocess._nested import EntityRef, UserRef
+
+
+class Assignment(Entity):
+    """User-to-work-item role assignment (join entity).
+
+    Pairs a user (``GeneralUser``) with a ``Role`` on an ``Assignable`` -
+    the authoritative record of who is assigned to a work item and in which
+    capacity (``Owner`` only records who created it).
+
+    Attributes:
+        general_user: Assigned user reference
+        role: Role reference
+        assignable: Assignable (work item) reference
+    """
+
+    general_user: UserRef | None = Field(
+        default=None, alias="GeneralUser", description="Assigned user"
+    )
+    role: EntityRef | None = Field(default=None, alias="Role", description="Role")
+    assignable: EntityRef | None = Field(
+        default=None, alias="Assignable", description="Assignable (work item)"
+    )
+
+
+class TeamAssignment(Entity):
+    """Team-to-work-item assignment (join entity).
+
+    Assigns a Team to an Assignable over a time window, carrying the
+    assignment's entity state.
+
+    Attributes:
+        start_date: Assignment start date/time
+        end_date: Assignment end date/time
+        team: Team reference
+        assignable: Assignable (work item) reference
+        entity_state: Workflow state reference
+    """
+
+    # 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")
+
+    # Relationships
+    team: EntityRef | None = Field(default=None, alias="Team", description="Team")
+    assignable: EntityRef | None = Field(
+        default=None, alias="Assignable", description="Assignable (work item)"
+    )
+    entity_state: EntityRef | None = Field(
+        default=None, alias="EntityState", description="Workflow state"
+    )
+
+
+class RoleEffort(Entity):
+    """Per-role effort allocation on an Assignable (join entity).
+
+    Breaks an Assignable's effort down by Role.
+
+    Attributes:
+        initial_estimate: Initial effort estimate >= 0
+        effort: Total effort >= 0
+        effort_completed: Completed effort >= 0
+        effort_todo: Remaining effort >= 0
+        time_spent: Time spent >= 0
+        time_remain: Time remaining >= 0
+        assignable: Assignable (work item) reference
+        role: Role reference
+    """
+
+    # Effort / time tracking
+    initial_estimate: float | None = Field(
+        default=None, alias="InitialEstimate", ge=0, description="Initial estimate"
+    )
+    effort: float | None = Field(default=None, alias="Effort", ge=0, description="Total effort")
+    effort_completed: float | None = Field(
+        default=None, alias="EffortCompleted", ge=0, description="Completed effort"
+    )
+    effort_todo: float | None = Field(
+        default=None, alias="EffortToDo", ge=0, description="Remaining effort"
+    )
+    time_spent: float | None = Field(
+        default=None, alias="TimeSpent", ge=0, description="Time spent"
+    )
+    time_remain: float | None = Field(
+        default=None, alias="TimeRemain", ge=0, description="Time remaining"
+    )
+
+    # Relationships
+    assignable: EntityRef | None = Field(
+        default=None, alias="Assignable", description="Assignable (work item)"
+    )
+    role: EntityRef | None = Field(default=None, alias="Role", description="Role")
+
+
+class Relation(Entity):
+    """Entity-to-entity relation (join entity).
+
+    Links two entities, typed by a ``RelationType`` (Dependency, Blocker,
+    Relation, Duplicate, ...). The direction carries meaning: the source is the
+    origin of the dependency - in a Blocker relation the source is the blocking
+    item and the target the blocked one.
+
+    TP exposes the same pair twice. ``Master``/``Slave`` are the original names
+    and are marked deprecated in ``/meta``; ``Inbound``/``Outbound`` are the
+    current ones. They are the same two records - ``Inbound`` mirrors
+    ``Master`` and ``Outbound`` mirrors ``Slave`` - so prefer the latter pair in
+    new code.
+
+    Attributes:
+        inbound: Source entity reference
+        outbound: Target entity reference
+        master: Source entity reference (deprecated upstream; prefer inbound)
+        slave: Target entity reference (deprecated upstream; prefer outbound)
+        relation_type: Relation-type reference
+    """
+
+    # Relationships
+    inbound: EntityRef | None = Field(default=None, alias="Inbound", description="Source entity")
+    outbound: EntityRef | None = Field(default=None, alias="Outbound", description="Target entity")
+    master: EntityRef | None = Field(
+        default=None, alias="Master", description="Source entity (deprecated upstream)"
+    )
+    slave: EntityRef | None = Field(
+        default=None, alias="Slave", description="Target entity (deprecated upstream)"
+    )
+    relation_type: EntityRef | None = Field(
+        default=None, alias="RelationType", description="Relation type"
+    )
+
+
+class Time(Entity):
+    """Time entry logged against an Assignable (join entity).
+
+    Records spent and remaining hours for a User against an Assignable on a
+    given date.
+
+    ``assignable`` is the general reference; TP additionally exposes a narrower
+    back-reference per work-item type, of which exactly one is populated for
+    any given entry (a ``CustomActivity`` entry, for instance, has a null
+    ``assignable``). They are declared so an entry's origin is readable without
+    a second fetch.
+
+    Attributes:
+        spent: Hours spent >= 0
+        remain: Hours remaining >= 0
+        is_estimation: Entry records an estimate rather than actual time
+        date: Date/time the work is logged against
+        description: Free-text description of the work
+        assignable: Assignable (work item) reference
+        user: User the time is logged for
+        project: Project reference (TP derives it from the Assignable)
+        role: Role reference
+        user_story: User story the entry was logged against, if any
+        task: Task the entry was logged against, if any
+        bug: Bug the entry was logged against, if any
+        request: Request the entry was logged against, if any
+        test_plan: Test plan the entry was logged against, if any
+        test_plan_run: Test plan run the entry was logged against, if any
+        custom_activity: Custom activity the entry was logged against, if any
+    """
+
+    # Effort / time tracking
+    spent: float | None = Field(default=None, alias="Spent", ge=0, description="Hours spent")
+    remain: float | None = Field(default=None, alias="Remain", ge=0, description="Hours remaining")
+    is_estimation: bool | None = Field(
+        default=None, alias="IsEstimation", description="Entry is an estimation"
+    )
+
+    # Date tracking
+    date: TPDateTime | None = Field(default=None, alias="Date", description="Date/time logged")
+
+    # Content
+    description: str | None = Field(default=None, alias="Description", description="Description")
+
+    # Relationships
+    assignable: EntityRef | None = Field(
+        default=None, alias="Assignable", description="Assignable (work item)"
+    )
+    user: UserRef | None = Field(default=None, alias="User", description="User")
+    project: EntityRef | None = Field(default=None, alias="Project", description="Project")
+    role: EntityRef | None = Field(default=None, alias="Role", description="Role")
+
+    # Narrow back-references: at most one is populated per entry.
+    user_story: EntityRef | None = Field(
+        default=None, alias="UserStory", description="User story logged against"
+    )
+    task: EntityRef | None = Field(default=None, alias="Task", description="Task logged against")
+    bug: EntityRef | None = Field(default=None, alias="Bug", description="Bug logged against")
+    request: EntityRef | None = Field(
+        default=None, alias="Request", description="Request logged against"
+    )
+    test_plan: EntityRef | None = Field(
+        default=None, alias="TestPlan", description="Test plan logged against"
+    )
+    test_plan_run: EntityRef | None = Field(
+        default=None, alias="TestPlanRun", description="Test plan run logged against"
+    )
+    custom_activity: EntityRef | None = Field(
+        default=None, alias="CustomActivity", description="Custom activity logged against"
+    )