targetprocess-py 0.1.0__tar.gz

targetprocess_py-0.1.0/.coderabbit.yaml

@@ -0,0 +1,147 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+#
+# This file supersedes the CodeRabbit dashboard settings for this repository:
+# once present, dashboard values no longer apply here, so any organisation-wide
+# settings we rely on must be restated in this file.
+
+language: en-ZA
+
+reviews:
+  profile: assertive
+  in_progress_fortune: false
+  # Withhold CodeRabbit's approval until every conversation on the PR is
+  # resolved and no error-mode pre-merge check is failing; approval is then
+  # granted automatically. This makes CodeRabbit re-approve once satisfied
+  # (a first-pass "changes requested" otherwise never clears to approved),
+  # and gives the error-mode pre-merge checks below their merge-blocking teeth.
+  request_changes_workflow: true
+
+  auto_review:
+    # No automatic reviews. Every pull request here is agent-authored and its
+    # coordinator requests each review explicitly ("@coderabbitai review", or
+    # "full review") once the content is final, so no included review or paid
+    # credit is spent on an intermediate push, and draft state gates nothing.
+    # With automatic reviews off CodeRabbit posts a passing "Review skipped"
+    # status on every push, so a required CodeRabbit status check no longer
+    # proves a review ran; the approving-review requirement is the gate.
+    # Bot-authored pull requests (Dependabot and the like) are not auto-reviewed
+    # regardless.
+    enabled: false
+
+  finishing_touches:
+    simplify:
+      enabled: true
+
+  pre_merge_checks:
+    # Only a requested reviewer — never the PR author — may ignore a failing
+    # error-mode check, so the author cannot self-bypass the error-mode gate
+    # defined below.
+    override_requested_reviewers_only: true
+
+    # The built-in docstring-coverage check cannot exclude test code, and test
+    # methods idiomatically carry no docstrings — so it is disabled here and
+    # replaced by the "Docstring coverage (non-test)" custom check below, which
+    # excludes tests by prose.
+    docstrings:
+      mode: "off"
+
+    custom_checks:
+      - name: "Docstring coverage (non-test)"
+        mode: "error"
+        instructions: |
+          Fail if any public function, method, or class ADDED or MODIFIED in
+          this pull request lacks a docstring. Judge each file by intent, not by
+          an exhaustive pattern list. EXCLUDE all test code: any file located in
+          a test directory at any depth (e.g. tests/, test/, __tests__/, spec/)
+          or whose name marks it as a test (test_*, *_test, *.test.*, *.spec.*
+          in any language or extension), and any test function or method (name
+          starting with "test") — test code idiomatically carries no docstrings
+          and must not count against coverage. Also exclude generated or
+          vendored code. Scope the check to languages that have a docstring
+          convention (Python, and JS/TS/JSX/TSX via JSDoc); ignore languages
+          that have none (YAML, shell, JSON).
+
+      - name: "Checklist complete"
+        mode: "error"
+        instructions: |
+          Parse task-list items in THIS pull request's own description only —
+          never in a linked issue, a comment, or any external document. GitHub
+          Flavored Markdown task lists use unordered ("-", "*", "+") or ordered
+          ("1." or "1)") list markers at any indentation level. IGNORE any
+          section whose heading is "Post-merge verification" (or that clearly
+          denotes post-merge / post-deploy checks): those are verified after
+          merge and must not gate this pre-merge check. Of the remaining items,
+          fail if any is unticked ("[ ]"). Treat "[x]" and "[X]" as ticked and
+          "[~]" (inapplicable) as addressed. Pass when no unticked items remain,
+          or the description has no gating task-list items.
+
+      - name: "No committed superpowers artefacts"
+        mode: "error"
+        instructions: |
+          Fail if this pull request ADDS any new file under docs/superpowers/
+          or docs/plans/. These directories hold transient brainstorming and
+          writing-plans working documents (design specs and implementation
+          plans) that are kept on disk for the working session only and must
+          never be committed — the living specification lives in SPEC.md,
+          updated alongside changes. A new file anywhere outside these two
+          directories is fine; the ban is scoped to them.
+
+  path_filters:
+    # Auto-generated lockfiles — reviewing their diffs is noise, not signal.
+    - "!**/package-lock.json"
+    - "!**/*.script.lock"
+    - "!**/poetry.lock"
+    - "!**/bun.lockb"
+    - "!**/uv.lock"
+
+  path_instructions:
+    - path: "src/targetprocess/**"
+      instructions: >
+        Async Python library for the TargetProcess v1 REST API. TP facts that are
+        correct and must not be "fixed": tokens are sent as an access_token query
+        parameter (TP has no header token scheme); dates arrive as /Date(ms±HHMM)/;
+        collection responses are {Next, Items} and pagination follows Next verbatim.
+    - path: "tests/**"
+      instructions: |
+        Pytest suite. New or modified test doubles must be constrained to a
+        real interface: Mock() and MagicMock() require spec= (or spec_set=),
+        and patch()/patch.object() require autospec=True or an explicit
+        spec. An unspecced double accepts any attribute access, hiding
+        exactly the interface-drift bugs a test exists to catch. For
+        TypedDicts and other shapes that spec poorly, use real stub dicts
+        instead of mocks.
+    - path: "tests/integration/cassettes/**"
+      instructions: >
+        Recorded VCR fixtures — flag immediately any unredacted credential,
+        PII (names, logins, emails), real TargetProcess hostname, or real
+        business content (issue titles, descriptions, comments): those must
+        be sanitised placeholder values. Bare numeric Ids are deliberately
+        preserved and must NOT be flagged — neither real entity Ids nor the
+        product-seeded lookup constants every TP tenant shares (Priority
+        1–5, EntityType 4): with names, logins, text and hostname already
+        placeholders, an Id on its own identifies nothing. Structural
+        fields — Id, ResourceType, dates, numeric/boolean fields, the
+        Items/Next/Prev envelope — are kept as recorded so a cassette still
+        exercises real parsing, pagination and filter behaviour
+        (docs/testing.md). On a write-path cassette the REQUEST body is
+        recorded as sent and is deliberately not field-scrubbed: its
+        Name/Description values are synthetic strings the test invented,
+        carrying the recording ticket's reference as a prefix, and must NOT
+        be flagged. Do flag a request body carrying text that reads as
+        having come off the live instance rather than being invented.
+    - path: ".github/workflows/**"
+      instructions: |
+        GitHub Actions CI — high blast radius. Validation jobs run on pull
+        requests; nothing here deploys. Flag changes that loosen branch gating,
+        broaden event triggers, widen permissions, or expose secrets.
+    - path: "**/.env"
+      instructions: |
+        Gitignored credentials file — it must never be committed. Treat any
+        .env appearing in a diff as a critical defect.
+
+chat:
+  art: false
+
+code_generation:
+  docstrings:
+    language: en-ZA

