chore: enhance API reference for SDK clients by Priyanshu-u07 · Pull Request #262 · kubeflow/sdk

Priyanshu-u07 · 2026-02-03T18:46:23Z

Description

This PR improves the API reference documentation for Kubeflow SDK clients by
expanding docstrings with clearer descriptions, parameters, return types,
error details, and practical usage examples.

These documentation-only changes improve developer experience without
modifying any runtime behavior or public APIs.

Fixes #260

Checklist:

Docs included if any changes are user facing

google-oss-prow · 2026-02-03T18:46:30Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign andreyvelich for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

github-actions · 2026-02-03T18:46:38Z

🎉 Welcome to the Kubeflow SDK! 🎉

Thanks for opening your first PR! We're happy to have you as part of our community 🚀

Here's what happens next:

If you haven't already, please check out our Contributing Guide for repo-specific guidelines and the Kubeflow Contributor Guide for general community standards
Our team will review your PR soon! cc @kubeflow/kubeflow-sdk-team

Join the community:

Slack: Join our #kubeflow-ml-experience and #kubeflow-trainer Slack channels
Meetings: Attend the Kubeflow SDK and ML Experience bi-weekly meetings

Feel free to ask questions in the comments if you need any help or clarification!
Thanks again for contributing to Kubeflow! 🙏

Copilot

Pull request overview

This PR enhances the auto-generated API reference for Kubeflow SDK clients by expanding method docstrings with clearer descriptions, return/raise details, and runnable usage examples (aimed at improving developer experience without changing intended runtime behavior).

Changes:

Expanded docstrings across TrainerClient, OptimizerClient, and ModelRegistryClient with richer parameter/return/raise sections.
Added practical usage examples for common client workflows (list/get/create/wait/delete/logs/events).
Clarified semantics around defaults (timeouts, polling, inferred connection settings).

Reviewed changes

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

File	Description
`kubeflow/trainer/api/trainer_client.py`	Docstring expansions and examples for Trainer client methods; one type-annotation change introduced.
`kubeflow/optimizer/api/optimizer_client.py`	Docstring expansions and examples for Optimizer client methods (optimize/jobs/logs/results/wait/events).
`kubeflow/hub/api/model_registry_client.py`	Docstring expansions and examples for Model Registry operations and connection options.

Copilot · 2026-02-26T23:09:35Z

kubeflow/trainer/api/trainer_client.py

+
+            client = TrainerClient()
+            job = client.wait_for_job_status(
+                name="my-job", 
+                status={constants.TRAINJOB_COMPLETE}


In the example, from kubeflow.trainer import constants imports the kubeflow.trainer.constants package (whose __init__.py is empty), so constants.TRAINJOB_COMPLETE will not exist; import the constants module/values instead (e.g., from kubeflow.trainer.constants import constants or from kubeflow.trainer.constants.constants import TRAINJOB_COMPLETE).

Copilot · 2026-02-26T23:09:35Z

kubeflow/optimizer/api/optimizer_client.py

+            }
+
+            # Define objective
+            objectives = [Objective(name="accuracy", goal=0.99, type="maximize")]


The example creates Objective(name=..., goal=..., type=...), but Objective is defined with fields metric and direction, so this snippet will raise TypeError if copied; update the example to match Objective(metric="accuracy", direction="maximize") (or similar).

Suggested change

objectives = [Objective(name="accuracy", goal=0.99, type="maximize")]

objectives = [Objective(metric="accuracy", direction="maximize")]

Copilot · 2026-02-26T23:09:36Z

kubeflow/optimizer/api/optimizer_client.py

