diff --git a/docs/source/reference/package-apis/client/index.md b/docs/source/reference/package-apis/client/index.md new file mode 100644 index 000000000..4f95f4f9d --- /dev/null +++ b/docs/source/reference/package-apis/client/index.md @@ -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 +``` diff --git a/docs/source/reference/package-apis/client/reference.md b/docs/source/reference/package-apis/client/reference.md new file mode 100644 index 000000000..18770096c --- /dev/null +++ b/docs/source/reference/package-apis/client/reference.md @@ -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__ +``` diff --git a/docs/source/reference/package-apis/index.md b/docs/source/reference/package-apis/index.md index df439ae3f..873747ec8 100644 --- a/docs/source/reference/package-apis/index.md +++ b/docs/source/reference/package-apis/index.md @@ -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 @@ -13,5 +14,6 @@ with custom hardware. :maxdepth: 1 :hidden: drivers/index.md +client/index.md exceptions.md ``` diff --git a/packages/jumpstarter/jumpstarter/config/client.py b/packages/jumpstarter/jumpstarter/config/client.py index 8cb24c504..ca631b465 100644 --- a/packages/jumpstarter/jumpstarter/config/client.py +++ b/packages/jumpstarter/jumpstarter/config/client.py @@ -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) @@ -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) @@ -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, @@ -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, @@ -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, @@ -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) @@ -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] @@ -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 @@ -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