class_docstr: A class representing an Experiment object.
  
  An Experiment object is usually obtained from
  :func:`determined.experimental.client.create_experiment`
  or :func:`determined.experimental.client.get_experiment` and contains helper methods
  that support querying the set of checkpoints associated with an experiment.
  
  Attributes:
      id: ID of experiment object in database.
      session: HTTP request session.
      config: (Mutable, Optional[Dict]) Experiment config for the experiment.
      state: (Mutable, Optional[experimentv1State) State of the experiment.
      archived: (Mutable, bool) True if experiment is archived, else false.
      name: (Mutable, str) Human-friendly name of the experiment.
      progress: (Mutable, float) Completion progress of experiment in range (0, 1.0) where 1.0
          is 100% completion.
      description: (Mutable, string) Description of the experiment.
      notes: (Mutable, str) Notes for the experiment.
      labels: (Mutable, Optional[List]) Labels associated with the experiment.
      project_id: (Mutable, int) The ID of the project associated with the experiment.
      workspace_id: (Mutable, int) The ID of the workspace associated with the experiment.
  
  Note:
      All attributes are cached by default.
  
      Some attributes are mutable and may be changed by methods that update these values,
      either automatically (eg. :meth:`wait()`) or explicitly with :meth:`reload()`.
class_docstr_tok: ["A","class","representing","an","Experiment","object",".","An","Experiment","object","is","usually","obtained","from",":","func",":","`","determined.experimental.client.create_experiment","`","or",":","func",":","`","determined.experimental.client.get_experiment","`","and","contains","helper","methods","that","support","querying","the","set","of","checkpoints","associated","with","an","experiment",".","Attributes",":","id",":","ID","of","experiment","object","in","database",".","session",":","HTTP","request","session",".","config",":","(","Mutable",",","Optional","[","Dict","]",")","Experiment","config","for","the","experiment",".","state",":","(","Mutable",",","Optional","[","experimentv1State",")","State","of","the","experiment",".","archived",":","(","Mutable",",","bool",")","True","if","experiment","is","archived",",","else","false",".","name",":","(","Mutable",",","str",")","Human-friendly","name","of","the","experiment",".","progress",":","(","Mutable",",","float",")","Completion","progress","of","experiment","in","range","(","0",",","1.0",")","where","1.0","is","100","%","completion",".","description",":","(","Mutable",",","string",")","Description","of","the","experiment",".","notes",":","(","Mutable",",","str",")","Notes","for","the","experiment",".","labels",":","(","Mutable",",","Optional","[","List","]",")","Labels","associated","with","the","experiment",".","project_id",":","(","Mutable",",","int",")","The","ID","of","the","project","associated","with","the","experiment",".","workspace_id",":","(","Mutable",",","int",")","The","ID","of","the","workspace","associated","with","the","experiment",".","Note",":","All","attributes","are","cached","by","default",".","Some","attributes","are","mutable","and","may","be","changed","by","methods","that","update","these","values",",","either","automatically","(","eg",".",":","meth",":","`","wait","(",")","`",")","or","explicitly","with",":","meth",":","`","reload","(",")","`","."]
docstr: Return the N :class:`~determined.experimental.Checkpoint` instances with the best
  validation metrics, as defined by the ``sort_by`` and ``smaller_is_better``
  arguments. This method will return the best checkpoint from the
  top N best-performing distinct trials of the experiment. Only checkpoints in
  a ``COMPLETED`` state with a matching ``COMPLETED`` validation are considered.
  
  Arguments:
      limit (int): The maximum number of checkpoints to return.
  
      sort_by (string, optional): The name of the validation metric to use for
          sorting checkpoints. If this parameter is unset, the metric defined
          in the experiment configuration searcher field will be
          used.
  
      smaller_is_better (bool, optional): Specifies whether to sort the
          metric above in ascending or descending order. If ``sort_by`` is unset,
          this parameter is ignored. By default, the value of ``smaller_is_better``
          from the experiment's configuration is used.
code: def top_n_checkpoints(
      self,
      limit: int,
      sort_by: Optional[str] = None,
      smaller_is_better: Optional[bool] = None,
  ) -> List[checkpoint.Checkpoint]:
      """
      Return the N :class:`~determined.experimental.Checkpoint` instances with the best
      validation metrics, as defined by the ``sort_by`` and ``smaller_is_better``
      arguments. This method will return the best checkpoint from the
      top N best-performing distinct trials of the experiment. Only checkpoints in
      a ``COMPLETED`` state with a matching ``COMPLETED`` validation are considered.
  
      Arguments:
          limit (int): The maximum number of checkpoints to return.
  
          sort_by (string, optional): The name of the validation metric to use for
              sorting checkpoints. If this parameter is unset, the metric defined
              in the experiment configuration searcher field will be
              used.
  
          smaller_is_better (bool, optional): Specifies whether to sort the
              metric above in ascending or descending order. If ``sort_by`` is unset,
              this parameter is ignored. By default, the value of ``smaller_is_better``
              from the experiment's configuration is used.
      """
      warnings.warn(
          "Experiment.top_n_checkpoints() has been deprecated and will be removed in a future "
          "version."
          "Please call Experiment.list_checkpoints(...,max_results=n) instead.",
          FutureWarning,
          stacklevel=2,
      )
  
      def get_with_offset(
          offset: int,
      ) -> bindings.v1GetExperimentCheckpointsResponse:
          return bindings.get_GetExperimentCheckpoints(
              self._session,
              id=self._id,
              offset=offset,
              states=[bindings.checkpointv1State.COMPLETED],
          )
  
      resps = api.read_paginated(get_with_offset)
  
      checkpoints = [
          checkpoint.Checkpoint._from_bindings(c, self._session)
          for r in resps
          for c in r.checkpoints
      ]
  
      if not checkpoints:
          raise AssertionError(
              "No checkpoint found for experiment {}".format(self.id)
          )
  
      if not sort_by:
          training = checkpoints[0].training
          assert training
          config = training.experiment_config
          sb = config.get("searcher", {}).get("metric")
          if not isinstance(sb, str):
              raise ValueError(
                  "no searcher.metric found in experiment config; please provide a sort_by metric"
              )
          sort_by = sb
          smaller_is_better = config.get("searcher", {}).get(
              "smaller_is_better", True
          )
  
      reverse = not smaller_is_better
  
      def key(ckpt: checkpoint.Checkpoint) -> Any:
          training = ckpt.training
          assert training
          metric = training.validation_metrics.get("avgMetrics") or {}
          metric = metric.get(sort_by)
  
          # Return a tuple that ensures checkpoints missing metrics appear last.
          if reverse:
              return metric is not None, metric
          else:
              return metric is None, metric
  
      checkpoints.sort(reverse=not smaller_is_better, key=key)
  
      # Ensure returned checkpoints are from distinct trials.
      t_ids = set()
      checkpoint_refs = []
      for ckpt in checkpoints:
          training = ckpt.training
          assert training
          if training.trial_id not in t_ids:
              checkpoint_refs.append(ckpt)
              t_ids.add(training.trial_id)
  
      return checkpoint_refs[:limit]
  
imports: import base64
  import enum
  import pathlib
  import sys
  import time
  import warnings
  from typing import Any, Dict, Iterator, List, Optional, Set, Union
  from determined.common import api
  from determined.common.api import bindings
  from determined.common.experimental import checkpoint, trial, workspace
  from determined.common.experimental._util import OrderBy
label_desc: Use image node_id 27 for calling the Experiment obj's underlying member method code with example usage: obj.top_n_checkpoints(limit, sort_by, smaller_is_better) and returns: checkpoint_refs, bindings, unknown,  metric, unknown,  metric