targetprocess_py-0.1.0/.commitlintrc.json

@@ -0,0 +1,35 @@
+{
+  "extends": ["@commitlint/config-conventional"],
+  "rules": {
+    "type-enum": [
+      2,
+      "always",
+      [
+        "feat",
+        "fix",
+        "docs",
+        "style",
+        "refactor",
+        "perf",
+        "test",
+        "build",
+        "ci",
+        "chore",
+        "revert"
+      ]
+    ],
+    "type-case": [2, "always", "lower-case"],
+    "type-empty": [2, "never"],
+    "subject-empty": [2, "never"],
+    "subject-full-stop": [2, "never", "."],
+    "subject-case": [
+      2,
+      "always",
+      ["lower-case", "sentence-case"]
+    ],
+    "header-max-length": [2, "always", 72],
+    "body-leading-blank": [2, "always"],
+    "body-max-line-length": [2, "always", 100],
+    "footer-leading-blank": [2, "always"]
+  }
+}

targetprocess_py-0.1.0/.env.example

@@ -0,0 +1,25 @@
+# Copy this file to .env and fill in real values. .env is gitignored and
+# must never be committed. See the "Secrets management" section of the
+# README for the env-var -> secrets-manager pattern.
+#
+#   cp .env.example .env
+
+# TargetProcess instance domain (no scheme), e.g. example.tpondemand.com
+TP_DOMAIN=example.tpondemand.com
+
+# TargetProcess API token, sent as the access_token query parameter.
+# Fetch it from your TP instance's account settings; never share or commit it.
+TP_TOKEN=your-api-token
+
+# Comma-separated allow-list of project ids the write examples may modify.
+# Only set this for a throwaway/sandbox project; never production.
+# Required by examples/create_bug.py and examples/bulk_updates.py.
+TP_WRITE_ALLOWED_PROJECT_IDS=
+
+# --- Integration-cassette recording only -------------------------------------
+# tests/integration/ replays committed cassettes offline and needs nothing set.
+# Re-recording against a live instance (ALLOW_PROD_RECORDING=1) uses this second
+# pair instead, read from the environment or from ~/.config/targetprocess/.env.
+# Leave both blank unless you are deliberately re-recording.
+TP_BASE_URL=
+TP_API_TOKEN=

