Merge branch 'main' into feature/aayush-oauth

Author: aayushsingh2502

README.md

@@ -1 +1,107 @@
-# python-tfe
+# HCP Terraform and Terraform Enterprise **Python** Client (pyTFE)
+
+[![PyPI](https://img.shields.io/pypi/v/pytfe.svg)](https://pypi.org/project/pytfe/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/pytfe.svg)](https://pypi.org/project/pytfe/)
+[![CI](https://github.com/hashicorp/python-tfe/actions/workflows/ci.yml/badge.svg)](https://github.com/hashicorp/python-tfe/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/hashicorp/python-tfe.svg)](./LICENSE)
+[![Issues](https://img.shields.io/github/issues/hashicorp/python-tfe.svg)](https://github.com/hashicorp/python-tfe/issues)
+
+The official **Python** API client for [HCP Terraform and Terraform Enterprise](https://www.hashicorp.com/products/terraform).
+
+This client targets the [HCP Terraform V2 API](https://developer.hashicorp.com/terraform/cloud-docs/api-docs).
+As Terraform Enterprise is the self-hosted distribution of HCP Terraform, this client supports both **HCP Terraform** and **Terraform Enterprise** use cases. In this repository and API, we refer to the platform generically as *Terraform Enterprise* unless a feature is explicitly called out as only supported in one or the other (rare).
+
+## Version Information
+
+We follow Semantic Versioning. During the initial alpha period we use `0.y.z`:
+- **Minor** (`0.y.z → 0.(y+1).z`): new, backwards-compatible features and enhancements.
+- **Patch** (`0.y.z → 0.y.(z+1)`): bug fixes and performance improvements.
+- Occasionally, a function signature change that fixes incorrect behavior may appear in a minor version.
+
+## Example Usage
+
+Construct a new **pyTFE** client, then use the resource services on the client to access different parts of the Terraform Enterprise API. The following example lists all organizations.
+
+### (Recommended) Using explicit config
+
+```python
+import os
+from pytfe import TFEClient, TFEConfig
+
+config = TFEConfig(
+    host="https://tfe.local",
+    token="insert-your-token-here",
+    retry_server_errors=True,
+    timeout=30.0,
+    user_agent="example-app/0.1 pytfe/0.1",
+)
+
+client = TFEClient(config)
+
+orgs = client.organizations.list()
+for org in orgs.items:
+    print(org.name)
+```
+
+### Using the default config with environment variables
+
+The default configuration reads the `TFE_ADDRESS` and `TFE_TOKEN` environment variables.
+
+1. `TFE_ADDRESS` — URL of an HCP Terraform or Terraform Enterprise instance. Example: `https://tfe.local`  
+2. `TFE_TOKEN` — An [API token](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens) for the HCP Terraform or Terraform Enterprise instance.
+
+
+Environment variables are used as a fallback when `host` or `token` are not provided explicitly:
+
+#### Using the default configuration
+```python
+from pytfe import TFEClient, TFEConfig
+
+# Equivalent to providing no values; falls back to env vars if set.
+client = TFEClient(TFEConfig())
+orgs = client.organizations.list()
+for org in orgs.items:
+    print(org.name)
+```
+
+#### When host or token is empty
+```python
+from pytfe import TFEClient, TFEConfig
+
+config = TFEConfig(address="", token="")
+client = TFEClient(config)
+
+orgs = client.organizations.list()
+for org in orgs.items:
+    print(org.name)
+```
+
+## Documentation
+
+- API reference and guides (SDK): **coming soon**  
+- Terraform Enterprise API: https://developer.hashicorp.com/terraform/enterprise/api-docs
+
+## Examples
+
+See the [`examples/`](./examples) directory for runnable snippets covering common workflows (workspaces, variables, configuration versions, runs/plans/applies, state, agents).
+
+## Running tests
+
+See [`TESTS.md`](./docs/TESTS.md). Typical flow:
+
+```bash
+pip install -e .[dev]
+make test
+```
+
+## Issues and Contributing
+
+See [`CONTRIBUTING.md`](./docs/CONTRIBUTING.md). We welcome issues and pull requests.
+
+## Releases
+
+See [`RELEASES.md`](./docs/RELEASES.md).
+
+## License
+
+This project is licensed under the **MPL-2.0**. See [`LICENSE`](./LICENSE).

doc/.keep

@@ -0,0 +1 @@
+# Contributing to pytfe

docs/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+## Release Process
+
+python-tfe can be released as often as required. Documentation updates and test fixes that only touch test files don't require a release or tag. You can just merge these changes into `main` once they have been approved.
+
+### Preparing a release
+
+Start by comparing the main branch with the last release in order to fully understand which changes are being released. Compare the last release tag with main. For each meaningful change, double check the following:
+
+1. Is the change added to CHANGELOG.md?
+2. Does the public package API follow all endpoint conventions, such as naming, pointer usage, and options availability? Once these are released, they are permanent in the current major release version.
+3. Are new features generally available in the HCP Terraform API? Or is there another considered reason to release them?
+
+Steps to prepare the changelog for a new release:
+
+1. Replace `# Unreleased` with the version you are releasing.
+2. Ensure there is a line with `# Unreleased` at the top of the changelog for future changes. Ideally we don't ask authors to add this line; this will make it clear where they should add their changelog entry.
+3. Ensure that each existing changelog entry for the new release has the author(s) attributed and a pull request linked, i.e `- Some new feature/bugfix by @some-github-user (#3)[link-to-pull-request]`
+4. Open a pull request with these changes titled `vX.XX.XX Changelog`. Once approved and merged, you can go ahead and create the release.
+
+### Creating a release
+
+1. [Create a new release in GitHub](https://help.github.com/en/github/administering-a-repository/creating-releases) by clicking on "Releases" and then "Draft a new release"
+2. Set the `Tag version` to a new tag, using [Semantic Versioning](https://semver.org/) as a guideline.
+3. Set the `Target` as `main`.
+4. Set the `Release title` to the tag you created, `vX.Y.Z`
+5. Use the description section to describe why you're releasing and what changes you've made. You should include links to merged PRs. Use the following headers in the description of your release:
+   - BREAKING CHANGES: Use this for any changes that aren't backwards compatible. Include details on how to handle these changes.
+   - FEATURES: Use this for any large new features added,
+   - ENHANCEMENTS: Use this for smaller new features added
+   - BUG FIXES: Use this for any bugs that were fixed.
+   - NOTES: Use this section if you need to include any additional notes on things like upgrading, upcoming deprecations, or any other information you might want to highlight.
+
+   Markdown example:
+
+   ```markdown
+   ENHANCEMENTS
+   * Add description of new small feature by @some-github-user (#3)[link-to-pull-request]
+
+   BUG FIXES
+   * Fix description of a bug by @some-github-user (#2)[link-to-pull-request]
+   * Fix description of another bug by @some-github-user (#1)[link-to-pull-request]
+   ```
+
+6. Don't attach any binaries. The zip and tar.gz assets are automatically created and attached after you publish your release.
+7. Click "Publish release" to save and publish your release.

docs/RELEASES.md

@@ -0,0 +1 @@
+# Running tests

docs/TESTS.md

@@ -0,0 +1,127 @@
+"""Simple Individual Agent operations example with the TFE Python SDK.
+
+This example demonstrates:
+1. Listing agents within agent pools
+2. Reading individual agent details
+3. Agent status monitoring
+4. Using the organization SDK client
+
+Note: Individual agents are created by running the agent binary, not through the API.
+This example shows how to manage agents that have already connected to agent pools.
+
+Make sure to set the following environment variables:
+- TFE_TOKEN: Your Terraform Cloud/Enterprise API token
+- TFE_ADDRESS: Your Terraform Cloud/Enterprise URL (optional, defaults to https://app.terraform.io)
+- TFE_ORG: Your organization name
+
+Usage:
+    export TFE_TOKEN="your-token-here"
+    export TFE_ORG="your-organization"
+    python examples/agent_simple.py
+"""
+
+import os
+
+from tfe.client import TFEClient
+from tfe.config import TFEConfig
+from tfe.errors import NotFound
+from tfe.models.agent import AgentListOptions
+
+
+def main():
+    """Main function demonstrating agent operations."""
+    # Get environment variables
+    token = os.environ.get("TFE_TOKEN")
+    org = os.environ.get("TFE_ORG")
+    address = os.environ.get("TFE_ADDRESS", "https://app.terraform.io")
+
+    if not token:
+        print("❌ TFE_TOKEN environment variable is required")
+        return 1
+
+    if not org:
+        print("❌ TFE_ORG environment variable is required")
+        return 1
+
+    # Create TFE client
+    config = TFEConfig(token=token, address=address)
+    client = TFEClient(config=config)
+
+    print(f"🔗 Connected to: {address}")
+    print(f"🏢 Organization: {org}")
+
+    try:
+        # Example 1: Find agent pools to demonstrate agent operations
+        print("\n📋 Finding agent pools...")
+        agent_pools = client.agent_pools.list(org)
+
+        # Convert to list to check if empty and get count
+        pool_list = list(agent_pools)
+        if not pool_list:
+            print("⚠️ No agent pools found. Create an agent pool first.")
+            return 1
+
+        print(f"Found {len(pool_list)} agent pools:")
+        for pool in pool_list:
+            print(f"  - {pool.name} (ID: {pool.id}, Agents: {pool.agent_count})")
+
+        # Example 2: List agents in each pool
+        print("\n🤖 Listing agents in each pool...")
+        total_agents = 0
+
+        for pool in pool_list:
+            print(f"\n📂 Agents in pool '{pool.name}':")
+
+            # Use optional parameters for listing
+            list_options = AgentListOptions(page_size=10)  # Optional parameter
+            agents = client.agents.list(pool.id, options=list_options)
+
+            # Convert to list to check if empty and iterate
+            agent_list = list(agents)
+            if agent_list:
+                total_agents += len(agent_list)
+                for agent in agent_list:
+                    print(f"  - Agent {agent.id}")
+                    print(f"    Name: {agent.name or 'Unnamed'}")
+                    print(f"    Status: {agent.status}")
+                    print(f"    Version: {agent.version or 'Unknown'}")
+                    print(f"    IP: {agent.ip_address or 'Unknown'}")
+                    print(f"    Last Ping: {agent.last_ping_at or 'Never'}")
+
+                    # Example 3: Read detailed agent information
+                    try:
+                        agent_details = client.agents.read(agent.id)
+                        print("    ✅ Agent details retrieved successfully")
+                        print(f"      Full name: {agent_details.name or 'Unnamed'}")
+                        print(f"      Current status: {agent_details.status}")
+                    except NotFound:
+                        print("    ⚠️ Agent details not accessible")
+                    except Exception as e:
+                        print(f"    ❌ Error reading agent details: {e}")
+
+                    print("")
+            else:
+                print("  No agents found in this pool")
+
+        if total_agents == 0:
+            print("\n⚠️ No agents found in any pools.")
+            print("To see agents in action:")
+            print("1. Create an agent pool")
+            print("2. Run a Terraform Enterprise agent binary connected to the pool")
+            print("3. Run this example again")
+        else:
+            print(f"\n📊 Total agents found across all pools: {total_agents}")
+
+        print("\n🎉 Agent operations completed successfully!")
+        return 0
+
+    except NotFound as e:
+        print(f"❌ Resource not found: {e}")
+        return 1
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    exit(main())