wandb 0.18.4__py3-none-any.whl → 0.18.6__py3-none-any.whl

wandb/apis/public/api.py

@@ -24,10 +24,11 @@ from wandb_gql.client import RetryError
 import wandb
 from wandb import env, util
 from wandb.apis import public
-from wandb.apis.internal import Api as InternalApi
 from wandb.apis.normalize import normalize_exceptions
 from wandb.apis.public.const import RETRY_TIMEDELTA
+from wandb.apis.public.utils import PathType, parse_org_from_registry_path
 from wandb.sdk.artifacts._validators import is_artifact_registry_project
+from wandb.sdk.internal.internal_api import Api as InternalApi
 from wandb.sdk.internal.thread_local_settings import _thread_local_api_settings
 from wandb.sdk.launch.utils import LAUNCH_DEFAULT_PROJECT
 from wandb.sdk.lib import retry, runid
@@ -100,7 +101,7 @@ class Api:
         Most common way to initialize
         >>> wandb.Api()
 
-    Arguments:
+    Args:
         overrides: (dict) You can set `base_url` if you are using a wandb server
             other than https://api.wandb.ai.
             You can also set defaults for `entity`, `project`, and `run`.
@@ -282,7 +283,7 @@ class Api:
     def create_project(self, name: str, entity: str) -> None:
         """Create a new project.
 
-        Arguments:
+        Args:
             name: (str) The name of the new project.
             entity: (str) The entity of the new project.
         """
@@ -297,7 +298,7 @@ class Api:
     ) -> "public.Run":
         """Create a new run.
 
-        Arguments:
+        Args:
             run_id: (str, optional) The ID to assign to the run, if given.  The run ID is automatically generated by
                 default, so in general, you do not need to specify this and should only do so at your own risk.
             project: (str, optional) If given, the project of the new run.
@@ -321,14 +322,14 @@ class Api:
     ) -> "public.RunQueue":
         """Create a new run queue (launch).
 
-        Arguments:
+        Args:
             name: (str) Name of the queue to create
             type: (str) Type of resource to be used for the queue. One of "local-container", "local-process", "kubernetes", "sagemaker", or "gcp-vertex".
             entity: (str) Optional name of the entity to create the queue. If None, will use the configured or default entity.
             prioritization_mode: (str) Optional version of prioritization to use. Either "V0" or None
-            config: (dict) Optional default resource configuration to be used for the queue. Use handlebars (eg. "{{var}}") to specify template variables.
+            config: (dict) Optional default resource configuration to be used for the queue. Use handlebars (eg. `{{var}}`) to specify template variables.
             template_variables: (dict) A dictionary of template variable schemas to be used with the config. Expected format of:
-                {
+                `{
                     "var-name": {
                         "schema": {
                             "type": ("string", "number", or "integer"),
@@ -338,7 +339,7 @@ class Api:
                             "enum": [..."(options)"]
                         }
                     }
-                }
+                }`
 
         Returns:
             The newly created `RunQueue`
@@ -434,13 +435,13 @@ class Api:
     ):
         """Upsert a run queue (launch).
 
-        Arguments:
+        Args:
             name: (str) Name of the queue to create
             entity: (str) Optional name of the entity to create the queue. If None, will use the configured or default entity.
-            resource_config: (dict) Optional default resource configuration to be used for the queue. Use handlebars (eg. "{{var}}") to specify template variables.
+            resource_config: (dict) Optional default resource configuration to be used for the queue. Use handlebars (eg. `{{var}}`) to specify template variables.
             resource_type: (str) Type of resource to be used for the queue. One of "local-container", "local-process", "kubernetes", "sagemaker", or "gcp-vertex".
             template_variables: (dict) A dictionary of template variable schemas to be used with the config. Expected format of:
-                {
+                `{
                     "var-name": {
                         "schema": {
                             "type": ("string", "number", or "integer"),
@@ -450,11 +451,11 @@ class Api:
                             "enum": [..."(options)"]
                         }
                     }
-                }
+                }`
             external_links: (dict) Optional dictionary of external links to be used with the queue. Expected format of:
-                {
+                `{
                     "name": "url"
-                }
+                }`
             prioritization_mode: (str) Optional version of prioritization to use. Either "V0" or None
 
         Returns:
@@ -540,7 +541,7 @@ class Api:
     def create_user(self, email, admin=False):
         """Create a new user.
 
