class_docstr: ExperimentClient providing all functionalities for the python API
  
  Note that the ExperimentClient is not meant to be instantiated by the user.
  Look at `orion.client.create_experiment` to build an ExperimentClient.
  
  Parameters
  ----------
  experiment: `orion.core.worker.experiment.Experiment`
      Experiment object serving for interaction with storage
class_docstr_tok: ["ExperimentClient","providing","all","functionalities","for","the","python","API","Note","that","the","ExperimentClient","is","not","meant","to","be","instantiated","by","the","user",".","Look","at","`","orion.client.create_experiment","`","to","build","an","ExperimentClient",".","Parameters","--","--","--","--","--","experiment",":","`","orion.core.worker.experiment.Experiment","`","Experiment","object","serving","for","interaction","with","storage"]
docstr: Suggest a trial to execute.
  
  Experiment must be in executable ('x') mode.
  
  If any trial is available (new or interrupted), it selects one and reserves it.
  Otherwise, the algorithm is used to generate a new trial that is registered in storage and
  reserved.
  
  Parameters
  ----------
  pool_size: int, optional
      Number of trials to sample at a time. If 0, default to global config if defined,
      else 1.  Increase it to improve the sampling speed if workers spend too much time
      waiting for algorithms to sample points. An algorithm will try sampling `pool_size`
      trials but may return less. Note: The method will still return only 1 trial even though
      if the pool size is larger than 1. This is because atomic reservation of trials
      can only be done one at a time.
  
  Returns
  -------
  `orior.core.worker.trial.Trial`
      Reserved trial for execution.
  
  Raises
  ------
  :class:`orion.core.utils.exceptions.WaitingForTrials`
      if the experiment is not completed and algorithm needs to wait for some
      trials to complete before it can suggest new trials.
  
  :class:`orion.core.utils.exceptions.BrokenExperiment`
      if too many trials failed to run and the experiment cannot continue.
      This is determined by ``max_broken`` in the configuration of the experiment.
  
  :class:`orion.core.utils.exceptions.ReservationRaceCondition`
      If a trial could not be reserved right after they were generated
  
  :class:`orion.core.utils.exceptions.CompletedExperiment`
      if the experiment was completed and algorithm could not sample new trials.
  
  :class:`orion.core.utils.exceptions.UnsupportedOperation`
      If the experiment was not loaded in executable mode.
