Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions docs/source/reference/package-apis/client/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Client API

This section provides reference documentation for Jumpstarter's client APIs. Covering topics such as:

- Listing exporters
- Requesting a lease
- Listing leases

please see the [Client API Reference](reference.md) for more details.

## Listing Exporters

The client library provides a function to list all exporters in the cluster.

```python
from jumpstarter.config.client import ClientConfigV1Alpha1

client = ClientConfigV1Alpha1.from_file("~/.config/jumpstarter/clients/majopela.yaml")
response = client.list_exporters(include_leases=True, include_online=True, page_size=1000)
for exporter in response.exporters:
if exporter.online:
print(exporter.name)
print(exporter.lease)

print("next page token: ", response.next_page_token)
```

```{toctree}
:maxdepth: 1
:hidden:
reference.md
```
24 changes: 24 additions & 0 deletions docs/source/reference/package-apis/client/reference.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Client API Reference

## Loading config files
```{eval-rst}
.. autoclass:: jumpstarter.config.client.ClientConfigV1Alpha1()
:members: from_file, from_env, load, list
:exclude-members: __init__
```

## Manipulating config files
```{eval-rst}
.. autoclass:: jumpstarter.config.client.ClientConfigV1Alpha1()
:no-index:
:members: save, dump_yaml, list, delete
:exclude-members: __init__
```

## Interact with the service
```{eval-rst}
.. autoclass:: jumpstarter.config.client.ClientConfigV1Alpha1()
:no-index:
:members: get_exporter, list_exporters, create_lease, delete_lease, lease, list_leases, update_lease
:exclude-members: __init__
```
Comment on lines +3 to +24
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify that all documented methods exist and have proper docstrings in the source file.

The documentation references 14 methods across three sections. Per the AI summary, docstrings were added to methods in packages/jumpstarter/jumpstarter/config/client.py, but I need to verify that all referenced methods exist and are properly documented.

Additionally, the list method appears in both section 1 (line 6) and section 2 (line 14). Please clarify if this is intentional (a shared utility method used in both loading and manipulating contexts) or if it should only appear in one section.


🏁 Script executed:

#!/bin/bash
# Description: Verify that all methods referenced in the documentation exist in ClientConfigV1Alpha1
# and have docstrings (non-empty __doc__ attributes).

# Find the client config file
config_file=$(fd -t f "client\.py" packages/jumpstarter/jumpstarter/config/ 2>/dev/null | head -1)

if [ -z "$config_file" ]; then
  echo "Error: Could not find client.py in packages/jumpstarter/jumpstarter/config/"
  exit 1
fi

echo "Checking file: $config_file"
echo ""

# List of methods to verify
methods=(
  "from_file" "from_env" "load" "list"
  "save" "dump_yaml" "delete"
  "get_exporter" "list_exporters" "create_lease" "delete_lease" "lease" "list_leases" "update_lease"
)

# Search for class definition and each method
echo "Verifying ClientConfigV1Alpha1 class and methods:"
rg -A 300 "class ClientConfigV1Alpha1" "$config_file" | head -400

Length of output: 11944


Remove the non-existent delete method from the documentation.

The delete method referenced in section 2 ("Manipulating config files", line 14) does not exist in the ClientConfigV1Alpha1 class. All other documented methods exist with proper docstrings. Remove delete from the :members: list in the second autoclass directive.

The list method appearing in both section 1 and section 2 is valid—it applies to both loading and manipulating workflows.

🤖 Prompt for AI Agents
In docs/source/reference/package-apis/client/reference.md around lines 3 to 24,
the second autoclass block under "Manipulating config files" incorrectly lists a
non-existent method `delete`; remove `delete` from the `:members:` list in that
second block so it reads only `save, dump_yaml, list` (preserving the existing
`:no-index:` and `:exclude-members:` lines).

2 changes: 2 additions & 0 deletions docs/source/reference/package-apis/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ This section provides reference documentation for Jumpstarter's package APIs and
components. The documentation covers:

- [Drivers](drivers/index.md): APIs for various driver categories
- [Client API](client/index.md): APIs for the client library: listing exporters, requesting a lease, etc.
- [Exceptions](exceptions.md): Exceptions raised by driver clients