-        Arguments:
+        Args:
             email: (str) The email address of the user
             admin: (bool) Whether this user should be a global instance admin
 
@@ -635,7 +636,7 @@ class Api:
             report = api.from_path("my_team/my_project/reports/My-Report-Vm11dsdf")
             ```
 
-        Arguments:
+        Args:
             path: (str) The path to the project, run, sweep or report
 
         Returns:
@@ -749,7 +750,7 @@ class Api:
     ) -> "public.Projects":
         """Get projects for a given entity.
 
-        Arguments:
+        Args:
             entity: (str) Name of the entity requested.  If None, will fall back to the
                 default entity passed to `Api`.  If no default entity, will raise a `ValueError`.
             per_page: (int) Sets the page size for query pagination.  None will use the default size.
@@ -773,7 +774,7 @@ class Api:
     def project(self, name: str, entity: Optional[str] = None) -> "public.Project":
         """Return the `Project` with the given name (and entity, if given).
 
-        Arguments:
+        Args:
             name: (str) The project name.
             entity: (str) Name of the entity requested.  If None, will fall back to the
                 default entity passed to `Api`.  If no default entity, will raise a `ValueError`.
@@ -781,8 +782,18 @@ class Api:
         Returns:
             A `Project` object.
         """
+        # For registry artifacts, capture potential org user inputted before resolving entity
+        org = entity if is_artifact_registry_project(name) else ""
+
         if entity is None:
             entity = self.settings["entity"] or self.default_entity
+
+        # For registry artifacts, resolve org-based entity
+        if is_artifact_registry_project(name):
+            settings_entity = self.settings["entity"] or self.default_entity
+            entity = InternalApi()._resolve_org_entity_name(
+                entity=settings_entity, organization=org
+            )
         return public.Project(self.client, entity, name, {})
 
     def reports(
@@ -792,7 +803,7 @@ class Api:
 
         WARNING: This api is in beta and will likely change in a future release
 
-        Arguments:
+        Args:
             path: (str) path to project the report resides in, should be in the form: "entity/project"
             name: (str, optional) optional name of the report requested.
             per_page: (int) Sets the page size for query pagination.  None will use the default size.
@@ -821,7 +832,7 @@ class Api:
     def create_team(self, team, admin_username=None):
         """Create a new team.
 
-        Arguments:
+        Args:
             team: (str) The name of the team
             admin_username: (str) optional username of the admin user of the team, defaults to the current user.
 
@@ -833,7 +844,7 @@ class Api:
     def team(self, team: str) -> "public.Team":
         """Return the matching `Team` with the given name.
 
-        Arguments:
+        Args:
             team: (str) The name of the team.
 
         Returns:
@@ -846,7 +857,7 @@ class Api:
 
         Note: This function only works for Local Admins, if you are trying to get your own user object, please use `api.viewer`.
 
-        Arguments:
+        Args:
             username_or_email: (str) The username or email address of the user
 
         Returns:
@@ -868,7 +879,7 @@ class Api:
 
         Note: This function only works for Local Admins, if you are trying to get your own user object, please use `api.viewer`.
 
-        Arguments:
+        Args:
             username_or_email: (str) The prefix or suffix of the user you want to find
 
         Returns:
@@ -926,11 +937,11 @@ class Api:
             api.runs(path="my_entity/my_project", order="+summary_metrics.loss")
             ```
 
-        Arguments:
+        Args:
             path: (str) path to project, should be in the form: "entity/project"
             filters: (dict) queries for specific runs using the MongoDB query language.
                 You can filter by run properties such as config.key, summary_metrics.key, state, entity, createdAt, etc.
-                For example: {"config.experiment_name": "foo"} would find runs with a config entry
+                For example: `{"config.experiment_name": "foo"}` would find runs with a config entry
                     of experiment name set to "foo"
                 You can compose operations to make more complicated queries,
                     see Reference for the language is at  https://docs.mongodb.com/manual/reference/operator/query
@@ -963,7 +974,7 @@ class Api:
     def run(self, path=""):
         """Return a single run by parsing path in the form entity/project/run_id.
 
-        Arguments:
+        Args:
             path: (str) path to run in the form `entity/project/run_id`.
                 If `api.entity` is set, this can be in the form `project/run_id`
                 and if `api.project` is set this can just be the run_id.
@@ -1018,7 +1029,7 @@ class Api:
     def sweep(self, path=""):
         """Return a sweep by parsing path in the form `entity/project/sweep_id`.
 
