TF-30335 Add Foundational SDK Core Framework and Structure #9

iam404 · 2025-09-08T08:31:52Z

Description

This PR lays the core foundation for a typed, ergonomic Python SDK for Terraform Enterprise.
It establishes a consistent HTTP transport with retries, JSON:API helpers, config loading, typed domain models, and resource services plus packaging and an example. This is the baseline we’ll grow into full TFE coverage.

Note: Organizations, Projects, Workspaces resources added here are not final draft.

Key Changes

Moved to hatchling, package name tfe.
Exposes TFEConfig, TFEClient, and errors as the primary import points.
HTTPTransport (Sync). Async Version is not tested. Retry policy & Error mapping.
src/tfe/client.py --> TFEClient:
Wires HTTPTransport from TFEConfig.
src/tfe/resources/_base.py --> base classes with pagination helpers. This need to be tested for all APIs.
src/tfe/types.py — Pydantic models and enums.
Python 3.9 support.

src/tfe/resources/workspaces.py

src/tfe/types.py

mukulmohan177 · 2025-09-08T08:56:13Z

tests/units/test_transport.py

@@ -0,0 +1,9 @@
+from tfe._http import HTTPTransport


I understand you have deleted the old tests because the new codebase has new class names, locations, and API surfaces, so the old tests would fail. Ensure you have a ticket for this at a later time.

src/tfe/_http.py

mukulmohan177 · 2025-09-08T09:00:52Z

src/tfe/_http.py

+
+    async def _asleep(self, attempt: int, retry_after: float | None):
+        if retry_after is not None: await anyio.sleep(retry_after); return
+        delay = min(self.backoff_cap, self.backoff_base * (2 ** attempt))


backoff_jitter is accepted in init but not applied here. Consider adding random jitter to the delay.

Ignore async methods, Async are not thoroughly tested.

src/tfe/types.py

examples/ws_list.py

Copilot

Pull Request Overview

This PR introduces a comprehensive rewrite of the python-tfe library to establish a modern, typed SDK foundation for Terraform Enterprise/Cloud. The changes include migrating to Pydantic-based models, implementing robust HTTP transport with retry logic, and restructuring the project for better maintainability and extensibility.

Replaced simple dataclass configuration with Pydantic-based TFEConfig and comprehensive error handling
Introduced HTTPTransport with retry policies and proper JSON:API support
Created typed domain models and resource services for Organizations, Projects, and Workspaces