docstr_tok: ["Suggest","a","trial","to","execute",".","Experiment","must","be","in","executable","(","'","x","'",")","mode",".","If","any","trial","is","available","(","new","or","interrupted",")",",","it","selects","one","and","reserves","it",".","Otherwise",",","the","algorithm","is","used","to","generate","a","new","trial","that","is","registered","in","storage","and","reserved",".","Parameters","--","--","--","--","--","pool_size",":","int",",","optional","Number","of","trials","to","sample","at","a","time",".","If","0",",","default","to","global","config","if","defined",",","else","1",".","Increase","it","to","improve","the","sampling","speed","if","workers","spend","too","much","time","waiting","for","algorithms","to","sample","points",".","An","algorithm","will","try","sampling","`","pool_size","`","trials","but","may","return","less",".","Note",":","The","method","will","still","return","only","1","trial","even","though","if","the","pool","size","is","larger","than","1",".","This","is","because","atomic","reservation","of","trials","can","only","be","done","one","at","a","time",".","Returns","--","--","--","-","`","orior.core.worker.trial.Trial","`","Reserved","trial","for","execution",".","Raises","--","--","--",":","class",":","`","orion.core.utils.exceptions.WaitingForTrials","`","if","the","experiment","is","not","completed","and","algorithm","needs","to","wait","for","some","trials","to","complete","before","it","can","suggest","new","trials",".",":","class",":","`","orion.core.utils.exceptions.BrokenExperiment","`","if","too","many","trials","failed","to","run","and","the","experiment","can","not","continue",".","This","is","determined","by","``","max_broken","``","in","the","configuration","of","the","experiment",".",":","class",":","`","orion.core.utils.exceptions.ReservationRaceCondition","`","If","a","trial","could","not","be","reserved","right","after","they","were","generated",":","class",":","`","orion.core.utils.exceptions.CompletedExperiment","`","if","the","experiment","was","completed","and","algorithm","could","not","sample","new","trials",".",":","class",":","`","orion.core.utils.exceptions.UnsupportedOperation","`","If","the","experiment","was","not","loaded","in","executable","mode","."]
code: def suggest(self, pool_size=0):
      """Suggest a trial to execute.
  
      Experiment must be in executable ('x') mode.
  
      If any trial is available (new or interrupted), it selects one and reserves it.
      Otherwise, the algorithm is used to generate a new trial that is registered in storage and
      reserved.
  
      Parameters
      ----------
      pool_size: int, optional
          Number of trials to sample at a time. If 0, default to global config if defined,
          else 1.  Increase it to improve the sampling speed if workers spend too much time
          waiting for algorithms to sample points. An algorithm will try sampling `pool_size`
          trials but may return less. Note: The method will still return only 1 trial even though
          if the pool size is larger than 1. This is because atomic reservation of trials
          can only be done one at a time.
  
      Returns
      -------
      `orior.core.worker.trial.Trial`
          Reserved trial for execution.
  
      Raises
      ------
      :class:`orion.core.utils.exceptions.WaitingForTrials`
          if the experiment is not completed and algorithm needs to wait for some
          trials to complete before it can suggest new trials.
  
      :class:`orion.core.utils.exceptions.BrokenExperiment`
          if too many trials failed to run and the experiment cannot continue.
          This is determined by ``max_broken`` in the configuration of the experiment.
  
      :class:`orion.core.utils.exceptions.ReservationRaceCondition`
          If a trial could not be reserved right after they were generated
  
      :class:`orion.core.utils.exceptions.CompletedExperiment`
          if the experiment was completed and algorithm could not sample new trials.
  
      :class:`orion.core.utils.exceptions.UnsupportedOperation`
          If the experiment was not loaded in executable mode.
  
      """
      self._check_if_executable()
      if not pool_size:
          pool_size = orion.core.config.worker.pool_size
      if not pool_size:
          pool_size = 1
  
      if self.is_broken:
          raise BrokenExperiment("Trials failed too many times")
  
      if self.is_done:
          raise CompletedExperiment(
              "Experiment is done, cannot sample more trials."
          )
  
      try:
          trial = reserve_trial(
              self._experiment, self._producer, pool_size
          )
  
      except (ReservationRaceCondition, WaitingForTrials) as e:
          if self.is_broken:
              raise BrokenExperiment(
                  "Trials failed too many times"
              ) from e
  
          raise e
  
      # This is to handle cases where experiment was completed during call to `reserve_trial`
      if trial is None and self.is_done:
          raise CompletedExperiment(
              "Producer is done, cannot sample more trials."
          )
      elif trial is None and self.is_broken:
          raise BrokenExperiment("Trials failed too many times")
  
      self._maintain_reservation(trial)
      return TrialCM(self, trial)
  
imports: from __future__ import annotations
  import inspect
  import logging
  import numbers
  import typing
  from contextlib import contextmanager
  from typing import Callable
  import orion.core
  from orion.algo.space import Space
  from orion.client.runner import Runner, prepare_trial_working_dir
  from orion.core.io.database import DuplicateKeyError
  from orion.core.utils.exceptions import BrokenExperiment, CompletedExperiment, ReservationRaceCondition, UnsupportedOperation, WaitingForTrials
  from orion.core.utils.format_trials import dict_to_trial
  from orion.core.utils.working_dir import SetupWorkingDir
  from orion.core.worker.experiment import AlgoT
  from orion.core.worker.producer import Producer
  from orion.core.worker.trial import AlreadyReleased, Trial, TrialCM
  from orion.core.worker.trial_pacemaker import TrialPacemaker
  from orion.executor.base import BaseExecutor, executor_factory
  from orion.plotting.base import PlotAccessor
  from orion.storage.base import FailedUpdate
label_desc: Use image node_id 32 for calling the ExperimentClient obj's underlying member method code with example usage: obj.suggest(pool_size) and returns: TrialCM