-        Arguments:
+        Args:
             path: (str, optional) path to sweep in the form entity/project/sweep_id.  If `api.entity`
                 is set, this can be in the form project/sweep_id and if `api.project` is set
                 this can just be the sweep_id.
@@ -1035,13 +1046,21 @@ class Api:
     def artifact_types(self, project: Optional[str] = None) -> "public.ArtifactTypes":
         """Return a collection of matching artifact types.
 
-        Arguments:
+        Args:
             project: (str, optional) If given, a project name or path to filter on.
 
         Returns:
             An iterable `ArtifactTypes` object.
         """
-        entity, project = self._parse_project_path(project)
+        project_path = project
+        entity, project = self._parse_project_path(project_path)
+        # If its a Registry project, the entity is considered to be an org instead
+        if is_artifact_registry_project(project):
+            settings_entity = self.settings["entity"] or self.default_entity
+            org = parse_org_from_registry_path(project_path, PathType.PROJECT)
+            entity = InternalApi()._resolve_org_entity_name(
+                entity=settings_entity, organization=org
+            )
         return public.ArtifactTypes(self.client, entity, project)
 
     @normalize_exceptions
@@ -1050,14 +1069,22 @@ class Api:
     ) -> "public.ArtifactType":
         """Return the matching `ArtifactType`.
 
-        Arguments:
+        Args:
             type_name: (str) The name of the artifact type to retrieve.
             project: (str, optional) If given, a project name or path to filter on.
 
         Returns:
             An `ArtifactType` object.
         """
-        entity, project = self._parse_project_path(project)
+        project_path = project
+        entity, project = self._parse_project_path(project_path)
+        # If its an Registry artifact, the entity is an org instead
+        if is_artifact_registry_project(project):
+            org = parse_org_from_registry_path(project_path, PathType.PROJECT)
+            settings_entity = self.settings["entity"] or self.default_entity
+            entity = InternalApi()._resolve_org_entity_name(
+                entity=settings_entity, organization=org
+            )
         return public.ArtifactType(self.client, entity, project, type_name)
 
     @normalize_exceptions
@@ -1066,7 +1093,7 @@ class Api:
     ) -> "public.ArtifactCollections":
         """Return a collection of matching artifact collections.
 
-        Arguments:
+        Args:
             project_name: (str) The name of the project to filter on.
             type_name: (str) The name of the artifact type to filter on.
             per_page: (int, optional) Sets the page size for query pagination.  None will use the default size.
@@ -1076,6 +1103,13 @@ class Api:
             An iterable `ArtifactCollections` object.
         """
         entity, project = self._parse_project_path(project_name)
+        # If iterating through Registry project, the entity is considered to be an org instead
+        if is_artifact_registry_project(project):
+            org = parse_org_from_registry_path(project_name, PathType.PROJECT)
+            settings_entity = self.settings["entity"] or self.default_entity
+            entity = InternalApi()._resolve_org_entity_name(
+                entity=settings_entity, organization=org
+            )
         return public.ArtifactCollections(
             self.client, entity, project, type_name, per_page=per_page
         )
@@ -1086,7 +1120,7 @@ class Api:
     ) -> "public.ArtifactCollection":
         """Return a single artifact collection by type and parsing path in the form `entity/project/name`.
 
-        Arguments:
+        Args:
             type_name: (str) The type of artifact collection to fetch.
             name: (str) An artifact collection name. May be prefixed with entity/project.
 
@@ -1094,6 +1128,13 @@ class Api:
             An `ArtifactCollection` object.
         """
         entity, project, collection_name = self._parse_artifact_path(name)
+        # If its an Registry artifact, the entity is considered to be an org instead
+        if is_artifact_registry_project(project):
+            org = parse_org_from_registry_path(name, PathType.ARTIFACT)
+            settings_entity = self.settings["entity"] or self.default_entity
+            entity = InternalApi()._resolve_org_entity_name(
+                entity=settings_entity, organization=org
+            )
         return public.ArtifactCollection(
             self.client, entity, project, collection_name, type_name
         )