+            job_name = client.optimize(
+                trial_template=tpl,


The optimize() example passes trial_template=tpl but tpl is not defined in the example, so readers can't run it as-is; either show how to construct a TrainJobTemplate or rename it to a clearly-marked placeholder (e.g., trial_template=my_template).

Suggested change

job_name = client.optimize(

trial_template=tpl,

# Assume `my_template` is a TrainJobTemplate defined elsewhere

job_name = client.optimize(

trial_template=my_template,

Copilot · 2026-02-26T23:09:36Z

kubeflow/optimizer/api/optimizer_client.py

        Returns:
-            A Result object containing the best hyperparameters and metrics, or None if
-            no best trial is available yet.
+            Optional[kubeflow.optimizer.types.Result]: A object containing the 


Grammar: "A object" should be "An object" in the return description.

Suggested change

Optional[kubeflow.optimizer.types.Result]: A object containing the

Optional[kubeflow.optimizer.types.Result]: An object containing the

Copilot · 2026-02-26T23:09:36Z

kubeflow/optimizer/api/optimizer_client.py

        Returns:
-            List of created OptimizationJobs. If no OptimizationJob exist,
-                an empty list is returned.
+            list[kubeflow.optimizer.types.OptimizationJob]: A list of created 
+                OptimizationJobs. If no jobs exist, an empty list is returned.


The docstring return types reference kubeflow.optimizer.types.OptimizationJob, but kubeflow.optimizer.types is not a public module exporting these symbols (they live under kubeflow.optimizer.types.optimization_types and are also re-exported from kubeflow.optimizer); use a resolvable fully-qualified path to avoid broken/incorrect API references.

Copilot · 2026-02-26T23:09:36Z

kubeflow/optimizer/api/optimizer_client.py


        Returns:
-            A list of Event objects associated with the OptimizationJob.
+            list[kubeflow.trainer.types.Event]: A list of Event objects 


The return type in the docstring points to kubeflow.trainer.types.Event, but Event is defined in kubeflow.trainer.types.types (and imported here from that module), so the displayed fully-qualified type will be incorrect; update the reference to a resolvable path (or just list[Event]).

Suggested change

list[kubeflow.trainer.types.Event]: A list of Event objects

list[Event]: A list of Event objects

Copilot · 2026-02-26T23:09:37Z

kubeflow/trainer/api/trainer_client.py


-    def list_jobs(self, runtime: types.Runtime | None = None) -> list[types.TrainJob]:
-        """List of the created TrainJobs. If a runtime is specified, only TrainJobs associated with
+    def list_jobs(self, runtime: Optional[types.Runtime] = None) -> list[types.TrainJob]:


list_jobs uses Optional[...] in its type annotation but Optional is not imported (and this module does not use postponed evaluation of annotations), which will raise a NameError at import time; import Optional from typing or switch back to types.Runtime | None.

Suggested change

def list_jobs(self, runtime: Optional[types.Runtime] = None) -> list[types.TrainJob]:

def list_jobs(self, runtime: types.Runtime | None = None) -> list[types.TrainJob]:

Copilot · 2026-02-26T23:09:37Z

kubeflow/trainer/api/trainer_client.py

        Returns:
-            A list of available training runtimes. If no runtimes exist, an empty list is returned.
+            list[kubeflow.trainer.types.Runtime]: A list of available training 
+                runtimes. If no runtimes exist, an empty list is returned.


The docstring return types reference kubeflow.trainer.types.Runtime, but kubeflow.trainer.types does not export these symbols (they live in kubeflow.trainer.types.types and are also re-exported from kubeflow.trainer), so the fully-qualified type names shown in the API reference will be misleading; use a resolvable path like kubeflow.trainer.Runtime/kubeflow.trainer.types.types.Runtime (and apply consistently for TrainJob/Event as well).

Copilot · 2026-02-26T23:09:37Z

kubeflow/optimizer/api/optimizer_client.py

+            from kubeflow.optimizer import OptimizerClient, constants
+
+            client = OptimizerClient()
+            job = client.wait_for_job_status(
+                name="my-opt-job", 
+                status={constants.OPTIMIZATION_JOB_COMPLETE}


In the example, from kubeflow.optimizer import constants imports the kubeflow.optimizer.constants package (empty __init__.py), so constants.OPTIMIZATION_JOB_COMPLETE will not exist; import the constants module/values instead (e.g., from kubeflow.optimizer.constants import constants).

Suggested change

from kubeflow.optimizer import OptimizerClient, constants

client = OptimizerClient()

job = client.wait_for_job_status(

name="my-opt-job",

status={constants.OPTIMIZATION_JOB_COMPLETE}

from kubeflow.optimizer import OptimizerClient

from kubeflow.optimizer.constants import constants

client = OptimizerClient()

job = client.wait_for_job_status(

name="my-opt-job",

status={constants.OPTIMIZATION_JOB_COMPLETE},

Signed-off-by: Priyanshu-u07 <connect.priyanshu8271@gmail.com>

Signed-off-by: Priyanshu Kumar <connect.priyanshu8271@gmail.com>

google-oss-prow bot requested review from fege and szaher February 3, 2026 18:46

google-oss-prow bot added the size/XL label Feb 3, 2026

Priyanshu-u07 changed the title ~~docs: enhance API reference for SDK clients~~ chore: enhance API reference for SDK clients Feb 3, 2026

Copilot AI review requested due to automatic review settings February 26, 2026 23:05

Copilot started reviewing on behalf of Priyanshu-u07 February 26, 2026 23:05 View session

Copilot AI reviewed Feb 26, 2026

View reviewed changes

docs: enhance API reference for SDK clients

b46e396

Signed-off-by: Priyanshu-u07 <connect.priyanshu8271@gmail.com>

Priyanshu-u07 force-pushed the docs/api-reference branch from c957abd to b46e396 Compare February 26, 2026 23:23

Merge branch 'main' into docs/api-reference

bc283dd

Signed-off-by: Priyanshu Kumar <connect.priyanshu8271@gmail.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: enhance API reference for SDK clients#262

chore: enhance API reference for SDK clients#262
Priyanshu-u07 wants to merge 2 commits intokubeflow:mainfrom
Priyanshu-u07:docs/api-reference

Priyanshu-u07 commented Feb 3, 2026

Uh oh!

google-oss-prow bot commented Feb 3, 2026

Uh oh!

github-actions bot commented Feb 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 26, 2026

Uh oh!

Copilot AI Feb 26, 2026

Uh oh!

Copilot AI Feb 26, 2026

Uh oh!

Copilot AI Feb 26, 2026

Uh oh!

Copilot AI Feb 26, 2026

Uh oh!

Copilot AI Feb 26, 2026

Uh oh!

Copilot AI Feb 26, 2026

Uh oh!

Copilot AI Feb 26, 2026

Uh oh!

Copilot AI Feb 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	objectives = [Objective(name="accuracy", goal=0.99, type="maximize")]
	objectives = [Objective(metric="accuracy", direction="maximize")]

	Optional[kubeflow.optimizer.types.Result]: A object containing the
	Optional[kubeflow.optimizer.types.Result]: An object containing the

	list[kubeflow.trainer.types.Event]: A list of Event objects
	list[Event]: A list of Event objects

	def list_jobs(self, runtime: Optional[types.Runtime] = None) -> list[types.TrainJob]:
	def list_jobs(self, runtime: types.Runtime \| None = None) -> list[types.TrainJob]:

Conversation

Priyanshu-u07 commented Feb 3, 2026

Uh oh!

google-oss-prow bot commented Feb 3, 2026

Uh oh!

github-actions bot commented Feb 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants