plynt 0.11.0__tar.gz

plynt-0.11.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default ownership for all files in this repository
+* @eschaar

plynt-0.11.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,37 @@
+name: Bug report
+description: Report a reproducible bug
+labels: ["bug"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened?
+      placeholder: A clear and concise description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Exact steps to reproduce the issue.
+      placeholder: |
+        1. ...
+        2. ...
+        3. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Python version, OS, and any relevant details.

plynt-0.11.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability report
+    url: https://github.com/eschaar/plynt/security/advisories/new
+    about: Please report security issues privately via GitHub Security Advisories.

plynt-0.11.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Suggest an improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What user or developer problem does this solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe your proposed approach.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What alternatives did you consider?

plynt-0.11.0/.github/ISSUE_TEMPLATE/release_smoke_checklist.yml

@@ -0,0 +1,84 @@
+name: Release smoke checklist
+description: Verify release automation and publish safety for a real release
+labels: ["release"]
+body:
+  - type: input
+    id: target_version
+    attributes:
+      label: Target version
+      description: Planned release version (SemVer)
+      placeholder: 0.2.2
+    validations:
+      required: true
+
+  - type: dropdown
+    id: release_reason
+    attributes:
+      label: Release reason
+      description: Select why this release is being made
+      options:
+        - Feature delivery
+        - Bug fix
+        - Security fix
+        - Maintenance
+        - Other
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: pre_release_checks
+    attributes:
+      label: Pre-release checks
+      description: Validate the baseline before merging the release PR
+      options:
+        - label: make check passed locally
+          required: true
+        - label: No manual version bump or manual git tag was created
+          required: true
+        - label: Release-please PR was reviewed and merged to main
+          required: true
+
+  - type: checkboxes
+    id: release_artifact_checks
+    attributes:
+      label: Release artifact checks
+      description: Confirm naming and generated artifacts
+      options:
+        - label: Git tag format is X.Y.Z (no v prefix)
+          required: true
+        - label: GitHub release title format is vX.Y.Z
+          required: true
+        - label: CHANGELOG entry exists for X.Y.Z
+          required: true
+
+  - type: checkboxes
+    id: publish_checks
+    attributes:
+      label: Publish checks
+      description: Validate publish workflow and guard settings
+      options:
+        - label: Publish workflow run succeeded for this release
+          required: true
+        - label: OIDC was used (no API token in workflow)
+          required: true
+        - label: ENABLE_PYPI_PUBLISH was intentionally set for this release path
+          required: true
+
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence links
+      description: Add links to PR, release page, and workflow runs
+      placeholder: |
+        - Release PR:
+        - GitHub release:
+        - Publish run:
+        - Verify run:
+    validations:
+      required: true
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: Optional risks, follow-ups, or deviations

plynt-0.11.0/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,16 @@
+# Pull Request
+
+## Summary
+
+<!-- What does this PR do? -->
+
+## Why
+
+<!-- Why is this change needed? -->
+
+## Version impact
+
+- [ ] None
+- [ ] Patch
+- [ ] Minor
+- [ ] Major

plynt-0.11.0/.github/copilot-instructions.md

@@ -0,0 +1,310 @@
+# Copilot Instructions
+
+These instructions define how GitHub Copilot and other AI agents must operate within this repository. They are aligned with the project's architecture, ADRs, and long-term goals.
+
+
+
+## Language, Documentation, and Coding Requirements
+
+- All comments, docstrings, and documentation must be written in clear, developer-friendly English.
+- Use language that is easy to understand for developers of varying backgrounds.
+- All markdown files must conform to markdown linting rules (e.g., blank lines around headings and lists, proper heading levels, no hard tabs, etc.).
+- Keep documentation lines, comments, and docstrings concise: aim for 80 characters per line, and never exceed 120 characters per line.
+- All code must use type hinting (type annotations) wherever possible, including function arguments, return types, and class attributes.
+- All tests must be written using pytest (no unittest or nose). Use pytest idioms and fixtures.
+- Prefer grouping tests in a class (e.g., TestSettings) that corresponds to the class under test.
+
+### Docstring style
+
+Use **Google-style docstrings** throughout. Apply the following rules:
+
+**Summary line**
+
+- One sentence, imperative mood, no trailing period.
+- Must stand alone — a reader should understand the purpose without reading
+  the body.
+- Good: `"""Return the global SObject catalog for the org."""`
+- Avoid: `"""This method returns..."""`
+
+**When to add `Args:` / `Returns:` / `Raises:` sections**
+
+Only add a section when it adds information not already expressed by the type
+hints and parameter names. Omit it when the signature is self-explanatory.
+
+| Situation | Add section? |
+| --- | --- |
+| Parameter has non-trivial semantics (format, validation, side-effects) | Yes |
+| Parameter name and type are self-explanatory | No |
+| Return type is a typed model and the summary says what it contains | No |
+| Return has subtle behaviour (e.g. `None` on 204, pagination semantics) | Yes |
+| Function always raises under a specific condition | Yes (`Raises:`) |
+| Private / internal method | No — one-liner only |
+
+**`Args:` format**
+
+```python
+Args:
+    record_id: Salesforce 15- or 18-character record ID.
+    fields: Field API names to include. Returns all fields when omitted.
+```
+
+- One line per parameter where possible.
+- No Sphinx cross-references (`:class:`, `:meth:`, `:attr:`).
+- Use plain names: `SalesforceQueryResponse`, not
+  `:class:`~plynt.connectors.salesforce.models.SalesforceQueryResponse``.
+
+**`Returns:` format**
+
+```python
+Returns:
+    Parsed query response with a ``records`` list and pagination state.
+```
+
+- Describe the value, not the type — the type is already in the signature.
+- Never repeat the class name as the sole content.
+
+**`Example::` blocks**
+
+- Add only on public API methods where usage is non-obvious.
+- Omit on private methods, simple getters, and one-liners.
+- Keep examples short — 4–8 lines maximum.
+
+**Class docstrings**
+
+- Describe the responsibility of the class, not its constructor.
+- Put constructor parameter docs on the class docstring, not on `__init__`.
+- Keep `__init__` docstrings to a single line or omit them entirely.
+
+**What to avoid**
+
+- Sphinx cross-reference syntax (`:class:`, `:meth:`, `:attr:`, `:param:`).
+- Restating the type hint in prose: `"Returns a str"` when `-> str` is present.
+- Long `Returns:` blocks that copy the class definition.
+- Docstrings on private helpers (`_method`) longer than one line.
+
+---
+
+## 1. Project Intent & Scope
+
+- Treat this repository as a framework-agnostic external API client library.
+- Prioritize long-term reuse and architectural consistency over short-term feature delivery or local optimizations.
+- When in doubt, defer to existing ADRs and design documentation.
+
+## 2. Architectural Decision Records (ADRs)
+
+- Always consult ADRs before making architectural or structural changes.
+- Do **not** override or reinterpret an accepted ADR.
+- If a required decision is missing or unclear:
+  - Flag the gap.
+  - Propose a new ADR instead of making assumptions.
+- Reference ADR identifiers (e.g., ADR-003) in code comments and commit messages.
+
+## 3. Core vs Optional Components
+
+- Treat the core package as minimal and framework-independent.
+- Do **not** introduce framework dependencies into the core.
+- All framework-specific functionality must live in optional modules.
+- Respect the modular installation model (extras such as `[django]`, `[fastapi]`, `[oauth]`).
+- Assume users may install only a subset of the package.
+
+## 4. Dependency Management Principles
+
+- Keep core dependencies minimal and stable.
+- Avoid introducing new dependencies without architectural justification.
+- When adding a dependency:
+  - Document the rationale.
+  - Assess impact on optional installs.
+  - Reference or propose an ADR.
+- Prefer standard library solutions when feasible.
+
+## 5. Sync and Async Design Constraints
+
+- Treat sync vs async as a transport concern only.
+- Services, models, and responses must remain execution-model agnostic.
+- Never duplicate business logic for sync and async paths.
+- Follow documented transport abstractions.
+
+## 6. Composition Over Inheritance
+
+- Prefer composition, explicit objects, and small interfaces.
+- Avoid deep inheritance hierarchies or “god base classes.”
+- Do **not** introduce implicit behavior via magic methods.
+- Align with documented architectural patterns.
+
+## 7. Service Layer Responsibilities
+
+- Services represent external domains or APIs.
+- Services:
+  - Define endpoints.
+  - Orchestrate requests.
+  - Select response models.
+- Services must **not**:
+  - Manage HTTP internals.
+  - Manage framework concerns.
+  - Perform I/O outside the client abstraction.
+
+## 8. Response and Error Handling
+
+- Centralize response parsing and error handling.
+- Avoid leaking raw HTTP responses outside the response layer.
+- Use typed response models consistently.
+- Do **not** implement ad-hoc error handling inside services or frameworks.
+
+## 9. Models and Validation
+
+- Models are data carriers only.
+- No business logic inside models.
+- Models must remain framework-independent.
+- Reuse models across services, framework adapters, and tests.
+- Follow documented validation and serialization rules.
+
+## 10. Authentication and Caching
+
+- Authentication must be pluggable, optional, and non-intrusive.
+- Do **not** hard-code authentication logic into services.
+- Token and response caching must:
+  - Be explicitly enabled.
+  - Use abstract cache interfaces.
+- Framework-specific caches must be implemented via adapters.
+
+## 11. Framework Integrations
+
+- Framework integrations (Django, FastAPI, etc.) must:
+  - Be thin adapters.
+  - Avoid duplicating core logic.
+  - Only depend on the core through public interfaces.
+- No framework assumptions may leak back into the core.
+
+## 12. Testing and Mocking Expectations
+
+- Design all code to be testable without real network calls.
+- Avoid global state and singletons.
+- Prefer HTTP-level mocking over service stubbing.
+- Follow documented testing conventions and tooling.
+
+## 13. Documentation-Driven Development
+
+- When behavior is unclear:
+  - Search for existing documentation.
+  - Reference ADRs, README, or design docs.
+- If documentation is missing or outdated:
+  - Note the discrepancy.
+  - Suggest documentation updates.
+- Do **not** “invent” undocumented behavior.
+
+## 14. Code Generation & Refactoring Behavior
+
+- Favor small, incremental changes.
+- Keep changes aligned with existing patterns.
+- Avoid large refactors without architectural context.
+- Always preserve backward compatibility unless explicitly instructed otherwise.
+
+## 15. Decision Escalation Rules
+
+- If a change impacts:
+  - Public APIs
+  - Dependency structure
+  - Installation model
+  - Core abstractions
+  → Stop and request an architectural decision.
+- Do **not** silently introduce breaking changes.
+
+## 16. Branch Workflow Safety
+
+- Do **not** commit directly to `main` or `master` unless the user explicitly
+  approves this in the current conversation.
+- Implement new functionality on a dedicated branch first.
+- Before starting work on a branch name, check whether that branch already
+  exists on the remote and whether it has already been merged.
+- If a branch has already been merged remotely, do not reuse it for new work;
+  create a new branch.
+
+## 17. Repo Operating Profile
+
+Use this profile for day-to-day implementation decisions in this repository.
+
+### 17.1 Source Boundaries
+
+- Core framework-agnostic code lives in `src/plynt/base`, `src/plynt/http`,
+  `src/plynt/middleware`, and `src/plynt/cache`.
+- Connector-specific code lives under `src/plynt/connectors/*`.
+- `src/plynt/connectors/salesforce` is the active validation connector.
+- Keep connector-to-connector dependencies out of scope.
+- If shared behavior is needed, move it to a neutral core abstraction.
+
+### 17.2 Canonical Local Commands
+
+- Bootstrap: `make install`
+- Full local gate: `make check`
+- Lint only: `make lint`
+- Tests only: `make unittests`
+- Full test matrix: `make test-all`
+- Coverage report: `make coverage`
+
+When validating focused changes, prefer targeted pytest runs first, then run
+`make check` before final handoff.
+
+### 17.3 Testing Conventions
+
+- Use pytest test classes that map to the unit under test where practical.
+- Prefer HTTP-level mocking over service stubbing.
+- Keep tests deterministic and avoid time- or network-dependent flakiness.
+- For connector additions, maintain sync and async parity in both code and
+  tests.
+
+### 17.4 AI Connector Track Rules
+
+- `plynt.connectors.llm` and Salesforce AI services may progress in parallel.
+- Do not make the LLM connector depend on Salesforce internals.
+- Do not make Salesforce AI services depend on `plynt.connectors.llm`.
+- Share only transport, streaming, middleware, and typed core abstractions.
+
+### 17.5 ADR Trigger Checklist
+
+Stop and request an ADR before implementation if the change affects:
+
+- Public API shape or compatibility promises
+- Dependency model (including new runtime dependencies)
+- Installation extras or package extraction boundaries
+- Transport contracts (HTTP, streaming, gRPC, SOAP)
+- Core abstraction responsibilities across layers
+
+### 17.6 Local Tooling Artifacts
+
+- Local vstack artifacts may exist for developer workflow support.
+- Do not commit local-only generated vstack artifacts unless explicitly
+  requested for repository governance.
+- Keep `.gitignore` aligned so local vstack output stays out of commits by
+  default.
+
+---
+
+## 🧭 Meta-Instruction for Copilot and AI Agents
+
+- Act as an architectural contributor, not just a code generator.
+- Prefer referencing decisions, documentation, and constraints over guessing intent.
+- When uncertain, surface questions and propose ADRs instead of making assumptions.
+
+### Python file/module naming conventions
+
+- Use the singular form for modules (files) that define a single main concept (e.g., `request.py`, `response.py`, `client.py`).
+- Use the plural form for modules that contain a collection of related objects or utilities (e.g., `errors.py`, `settings.py`, `utils.py`).
+- Classes are always singular (e.g., `Request`, `Response`, `User`).
+- Packages (folders) are usually plural if they contain a collection (e.g., `models`, `services`), but singular is allowed if it fits the domain.
+- Follow the conventions of the Python standard library and popular frameworks for consistency.
+
+> Example: `request.py` and `response.py` for single data carriers; `errors.py` for multiple error types.
+
+### Class naming length and consistency
+
+- Before naming a new public class, check sibling classes already exported in
+  the same module's `__all__` and follow their established
+  `<Adjective><Domain><Concept>` pattern instead of inventing a new shape.
+- Avoid redundant words that repeat what a wrapped protocol or base type
+  already conveys (e.g. prefer `CacheSalesforceCDCCheckpointStore` over
+  `CacheBackendSalesforceCDCCheckpointStore` when the sibling
+  `InMemorySalesforceCDCCheckpointStore` already sets the pattern).
+- Renaming an already-exported public symbol touches the defining module, the
+  package `__init__.py` (import and `__all__`), tests, and any docs/how-to
+  examples referencing it. Grep the repository for the old name before
+  declaring a rename complete.

plynt-0.11.0/.github/dependabot.yml

@@ -0,0 +1,41 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    assignees:
+      - "eschaar"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      pip-patch-minor:
+        patterns:
+          - "*"
+        update-types:
+          - "patch"
+          - "minor"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    assignees:
+      - "eschaar"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "chore(ci)"
+    groups:
+      gha-patch-minor:
+        patterns:
+          - "*"
+        update-types:
+          - "patch"
+          - "minor"

plynt-0.11.0/.github/workflows/automerge.yml

@@ -0,0 +1,128 @@
+# Automerge workflow.
+# Purpose: automatically merge safe Dependabot pull requests without manual review.
+# Policy: auto-merge is enabled for:
+#   - github-actions ecosystem: patch and minor version updates
+#   - pip ecosystem: patch version updates only
+# Major version bumps and non-Dependabot PRs are never auto-merged.
+# Requires the repository setting "Allow auto-merge" to be enabled.
+name: "Dependabot Safe Auto-merge for Patch and Minor Updates"
+
+on:
+  pull_request_target:
+    branches:
+      - main
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    if: github.actor == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Fetch Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v3
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Decide if this PR is eligible
+        id: decision
+        env:
+          PACKAGE_ECOSYSTEM: ${{ steps.metadata.outputs.package-ecosystem }}
+          UPDATE_TYPE: ${{ steps.metadata.outputs.update-type }}
+        run: |
+          should_automerge=false
+
+          if [[ "$PACKAGE_ECOSYSTEM" == "github-actions" ]]; then
+            if [[ "$UPDATE_TYPE" == "version-update:semver-patch" || "$UPDATE_TYPE" == "version-update:semver-minor" ]]; then
+              should_automerge=true
+            fi
+          fi
+
+          if [[ "$PACKAGE_ECOSYSTEM" == "pip" ]]; then
+            if [[ "$UPDATE_TYPE" == "version-update:semver-patch" ]]; then
+              should_automerge=true
+            fi
+          fi
+
+          echo "should_automerge=$should_automerge" >> "$GITHUB_OUTPUT"
+          echo "package_ecosystem=$PACKAGE_ECOSYSTEM" >> "$GITHUB_OUTPUT"
+          echo "update_type=$UPDATE_TYPE" >> "$GITHUB_OUTPUT"
+
+      - name: Approve eligible PR
+        if: steps.decision.outputs.should_automerge == 'true'
+        uses: actions/github-script@v9
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            await github.rest.pulls.createReview({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.payload.pull_request.number,
+              event: "APPROVE",
+              body: "Auto-approved for safe Dependabot update policy."
+            })
+
+      - name: Update branch for eligible PR
+        if: steps.decision.outputs.should_automerge == 'true'
+        uses: actions/github-script@v9
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            // Intentional strategy:
+            // - Always request an update for eligible PRs instead of pre-checking merge state.
+            // - GitHub may report transient/unknown merge state during event handling.
+            // - updateBranch is idempotent; if already current, GitHub returns a benign 422/no-op.
+            // This keeps automerge flow deterministic without relying on flaky preconditions.
+            try {
+              await github.rest.pulls.updateBranch({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: context.payload.pull_request.number
+              })
+              core.info("Requested branch update from base branch.")
+            } catch (error) {
+              const msg = String(error.message || "")
+              if (error.status === 422 || msg.includes("not behind")) {
+                // Expected no-op path when branch is already up to date.
+                core.info("Branch already up to date; continuing.")
+              } else {
+                core.setFailed("Could not update branch before automerge. " + msg)
+              }
+            }
+
+      - name: Enable auto-merge for eligible PR
+        if: steps.decision.outputs.should_automerge == 'true'
+        uses: actions/github-script@v9
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            try {
+              await github.graphql(
+                `mutation($pullRequestId: ID!) {
+                  enablePullRequestAutoMerge(input: {pullRequestId: $pullRequestId, mergeMethod: SQUASH}) {
+                    pullRequest { number }
+                  }
+                }`,
+                { pullRequestId: context.payload.pull_request.node_id }
+              )
+            } catch (error) {
+              core.setFailed(
+                "Could not enable auto-merge. Ensure repository auto-merge is enabled and branch protections are satisfied.\n" +
+                error.message
+              )
+            }
+
+      - name: Log skipped PR
+        if: steps.decision.outputs.should_automerge != 'true'
+        run: |
+          echo "Automerge skipped by policy."
+          echo "ecosystem=${{ steps.decision.outputs.package_ecosystem }}"
+          echo "update_type=${{ steps.decision.outputs.update_type }}"