@@ -1120,7 +1161,7 @@ class Api:
     ) -> "public.Artifacts":
         """Return an `Artifacts` collection from the given parameters.
 
-        Arguments:
+        Args:
             type_name: (str) The type of artifacts to fetch.
             name: (str) An artifact collection name. May be prefixed with entity/project.
             per_page: (int, optional) Sets the page size for query pagination.  None will use the default size.
@@ -1131,6 +1172,13 @@ class Api:
             An iterable `Artifacts` object.
         """
         entity, project, collection_name = self._parse_artifact_path(name)
+        # If its an Registry project, the entity is considered to be an org instead
+        if is_artifact_registry_project(project):
+            org = parse_org_from_registry_path(name, PathType.ARTIFACT)
+            settings_entity = self.settings["entity"] or self.default_entity
+            entity = InternalApi()._resolve_org_entity_name(
+                entity=settings_entity, organization=org
+            )
         return public.Artifacts(
             self.client,
             entity,
@@ -1142,37 +1190,25 @@ class Api:
         )
 
     @normalize_exceptions
-    def artifact(self, name, type=None):
-        """Return a single artifact by parsing path in the form `project/name` or `entity/project/name`.
-
-        Arguments:
-            name: (str) An artifact name. May be prefixed with project/ or entity/project/.
-                    If no entity is specified in the name, the Run or API setting's entity is used.
-                Valid names can be in the following forms:
-                    name:version
-                    name:alias
-            type: (str, optional) The type of artifact to fetch.
-
-        Returns:
-            A `Artifact` object.
-        """
+    def _artifact(
+        self, name: str, type: Optional[str] = None, enable_tracking: bool = False
+    ):
         if name is None:
             raise ValueError("You must specify name= to fetch an artifact.")
         entity, project, artifact_name = self._parse_artifact_path(name)
 
-        organization = ""
         # If its an Registry artifact, the entity is an org instead
         if is_artifact_registry_project(project):
-            # Update `organization` only if an organization name was provided,
-            # otherwise use the default that you already set above.
-            try:
-                organization, _, _ = name.split("/")
-            except ValueError:
-                organization = ""
+            organization = name.split("/")[0] if name.count("/") == 2 else ""
             # set entity to match the settings since in above code it was potentially set to an org
-            entity = self.settings["entity"] or self.default_entity
+            settings_entity = self.settings["entity"] or self.default_entity
+            # Registry artifacts are under the org entity. Because we offer a shorthand and alias for this path,
+            # we need to fetch the org entity to for the user behind the scenes.
+            entity = InternalApi()._resolve_org_entity_name(
+                entity=settings_entity, organization=organization
+            )
         artifact = wandb.Artifact._from_name(
-            entity, project, artifact_name, self.client, organization
+            entity, project, artifact_name, self.client, enable_tracking
         )
         if type is not None and artifact.type != type:
             raise ValueError(
@@ -1180,11 +1216,35 @@ class Api:
             )
         return artifact
 
+    @normalize_exceptions
+    def artifact(self, name: str, type: Optional[str] = None):
+        """Return a single artifact by parsing path in the form `project/name` or `entity/project/name`.
+
+        Args:
+            name: (str) An artifact name. May be prefixed with project/ or entity/project/.
+                    If no entity is specified in the name, the Run or API setting's entity is used.
+                Valid names can be in the following forms:
+                    name:version
+                    name:alias
+            type: (str, optional) The type of artifact to fetch.
+
+        Returns:
+            An `Artifact` object.
+
+        Raises:
+            ValueError: If the artifact name is not specified.
+            ValueError: If the artifact type is specified but does not match the type of the fetched artifact.
+
+        Note:
+        This method is intended for external use only. Do not call `api.artifact()` within the wandb repository code.
+        """
+        return self._artifact(name=name, type=type, enable_tracking=True)
+
     @normalize_exceptions
     def job(self, name: Optional[str], path: Optional[str] = None) -> "public.Job":
         """Return a `Job` from the given parameters.
 
-        Arguments:
+        Args:
             name: (str) The job name.
             path: (str, optional) If given, the root path in which to download the job artifact.
 
@@ -1203,7 +1263,7 @@ class Api:
     def list_jobs(self, entity: str, project: str) -> List[Dict[str, Any]]:
         """Return a list of jobs, if any, for the given entity and project.
 