Reviewed Changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pyproject.toml	Updated build system to hatchling, changed package name to "tfe", added new dependencies
src/tfe/init.py	New module exports for TFEConfig, TFEClient, and errors
src/tfe/config.py	New Pydantic-based configuration with environment variable support
src/tfe/client.py	New TFEClient implementation using HTTPTransport
src/tfe/_http.py	HTTP transport layer with retry logic and error mapping
src/tfe/errors.py	Comprehensive error hierarchy for different API conditions
src/tfe/types.py	Pydantic models for core domain objects
src/tfe/resources/*.py	Resource service implementations for Organizations, Projects, Workspaces
examples/ws_list.py	Example usage of the new SDK
tests/units/*.py	Updated test files for new structure

Comments suppressed due to low confidence (1)

pyproject.toml:1

The classifier for Python 3.9 is missing but the project requires Python >=3.9. Add 'Programming Language :: Python :: 3.9', to the classifiers list.

[build-system]

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-09-08T11:22:12Z

src/tfe/resources/workspaces.py

+    return ExecutionMode._value2member_map_.get(v)  # type: ignore[return-value]
+
+


Accessing private attribute _value2member_map_ is not recommended. Use the public try/except ValueError pattern with ExecutionMode(v) instead.

Suggested change

return ExecutionMode._value2member_map_.get(v) # type: ignore[return-value]

try:

return ExecutionMode(v)

except ValueError:

return None

Copilot · 2025-09-08T11:22:12Z

src/tfe/_http.py

+        self._sync = httpx.Client(
+            http2=http2, timeout=timeout, verify=ca_bundle or verify_tls
+        )  # proxies=proxies
+        self._async = httpx.AsyncClient(
+            http2=http2, timeout=timeout, verify=ca_bundle or verify_tls
+        )  # proxies=proxies


The commented out proxies=proxies suggests incomplete implementation. Either implement proxy support or remove the commented code and the proxies parameter if not needed.

Suggested change

self._sync = httpx.Client(

http2=http2, timeout=timeout, verify=ca_bundle or verify_tls

) # proxies=proxies

self._async = httpx.AsyncClient(

http2=http2, timeout=timeout, verify=ca_bundle or verify_tls

) # proxies=proxies

client_kwargs = {

"http2": http2,

"timeout": timeout,

"verify": ca_bundle or verify_tls,

}

if proxies is not None:

client_kwargs["proxies"] = proxies

self._sync = httpx.Client(**client_kwargs)

self._async = httpx.AsyncClient(**client_kwargs)

Copilot · 2025-09-08T11:22:12Z

src/tfe/resources/_base.py

+
+
+"""
+Warning: Do Not Use this Async Service as its not stable with HashiCorp API.


Grammar error: 'its' should be 'it's' (it is). Should read: 'Warning: Do Not Use this Async Service as it's not stable with HashiCorp API.'

Suggested change

Warning: Do Not Use this Async Service as its not stable with HashiCorp API.

Warning: Do Not Use this Async Service as it's not stable with HashiCorp API.

mukulmohan177

It looks good. The core abstractions (TFEClient, config, transport, and resource layers) are thoughtfully designed and this can be extended in the future meeting our scalability requirements.

KshitijaChoudhari · 2025-09-08T14:05:45Z

Summary Table

Area	Issue/Concern	Action Required

Enum Handling | Unsafe enum construction | No action required, enum will be added as a class later
Pydantic Models | Mutable default list | Best Practice: Use Field(default_factory=list) , but given version wshould not cause any issues |
HTTP Proxies | Parameter not implemented | Implement -> more research needed, team will take a look |
Async Services | Not supported/stable | Currently async not supported, should be fine |
Tests | Insufficient coverage | Add more tests in later PRs |
Documentation | Missing docstrings & usage | Add more docs when more Code is submitted |

TF-30335 Add Foundational SDK Core Framework and Structure

fec08a8

iam404 requested a review from a team as a code owner September 8, 2025 08:31

remove older test cases

6a33784

mukulmohan177 reviewed Sep 8, 2025

View reviewed changes

src/tfe/resources/workspaces.py Outdated Show resolved Hide resolved

mukulmohan177 reviewed Sep 8, 2025

View reviewed changes

src/tfe/types.py Outdated Show resolved Hide resolved

mukulmohan177 reviewed Sep 8, 2025

View reviewed changes

src/tfe/_http.py Show resolved Hide resolved

mukulmohan177 reviewed Sep 8, 2025

View reviewed changes

Ruff formatter rerun

da056ef

KshitijaChoudhari reviewed Sep 8, 2025

View reviewed changes

src/tfe/types.py Outdated Show resolved Hide resolved

KshitijaChoudhari reviewed Sep 8, 2025

View reviewed changes

examples/ws_list.py Outdated Show resolved Hide resolved

iam404 added 4 commits September 8, 2025 15:27

Fix runff checks

b070f02

Fix mypy lint errors / warning

73da74f

fix ruff formating

21485c7

ruff check fixes

73be753

isivaselvan requested a review from Copilot September 8, 2025 11:21

Copilot AI reviewed Sep 8, 2025

View reviewed changes

mukulmohan177 approved these changes Sep 8, 2025

View reviewed changes

iam404 merged commit 0bce1e1 into main Sep 8, 2025
11 checks passed

		return ExecutionMode._value2member_map_.get(v) # type: ignore[return-value]

-    return ExecutionMode._value2member_map_.get(v)  # type: ignore[return-value]
+    try:
+        return ExecutionMode(v)
+    except ValueError:
+        return None

-        self._sync = httpx.Client(
-            http2=http2, timeout=timeout, verify=ca_bundle or verify_tls
-        )  # proxies=proxies
-        self._async = httpx.AsyncClient(
-            http2=http2, timeout=timeout, verify=ca_bundle or verify_tls
-        )  # proxies=proxies
+        client_kwargs = {
+            "http2": http2,
+            "timeout": timeout,
+            "verify": ca_bundle or verify_tls,
+        }
+        if proxies is not None:
+            client_kwargs["proxies"] = proxies
+        self._sync = httpx.Client(**client_kwargs)
+        self._async = httpx.AsyncClient(**client_kwargs)



		"""
		Warning: Do Not Use this Async Service as its not stable with HashiCorp API.

TF-30335 Add Foundational SDK Core Framework and Structure #9

TF-30335 Add Foundational SDK Core Framework and Structure #9

Uh oh!

Conversation

iam404 commented Sep 8, 2025

Description

Key Changes

Uh oh!

Uh oh!

Uh oh!

mukulmohan177 Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mukulmohan177 Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

iam404 Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

mukulmohan177 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

KshitijaChoudhari commented Sep 8, 2025

Summary Table

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants