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: Insert a new trial.
  
  Experiment must be in writable ('w') or executable ('x') mode.
  
  Parameters
  ----------
  params: dict
      Parameters of the new trial to add to the database. These parameters
      must comply with the space definition otherwise a ValueError will be raised.
  results: list, optional
      Results to be set for the new trial. Results must have the format
      {name: <str>: type: <'objective', 'constraint' or 'gradient'>, value=<float>} otherwise
      a ValueError will be raised.
      Note that passing results will mark the trial as completed and therefore cannot be
      reserved. The returned trial will have status 'completed'.
      If the results are invalid, the trial will still be inserted but reservation will be
      released.
  reserve: bool, optional
      If reserve=True, the inserted trial will be reserved. `reserve` cannot be True if
      `results` are given.
      Defaults to False.
  
  Returns
  -------
  `orion.core.worker.trial.Trial`
      The trial inserted in storage. If `reserve=True` and no results are given, the returned
      trial will be in a `reserved` status.
  
  Raises
  ------
  `ValueError`
      - If results are given and reserve=True
      - If params have invalid format
      - If results have invalid format
  `orion.core.io.database.DuplicateKeyError`
      - If a trial with identical params already exist for the current experiment.
  `orion.core.utils.exceptions.UnsupportedOperation`
      If the experiment was not loaded in writable mode.
docstr_tok: ["Insert","a","new","trial",".","Experiment","must","be","in","writable","(","'","w","'",")","or","executable","(","'","x","'",")","mode",".","Parameters","--","--","--","--","--","params",":","dict","Parameters","of","the","new","trial","to","add","to","the","database",".","These","parameters","must","comply","with","the","space","definition","otherwise","a","ValueError","will","be","raised",".","results",":","list",",","optional","Results","to","be","set","for","the","new","trial",".","Results","must","have","the","format","{","name",":","<","str",">",":","type",":","<","'objective","'",",","'constraint","'","or","'gradient","'",">",",","value=","<","float",">","}","otherwise","a","ValueError","will","be","raised",".","Note","that","passing","results","will","mark","the","trial","as","completed","and","therefore","can","not","be","reserved",".","The","returned","trial","will","have","status","'completed","'",".","If","the","results","are","invalid",",","the","trial","will","still","be","inserted","but","reservation","will","be","released",".","reserve",":","bool",",","optional","If","reserve=True",",","the","inserted","trial","will","be","reserved",".","`","reserve","`","can","not","be","True","if","`","results","`","are","given",".","Defaults","to","False",".","Returns","--","--","--","-","`","orion.core.worker.trial.Trial","`","The","trial","inserted","in","storage",".","If","`","reserve=True","`","and","no","results","are","given",",","the","returned","trial","will","be","in","a","`","reserved","`","status",".","Raises","--","--","--","`","ValueError","`","-","If","results","are","given","and","reserve=True","-","If","params","have","invalid","format","-","If","results","have","invalid","format","`","orion.core.io.database.DuplicateKeyError","`","-","If","a","trial","with","identical","params","already","exist","for","the","current","experiment",".","`","orion.core.utils.exceptions.UnsupportedOperation","`","If","the","experiment","was","not","loaded","in","writable","mode","."]
code: def insert(self, params, results=None, reserve=False):
      """Insert a new trial.
  
      Experiment must be in writable ('w') or executable ('x') mode.
  
      Parameters
      ----------
      params: dict
          Parameters of the new trial to add to the database. These parameters
          must comply with the space definition otherwise a ValueError will be raised.
      results: list, optional
          Results to be set for the new trial. Results must have the format
          {name: <str>: type: <'objective', 'constraint' or 'gradient'>, value=<float>} otherwise
          a ValueError will be raised.
          Note that passing results will mark the trial as completed and therefore cannot be
          reserved. The returned trial will have status 'completed'.
          If the results are invalid, the trial will still be inserted but reservation will be
          released.
      reserve: bool, optional
          If reserve=True, the inserted trial will be reserved. `reserve` cannot be True if
          `results` are given.
          Defaults to False.
  
      Returns
      -------
      `orion.core.worker.trial.Trial`
          The trial inserted in storage. If `reserve=True` and no results are given, the returned
          trial will be in a `reserved` status.
  
      Raises
      ------
      `ValueError`
          - If results are given and reserve=True
          - If params have invalid format
          - If results have invalid format
      `orion.core.io.database.DuplicateKeyError`
          - If a trial with identical params already exist for the current experiment.
      `orion.core.utils.exceptions.UnsupportedOperation`
          If the experiment was not loaded in writable mode.
  
      """
      self._check_if_writable()
  
      if results and reserve:
          raise ValueError(
              "Cannot observe a trial and reserve it. A trial with results has status "
              "`completed` and cannot be reserved."
          )
      trial = dict_to_trial(params, self.space)
      try:
          self._experiment.register_trial(trial, status="reserved")
          self._maintain_reservation(trial)
      except DuplicateKeyError as e:
          message = (
              f"A trial with params {params} already exist for experiment "
              f"{self.name}-v{self.version}"
          )
          raise DuplicateKeyError(message) from e
  
      if results:
          try:
              self.observe(trial, results)
          except ValueError:
              self._release_reservation(trial)
              raise
  
          return trial
  
      if not reserve:
          self.release(trial)
  
      return 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 29 for calling the ExperimentClient obj's underlying member method code with example usage: obj.insert(params, results, reserve) and returns: trial, trial