-        Arguments:
+        Args:
             entity: (str) The entity for the listed job(s).
             project: (str) The project for the listed job(s).
 
@@ -1281,7 +1341,7 @@ class Api:
     def artifact_exists(self, name: str, type: Optional[str] = None) -> bool:
         """Return whether an artifact version exists within a specified project and entity.
 
-        Arguments:
+        Args:
             name: (str) An artifact name. May be prefixed with entity/project.
                 If entity or project is not specified, it will be inferred from the override params if populated.
                 Otherwise, entity will be pulled from the user settings and project will default to "uncategorized".
@@ -1294,7 +1354,7 @@ class Api:
             True if the artifact version exists, False otherwise.
         """
         try:
-            self.artifact(name, type)
+            self._artifact(name, type)
             return True
         except wandb.errors.CommError:
             return False
@@ -1303,7 +1363,7 @@ class Api:
     def artifact_collection_exists(self, name: str, type: str) -> bool:
         """Return whether an artifact collection exists within a specified project and entity.
 
-        Arguments:
+        Args:
             name: (str) An artifact collection name. May be prefixed with entity/project.
                 If entity or project is not specified, it will be inferred from the override params if populated.
                 Otherwise, entity will be pulled from the user settings and project will default to "uncategorized".

wandb/apis/public/artifacts.py

@@ -50,6 +50,7 @@ ARTIFACT_FILES_FRAGMENT = """fragment ArtifactFilesFragment on Artifact {
                 updatedAt
                 digest
                 md5
+                directUrl
             }
             cursor
         }
@@ -759,6 +760,8 @@ class Artifacts(Paginator):
         per_page: int = 50,
         tags: Optional[Union[str, List[str]]] = None,
     ):
+        from wandb.sdk.artifacts.artifact import _gql_artifact_fragment
+
         self.entity = entity
         self.collection_name = collection_name
         self.type = type
@@ -804,7 +807,7 @@ class Artifacts(Paginator):
                 artifact_collection_edge_name(
                     server_supports_artifact_collections_gql_edges(client)
                 ),
-                wandb.Artifact._get_gql_artifact_fragment(),
+                _gql_artifact_fragment(),
             )
         )
         super().__init__(client, variables, per_page)
@@ -859,6 +862,8 @@ class RunArtifacts(Paginator):
     def __init__(
         self, client: Client, run: "Run", mode="logged", per_page: Optional[int] = 50
     ):
+        from wandb.sdk.artifacts.artifact import _gql_artifact_fragment
+
         output_query = gql(
             """
             query RunOutputArtifacts(
@@ -883,7 +888,7 @@ class RunArtifacts(Paginator):
                 }
             }
             """
-            + wandb.Artifact._get_gql_artifact_fragment()
+            + _gql_artifact_fragment()
         )
 
         input_query = gql(
@@ -910,7 +915,7 @@ class RunArtifacts(Paginator):
                 }
             }
             """
-            + wandb.Artifact._get_gql_artifact_fragment()
+            + _gql_artifact_fragment()
         )
 
         self.run = run

wandb/apis/public/files.py

@@ -13,6 +13,7 @@ from wandb import util
 from wandb.apis.attrs import Attrs
 from wandb.apis.normalize import normalize_exceptions
 from wandb.apis.paginator import Paginator
+from wandb.apis.public import utils
 from wandb.apis.public.api import Api
 from wandb.apis.public.const import RETRY_TIMEDELTA
 from wandb.sdk.lib import retry
@@ -116,7 +117,7 @@ class File(Attrs):
         mimetype (string): mimetype of file
         updated_at (string): timestamp of last update
         size (int): size of file in bytes
-
+        path_uri (str): path to file in the bucket, currently only available for files stored in S3
     """
 
     def __init__(self, client, attrs):
@@ -131,6 +132,20 @@ class File(Attrs):
             return int(size_bytes)
         return 0
 
