wandb 0.21.0__py3-none-win_amd64.whl → 0.21.2__py3-none-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (153) hide show
  1. wandb/__init__.py +16 -14
  2. wandb/__init__.pyi +427 -450
  3. wandb/agents/pyagent.py +41 -12
  4. wandb/analytics/sentry.py +7 -2
  5. wandb/apis/importers/mlflow.py +1 -1
  6. wandb/apis/public/__init__.py +1 -1
  7. wandb/apis/public/api.py +525 -360
  8. wandb/apis/public/artifacts.py +207 -13
  9. wandb/apis/public/automations.py +19 -3
  10. wandb/apis/public/files.py +172 -33
  11. wandb/apis/public/history.py +67 -15
  12. wandb/apis/public/integrations.py +25 -2
  13. wandb/apis/public/jobs.py +90 -2
  14. wandb/apis/public/projects.py +130 -79
  15. wandb/apis/public/query_generator.py +11 -1
  16. wandb/apis/public/registries/_utils.py +14 -16
  17. wandb/apis/public/registries/registries_search.py +183 -304
  18. wandb/apis/public/reports.py +96 -15
  19. wandb/apis/public/runs.py +299 -105
  20. wandb/apis/public/sweeps.py +222 -22
  21. wandb/apis/public/teams.py +41 -4
  22. wandb/apis/public/users.py +45 -4
  23. wandb/automations/_generated/delete_automation.py +1 -3
  24. wandb/automations/_generated/enums.py +13 -11
  25. wandb/beta/workflows.py +66 -30
  26. wandb/bin/gpu_stats.exe +0 -0
  27. wandb/bin/wandb-core +0 -0
  28. wandb/cli/cli.py +127 -3
  29. wandb/env.py +8 -0
  30. wandb/errors/errors.py +4 -1
  31. wandb/integration/lightning/fabric/logger.py +3 -4
  32. wandb/integration/metaflow/__init__.py +6 -0
  33. wandb/integration/metaflow/data_pandas.py +74 -0
  34. wandb/integration/metaflow/data_pytorch.py +75 -0
  35. wandb/integration/metaflow/data_sklearn.py +76 -0
  36. wandb/integration/metaflow/errors.py +13 -0
  37. wandb/integration/metaflow/metaflow.py +167 -223
  38. wandb/integration/openai/fine_tuning.py +1 -2
  39. wandb/integration/weave/__init__.py +6 -0
  40. wandb/integration/weave/interface.py +49 -0
  41. wandb/integration/weave/weave.py +63 -0
  42. wandb/jupyter.py +5 -5
  43. wandb/plot/custom_chart.py +30 -7
  44. wandb/proto/v3/wandb_internal_pb2.py +281 -280
  45. wandb/proto/v3/wandb_telemetry_pb2.py +4 -4
  46. wandb/proto/v4/wandb_internal_pb2.py +280 -280
  47. wandb/proto/v4/wandb_telemetry_pb2.py +4 -4
  48. wandb/proto/v5/wandb_internal_pb2.py +280 -280
  49. wandb/proto/v5/wandb_telemetry_pb2.py +4 -4
  50. wandb/proto/v6/wandb_internal_pb2.py +280 -280
  51. wandb/proto/v6/wandb_telemetry_pb2.py +4 -4
  52. wandb/proto/wandb_deprecated.py +6 -0
  53. wandb/sdk/artifacts/_factories.py +17 -0
  54. wandb/sdk/artifacts/_generated/__init__.py +221 -13
  55. wandb/sdk/artifacts/_generated/artifact_by_id.py +17 -0
  56. wandb/sdk/artifacts/_generated/artifact_by_name.py +22 -0
  57. wandb/sdk/artifacts/_generated/artifact_collection_membership_file_urls.py +43 -0
  58. wandb/sdk/artifacts/_generated/artifact_created_by.py +47 -0
  59. wandb/sdk/artifacts/_generated/artifact_file_urls.py +22 -0
  60. wandb/sdk/artifacts/_generated/artifact_type.py +31 -0
  61. wandb/sdk/artifacts/_generated/artifact_used_by.py +43 -0
  62. wandb/sdk/artifacts/_generated/artifact_via_membership_by_name.py +26 -0
  63. wandb/sdk/artifacts/_generated/delete_artifact.py +28 -0
  64. wandb/sdk/artifacts/_generated/enums.py +5 -0
  65. wandb/sdk/artifacts/_generated/fetch_artifact_manifest.py +38 -0
  66. wandb/sdk/artifacts/_generated/fetch_registries.py +32 -0
  67. wandb/sdk/artifacts/_generated/fragments.py +279 -41
  68. wandb/sdk/artifacts/_generated/link_artifact.py +6 -0
  69. wandb/sdk/artifacts/_generated/operations.py +654 -51
  70. wandb/sdk/artifacts/_generated/registry_collections.py +34 -0
  71. wandb/sdk/artifacts/_generated/registry_versions.py +34 -0
  72. wandb/sdk/artifacts/_generated/unlink_artifact.py +25 -0
  73. wandb/sdk/artifacts/_graphql_fragments.py +3 -86
  74. wandb/sdk/artifacts/_internal_artifact.py +19 -8
  75. wandb/sdk/artifacts/_validators.py +14 -4
  76. wandb/sdk/artifacts/artifact.py +512 -618
  77. wandb/sdk/artifacts/artifact_file_cache.py +10 -6
  78. wandb/sdk/artifacts/artifact_manifest.py +10 -9
  79. wandb/sdk/artifacts/artifact_manifest_entry.py +9 -10
  80. wandb/sdk/artifacts/artifact_manifests/artifact_manifest_v1.py +5 -3
  81. wandb/sdk/artifacts/storage_handlers/http_handler.py +1 -1
  82. wandb/sdk/artifacts/storage_handlers/s3_handler.py +1 -1
  83. wandb/sdk/artifacts/storage_policies/wandb_storage_policy.py +1 -1
  84. wandb/sdk/data_types/audio.py +38 -10
  85. wandb/sdk/data_types/base_types/media.py +6 -56
  86. wandb/sdk/data_types/graph.py +48 -14
  87. wandb/sdk/data_types/helper_types/bounding_boxes_2d.py +1 -3
  88. wandb/sdk/data_types/helper_types/image_mask.py +1 -3
  89. wandb/sdk/data_types/histogram.py +34 -21
  90. wandb/sdk/data_types/html.py +35 -12
  91. wandb/sdk/data_types/image.py +104 -68
  92. wandb/sdk/data_types/molecule.py +32 -19
  93. wandb/sdk/data_types/object_3d.py +36 -17
  94. wandb/sdk/data_types/plotly.py +18 -5
  95. wandb/sdk/data_types/saved_model.py +4 -6
  96. wandb/sdk/data_types/table.py +59 -30
  97. wandb/sdk/data_types/video.py +53 -26
  98. wandb/sdk/integration_utils/auto_logging.py +2 -2
  99. wandb/sdk/interface/interface_queue.py +1 -4
  100. wandb/sdk/interface/interface_shared.py +26 -37
  101. wandb/sdk/interface/interface_sock.py +24 -14
  102. wandb/sdk/internal/internal_api.py +6 -0
  103. wandb/sdk/internal/job_builder.py +6 -0
  104. wandb/sdk/internal/settings_static.py +2 -3
  105. wandb/sdk/launch/agent/agent.py +8 -1
  106. wandb/sdk/launch/agent/run_queue_item_file_saver.py +2 -2
  107. wandb/sdk/launch/create_job.py +15 -2
  108. wandb/sdk/launch/inputs/internal.py +3 -4
  109. wandb/sdk/launch/inputs/schema.py +1 -0
  110. wandb/sdk/launch/runner/kubernetes_monitor.py +1 -0
  111. wandb/sdk/launch/runner/kubernetes_runner.py +323 -1
  112. wandb/sdk/launch/sweeps/scheduler.py +2 -3
  113. wandb/sdk/lib/asyncio_compat.py +19 -16
  114. wandb/sdk/lib/asyncio_manager.py +252 -0
  115. wandb/sdk/lib/deprecate.py +1 -7
  116. wandb/sdk/lib/disabled.py +1 -1
  117. wandb/sdk/lib/hashutil.py +27 -5
  118. wandb/sdk/lib/module.py +7 -13
  119. wandb/sdk/lib/printer.py +2 -2
  120. wandb/sdk/lib/printer_asyncio.py +3 -1
  121. wandb/sdk/lib/progress.py +0 -19
  122. wandb/sdk/lib/retry.py +185 -78
  123. wandb/sdk/lib/service/service_client.py +106 -0
  124. wandb/sdk/lib/service/service_connection.py +20 -26
  125. wandb/sdk/lib/service/service_token.py +30 -13
  126. wandb/sdk/mailbox/mailbox.py +13 -5
  127. wandb/sdk/mailbox/mailbox_handle.py +22 -13
  128. wandb/sdk/mailbox/response_handle.py +42 -106
  129. wandb/sdk/mailbox/wait_with_progress.py +7 -42
  130. wandb/sdk/wandb_init.py +77 -116
  131. wandb/sdk/wandb_login.py +19 -15
  132. wandb/sdk/wandb_metric.py +2 -0
  133. wandb/sdk/wandb_run.py +497 -469
  134. wandb/sdk/wandb_settings.py +145 -4
  135. wandb/sdk/wandb_setup.py +204 -124
  136. wandb/sdk/wandb_sweep.py +14 -13
  137. wandb/sdk/wandb_watch.py +4 -6
  138. wandb/sync/sync.py +10 -0
  139. wandb/util.py +58 -1
  140. wandb/wandb_run.py +1 -2
  141. {wandb-0.21.0.dist-info → wandb-0.21.2.dist-info}/METADATA +1 -1
  142. {wandb-0.21.0.dist-info → wandb-0.21.2.dist-info}/RECORD +145 -129
  143. wandb/sdk/interface/interface_relay.py +0 -38
  144. wandb/sdk/interface/router.py +0 -89
  145. wandb/sdk/interface/router_queue.py +0 -43
  146. wandb/sdk/interface/router_relay.py +0 -50
  147. wandb/sdk/interface/router_sock.py +0 -32
  148. wandb/sdk/lib/sock_client.py +0 -236
  149. wandb/vendor/pynvml/__init__.py +0 -0
  150. wandb/vendor/pynvml/pynvml.py +0 -4779
  151. {wandb-0.21.0.dist-info → wandb-0.21.2.dist-info}/WHEEL +0 -0
  152. {wandb-0.21.0.dist-info → wandb-0.21.2.dist-info}/entry_points.txt +0 -0
  153. {wandb-0.21.0.dist-info → wandb-0.21.2.dist-info}/licenses/LICENSE +0 -0