These references are useful for developers extending Jumpstarter or integrating
Expand All @@ -13,5 +14,6 @@ with custom hardware.
:maxdepth: 1
:hidden:
drivers/index.md
client/index.md
exceptions.md
```
46 changes: 46 additions & 0 deletions packages/jumpstarter/jumpstarter/config/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,7 @@ async def get_exporter(
self,
name: str,
):
"""Gets an exporter by name."""
svc = ClientService(channel=await self.channel(), namespace=self.metadata.namespace)
return await svc.GetExporter(name=name)

Expand All @@ -161,6 +162,20 @@ async def list_exporters(
include_leases: bool = False,
include_online: bool = False,
):
"""Lists exporters.

Args:
* page_size: The number of exporters to return.
* page_token: The token to use to get the next page of exporters.
* filter: A filter to apply to the list of exporters.
* include_leases: Whether to include leases in the response.
* include_online: Whether to include online status in the response.
Returns:
.exporters: list[Exporter]
.next_page_token: str | None
.include_online: bool : Whether to include online status in the response.
.include_leases: bool : Whether to include leases in the response.
"""
svc = ClientService(channel=await self.channel(), namespace=self.metadata.namespace)
exporters_response = await svc.ListExporters(page_size=page_size, page_token=page_token, filter=filter)

Expand Down Expand Up @@ -202,6 +217,13 @@ async def create_lease(
duration: timedelta,
begin_time: datetime | None = None,
):
"""Creates a lease request.

Args:
* selector: The selector to use to create the lease.
* duration: The duration of the lease.
* begin_time: The beginning time of the lease.
"""
svc = ClientService(channel=await self.channel(), namespace=self.metadata.namespace)
return await svc.CreateLease(
selector=selector,
Expand All @@ -215,6 +237,7 @@ async def delete_lease(
self,
name: str,
):
"""Deletes a lease by name."""
svc = ClientService(channel=await self.channel(), namespace=self.metadata.namespace)
await svc.DeleteLease(
name=name,
Expand All @@ -229,6 +252,17 @@ async def list_leases(
filter: str | None = None,
only_active: bool = True,
):
"""Lists leases.

Args:
* page_size: The number of leases to return.
* page_token: The token to use to get the next page of leases.
* filter: A filter to apply to the list of leases.
* only_active: Whether to only include active leases.
Returns:
.leases: list[Lease]
.next_page_token: str | None
"""
svc = ClientService(channel=await self.channel(), namespace=self.metadata.namespace)
return await svc.ListLeases(
page_size=page_size,
Expand All @@ -245,6 +279,15 @@ async def update_lease(
duration: timedelta | None = None,
begin_time: datetime | None = None,
):
"""Updates a lease by name.
Can be used to extend the duration of an active lease, or modify the desired begin
time and duration of a lease request.

Args:
* name: The name of the lease to update.
* duration: The duration of the lease.
* begin_time: The beginning time of the lease.
"""
svc = ClientService(channel=await self.channel(), namespace=self.metadata.namespace)
return await svc.UpdateLease(name=name, duration=duration, begin_time=begin_time)

Expand Down Expand Up @@ -290,6 +333,7 @@ async def lease_async(

@classmethod
def from_file(cls, path: os.PathLike):
"""Loads a client config from a file path."""
with open(path) as f:
v = cls.model_validate(yaml.safe_load(f))
v.alias = os.path.basename(path).split(".")[0]
Expand All @@ -310,6 +354,7 @@ def try_from_env(cls):

@classmethod
def from_env(cls):
"""Loads a client config from the environment variables."""
return cls()

@classmethod
Expand Down Expand Up @@ -341,6 +386,7 @@ def save(cls, config: Self, path: Optional[os.PathLike] = None) -> Path:

@classmethod
def dump_yaml(cls, config: Self) -> str:
"""Dumps a client config as YAML."""
return yaml.safe_dump(config.model_dump(mode="json", exclude={"path", "alias"}), sort_keys=False)

@classmethod
Expand Down