+    @property
+    def path_uri(self) -> str:
+        """
+        Returns the uri path to the file in the storage bucket.
+        """
+        path_uri = ""
+        try:
+            path_uri = utils.parse_s3_url_to_s3_uri(self._attrs["directUrl"])
+        except ValueError:
+            wandb.termwarn("path_uri is only available for files stored in S3")
+        except LookupError:
+            wandb.termwarn("Unable to find direct_url of file")
+        return path_uri
+
     @normalize_exceptions
     @retry.retriable(
         retry_timedelta=RETRY_TIMEDELTA,
@@ -146,7 +161,7 @@ class File(Attrs):
     ) -> io.TextIOWrapper:
         """Downloads a file previously saved by a run from the wandb server.
 
-        Arguments:
+        Args:
             replace (boolean): If `True`, download will overwrite a local file
                 if it exists. Defaults to `False`.
             root (str): Local directory to save the file.  Defaults to ".".

wandb/apis/public/jobs.py

@@ -45,7 +45,7 @@ class Job:
 
     def __init__(self, api: "Api", name, path: Optional[str] = None) -> None:
         try:
-            self._job_artifact = api.artifact(name, type="job")
+            self._job_artifact = api._artifact(name, type="job")
         except CommError:
             raise CommError(f"Job artifact {name} not found")
         if path:
@@ -94,7 +94,7 @@ class Job:
         if is_id:
             code_artifact = wandb.Artifact._from_id(artifact_string, self._api._client)
         else:
-            code_artifact = self._api.artifact(name=artifact_string, type="code")
+            code_artifact = self._api._artifact(name=artifact_string, type="code")
         if code_artifact is None:
             raise LaunchError("No code artifact found")
         if code_artifact.state == ArtifactState.DELETED:

wandb/apis/public/query_generator.py

@@ -21,7 +21,7 @@ class QueryGenerator:
 
     @classmethod
     def format_order_key(cls, key: str):
-        if key.startswith("+") or key.startswith("-"):
+        if key.startswith(("+", "-")):
             direction = key[0]
             key = key[1:]
         else:

wandb/apis/public/runs.py

@@ -178,7 +178,7 @@ class Runs(Paginator):
     ):
         """Return sampled history metrics for all runs that fit the filters conditions.
 
-        Arguments:
+        Args:
             samples : (int, optional) The number of samples to return per run
             keys : (list[str], optional) Only return metrics for specific keys
             x_axis : (str, optional) Use this metric as the xAxis defaults to _step
@@ -609,7 +609,7 @@ class Run(Attrs):
     def files(self, names=None, per_page=50):
         """Return a file path for each file named.
 
-        Arguments:
+        Args:
             names (list): names of the requested files, if empty returns all files
             per_page (int): number of results per page.
 
@@ -622,7 +622,7 @@ class Run(Attrs):
     def file(self, name):
         """Return the path of a file with a given name in the artifact.
 
-        Arguments:
+        Args:
             name (str): name of requested file.
 
         Returns:
@@ -634,7 +634,7 @@ class Run(Attrs):
     def upload_file(self, path, root="."):
         """Upload a file.
 
-        Arguments:
+        Args:
             path (str): name of file to upload.
             root (str): the root path to save the file relative to.  i.e.
                 If you want to have the file saved in the run as "my_dir/file.txt"
@@ -662,7 +662,7 @@ class Run(Attrs):
 
         This is simpler and faster if you are ok with the history records being sampled.
 
-        Arguments:
+        Args:
             samples : (int, optional) The number of samples to return
             pandas : (bool, optional) Return a pandas dataframe
             keys : (list, optional) Only return metrics for specific keys
@@ -709,7 +709,7 @@ class Run(Attrs):
             losses = [row["Loss"] for row in history]
             ```
 
-        Arguments:
+        Args:
             keys ([str], optional): only fetch these keys, and only fetch rows that have all of keys defined.
             page_size (int, optional): size of pages to fetch from the api.
             min_step (int, optional): the minimum number of pages to scan at a time.
@@ -815,7 +815,7 @@ class Run(Attrs):
     def use_artifact(self, artifact, use_as=None):
         """Declare an artifact as an input to a run.
 
-        Arguments:
+        Args:
             artifact (`Artifact`): An artifact returned from
                 `wandb.Api().artifact(name)`
             use_as (string, optional): A string identifying
@@ -853,7 +853,7 @@ class Run(Attrs):
     ):
         """Declare an artifact as output of a run.
 
-        Arguments:
+        Args:
             artifact (`Artifact`): An artifact returned from
                 `wandb.Api().artifact(name)`.
             aliases (list, optional): Aliases to apply to this artifact.