diff --git a/models/ref/python/public-api/api.mdx b/models/ref/python/public-api/api.mdx index 90edc0f53f..ad94821e56 100644 --- a/models/ref/python/public-api/api.mdx +++ b/models/ref/python/public-api/api.mdx @@ -125,7 +125,7 @@ Returns a single artifact. **Examples:** - In the proceeding code snippets "entity", "project", "artifact", "version", and "alias" are placeholders for your W&B entity, name of the project the artifact is in, the name of the artifact, and artifact's version, respectively. + In the following code snippets "entity", "project", "artifact", "version", and "alias" are placeholders for your W&B entity, name of the project the artifact is in, the name of the artifact, and artifact's version, respectively. ```python import wandb @@ -357,12 +357,16 @@ Return an `Artifacts` collection. **Args:** - type_name: The type of artifacts to fetch. name: The artifact's collection name. Optionally append the entity that logged the artifact as a prefix followed by a forward slash. per_page: Sets the page size for query pagination. Usually there is no reason to change this. tags: Only return artifacts with all of these tags. + + - `type_name`: The type of artifacts to fetch. + - `name`: The artifact's collection name. Optionally append the entity that logged the artifact as a prefix followed by a forward slash. + - `per_page`: Sets the page size for query pagination. Usually there is no reason to change this. + - `tags`: Only return artifacts with all of these tags. **Returns:** - An iterable `Artifacts` object. + An iterable `Artifacts` object. diff --git a/models/ref/python/public-api/registry.mdx b/models/ref/python/public-api/registry.mdx index d1b06cbce0..3d93bf7eac 100644 --- a/models/ref/python/public-api/registry.mdx +++ b/models/ref/python/public-api/registry.mdx @@ -419,7 +419,7 @@ Updates the role of a member (user or team) within this registry. **Examples:** - Make all users in the registry admins: ```python + Make all users in the registry admins ```python import wandb api = wandb.Api() diff --git a/models/ref/python/public-api/run.mdx b/models/ref/python/public-api/run.mdx index 3643baa46a..86001ec95e 100644 --- a/models/ref/python/public-api/run.mdx +++ b/models/ref/python/public-api/run.mdx @@ -282,6 +282,46 @@ create( Create a run for the given project. +For most use cases, use `wandb.init()`. `wandb.init()` provides more robust logic for creating and updating runs. `wandb.apis.public.Run.create` is intended for specific scenarios such as creating runs in a "pending" state for jobs that may be unschedulable (for example, in a Kubernetes cluster with insufficient GPUs or high contention). These pending runs can later be resumed and tracked by W&B. + +Runs created with this method have limited functionality. Calling `update()` on a run created this way may not work as expected. + + + +**Args:** + + - `api`: The W&B API instance. + - `run_id`: Optional run ID. If not provided, a random ID will be generated. + - `project`: Optional project name. Defaults to the project in API settings or "uncategorized". + - `entity`: Optional entity (user or team) name. + - `state`: Initial state of the run. Use "pending" for runs that will be resumed later, or "running" for immediate execution. + + + +**Returns:** + A Run object representing the created run. + + + +**Example:** + Creating a pending run for later execution + +```python +import wandb + +api = wandb.Api() + +run_name = "my-pending-run" + +run = Run.create( + api=api, + project="project", + entity="entity", + state="pending", + run_id=run_name, +) +``` + --- ### method `Run.delete` diff --git a/models/ref/python/public-api/user.mdx b/models/ref/python/public-api/user.mdx index 38b3ce0179..c3d39d1d3b 100644 --- a/models/ref/python/public-api/user.mdx +++ b/models/ref/python/public-api/user.mdx @@ -11,43 +11,27 @@ import { GitHubLink } from '/snippets/en/_includes/github-source-link.mdx'; ## class `User` -A class representing a W&B user with authentication and management capabilities. +A user on a W&B instance. -This class provides methods to manage W&B users, including creating users, managing API keys, and accessing team memberships. It inherits from Attrs to handle user attributes. +This allows managing a user's API keys and accessing information like team memberships. The `create` class method can be used to create a new user. + +Some operations require admin privileges. -### method `User.__init__` -```python -__init__(client: 'RetryingClient', attrs: 'MutableMapping[str, Any]') -``` **Args:** - - `client`: (`wandb.apis.internal.Api`) The client instance to use - - `attrs`: (dict) The user attributes - - - -**Note:** - -> Some operations require admin privileges - - - + - `client`: The GraphQL client to use for network operations. + - `attrs`: A subset of the User type in the GraphQL schema. - - ---- - ### property User.api_keys -List of API key names associated with the user. +Names of the user's API keys. +These are just API key names, *not* the full secrets, and they cannot be used like API keys. - -**Returns:** - Names of API keys associated with the user. Empty list if user has no API keys or if API key data hasn't been loaded. +The list is empty if the user has no API keys or if API keys have not been loaded. @@ -57,12 +41,9 @@ List of API key names associated with the user. ### property User.teams -List of team names that the user is a member of. - +Names of the user's teams. - -**Returns:** - Names of teams the user belongs to. Empty list if user has no team memberships or if teams data hasn't been loaded. +This is an empty list if the user has no team memberships or if teams data was not loaded. @@ -72,7 +53,7 @@ List of team names that the user is a member of. ### property User.user_api -An instance of the api using credentials from the user. +A `wandb.Api` instance using the user's credentials. @@ -82,28 +63,6 @@ An instance of the api using credentials from the user. - `Api | None`: The user_api property value. --- -### classmethod `User.create` - -```python -create(api: 'Api', email: 'str', admin: 'bool' = False) → Self -``` - -Create a new user. - - - -**Args:** - - - `api` (`Api`): The api instance to use - - `email` (str): The name of the team - - `admin` (bool): Whether this user should be a global instance admin - - - -**Returns:** - A `User` object - ---- ### method `User.delete_api_key` @@ -111,23 +70,18 @@ Create a new user. delete_api_key(api_key: 'str') → bool ``` -Delete a user's api key. +Delete a user's API key. **Args:** - - `api_key` (str): The name of the API key to delete. This should be one of the names returned by the `api_keys` property. + - `api_key`: The name of the API key to delete. This should be one of the names returned by the `api_keys` property. **Returns:** - Boolean indicating success - - - -**Raises:** - ValueError if the api_key couldn't be found + True on success, false on failure. --- @@ -137,16 +91,16 @@ Delete a user's api key. generate_api_key(description: 'str | None' = None) → str | None ``` -Generate a new api key. +Generate a new API key. **Args:** - - `description` (str, optional): A description for the new API key. This can be used to identify the purpose of the API key. + - `description`: A description for the new API key. This can be used to identify the purpose of the API key. **Returns:** - The new api key, or None on failure + The generated API key (the full secret, not just the name), or None on failure.