targetprocess_py-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,80 @@
+name: Bug report
+description: Report something that is not working as expected
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report! Please fill in the
+        sections below so we can reproduce and fix it.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: A concise description of the problem.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: |
+        The smallest self-contained example that triggers the bug. Include the
+        code, the command you ran, and any relevant environment details. Redact
+        real tokens — never paste a live `TP_TOKEN`.
+      placeholder: |
+        1. ...
+        2. ...
+        3. ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behaviour
+      description: |
+        Include the full traceback or error message if there is one. Redact
+        tokens, credentials, authorisation headers, cookies, and query strings
+        before posting — a traceback often carries the request URL.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Library version, Python version, OS, and anything else relevant.
+      placeholder: |
+        - targetprocess-py: 0.x.y
+        - Python: 3.12.x
+        - OS: ...
+    validations:
+      required: true
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      description: |
+        How urgent is this? P1 blocks work with no reasonable workaround, P2 has
+        real impact but a workaround exists, P3 is cosmetic or minor. P0 is
+        reserved for security incidents — report those via the security link on
+        the issue chooser instead.
+      options:
+        - "P1 — High"
+        - "P2 — Medium"
+        - "P3 — Low"
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Anything else? Links, related issues, screenshots.
+    validations:
+      required: false

targetprocess_py-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,9 @@
+blank_issues_enabled: false
+contact_links:
+  # GitHub's "report a vulnerability" advisory route needs private vulnerability
+  # reporting, which this private repository does not expose, so the security
+  # contact is e-mail. Switch to the advisories URL if the repo is ever made
+  # public and the feature is enabled.
+  - name: Security report
+    url: mailto:louis@man8.com?subject=targetprocess-py%20security%20report
+    about: Report a security vulnerability privately by e-mail, not as a public issue.

targetprocess_py-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,66 @@
+name: Feature request
+description: Suggest a new capability or improvement
+title: "[Feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion! Tell us what you want and why.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What is currently hard or impossible to do?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What would you like the library to do instead?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any workarounds or other approaches you thought about.
+    validations:
+      required: false
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Which part of the library does this touch?
+      options:
+        - "area: client"
+        - "area: models"
+        - "area: transport"
+        - "area: observability"
+        - "area: docs"
+        - "area: ci"
+        - "area: testing"
+    validations:
+      required: true
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      description: |
+        How important is this to you? P1 blocks work with no reasonable
+        workaround, P2 has real impact but a workaround exists, P3 is cosmetic
+        or minor.
+      options:
+        - "P1 — High"
+        - "P2 — Medium"
+        - "P3 — Low"
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Anything else? Links, mockups, related issues.
+    validations:
+      required: false

targetprocess_py-0.1.0/.github/dependabot.yml

@@ -0,0 +1,107 @@
+# Automated dependency updates. Two ecosystems are in play here:
+#
+#   uv             — the locked Python environment (pyproject.toml + uv.lock).
+#                    versioning-strategy: lockfile-only keeps Dependabot out of
+#                    pyproject.toml entirely, so the declared floors stay
+#                    deliberate while the resolved versions CI installs stay
+#                    current. See the strategy note on that key below.
+#   github-actions — the SHA-pinned actions in .github/workflows/. Pinning to a
+#                    commit is the supply-chain-safe form but it never floats, so
+#                    without Dependabot those pins silently rot.
+#   pre-commit     — the hook repos pinned by `rev:` in .pre-commit-config.yaml.
+#                    Same rot problem as the action pins. The ruff/mypy hooks are
+#                    not listed there: they run via `uv run`, so the uv ecosystem
+#                    above already keeps them current.
+#
+# Every update lands as a pull request, so the existing gates (ruff, ruff-format,
+# mypy --strict, pytest with --cov-fail-under=90, the pre-commit hook suite,
+# duplication detection, CodeQL, CodeRabbit review) decide whether a bump is safe
+# before it reaches main.
+version: 2
+
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    # Explicit rather than the default "auto", which guesses app-vs-library and
+    # would rewrite pyproject.toml: "increase" raises the floor to the newest
+    # release, and "widen" adds an upper bound. Neither is right for a published
+    # library — an upper cap propagates into every downstream resolution, and a
+    # raised floor drops support for versions that still work. lockfile-only
+    # confines Dependabot to uv.lock. Because the constraints here are open-ended
+    # (httpx>=0.27.0, pydantic>=2.0.0, easylimit>=0.3.4), the manifest already
+    # permits new releases, so this forgoes no upgrades: majors still land, they
+    # just arrive as a lock change plus a green/red CI signal, and widening the
+    # declared floor stays a deliberate human decision.
+    versioning-strategy: "lockfile-only"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "07:00"
+      timezone: "Africa/Johannesburg"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+      prefix-development: "deps-dev"
+      include: "scope"
+    groups:
+      # Test/lint/type tooling moves together: a mypy or ruff bump is judged by
+      # whether CI still passes, so batching them keeps review cost proportional.
+      dev-tooling:
+        patterns:
+          - "pytest*"
+          - "mypy*"
+          - "ruff"
+          - "coverage*"
+          - "vcrpy"
+          - "pre-commit"
+      # Runtime dependencies are batched only for minor/patch. Majors are
+      # deliberately left ungrouped so each arrives as its own PR — httpx,
+      # pydantic and easylimit are the library's public surface (pydantic v2
+      # models and httpx types leak into user code), so a major needs to be
+      # reviewed and released on its own.
+      runtime-minor-patch:
+        patterns:
+          - "httpx"
+          - "pydantic*"
+          - "easylimit"
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "07:00"
+      timezone: "Africa/Johannesburg"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    groups:
+      pre-commit:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "07:00"
+      timezone: "Africa/Johannesburg"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

targetprocess_py-0.1.0/.github/labels.yml