wandb/sdk/wandb_run.py CHANGED
@@ -131,6 +131,7 @@ if TYPE_CHECKING:
131
131
  input_types: dict[str, Any]
132
132
  output_types: dict[str, Any]
133
133
  runtime: str | None
134
+ services: dict[str, str]
134
135
 
135
136
 
136
137
  logger = logging.getLogger("wandb")
@@ -474,62 +475,47 @@ class RunStatus:
474
475
 
475
476
 
476
477
  class Run:
477
- """A unit of computation logged by wandb. Typically, this is an ML experiment.
478
+ """A unit of computation logged by W&B. Typically, this is an ML experiment.
478
479
 
479
- Create a run with `wandb.init()`:
480
- ```python
481
- import wandb
480
+ Call [`wandb.init()`](https://docs.wandb.ai/ref/python/init/) to create a
481
+ new run. `wandb.init()` starts a new run and returns a `wandb.Run` object.
482
+ Each run is associated with a unique ID (run ID). W&B recommends using
483
+ a context (`with` statement) manager to automatically finish the run.
482
484
 
483
- run = wandb.init()
484
- ```
485
+ For distributed training experiments, you can either track each process
486
+ separately using one run per process or track all processes to a single run.
487
+ See [Log distributed training experiments](https://docs.wandb.ai/guides/track/log/distributed-training)
488
+ for more information.
485
489
 
486
- There is only ever at most one active `wandb.Run` in any process,
487
- and it is accessible as `wandb.run`:
488
- ```python
489
- import wandb
490
+ You can log data to a run with `wandb.Run.log()`. Anything you log using
491
+ `wandb.Run.log()` is sent to that run. See
492
+ [Create an experiment](https://docs.wandb.ai/guides/track/launch) or
493
+ [`wandb.init`](https://docs.wandb.ai/ref/python/init/) API reference page
494
+ or more information.
490
495
 
491
- assert wandb.run is None
496
+ There is a another `Run` object in the
497
+ [`wandb.apis.public`](https://docs.wandb.ai/ref/python/public-api/api/)
498
+ namespace. Use this object is to interact with runs that have already been
499
+ created.
492
500
 
493
- wandb.init()
501
+ Attributes:
502
+ summary: (Summary) A summary of the run, which is a dictionary-like
503
+ object. For more information, see
504
+ [Log summary metrics](https://docs.wandb.ai/guides/track/log/log-summary/).
494
505
 
495
- assert wandb.run is not None
496
- ```
497
- anything you log with `wandb.log` will be sent to that run.
506
+ Examples:
507
+ Create a run with `wandb.init()`:
498
508
 
499
- If you want to start more runs in the same script or notebook, you'll need to
500
- finish the run that is in-flight. Runs can be finished with `wandb.finish` or
501
- by using them in a `with` block:
502
509
  ```python
503
510
  import wandb
504
511
 
505
- wandb.init()
506
- wandb.finish()
507
-
508
- assert wandb.run is None
509
-
510
- with wandb.init() as run:
511
- pass # log data here
512
-
513
- assert wandb.run is None
512
+ # Start a new run and log some data
513
+ # Use context manager (`with` statement) to automatically finish the run
514
+ with wandb.init(entity="entity", project="project") as run:
515
+ run.log({"accuracy": acc, "loss": loss})
514
516
  ```
515
517
 
516
- See the documentation for `wandb.init` for more on creating runs, or check out
517
- [our guide to `wandb.init`](https://docs.wandb.ai/guides/track/launch).
518
-
519
- In distributed training, you can either create a single run in the rank 0 process
520
- and then log information only from that process, or you can create a run in each process,
521
- logging from each separately, and group the results together with the `group` argument
522
- to `wandb.init`. For more details on distributed training with W&B, check out
523
- [our guide](https://docs.wandb.ai/guides/track/log/distributed-training).
524
-
525
- Currently, there is a parallel `Run` object in the `wandb.Api`. Eventually these
526
- two objects will be merged.
527
-
528
- Attributes:
529
- summary: (Summary) Single values set for each `wandb.log()` key. By
530
- default, summary is set to the last value logged. You can manually
531
- set summary to the best value, like max accuracy, instead of the
532
- final value.
518
+ <!-- lazydoc-ignore-init: internal -->
533
519
  """
534
520
 
535
521
  _telemetry_obj: telemetry.TelemetryRecord
@@ -850,6 +836,7 @@ class Run:
850
836
  @_log_to_run
851
837
  @_attach
852
838
  def config_static(self) -> wandb_config.ConfigStatic:
839
+ """Static config object associated with this run."""
853
840
  return wandb_config.ConfigStatic(self._config)
854
841
 
855
842
  @property
@@ -957,7 +944,10 @@ class Run:
957
944
  @_log_to_run
958
945
  @_attach
959
946
  def starting_step(self) -> int:
960
- """The first step of the run."""
947
+ """The first step of the run.
948
+
949
+ <!-- lazydoc-ignore: internal -->
950
+ """
961
951
  return self._starting_step
962
952
 
963
953
  @property
@@ -973,7 +963,9 @@ class Run:
973
963
  def step(self) -> int:
974
964
  """Current value of the step.
975
965
 
976
- This counter is incremented by `wandb.log`.
966
+ This counter is incremented by `wandb.Run.log()`.
967
+
968
+ <!-- lazydoc-ignore: internal -->
977
969
  """
978
970
  return self._step
979
971
 
@@ -981,26 +973,30 @@ class Run:
981
973
  @_log_to_run
982
974
  @_attach
983
975
  def offline(self) -> bool:
976
+ """True if the run is offline, False otherwise."""
984
977
  return self._settings._offline
985
978
 
986
979
  @property
987
980
  @_log_to_run
988
981
  @_attach
989
982
  def disabled(self) -> bool:
983
+ """True if the run is disabled, False otherwise."""
990
984
  return self._settings._noop
991
985
 
992
986
  @property
993
987
  @_log_to_run
994
988
  @_attach
995
989
  def group(self) -> str:
996
- """Name of the group associated with the run.
990
+ """Returns the name of the group associated with this run.
997
991
 
998
- Setting a group helps the W&B UI organize runs in a sensible way.
992
+ Grouping runs together allows related experiments to be organized and
993
+ visualized collectively in the W&B UI. This is especially useful for
994
+ scenarios such as distributed training or cross-validation, where
995
+ multiple runs should be viewed and managed as a unified experiment.
999
996
 
1000
- If you are doing a distributed training you should give all of the
1001
- runs in the training the same group.
1002
- If you are doing cross-validation you should give all the cross-validation
1003
- folds the same group.
997
+ In shared mode, where all processes share the same run object,
998
+ setting a group is usually unnecessary, since there is only one
999
+ run and no grouping is required.
1004
1000
  """
1005
1001
  return self._settings.run_group or ""
1006
1002
 
@@ -1008,13 +1004,24 @@ class Run:
1008
1004
  @_log_to_run
1009
1005
  @_attach
1010
1006
  def job_type(self) -> str:
1007
+ """Name of the job type associated with the run.
1008
+
1009
+ View a run's job type in the run's Overview page in the W&B App.
1010
+
1011
+ You can use this to categorize runs by their job type, such as
1012
+ "training", "evaluation", or "inference". This is useful for organizing
1013
+ and filtering runs in the W&B UI, especially when you have multiple
1014
+ runs with different job types in the same project. For more
1015
+ information, see [Organize runs](https://docs.wandb.ai/guides/runs/#organize-runs).
1016
+ """
1011
1017
  return self._settings.run_job_type or ""
1012
1018
 
1013
1019
  def project_name(self) -> str:
1014
- """Name of the W&B project associated with the run.
1020
+ """This method is deprecated and will be removed in a future release. Use `run.project` instead.
1021
+
1022
+ Name of the W&B project associated with the run.
1015
1023
 
1016
- Note: this method is deprecated and will be removed in a future release.
1017
- Please use `run.project` instead.
1024
+ <!-- lazydoc-ignore: internal -->
1018
1025
  """
1019
1026
  deprecate.deprecate(
1020
1027
  field_name=Deprecated.run__project_name,
@@ -1035,12 +1042,12 @@ class Run:
1035
1042
 
1036
1043
  @_log_to_run
1037
1044
  def get_project_url(self) -> str | None:
1038
- """URL of the W&B project associated with the run, if there is one.
1045
+ """This method is deprecated and will be removed in a future release. Use `run.project_url` instead.
1039
1046
 
1047
+ URL of the W&B project associated with the run, if there is one.
1040
1048
  Offline runs do not have a project URL.
1041
1049
 
1042
- Note: this method is deprecated and will be removed in a future release.
1043
- Please use `run.project_url` instead.
1050
+ <!-- lazydoc-ignore: internal -->
1044
1051
  """
1045
1052
  deprecate.deprecate(
1046
1053
  field_name=Deprecated.run__get_project_url,
@@ -1087,28 +1094,36 @@ class Run:
1087
1094
  many runs to share the same artifact. Specifying name allows you to achieve that.
1088
1095
  include_fn: A callable that accepts a file path and (optionally) root path and
1089
1096
  returns True when it should be included and False otherwise. This
1090
- defaults to: `lambda path, root: path.endswith(".py")`
1097
+ defaults to `lambda path, root: path.endswith(".py")`.
1091
1098
  exclude_fn: A callable that accepts a file path and (optionally) root path and
1092
1099
  returns `True` when it should be excluded and `False` otherwise. This
1093
1100
  defaults to a function that excludes all files within `<root>/.wandb/`
1094
1101
  and `<root>/wandb/` directories.
1095
1102
 
1096
1103
  Examples:
1097
- Basic usage
1098
- ```python
1104
+ Basic usage
1105
+
1106
+ ```python
1107
+ import wandb
1108
+
1109
+ with wandb.init() as run:
1099
1110
  run.log_code()
1100
- ```
1111
+ ```
1112
+
1113
+ Advanced usage
1101
1114
 
1102
- Advanced usage
1103
- ```python
1115
+ ```python
1116
+ import wandb
1117
+
1118
+ with wandb.init() as run:
1104
1119
  run.log_code(
1105
- "../",
1120
+ root="../",
1106
1121
  include_fn=lambda path: path.endswith(".py") or path.endswith(".ipynb"),
1107
1122
  exclude_fn=lambda path, root: os.path.relpath(path, root).startswith(
1108
1123
  "cache/"
1109
1124
  ),
1110
1125
  )
1111
- ```
1126
+ ```
1112
1127
 
1113
1128
  Returns:
1114
1129
  An `Artifact` object if code was logged
@@ -1161,12 +1176,12 @@ class Run:
1161
1176
 
1162
1177
  @_log_to_run
1163
1178
  def get_sweep_url(self) -> str | None:
1164
- """The URL of the sweep associated with the run, if there is one.
1179
+ """This method is deprecated and will be removed in a future release. Use `run.sweep_url` instead.
1165
1180
 
1181
+ The URL of the sweep associated with the run, if there is one.
1166
1182
  Offline runs do not have a sweep URL.
1167
1183
 
1168
- Note: this method is deprecated and will be removed in a future release.
1169
- Please use `run.sweep_url` instead.
1184
+ <!-- lazydoc-ignore: internal -->
1170
1185
  """
1171
1186
  deprecate.deprecate(
1172
1187
  field_name=Deprecated.run__get_sweep_url,
@@ -1191,12 +1206,11 @@ class Run:
1191
1206
 
1192
1207
  @_log_to_run
1193
1208
  def get_url(self) -> str | None:
1194
- """URL of the W&B run, if there is one.
1209
+ """This method is deprecated and will be removed in a future release. Use `run.url` instead.
1195
1210
 
1196
- Offline runs do not have a URL.
1211
+ URL of the W&B run, if there is one. Offline runs do not have a URL.
1197
1212
 
1198
- Note: this method is deprecated and will be removed in a future release.
1199
- Please use `run.url` instead.
1213
+ <!-- lazydoc-ignore: internal -->
1200
1214
  """
1201
1215
  deprecate.deprecate(
1202
1216
  field_name=Deprecated.run__get_url,
@@ -1319,7 +1333,7 @@ class Run:
1319
1333
  @_log_to_run
1320
1334
  @_attach
1321
1335
  def display(self, height: int = 420, hidden: bool = False) -> bool:
1322
- """Display this run in jupyter."""
1336
+ """Display this run in Jupyter."""
1323
1337
  if self._settings.silent:
1324
1338
  return False
1325
1339
 
@@ -1338,7 +1352,10 @@ class Run:
1338
1352
  @_log_to_run
1339
1353
  @_attach
1340
1354
  def to_html(self, height: int = 420, hidden: bool = False) -> str:
1341
- """Generate HTML containing an iframe displaying the current run."""
1355
+ """Generate HTML containing an iframe displaying the current run.
1356
+
1357
+ <!-- lazydoc-ignore: internal -->
1358
+ """
1342
1359
  url = self._settings.run_url + "?jupyter=true"
1343
1360
  style = f"border:none;width:100%;height:{height}px;"
1344
1361
  prefix = ""
@@ -1489,7 +1506,7 @@ class Run:
1489
1506
  ) -> dict[str, Any]:
1490
1507
  """Process and replace chart objects with their underlying table values.
1491
1508
 
1492
- This processes the chart objects passed to `run.log()`, replacing their entries
1509
+ This processes the chart objects passed to `wandb.Run.log()`, replacing their entries
1493
1510
  in the given dictionary (which is saved to the run's history) and adding them
1494
1511
  to the run's config.
1495
1512
 
@@ -1745,91 +1762,94 @@ class Run:
1745
1762
  """Upload run data.
1746
1763
 
1747
1764
  Use `log` to log data from runs, such as scalars, images, video,
1748
- histograms, plots, and tables.
1765
+ histograms, plots, and tables. See [Log objects and media](https://docs.wandb.ai/guides/track/log) for
1766
+ code snippets, best practices, and more.
1749
1767
 
1750
- See our [guides to logging](https://docs.wandb.ai/guides/track/log) for
1751
- live examples, code snippets, best practices, and more.
1768
+ Basic usage:
1752
1769
 
1753
- The most basic usage is `run.log({"train-loss": 0.5, "accuracy": 0.9})`.
1754
- This will save the loss and accuracy to the run's history and update
1755
- the summary values for these metrics.
1770
+ ```python
1771
+ import wandb
1756
1772
 
1757
- Visualize logged data in the workspace at [wandb.ai](https://wandb.ai),
1773
+ with wandb.init() as run:
1774
+ run.log({"train-loss": 0.5, "accuracy": 0.9})
1775
+ ```
1776
+
1777
+ The previous code snippet saves the loss and accuracy to the run's
1778
+ history and updates the summary values for these metrics.
1779
+
1780
+ Visualize logged data in a workspace at [wandb.ai](https://wandb.ai),
1758
1781
  or locally on a [self-hosted instance](https://docs.wandb.ai/guides/hosting)
1759
- of the W&B app, or export data to visualize and explore locally, e.g. in
1760
- Jupyter notebooks, with [our API](https://docs.wandb.ai/guides/track/public-api-guide).
1761
-
1762
- Logged values don't have to be scalars. Logging any wandb object is supported.
1763
- For example `run.log({"example": wandb.Image("myimage.jpg")})` will log an
1764
- example image which will be displayed nicely in the W&B UI.
1765
- See the [reference documentation](https://docs.wandb.com/ref/python/data-types)
1766
- for all of the different supported types or check out our
1767
- [guides to logging](https://docs.wandb.ai/guides/track/log) for examples,
1768
- from 3D molecular structures and segmentation masks to PR curves and histograms.
1769
- You can use `wandb.Table` to log structured data. See our
1770
- [guide to logging tables](https://docs.wandb.ai/guides/models/tables/tables-walkthrough)
1771
- for details.
1772
-
1773
- The W&B UI organizes metrics with a forward slash (`/`) in their name
1782
+ of the W&B app, or export data to visualize and explore locally, such as in a
1783
+ Jupyter notebook, with the [Public API](https://docs.wandb.ai/guides/track/public-api-guide).
1784
+
1785
+ Logged values don't have to be scalars. You can log any
1786
+ [W&B supported Data Type](https://docs.wandb.ai/ref/python/data-types/)
1787
+ such as images, audio, video, and more. For example, you can use
1788
+ `wandb.Table` to log structured data. See
1789
+ [Log tables, visualize and query data](https://docs.wandb.ai/guides/models/tables/tables-walkthrough)
1790
+ tutorial for more details.
1791
+
1792
+ W&B organizes metrics with a forward slash (`/`) in their name
1774
1793
  into sections named using the text before the final slash. For example,
1775
1794
  the following results in two sections named "train" and "validate":
1776
1795
 
1777
- ```
1778
- run.log(
1779
- {
1780
- "train/accuracy": 0.9,
1781
- "train/loss": 30,
1782
- "validate/accuracy": 0.8,
1783
- "validate/loss": 20,
1784
- }
1785
- )
1796
+ ```python
1797
+ with wandb.init() as run:
1798
+ # Log metrics in the "train" section.
1799
+ run.log(
1800
+ {
1801
+ "train/accuracy": 0.9,
1802
+ "train/loss": 30,
1803
+ "validate/accuracy": 0.8,
1804
+ "validate/loss": 20,
1805
+ }
1806
+ )
1786
1807
  ```
1787
1808
 
1788
1809
  Only one level of nesting is supported; `run.log({"a/b/c": 1})`
1789
1810
  produces a section named "a/b".
1790
1811
 
1791
- `run.log` is not intended to be called more than a few times per second.
1812
+ `run.log()` is not intended to be called more than a few times per second.
1792
1813
  For optimal performance, limit your logging to once every N iterations,
1793
1814
  or collect data over multiple iterations and log it in a single step.
1794
1815
 
1795
- ### The W&B step
1796
-
1797
- With basic usage, each call to `log` creates a new "step".
1816
+ By default, each call to `log` creates a new "step".
1798
1817
  The step must always increase, and it is not possible to log
1799
- to a previous step.
1818
+ to a previous step. You can use any metric as the X axis in charts.
1819
+ See [Custom log axes](https://docs.wandb.ai/guides/track/log/customize-logging-axes/)
1820
+ for more details.
1800
1821
 
1801
- Note that you can use any metric as the X axis in charts.
1802
1822
  In many cases, it is better to treat the W&B step like
1803
1823
  you'd treat a timestamp rather than a training step.
1804
1824
 
1805
- ```
1806
- # Example: log an "epoch" metric for use as an X axis.
1807
- run.log({"epoch": 40, "train-loss": 0.5})
1825
+ ```python
1826
+ with wandb.init() as run:
1827
+ # Example: log an "epoch" metric for use as an X axis.
1828
+ run.log({"epoch": 40, "train-loss": 0.5})
1808
1829
  ```
1809
1830
 
1810
- See also [define_metric](https://docs.wandb.ai/ref/python/run#define_metric).
1811
-
1812
- It is possible to use multiple `log` invocations to log to
1831
+ It is possible to use multiple `wandb.Run.log()` invocations to log to
1813
1832
  the same step with the `step` and `commit` parameters.
1814
1833
  The following are all equivalent:
1815
1834
 
1816
- ```
1817
- # Normal usage:
1818
- run.log({"train-loss": 0.5, "accuracy": 0.8})
1819
- run.log({"train-loss": 0.4, "accuracy": 0.9})
1820
-
1821
- # Implicit step without auto-incrementing:
1822
- run.log({"train-loss": 0.5}, commit=False)
1823
- run.log({"accuracy": 0.8})
1824
- run.log({"train-loss": 0.4}, commit=False)
1825
- run.log({"accuracy": 0.9})
1826
-
1827
- # Explicit step:
1828
- run.log({"train-loss": 0.5}, step=current_step)
1829
- run.log({"accuracy": 0.8}, step=current_step)
1830
- current_step += 1
1831
- run.log({"train-loss": 0.4}, step=current_step)
1832
- run.log({"accuracy": 0.9}, step=current_step)
1835
+ ```python
1836
+ with wandb.init() as run:
1837
+ # Normal usage:
1838
+ run.log({"train-loss": 0.5, "accuracy": 0.8})
1839
+ run.log({"train-loss": 0.4, "accuracy": 0.9})
1840
+
1841
+ # Implicit step without auto-incrementing:
1842
+ run.log({"train-loss": 0.5}, commit=False)
1843
+ run.log({"accuracy": 0.8})
1844
+ run.log({"train-loss": 0.4}, commit=False)
1845
+ run.log({"accuracy": 0.9})
1846
+
1847
+ # Explicit step:
1848
+ run.log({"train-loss": 0.5}, step=current_step)
1849
+ run.log({"accuracy": 0.8}, step=current_step)
1850
+ current_step += 1
1851
+ run.log({"train-loss": 0.4}, step=current_step)
1852
+ run.log({"accuracy": 0.9}, step=current_step)
1833
1853
  ```
1834
1854
 
1835
1855
  Args:
@@ -1847,59 +1867,64 @@ class Run:
1847
1867
  otherwise, the default is `commit=False`.
1848
1868
 
1849
1869
  Examples:
1850
- For more and more detailed examples, see
1851
- [our guides to logging](https://docs.wandb.com/guides/track/log).
1870
+ For more and more detailed examples, see
1871
+ [our guides to logging](https://docs.wandb.com/guides/track/log).
1872
+
1873
+ Basic usage
1874
+
1875
+ ```python
1876
+ import wandb
1852
1877
 
1853
- ### Basic usage
1854
- ```python
1855
- import wandb
1878
+ with wandb.init() as run:
1879
+ run.log({"train-loss": 0.5, "accuracy": 0.9
1880
+ ```
1856
1881
 
1857
- run = wandb.init()
1858
- run.log({"accuracy": 0.9, "epoch": 5})
1859
- ```
1882
+ Incremental logging
1860
1883
 
1861
- ### Incremental logging
1862
- ```python
1863
- import wandb
1884
+ ```python
1885
+ import wandb
1864
1886
 
1865
- run = wandb.init()
1887
+ with wandb.init() as run:
1866
1888
  run.log({"loss": 0.2}, commit=False)
1867
1889
  # Somewhere else when I'm ready to report this step:
1868
1890
  run.log({"accuracy": 0.8})
1869
- ```
1891
+ ```
1870
1892
 
1871
- ### Histogram
1872
- ```python
1873
- import numpy as np
1874
- import wandb
1893
+ Histogram
1875
1894
 
1876
- # sample gradients at random from normal distribution
1877
- gradients = np.random.randn(100, 100)
1878
- run = wandb.init()
1895
+ ```python
1896
+ import numpy as np
1897
+ import wandb
1898
+
1899
+ # sample gradients at random from normal distribution
1900
+ gradients = np.random.randn(100, 100)
1901
+ with wandb.init() as run:
1879
1902
  run.log({"gradients": wandb.Histogram(gradients)})
1880
- ```
1903
+ ```
1881
1904
 
1882
- ### Image from numpy
1883
- ```python
1884
- import numpy as np
1885
- import wandb
1905
+ Image from NumPy
1886
1906
 
1887
- run = wandb.init()
1907
+ ```python
1908
+ import numpy as np
1909
+ import wandb
1910
+
1911
+ with wandb.init() as run:
1888
1912
  examples = []
1889
1913
  for i in range(3):
1890
1914
  pixels = np.random.randint(low=0, high=256, size=(100, 100, 3))
1891
1915
  image = wandb.Image(pixels, caption=f"random field {i}")
1892
1916
  examples.append(image)
1893
1917
  run.log({"examples": examples})
1894
- ```
1918
+ ```
1919
+
1920
+ Image from PIL
1895
1921
 
1896
- ### Image from PIL
1897
- ```python
1898
- import numpy as np
1899
- from PIL import Image as PILImage
1900
- import wandb
1922
+ ```python
1923
+ import numpy as np
1924
+ from PIL import Image as PILImage
1925
+ import wandb
1901
1926
 
1902
- run = wandb.init()
1927
+ with wandb.init() as run:
1903
1928
  examples = []
1904
1929
  for i in range(3):
1905
1930
  pixels = np.random.randint(
@@ -1912,14 +1937,15 @@ class Run:
1912
1937
  image = wandb.Image(pil_image, caption=f"random field {i}")
1913
1938
  examples.append(image)
1914
1939
  run.log({"examples": examples})
1915
- ```
1940
+ ```
1941
+
1942
+ Video from NumPy
1916
1943
 
1917
- ### Video from numpy
1918
- ```python
1919
- import numpy as np
1920
- import wandb
1944
+ ```python
1945
+ import numpy as np
1946
+ import wandb
1921
1947
 
1922
- run = wandb.init()
1948
+ with wandb.init() as run:
1923
1949
  # axes are (time, channel, height, width)
1924
1950
  frames = np.random.randint(
1925
1951
  low=0,
@@ -1928,35 +1954,38 @@ class Run:
1928
1954
  dtype=np.uint8,
1929
1955
  )
1930
1956
  run.log({"video": wandb.Video(frames, fps=4)})
1931
- ```
1957
+ ```
1932
1958
 
1933
- ### Matplotlib Plot
1934
- ```python
1935
- from matplotlib import pyplot as plt
1936
- import numpy as np
1937
- import wandb
1959
+ Matplotlib plot
1938
1960
 
1939
- run = wandb.init()
1961
+ ```python
1962
+ from matplotlib import pyplot as plt
1963
+ import numpy as np
1964
+ import wandb
1965
+
1966
+ with wandb.init() as run:
1940
1967
  fig, ax = plt.subplots()
1941
1968
  x = np.linspace(0, 10)
1942
1969
  y = x * x
1943
1970
  ax.plot(x, y) # plot y = x^2
1944
1971
  run.log({"chart": fig})
1945
- ```
1972
+ ```
1973
+
1974
+ PR Curve
1946
1975
 
1947
- ### PR Curve
1948
- ```python
1949
- import wandb
1976
+ ```python
1977
+ import wandb
1950
1978
 
1951
- run = wandb.init()
1979
+ with wandb.init() as run:
1952
1980
  run.log({"pr": wandb.plot.pr_curve(y_test, y_probas, labels)})
1953
- ```
1981
+ ```
1982
+
1983
+ 3D Object
1954
1984
 
1955
- ### 3D Object
1956
- ```python
1957
- import wandb
1985
+ ```python
1986
+ import wandb
1958
1987
 
1959
- run = wandb.init()
1988
+ with wandb.init() as run:
1960
1989
  run.log(
1961
1990
  {
1962
1991
  "generated_samples": [
@@ -1966,11 +1995,11 @@ class Run:
1966
1995
  ]
1967
1996
  }
1968
1997
  )
1969
- ```
1998
+ ```
1970
1999
 
1971
2000
  Raises:
1972
- wandb.Error: if called before `wandb.init`
1973
- ValueError: if invalid data is passed
2001
+ wandb.Error: If called before `wandb.init()`.
2002
+ ValueError: If invalid data is passed.
1974
2003
 
1975
2004
  """
1976
2005
  if step is not None:
@@ -2005,42 +2034,48 @@ class Run:
2005
2034
 
2006
2035
  A `base_path` may be provided to control the directory structure of
2007
2036
  uploaded files. It should be a prefix of `glob_str`, and the directory
2008
- structure beneath it is preserved. It's best understood through
2009
- examples:
2010
-
2011
- ```
2012
- wandb.save("these/are/myfiles/*")
2013
- # => Saves files in a "these/are/myfiles/" folder in the run.
2014
-
2015
- wandb.save("these/are/myfiles/*", base_path="these")
2016
- # => Saves files in an "are/myfiles/" folder in the run.
2017
-
2018
- wandb.save("/User/username/Documents/run123/*.txt")
2019
- # => Saves files in a "run123/" folder in the run. See note below.
2020
-
2021
- wandb.save("/User/username/Documents/run123/*.txt", base_path="/User")
2022
- # => Saves files in a "username/Documents/run123/" folder in the run.
2023
-
2024
- wandb.save("files/*/saveme.txt")
2025
- # => Saves each "saveme.txt" file in an appropriate subdirectory
2026
- # of "files/".
2027
- ```
2037
+ structure beneath it is preserved.
2028
2038
 
2029
- Note: when given an absolute path or glob and no `base_path`, one
2039
+ When given an absolute path or glob and no `base_path`, one
2030
2040
  directory level is preserved as in the example above.
2031
2041
 
2032
2042
  Args:
2033
2043
  glob_str: A relative or absolute path or Unix glob.
2034
2044
  base_path: A path to use to infer a directory structure; see examples.
2035
2045
  policy: One of `live`, `now`, or `end`.
2036
- * live: upload the file as it changes, overwriting the previous version
2037
- * now: upload the file once now
2038
- * end: upload file when the run ends
2046
+ - live: upload the file as it changes, overwriting the previous version
2047
+ - now: upload the file once now
2048
+ - end: upload file when the run ends
2039
2049
 
2040
2050
  Returns:
2041
2051
  Paths to the symlinks created for the matched files.
2042
2052
 
2043
2053
  For historical reasons, this may return a boolean in legacy code.
2054
+
2055
+ ```python
2056
+ import wandb
2057
+
2058
+ run = wandb.init()
2059
+
2060
+ run.save("these/are/myfiles/*")
2061
+ # => Saves files in a "these/are/myfiles/" folder in the run.
2062
+
2063
+ run.save("these/are/myfiles/*", base_path="these")
2064
+ # => Saves files in an "are/myfiles/" folder in the run.
2065
+
2066
+ run.save("/User/username/Documents/run123/*.txt")
2067
+ # => Saves files in a "run123/" folder in the run. See note below.
2068
+
2069
+ run.save("/User/username/Documents/run123/*.txt", base_path="/User")
2070
+ # => Saves files in a "username/Documents/run123/" folder in the run.
2071
+
2072
+ run.save("files/*/saveme.txt")
2073
+ # => Saves each "saveme.txt" file in an appropriate subdirectory
2074
+ # of "files/".
2075
+
2076
+ # Explicitly finish the run since a context manager is not used.
2077
+ run.finish()
2078
+ ```
2044
2079
  """
2045
2080
  if isinstance(glob_str, bytes):
2046
2081
  # Preserved for backward compatibility: allow bytes inputs.
@@ -2194,6 +2229,7 @@ class Run:
2194
2229
  - Crashed: Run that stopped sending heartbeats unexpectedly.
2195
2230
  - Finished: Run completed successfully (`exit_code=0`) with all data synced.
2196
2231
  - Failed: Run completed with errors (`exit_code!=0`).
2232
+ - Killed: Run was forcibly stopped before it could finish.
2197
2233
 
2198
2234
  Args:
2199
2235
  exit_code: Integer indicating the run's exit status. Use 0 for success,
@@ -2687,22 +2723,16 @@ class Run:
2687
2723
  wait_with_progress(
2688
2724
  exit_handle,
2689
2725
  timeout=None,
2690
- progress_after=1,
2691
2726
  display_progress=functools.partial(
2692
2727
  self._display_finish_stats,
2693
2728
  progress_printer,
2694
2729
  ),
2695
2730
  )
2696
2731
 
2697
- # Print some final statistics.
2698
2732
  poll_exit_handle = self._backend.interface.deliver_poll_exit()
2699
2733
  result = poll_exit_handle.wait_or(timeout=None)
2700
- progress.print_sync_dedupe_stats(
2701
- self._printer,
2702
- result.response.poll_exit_response,
2703
- )
2704
-
2705
2734
  self._poll_exit_response = result.response.poll_exit_response
2735
+
2706
2736
  internal_messages_handle = self._backend.interface.deliver_internal_messages()
2707
2737
  result = internal_messages_handle.wait_or(timeout=None)
2708
2738
  self._internal_messages_response = result.response.internal_messages_response
@@ -2748,23 +2778,26 @@ class Run:
2748
2778
  goal: str | None = None,
2749
2779
  overwrite: bool | None = None,
2750
2780
  ) -> wandb_metric.Metric:
2751
- """Customize metrics logged with `wandb.log()`.
2781
+ """Customize metrics logged with `wandb.Run.log()`.
2752
2782
 
2753
2783
  Args:
2754
2784
  name: The name of the metric to customize.
2755
2785
  step_metric: The name of another metric to serve as the X-axis
2756
2786
  for this metric in automatically generated charts.
2757
2787
  step_sync: Automatically insert the last value of step_metric into
2758
- `run.log()` if it is not provided explicitly. Defaults to True
2788
+ `wandb.Run.log()` if it is not provided explicitly. Defaults to True
2759
2789
  if step_metric is specified.
2760
2790
  hidden: Hide this metric from automatic plots.
2761
2791
  summary: Specify aggregate metrics added to summary.
2762
2792
  Supported aggregations include "min", "max", "mean", "last",
2763
- "best", "copy" and "none". "best" is used together with the
2764
- goal parameter. "none" prevents a summary from being generated.
2765
- "copy" is deprecated and should not be used.
2793
+ "first", "best", "copy" and "none". "none" prevents a summary
2794
+ from being generated. "best" is used together with the goal
2795
+ parameter, "best" is deprecated and should not be used, use
2796
+ "min" or "max" instead. "copy" is deprecated and should not be
2797
+ used.
2766
2798
  goal: Specify how to interpret the "best" summary type.
2767
- Supported options are "minimize" and "maximize".
2799
+ Supported options are "minimize" and "maximize". "goal" is
2800
+ deprecated and should not be used, use "min" or "max" instead.
2768
2801
  overwrite: If false, then this call is merged with previous
2769
2802
  `define_metric` calls for the same metric by using their
2770
2803
  values for any unspecified parameters. If true, then
@@ -2837,7 +2870,7 @@ class Run:
2837
2870
  if summary:
2838
2871
  summary_items = [s.lower() for s in summary.split(",")]
2839
2872
  summary_ops = []
2840
- valid = {"min", "max", "mean", "best", "last", "copy", "none"}
2873
+ valid = {"min", "max", "mean", "best", "last", "copy", "none", "first"}
2841
2874
  # TODO: deprecate copy and best
2842
2875
  for i in summary_items:
2843
2876
  if i not in valid:
@@ -2888,29 +2921,22 @@ class Run:
2888
2921
  idx: int | None = None,
2889
2922
  log_graph: bool = False,
2890
2923
  ) -> None:
2891
- """Hooks into the given PyTorch model(s) to monitor gradients and the model's computational graph.
2924
+ """Hook into given PyTorch model to monitor gradients and the model's computational graph.
2892
2925
 
2893
- This function can track parameters, gradients, or both during training. It should be
2894
- extended to support arbitrary machine learning models in the future.
2926
+ This function can track parameters, gradients, or both during training.
2895
2927
 
2896
2928
  Args:
2897
- models (Union[torch.nn.Module, Sequence[torch.nn.Module]]):
2898
- A single model or a sequence of models to be monitored.
2899
- criterion (Optional[torch.F]):
2900
- The loss function being optimized (optional).
2901
- log (Optional[Literal["gradients", "parameters", "all"]]):
2902
- Specifies whether to log "gradients", "parameters", or "all".
2903
- Set to None to disable logging. (default="gradients")
2904
- log_freq (int):
2905
- Frequency (in batches) to log gradients and parameters. (default=1000)
2906
- idx (Optional[int]):
2907
- Index used when tracking multiple models with `wandb.watch`. (default=None)
2908
- log_graph (bool):
2909
- Whether to log the model's computational graph. (default=False)
2929
+ models: A single model or a sequence of models to be monitored.
2930
+ criterion: The loss function being optimized (optional).
2931
+ log: Specifies whether to log "gradients", "parameters", or "all".
2932
+ Set to None to disable logging. (default="gradients").
2933
+ log_freq: Frequency (in batches) to log gradients and parameters. (default=1000)
2934
+ idx: Index used when tracking multiple models with `wandb.watch`. (default=None)
2935
+ log_graph: Whether to log the model's computational graph. (default=False)
2910
2936
 
2911
2937
  Raises:
2912
2938
  ValueError:
2913
- If `wandb.init` has not been called or if any of the models are not instances
2939
+ If `wandb.init()` has not been called or if any of the models are not instances
2914
2940
  of `torch.nn.Module`.
2915
2941
  """
2916
2942
  wandb.sdk._watch(self, models, criterion, log, log_freq, idx, log_graph)
@@ -2923,8 +2949,7 @@ class Run:
2923
2949
  """Remove pytorch model topology, gradient and parameter hooks.
2924
2950
 
2925
2951
  Args:
2926
- models (torch.nn.Module | Sequence[torch.nn.Module]):
2927
- Optional list of pytorch models that have had watch called on them
2952
+ models: Optional list of pytorch models that have had watch called on them.
2928
2953
  """
2929
2954
  wandb.sdk._unwatch(self, models=models)
2930
2955
 
@@ -2936,10 +2961,10 @@ class Run:
2936
2961
  artifact: Artifact,
2937
2962
  target_path: str,
2938
2963
  aliases: list[str] | None = None,
2939
- ) -> Artifact | None:
2964
+ ) -> Artifact:
2940
2965
  """Link the given artifact to a portfolio (a promoted collection of artifacts).
2941
2966
 
2942
- The linked artifact will be visible in the UI for the specified portfolio.
2967
+ Linked artifacts are visible in the UI for the specified portfolio.
2943
2968
 
2944
2969
  Args:
2945
2970
  artifact: the (public or local) artifact which will be linked
@@ -2950,7 +2975,7 @@ class Run:
2950
2975
  The alias "latest" will always be applied to the latest version of an artifact that is linked.
2951
2976
 
2952
2977
  Returns:
2953
- The linked artifact if linking was successful, otherwise None.
2978
+ The linked artifact.
2954
2979
 
2955
2980
  """
2956
2981
  if artifact.is_draft() and not artifact._is_draft_save_started():
@@ -2987,19 +3012,46 @@ class Run:
2987
3012
  Call `download` or `file` on the returned object to get the contents locally.
2988
3013
 
2989
3014
  Args:
2990
- artifact_or_name: (str or Artifact) An artifact name.
2991
- May be prefixed with project/ or entity/project/.
2992
- If no entity is specified in the name, the Run or API setting's entity is used.
2993
- Valid names can be in the following forms:
2994
- - name:version
2995
- - name:alias
2996
- You can also pass an Artifact object created by calling `wandb.Artifact`
2997
- type: (str, optional) The type of artifact to use.
2998
- aliases: (list, optional) Aliases to apply to this artifact
3015
+ artifact_or_name: The name of the artifact to use. May be prefixed
3016
+ with the name of the project the artifact was logged to
3017
+ ("<entity>" or "<entity>/<project>"). If no
3018
+ entity is specified in the name, the Run or API setting's entity is used.
3019
+ Valid names can be in the following forms
3020
+ - name:version
3021
+ - name:alias
3022
+ type: The type of artifact to use.
3023
+ aliases: Aliases to apply to this artifact
2999
3024
  use_as: This argument is deprecated and does nothing.
3000
3025
 
3001
3026
  Returns:
3002
3027
  An `Artifact` object.
3028
+
3029
+ Examples:
3030
+ ```python
3031
+ import wandb
3032
+
3033
+ run = wandb.init(project="<example>")
3034
+
3035
+ # Use an artifact by name and alias
3036
+ artifact_a = run.use_artifact(artifact_or_name="<name>:<alias>")
3037
+
3038
+ # Use an artifact by name and version
3039
+ artifact_b = run.use_artifact(artifact_or_name="<name>:v<version>")
3040
+
3041
+ # Use an artifact by entity/project/name:alias
3042
+ artifact_c = run.use_artifact(
3043
+ artifact_or_name="<entity>/<project>/<name>:<alias>"
3044
+ )
3045
+
3046
+ # Use an artifact by entity/project/name:version
3047
+ artifact_d = run.use_artifact(
3048
+ artifact_or_name="<entity>/<project>/<name>:v<version>"
3049
+ )
3050
+
3051
+ # Explicitly finish the run since a context manager is not used.
3052
+ run.finish()
3053
+ ```
3054
+
3003
3055
  """
3004
3056
  if self._settings._offline:
3005
3057
  raise TypeError("Cannot use artifact when in offline mode.")
@@ -3128,24 +3180,20 @@ class Run:
3128
3180
  This is useful when distributed jobs need to all contribute to the same artifact.
3129
3181
 
3130
3182
  Args:
3131
- artifact_or_path: (str or Artifact) A path to the contents of this artifact,
3183
+ artifact_or_path: A path to the contents of this artifact,
3132
3184
  can be in the following forms:
3133
- - `/local/directory`
3134
- - `/local/directory/file.txt`
3135
- - `s3://bucket/path`
3136
- You can also pass an Artifact object created by calling
3137
- `wandb.Artifact`.
3138
- name: (str, optional) An artifact name. May be prefixed with entity/project.
3139
- Valid names can be in the following forms:
3140
- - name:version
3141
- - name:alias
3142
- - digest
3143
- This will default to the basename of the path prepended with the current
3144
- run id if not specified.
3145
- type: (str) The type of artifact to log, examples include `dataset`, `model`
3146
- aliases: (list, optional) Aliases to apply to this artifact,
3147
- defaults to `["latest"]`
3148
- distributed_id: (string, optional) Unique string that all distributed jobs share. If None,
3185
+ - `/local/directory`
3186
+ - `/local/directory/file.txt`
3187
+ - `s3://bucket/path`
3188
+ name: An artifact name. May be prefixed with "entity/project". Defaults
3189
+ to the basename of the path prepended with the current run ID
3190
+ if not specified. Valid names can be in the following forms:
3191
+ - name:version
3192
+ - name:alias
3193
+ - digest
3194
+ type: The type of artifact to log. Common examples include `dataset`, `model`.
3195
+ aliases: Aliases to apply to this artifact, defaults to `["latest"]`.
3196
+ distributed_id: Unique string that all distributed jobs share. If None,
3149
3197
  defaults to the run's group name.
3150
3198
 
3151
3199
  Returns:
@@ -3182,24 +3230,24 @@ class Run:
3182
3230
  Subsequent "upserts" with the same distributed ID will result in a new version.
3183
3231
 
3184
3232
  Args:
3185
- artifact_or_path: (str or Artifact) A path to the contents of this artifact,
3233
+ artifact_or_path: A path to the contents of this artifact,
3186
3234
  can be in the following forms:
3187
3235
  - `/local/directory`
3188
3236
  - `/local/directory/file.txt`
3189
3237
  - `s3://bucket/path`
3190
3238
  You can also pass an Artifact object created by calling
3191
3239
  `wandb.Artifact`.
3192
- name: (str, optional) An artifact name. May be prefixed with entity/project.
3240
+ name: An artifact name. May be prefixed with entity/project.
3193
3241
  Valid names can be in the following forms:
3194
3242
  - name:version
3195
3243
  - name:alias
3196
3244
  - digest
3197
3245
  This will default to the basename of the path prepended with the current
3198
3246
  run id if not specified.
3199
- type: (str) The type of artifact to log, examples include `dataset`, `model`
3200
- aliases: (list, optional) Aliases to apply to this artifact,
3247
+ type: The type of artifact to log, examples include `dataset`, `model`
3248
+ aliases: Aliases to apply to this artifact,
3201
3249
  defaults to `["latest"]`
3202
- distributed_id: (string, optional) Unique string that all distributed jobs share. If None,
3250
+ distributed_id: Unique string that all distributed jobs share. If None,
3203
3251
  defaults to the run's group name.
3204
3252
 
3205
3253
  Returns:
@@ -3379,39 +3427,24 @@ class Run:
3379
3427
  ) -> None:
3380
3428
  """Logs a model artifact containing the contents inside the 'path' to a run and marks it as an output to this run.
3381
3429
 
3430
+ The name of model artifact can only contain alphanumeric characters,
3431
+ underscores, and hyphens.
3432
+
3382
3433
  Args:
3383
3434
  path: (str) A path to the contents of this model,
3384
3435
  can be in the following forms:
3385
3436
  - `/local/directory`
3386
3437
  - `/local/directory/file.txt`
3387
3438
  - `s3://bucket/path`
3388
- name: (str, optional) A name to assign to the model artifact that the file contents will be added to.
3389
- The string must contain only the following alphanumeric characters: dashes, underscores, and dots.
3390
- This will default to the basename of the path prepended with the current
3391
- run id if not specified.
3392
- aliases: (list, optional) Aliases to apply to the created model artifact,
3439
+ name: A name to assign to the model artifact that
3440
+ the file contents will be added to. This will default to the
3441
+ basename of the path prepended with the current run id if
3442
+ not specified.
3443
+ aliases: Aliases to apply to the created model artifact,
3393
3444
  defaults to `["latest"]`
3394
3445
 
3395
- Examples:
3396
- ```python
3397
- run.log_model(
3398
- path="/local/directory",
3399
- name="my_model_artifact",
3400
- aliases=["production"],
3401
- )
3402
- ```
3403
-
3404
- Invalid usage
3405
- ```python
3406
- run.log_model(
3407
- path="/local/directory",
3408
- name="my_entity/my_project/my_model_artifact",
3409
- aliases=["production"],
3410
- )
3411
- ```
3412
-
3413
3446
  Raises:
3414
- ValueError: if name has invalid special characters
3447
+ ValueError: If name has invalid special characters.
3415
3448
 
3416
3449
  Returns:
3417
3450
  None
@@ -3427,40 +3460,18 @@ class Run:
3427
3460
  """Download the files logged in a model artifact 'name'.
3428
3461
 
3429
3462
  Args:
3430
- name: (str) A model artifact name. 'name' must match the name of an existing logged
3431
- model artifact.
3432
- May be prefixed with entity/project/. Valid names
3433
- can be in the following forms:
3434
- - model_artifact_name:version
3435
- - model_artifact_name:alias
3463
+ name: A model artifact name. 'name' must match the name of an existing logged
3464
+ model artifact. May be prefixed with `entity/project/`. Valid names
3465
+ can be in the following forms
3466
+ - model_artifact_name:version
3467
+ - model_artifact_name:alias
3436
3468
 
3437
- Examples:
3438
- ```python
3439
- run.use_model(
3440
- name="my_model_artifact:latest",
3441
- )
3442
-
3443
- run.use_model(
3444
- name="my_project/my_model_artifact:v0",
3445
- )
3446
-
3447
- run.use_model(
3448
- name="my_entity/my_project/my_model_artifact:<digest>",
3449
- )
3450
- ```
3451
-
3452
- Invalid usage
3453
- ```python
3454
- run.use_model(
3455
- name="my_entity/my_project/my_model_artifact",
3456
- )
3457
- ```
3469
+ Returns:
3470
+ path (str): Path to downloaded model artifact file(s).
3458
3471
 
3459
3472
  Raises:
3460
- AssertionError: if model artifact 'name' is of a type that does not contain the substring 'model'.
3461
-
3462
- Returns:
3463
- path: (str) path to downloaded model artifact file(s).
3473
+ AssertionError: If model artifact 'name' is of a type that does
3474
+ not contain the substring 'model'.
3464
3475
  """
3465
3476
  if self._settings._offline:
3466
3477
  # Downloading artifacts is not supported when offline.
@@ -3494,66 +3505,43 @@ class Run:
3494
3505
  ) -> Artifact | None:
3495
3506
  """Log a model artifact version and link it to a registered model in the model registry.
3496
3507
 
3497
- The linked model version will be visible in the UI for the specified registered model.
3508
+ Linked model versions are visible in the UI for the specified registered model.
3498
3509
 
3499
- Steps:
3500
- - Check if 'name' model artifact has been logged. If so, use the artifact version that matches the files
3501
- located at 'path' or log a new version. Otherwise log files under 'path' as a new model artifact, 'name'
3502
- of type 'model'.
3503
- - Check if registered model with name 'registered_model_name' exists in the 'model-registry' project.
3504
- If not, create a new registered model with name 'registered_model_name'.
3505
- - Link version of model artifact 'name' to registered model, 'registered_model_name'.
3506
- - Attach aliases from 'aliases' list to the newly linked model artifact version.
3510
+ This method will:
3511
+ - Check if 'name' model artifact has been logged. If so, use the artifact version that matches the files
3512
+ located at 'path' or log a new version. Otherwise log files under 'path' as a new model artifact, 'name'
3513
+ of type 'model'.
3514
+ - Check if registered model with name 'registered_model_name' exists in the 'model-registry' project.
3515
+ If not, create a new registered model with name 'registered_model_name'.
3516
+ - Link version of model artifact 'name' to registered model, 'registered_model_name'.
3517
+ - Attach aliases from 'aliases' list to the newly linked model artifact version.
3507
3518
 
3508
3519
  Args:
3509
- path: (str) A path to the contents of this model,
3510
- can be in the following forms:
3511
- - `/local/directory`
3512
- - `/local/directory/file.txt`
3513
- - `s3://bucket/path`
3514
- registered_model_name: (str) - the name of the registered model that the model is to be linked to.
3515
- A registered model is a collection of model versions linked to the model registry, typically representing a
3516
- team's specific ML Task. The entity that this registered model belongs to will be derived from the run
3517
- name: (str, optional) - the name of the model artifact that files in 'path' will be logged to. This will
3518
- default to the basename of the path prepended with the current run id if not specified.
3519
- aliases: (List[str], optional) - alias(es) that will only be applied on this linked artifact
3520
- inside the registered model.
3521
- The alias "latest" will always be applied to the latest version of an artifact that is linked.
3522
-
3523
- Examples:
3524
- ```python
3525
- run.link_model(
3526
- path="/local/directory",
3527
- registered_model_name="my_reg_model",
3528
- name="my_model_artifact",
3529
- aliases=["production"],
3530
- )
3531
- ```
3532
-
3533
- Invalid usage
3534
- ```python
3535
- run.link_model(
3536
- path="/local/directory",
3537
- registered_model_name="my_entity/my_project/my_reg_model",
3538
- name="my_model_artifact",
3539
- aliases=["production"],
3540
- )
3541
-
3542
- run.link_model(
3543
- path="/local/directory",
3544
- registered_model_name="my_reg_model",
3545
- name="my_entity/my_project/my_model_artifact",
3546
- aliases=["production"],
3547
- )
3548
- ```
3520
+ path: (str) A path to the contents of this model, can be in the
3521
+ following forms:
3522
+ - `/local/directory`
3523
+ - `/local/directory/file.txt`
3524
+ - `s3://bucket/path`
3525
+ registered_model_name: The name of the registered model that the
3526
+ model is to be linked to. A registered model is a collection of
3527
+ model versions linked to the model registry, typically
3528
+ representing a team's specific ML Task. The entity that this
3529
+ registered model belongs to will be derived from the run.
3530
+ name: The name of the model artifact that files in 'path' will be
3531
+ logged to. This will default to the basename of the path
3532
+ prepended with the current run id if not specified.
3533
+ aliases: Aliases that will only be applied on this linked artifact
3534
+ inside the registered model. The alias "latest" will always be
3535
+ applied to the latest version of an artifact that is linked.
3549
3536
 
3550
3537
  Raises:
3551
- AssertionError: if registered_model_name is a path or
3552
- if model artifact 'name' is of a type that does not contain the substring 'model'
3553
- ValueError: if name has invalid special characters
3538
+ AssertionError: If registered_model_name is a path or
3539
+ if model artifact 'name' is of a type that does not contain
3540
+ the substring 'model'.
3541
+ ValueError: If name has invalid special characters.
3554
3542
 
3555
3543
  Returns:
3556
- The linked artifact if linking was successful, otherwise None.
3544
+ The linked artifact if linking was successful, otherwise `None`.
3557
3545
  """
3558
3546
  name_parts = registered_model_name.split("/")
3559
3547
  if len(name_parts) != 1:
@@ -3596,13 +3584,13 @@ class Run:
3596
3584
  level: str | AlertLevel | None = None,
3597
3585
  wait_duration: int | float | timedelta | None = None,
3598
3586
  ) -> None:
3599
- """Launch an alert with the given title and text.
3587
+ """Create an alert with the given title and text.
3600
3588
 
3601
3589
  Args:
3602
- title: (str) The title of the alert, must be less than 64 characters long.
3603
- text: (str) The text body of the alert.
3604
- level: (str or AlertLevel, optional) The alert level to use, either: `INFO`, `WARN`, or `ERROR`.
3605
- wait_duration: (int, float, or timedelta, optional) The time to wait (in seconds) before sending another
3590
+ title: The title of the alert, must be less than 64 characters long.
3591
+ text: The text body of the alert.
3592
+ level: The alert level to use, either: `INFO`, `WARN`, or `ERROR`.
3593
+ wait_duration: The time to wait (in seconds) before sending another
3606
3594
  alert with this title.
3607
3595
  """
3608
3596
  level = level or AlertLevel.INFO
@@ -3714,24 +3702,27 @@ class Run:
3714
3702
  self._printer.display(f"Tracking run with wandb version {wandb.__version__}")
3715
3703
 
3716
3704
  def _header_sync_info(self) -> None:
3705
+ sync_location_msg = f"Run data is saved locally in {self._printer.files(self._settings.sync_dir)}"
3706
+
3717
3707
  if self._settings._offline:
3718
- self._printer.display(
3719
- [
3720
- f"W&B syncing is set to {self._printer.code('`offline`')}"
3721
- f" in this directory. Run {self._printer.code('`wandb online`')}"
3722
- f" or set {self._printer.code('WANDB_MODE=online')}"
3723
- " to enable cloud syncing.",
3724
- ]
3708
+ offline_warning = (
3709
+ f"W&B syncing is set to {self._printer.code('`offline`')} "
3710
+ f"in this directory. Run {self._printer.code('`wandb online`')} "
3711
+ f"or set {self._printer.code('WANDB_MODE=online')} "
3712
+ "to enable cloud syncing."
3725
3713
  )
3714
+ self._printer.display([offline_warning, sync_location_msg])
3726
3715
  else:
3727
- sync_dir = self._settings.sync_dir
3728
- info = [f"Run data is saved locally in {self._printer.files(sync_dir)}"]
3716
+ messages = [sync_location_msg]
3717
+
3729
3718
  if not self._printer.supports_html:
3730
- info.append(
3719
+ disable_sync_msg = (
3731
3720
  f"Run {self._printer.code('`wandb offline`')} to turn off syncing."
3732
3721
  )
3722
+ messages.append(disable_sync_msg)
3723
+
3733
3724
  if not self._settings.quiet and not self._settings.silent:
3734
- self._printer.display(info)
3725
+ self._printer.display(messages)
3735
3726
 
3736
3727
  def _header_run_info(self) -> None:
3737
3728
  settings, printer = self._settings, self._printer
@@ -3896,64 +3887,101 @@ class Run:
3896
3887
  if settings.quiet or settings.silent:
3897
3888
  return
3898
3889
 
3899
- panel = []
3890
+ panel: list[str] = []
3900
3891
 
3901
- # Render history if available
3902
- if history:
3903
- logger.info("rendering history")
3892
+ if history and (
3893
+ history_grid := Run._footer_history(history, printer, settings)
3894
+ ):
3895
+ panel.append(history_grid)
3904
3896
 
3905
- sampled_history = {
3906
- item.key: wandb.util.downsample(
3907
- item.values_float or item.values_int, 40
3908
- )
3909
- for item in history.item
3910
- if not item.key.startswith("_")
3911
- }
3897
+ if summary and (
3898
+ summary_grid := Run._footer_summary(summary, printer, settings)
3899
+ ):
3900
+ panel.append(summary_grid)
3912
3901
 
3913
- history_rows = []
3914
- for key, values in sorted(sampled_history.items()):
3915
- if any(not isinstance(value, numbers.Number) for value in values):
3916
- continue
3917
- sparkline = printer.sparklines(values)
3918
- if sparkline:
3919
- history_rows.append([key, sparkline])
3920
- if history_rows:
3921
- history_grid = printer.grid(
3922
- history_rows,
3923
- "Run history:",
3924
- )
3925
- panel.append(history_grid)
3902
+ if panel:
3903
+ printer.display(printer.panel(panel))
3926
3904
 
3927
- # Render summary if available
3928
- if summary:
3929
- final_summary = {}
3930
- for item in summary.item:
3931
- if item.key.startswith("_") or len(item.nested_key) > 0:
3932
- continue
3933
- final_summary[item.key] = json.loads(item.value_json)
3934
-
3935
- logger.info("rendering summary")
3936
- summary_rows = []
3937
- for key, value in sorted(final_summary.items()):
3938
- # arrays etc. might be too large. for now, we just don't print them
3939
- if isinstance(value, str):
3940
- value = value[:20] + "..." * (len(value) >= 20)
3941
- summary_rows.append([key, value])
3942
- elif isinstance(value, numbers.Number):
3943
- value = round(value, 5) if isinstance(value, float) else value
3944
- summary_rows.append([key, str(value)])
3945
- else:
3946
- continue
3905
+ @staticmethod
3906
+ def _footer_history(
3907
+ history: SampledHistoryResponse,
3908
+ printer: printer.Printer,
3909
+ settings: Settings,
3910
+ ) -> str | None:
3911
+ """Returns the run history formatted for printing to the console."""
3912
+ sorted_history_items = sorted(
3913
+ (item for item in history.item if not item.key.startswith("_")),
3914
+ key=lambda item: item.key,
3915
+ )
3947
3916
 
3948
- if summary_rows:
3949
- summary_grid = printer.grid(
3950
- summary_rows,
3951
- "Run summary:",
3952
- )
3953
- panel.append(summary_grid)
3917
+ history_rows: list[list[str]] = []
3918
+ for item in sorted_history_items:
3919
+ if len(history_rows) >= settings.max_end_of_run_history_metrics:
3920
+ break
3954
3921
 
3955
- if panel:
3956
- printer.display(printer.panel(panel))
3922
+ values = wandb.util.downsample(
3923
+ item.values_float or item.values_int,
3924
+ 40,
3925
+ )
3926
+
3927
+ if sparkline := printer.sparklines(values):
3928
+ history_rows.append([item.key, sparkline])
3929
+
3930
+ if not history_rows:
3931
+ return None
3932
+
3933
+ if len(history_rows) < len(sorted_history_items):
3934
+ remaining = len(sorted_history_items) - len(history_rows)
3935
+ history_rows.append([f"+{remaining:,d}", "..."])
3936
+
3937
+ return printer.grid(history_rows, "Run history:")
3938
+
3939
+ @staticmethod
3940
+ def _footer_summary(
3941
+ summary: GetSummaryResponse,
3942
+ printer: printer.Printer,
3943
+ settings: Settings,
3944
+ ) -> str | None:
3945
+ """Returns the run summary formatted for printing to the console."""
3946
+ sorted_summary_items = sorted(
3947
+ (
3948
+ item
3949
+ for item in summary.item
3950
+ if not item.key.startswith("_") and not item.nested_key
3951
+ ),
3952
+ key=lambda item: item.key,
3953
+ )
3954
+
3955
+ summary_rows: list[list[str]] = []
3956
+ skipped = 0
3957
+ for item in sorted_summary_items:
3958
+ if len(summary_rows) >= settings.max_end_of_run_summary_metrics:
3959
+ break
3960
+
3961
+ try:
3962
+ value = json.loads(item.value_json)
3963
+ except json.JSONDecodeError:
3964
+ logger.exception(f"Error decoding summary[{item.key!r}]")
3965
+ skipped += 1
3966
+ continue
3967
+
3968
+ if isinstance(value, str):
3969
+ value = value[:20] + "..." * (len(value) >= 20)
3970
+ summary_rows.append([item.key, value])
3971
+ elif isinstance(value, numbers.Number):
3972
+ value = round(value, 5) if isinstance(value, float) else value
3973
+ summary_rows.append([item.key, str(value)])
3974
+ else:
3975
+ skipped += 1
3976
+
3977
+ if not summary_rows:
3978
+ return None
3979
+
3980
+ if len(summary_rows) < len(sorted_summary_items) - skipped:
3981
+ remaining = len(sorted_summary_items) - len(summary_rows) - skipped
3982
+ summary_rows.append([f"+{remaining:,d}", "..."])
3983
+
3984
+ return printer.grid(summary_rows, "Run summary:")
3957
3985
 
3958
3986
  @staticmethod
3959
3987
  def _footer_internal_messages(
@@ -3985,19 +4013,19 @@ def restore(
3985
4013
  By default, will only download the file if it doesn't already exist.
3986
4014
 
3987
4015
  Args:
3988
- name: the name of the file
3989
- run_path: optional path to a run to pull files from, i.e. `username/project_name/run_id`
4016
+ name: The name of the file.
4017
+ run_path: Optional path to a run to pull files from, i.e. `username/project_name/run_id`
3990
4018
  if wandb.init has not been called, this is required.
3991
- replace: whether to download the file even if it already exists locally
3992
- root: the directory to download the file to. Defaults to the current
4019
+ replace: Whether to download the file even if it already exists locally
4020
+ root: The directory to download the file to. Defaults to the current
3993
4021
  directory or the run directory if wandb.init was called.
3994
4022
 
3995
4023
  Returns:
3996
- None if it can't find the file, otherwise a file object open for reading
4024
+ None if it can't find the file, otherwise a file object open for reading.
3997
4025
 
3998
4026
  Raises:
3999
- wandb.CommError: if we can't connect to the wandb backend
4000
- ValueError: if the file is not found or can't find run_path
4027
+ CommError: If W&B can't connect to the W&B backend.
4028
+ ValueError: If the file is not found or can't find run_path.
4001
4029
  """
4002
4030
  is_disabled = wandb.run is not None and wandb.run.disabled
4003
4031
  run = None if is_disabled else wandb.run