move to iterrator

Author: iam404

README.md

@@ -36,8 +36,7 @@ config = TFEConfig(
 
 client = TFEClient(config)
 
-orgs = client.organizations.list()
-for org in orgs.items:
+for org in client.organizations.list():
     print(org.name)
 ```
 
@@ -57,8 +56,7 @@ 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:
+for org in client.organizations.list():
     print(org.name)
 ```
 
@@ -69,11 +67,32 @@ from pytfe import TFEClient, TFEConfig
 config = TFEConfig(address="", token="")
 client = TFEClient(config)
 
-orgs = client.organizations.list()
-for org in orgs.items:
+for org in client.organizations.list():
     print(org.name)
 ```
 
+## Listing resources
+
+Anything named `list` or `list_*` on a resource service returns an **iterator**, not a Python `list`. Pagination is handled for you under the hood — the iterator keeps fetching pages from the API until there are no more. This mirrors the underlying HCP Terraform API, where every list endpoint is paginated (`page[number]` / `page[size]`), and keeps memory flat even when an organization has thousands of workspaces or runs.
+
+You'll use it one of two ways:
+
+```python
+# Stream — handy when you might break early or when results are large
+for ws in client.workspaces.list("my-org"):
+    if ws.name.startswith("prod-"):
+        print(ws.id, ws.name)
+
+# Materialize — when you actually want a list to index, len(), or pass around
+workspaces = list(client.workspaces.list("my-org"))
+print(f"found {len(workspaces)} workspaces")
+```
+
+A couple of things worth knowing:
+
+- The iterator is **single-use**. Once you've walked it, iterating again gives you nothing. Capture it with `list(...)` first if you need to reuse the result.
+- Filters and page size live on the `*ListOptions` model for each resource — e.g. `WorkspaceListOptions(search="prod", page_size=50)`. Pagination still happens transparently; `page_size` only controls how big each underlying API page is.
+
 ## Documentation
 
 - API reference and guides (SDK): **coming soon**  

examples/registry_module.py

@@ -304,8 +304,7 @@ def main():
                 registry_name=RegistryName.PRIVATE,
             )
 
-            versions = client.registry_modules.list_versions(module_id)
-            versions_list = list(versions) if hasattr(versions, "__iter__") else []
+            versions_list = list(client.registry_modules.list_versions(module_id))
             print(f"Found {len(versions_list)} versions")
 
             for i, version in enumerate(versions_list[:3], 1):

examples/team.py

@@ -240,7 +240,7 @@ def main():
             )
         if args.list_members:
             _print_header(f"Listing members of team {args.team_id}")
-            users = client.teams.list_users(args.team_id)
+            users = list(client.teams.list_users(args.team_id))
             print(f"users ({len(users)}):")
             for u in users:
                 print(f"  - {u.id} {getattr(u, 'username', '')}")

src/pytfe/resources/registry_module.py

@@ -217,8 +217,15 @@ def read_version(
 
         return self._parse_registry_module_version(data)
 
-    def list_versions(self, module_id: RegistryModuleID) -> list[RegistryModuleVersion]:  # type: ignore[valid-type]
-        """List all versions of a registry module."""
+    def list_versions(
+        self, module_id: RegistryModuleID
+    ) -> Iterator[RegistryModuleVersion]:
+        """List all versions of a registry module.
+
+        The endpoint returns all versions in a single response (no pagination),
+        but the signature matches the rest of the SDK — wrap in ``list(...)``
+        if you need a materialized list.
+        """
         if not self._validate_module_id(module_id):
             raise ValueError("Invalid module ID")
 
@@ -241,12 +248,12 @@ def list_versions(self, module_id: RegistryModuleID) -> list[RegistryModuleVersi
             # Handle the case where data might be None or empty
             data = response_data.get("data", []) if response_data else []
 
-            versions = []
+            versions: list[RegistryModuleVersion] = []
             for item in data:
                 if item:  # Skip None items
                     versions.append(self._parse_registry_module_version(item))
 
-            return versions
+            return iter(versions)
 
         except Exception:
             # Fallback: If the API endpoint doesn't exist, try to get versions from the module itself
@@ -270,9 +277,9 @@ def list_versions(self, module_id: RegistryModuleID) -> list[RegistryModuleVersi
                     }
                     versions.append(self._parse_registry_module_version(version_data))
 
-                return versions
+                return iter(versions)
             except Exception:
-                return []  # Return empty list if all methods fail
+                return iter([])  # Return empty iterator if all methods fail
 
     def read_terraform_registry_module(
         self, module_id: RegistryModuleID, version: str

src/pytfe/resources/team.py

@@ -190,10 +190,14 @@ def remove_organization_memberships(
         )
         return None
 
-    def list_users(self, team_id: str) -> list[User]:
+    def list_users(self, team_id: str) -> Iterator[User]:
         """List the users that belong to a team.
 
-        Implemented via ``GET /teams/{id}?include=users``.
+        Implemented via ``GET /teams/{id}?include=users`` — the API has no
+        dedicated paginated endpoint for team users, so all results arrive
+        in a single response. The signature still returns an iterator to
+        stay consistent with the other ``list_*`` methods in the SDK; wrap
+        the result in ``list(...)`` if you need a materialized list.
         """
         if not valid_string_id(team_id):
             raise InvalidTeamIDError()
@@ -204,14 +208,12 @@ def list_users(self, team_id: str) -> list[User]:
         )
         payload = r.json() or {}
         included = payload.get("included") or []
-        users: list[User] = []
         for inc in included:
             if inc.get("type") != "users":
                 continue
             attrs = dict(inc.get("attributes") or {})
             attrs["id"] = inc.get("id")
-            users.append(User.model_validate(attrs))
-        return users
+            yield User.model_validate(attrs)
 
     def list_organization_memberships(
         self,