class_docstr: ``CheckpointContext`` gives access to checkpoint-related features of a Determined cluster.
class_docstr_tok: ["``","CheckpointContext","``","gives","access","to","checkpoint-related","features","of","a","Determined","cluster","."]
docstr: ``upload()`` chooses a random ``storage_id``, then uploads the contents of ``ckpt_dir`` to
  checkpoint storage into a directory by the name of the ``storage_id``.  The name of the
  ``ckpt_dir`` is not preserved.
  
  When ``shard=False``, only the chief worker (``distributed.rank==0``) may call ``upload()``.
  
  When ``shard=True``, ``upload()`` becomes a synchronization point between workers, so all
  workers must call upload().  Those workers with nothing to upload may pass
  ``ckpt_dir=None``. The final checkpoint stored in checkpoint storage will contain a union
  of the contents from each ckpt_dir.
  
  Each worker may optionally provide a ``selector`` that accepts a path
  relative to the checkpoint root, and returns True for paths that should be uploaded.
  
  Returns:  The ``storage_id`` for this checkpoint.
  
  Example:
  
  .. code::
  
     if core_context.distributed.rank == 0:
         storage_id = core_context.checkpoint.upload(ckpt_dir, shard=False)
         print(f"done uploading checkpoint {storage_id}")
docstr_tok: ["``","upload","(",")","``","chooses","a","random","``","storage_id","``",",","then","uploads","the","contents","of","``","ckpt_dir","``","to","checkpoint","storage","into","a","directory","by","the","name","of","the","``","storage_id","``",".","The","name","of","the","``","ckpt_dir","``","is","not","preserved",".","When","``","shard=False","``",",","only","the","chief","worker","(","``","distributed.rank==0","``",")","may","call","``","upload","(",")","``",".","When","``","shard=True","``",",","``","upload","(",")","``","becomes","a","synchronization","point","between","workers",",","so","all","workers","must","call","upload","(",")",".","Those","workers","with","nothing","to","upload","may","pass","``","ckpt_dir=None","``",".","The","final","checkpoint","stored","in","checkpoint","storage","will","contain","a","union","of","the","contents","from","each","ckpt_dir",".","Each","worker","may","optionally","provide","a","``","selector","``","that","accepts","a","path","relative","to","the","checkpoint","root",",","and","returns","True","for","paths","that","should","be","uploaded",".","Returns",":","The","``","storage_id","``","for","this","checkpoint",".","Example",":","..","code",":",":","if","core_context.distributed.rank","==","0",":","storage_id","=","core_context.checkpoint.upload","(","ckpt_dir",",","shard=False",")","print","(","f","''","done","uploading","checkpoint","{","storage_id","}","''",")"]
code: def upload(
      self,
      ckpt_dir: Optional[Union[str, os.PathLike]],
      metadata: Optional[Dict[str, Any]] = None,
      *,
      shard: bool = False,
      selector: Optional[Callable[[str], bool]] = None,
  ) -> str:
      """
      ``upload()`` chooses a random ``storage_id``, then uploads the contents of ``ckpt_dir`` to
      checkpoint storage into a directory by the name of the ``storage_id``.  The name of the
      ``ckpt_dir`` is not preserved.
  
      When ``shard=False``, only the chief worker (``distributed.rank==0``) may call ``upload()``.
  
      When ``shard=True``, ``upload()`` becomes a synchronization point between workers, so all
      workers must call upload().  Those workers with nothing to upload may pass
      ``ckpt_dir=None``. The final checkpoint stored in checkpoint storage will contain a union
      of the contents from each ckpt_dir.
  
      Each worker may optionally provide a ``selector`` that accepts a path
      relative to the checkpoint root, and returns True for paths that should be uploaded.
  
      Returns:  The ``storage_id`` for this checkpoint.
  
      Example:
  
      .. code::
  
         if core_context.distributed.rank == 0:
             storage_id = core_context.checkpoint.upload(ckpt_dir, shard=False)
             print(f"done uploading checkpoint {storage_id}")
      """
      if ckpt_dir is not None:
          ckpt_dir = os.fspath(ckpt_dir)
  
      # The simple and sharded cases can technically be written as one function but it becomes
      # far more complicated than having two codepaths.
      if not shard:
          if self._dist.rank != 0:
              raise RuntimeError(
                  f"cannot call .upload(shard=False) from non-chief worker "
                  f"(rank={self._dist.rank})"
              )
          if ckpt_dir is None:
              raise RuntimeError(
                  "cannot call .upload(ckpt_dir=None, shard=False), which would result in doing "
                  "nothing at all"
              )
          return self._upload_single(
              ckpt_dir, metadata, selector=selector
          )
      else:
          storage_id = None
          if self._dist.rank == 0:
              storage_id = str(uuid.uuid4())
          storage_id = self._dist.broadcast(storage_id)
  
          assert storage_id
          return self._upload_sharded(
              ckpt_dir, storage_id, metadata, selector=selector
          )
  
imports: import contextlib
  import datetime
  import enum
  import hashlib
  import json
  import logging
  import os
  import pathlib
  import uuid
  from typing import Any, Callable, Dict, Iterator, List, Optional, Set, Tuple, Union
  from determined import core, tensorboard
  from determined.common import api, storage
  from determined.common.api import bindings
label_desc: Use image node_id 2 for calling the CheckpointContext obj's underlying member method code with example usage: obj.upload(ckpt_dir, metadata) and returns: self, self