@@ -0,0 +1,56 @@
+# Issue and pull-request label set for targetprocess-py.
+#
+# GitHub's 9 default labels plus the two Dependabot labels
+# (`dependencies`, `python:uv`) are already present; this file defines the
+# project-specific priority and area labels that sit on top of them.
+#
+# To (re)apply this set to the repository, run:
+#
+#   scripts/apply_labels.sh
+#
+# which calls `gh label create` (or `--force` to update colours/descriptions).
+# Existing labels are left untouched unless they appear below.
+#
+# The priority and area dropdowns in the issue forms record the reporter's
+# choice in the issue body only — GitHub applies just the form's own top-level
+# `labels:` key, so the P#/area labels below still have to be applied by hand
+# (or by a future labeler workflow) during triage.
+
+# --- Priority ---------------------------------------------------------------
+# P0 is reserved for security incidents and outages and is not exposed in the
+# issue-template dropdowns; file those via the Security report contact link.
+- name: "P0 — Critical"
+  color: "b60205"
+  description: "Security incident or outage; drop everything."
+- name: "P1 — High"
+  color: "d93f0b"
+  description: "Blocks work, no reasonable workaround."
+- name: "P2 — Medium"
+  color: "fbca04"
+  description: "Real impact, a workaround exists."
+- name: "P3 — Low"
+  color: "0e8a16"
+  description: "Cosmetic or minor; nice to have."
+
+# --- Area -------------------------------------------------------------------
+- name: "area: client"
+  color: "1d76db"
+  description: "Client layer and resource managers."
+- name: "area: models"
+  color: "5319e7"
+  description: "Pydantic entity and reference models."
+- name: "area: transport"
+  color: "006b75"
+  description: "HTTP transport, auth, retry, rate limiting."
+- name: "area: observability"
+  color: "0052cc"
+  description: "Logging, scrubbing, request-id propagation."
+- name: "area: docs"
+  color: "0075ca"
+  description: "README, usage guide, examples, SPEC."
+- name: "area: ci"
+  color: "6f42c1"
+  description: "GitHub Actions, pre-commit, Dependabot, CodeRabbit."
+- name: "area: testing"
+  color: "a2eeef"
+  description: "pytest suite, VCR cassettes, coverage."

targetprocess_py-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,62 @@
+<!--
+Thanks for the pull request! Title it as a Conventional Commits subject
+(`type(scope): description`): squash merge makes it the commit on main, and CI
+checks it as one. Fill in the sections below, then complete the
+checklist. CodeRabbit's "Checklist complete" pre-merge check fails if any
+unticked ("- [ ]") task-list item remains in this description, so tick each
+box as you go (or mark inapplicable items with "[~]").
+-->
+
+## Summary
+
+<!-- What does this change do, and why? Reference the issue or work item
+     this closes. -->
+
+Closes #
+
+## Changes
+
+<!-- Bullet list of the meaningful changes. Group by area if the PR spans
+     more than one (e.g. transport, models, docs). -->
+
+-
+
+## Testing
+
+<!-- How did you verify this? Which commands did you run? Paste a short,
+     redacted transcript if useful. Never paste a live TP_TOKEN. -->
+
+-
+
+## Context
+
+<!-- Anything a reviewer should know: alternatives considered, follow-ups,
+     risk, migration notes, or "none". -->
+
+-
+
+## Checklist
+
+- [ ] `uv run ruff check .` and `uv run ruff format --check .` pass
+- [ ] `uv run mypy --strict src` passes
+- [ ] `uv run pytest -q` passes and coverage stays at or above 90%
+- [ ] `uv run pre-commit run --all-files --hook-stage pre-commit` passes
+- [ ] `uv run pre-commit run --all-files --hook-stage pre-push` passes
+- [ ] New public functions, methods, and classes have docstrings
+- [ ] No real credentials, tokens, or PII are added to the diff
+- [ ] `TODO`/`FIXME`/`HACK`/`XXX` markers name an issue (e.g. `TODO(#123)`)
+
+<!--
+Post-merge verification does not belong in this description. It lives on the
+linked work item under its own "## Post-merge verification" heading, where it
+gates that item's Verify -> Done transition. Keeping it there leaves this
+checklist purely pre-merge, so "all boxes ticked" and "ready to merge" mean the
+same thing.
+-->
+
+<!--
+Implicit merge gates — CI passing, the CodeRabbit review, human approval — are
+deliberately absent from the checklist above. Branch protection already
+enforces them, and rendering them as boxes invites a tick before the gate has
+actually cleared.
+-->