🚀 Add Explorer API (v2) support to pytfe

[jasodeep]

📌 Description

This PR adds support for the HCP Terraform / Terraform Enterprise Explorer API (v2) to pytfe, exposed via:

TFEClient.explorer

The Explorer API enables organization-scoped visibility and analytics, including:

• Workspaces
• Terraform versions
• Registry providers
• Modules

It also supports:

• CSV export
• Saved views (CRUD operations)
• Re-running saved views (JSON / CSV)

This implementation covers public v2 routes under:

/api/v2/organizations/:organization/explorer
/api/v2/organizations/:organization/explorer/views/*

---

✨ Changes Included

📦 Models

• Added new Pydantic models:

  • src/pytfe/models/explorer.py

• Exported models via:

  • src/pytfe/models/__init__.py

🔧 Resources

• Added new resource:

  • Explorer → src/pytfe/resources/explorer.py

• Pagination aligned with existing _Service patterns

🧠 Client

• Added:

  TFEClient.explorer

  in src/pytfe/client.py

❗ Errors

• Introduced:

  • InvalidExplorerSavedViewIDError in src/pytfe/errors.py

🧪 Tests

• Added unit tests with mocked HTTP:

  • tests/units/test_explorer.py

📘 Examples

• Added usage example:

  • examples/explorer.py

📝 Changelog

• Updated:

  • CHANGELOG.md under v0.2.0 (Unreleased)

---

🧪 Testing Plan

🔹 Local (No live cluster)

make dev-install   # Python ≥ 3.10
make check
make test

---

🔹 Optional (Live HCP Terraform / TFE)

Set environment variables:

export TFE_ADDRESS=<your-address>
export TFE_TOKEN=<your-token>
export TFE_ORGANIZATION=<your-org>

Run:

python examples/explorer.py

Optional (Saved View flows)

export TFE_EXPLORER_VIEW_ID=<view-id>
export TFE_EXPLORER_DEMO_MUTATIONS=1

⚠️ This will perform create/update/delete operations on a uniquely named view.

Ensure:

• Token has required Explorer API permissions
• Organization access is valid

---

🔄 Rollback Plan

• Revert this PR from main

• Removes:

  • client.explorer
  • Explorer models/resources/tests

✅ No infra or migration rollback required

---

🔐 Changes to Security Controls

• No changes in this repository

• Authentication:

  • Uses existing HTTPTransport + bearer token

• Authorization:

  • Enforced by HCP Terraform / TFE APIs

---

✅ PCI Review Checklist

• Clear description and justification provided
• Rollback plan documented (PR revert sufficient)
• No changes to security controls

---

🧾 CONTRIBUTING Checklist

• Code formatted (make fmt)
• Lint passes (make lint)
• Type checks pass (make type-check)
• Tests pass (make test)
• Unit tests added for new functionality
• CHANGELOG.md updated
• Example added under examples/
• Docstrings added for public classes/methods

[hashicorp-cla-app]

All committers have signed the CLA.

[rigalGit]

Looks good, please check some minor comments.