class_docstr: Tuner is the recommended way of launching hyperparameter tuning jobs with Ray Tune.
  
  Args:
      trainable: The trainable to be tuned.
      param_space: Search space of the tuning job.
          One thing to note is that both preprocessor and dataset can be tuned here.
      tune_config: Tuning algorithm specific configs.
          Refer to ray.tune.tune_config.TuneConfig for more info.
      run_config: Runtime configuration that is specific to individual trials.
          If passed, this will overwrite the run config passed to the Trainer,
          if applicable. Refer to ray.train.RunConfig for more info.
  
  Usage pattern:
  
  .. code-block:: python
  
      from sklearn.datasets import load_breast_cancer
  
      from ray import tune
      from ray.data import from_pandas
      from ray.train import RunConfig, ScalingConfig
      from ray.train.xgboost import XGBoostTrainer
      from ray.tune.tuner import Tuner
  
      def get_dataset():
          data_raw = load_breast_cancer(as_frame=True)
          dataset_df = data_raw["data"]
          dataset_df["target"] = data_raw["target"]
          dataset = from_pandas(dataset_df)
          return dataset
  
      trainer = XGBoostTrainer(
          label_column="target",
          params={},
          datasets={"train": get_dataset()},
      )
  
      param_space = {
          "scaling_config": ScalingConfig(
              num_workers=tune.grid_search([2, 4]),
              resources_per_worker={
                  "CPU": tune.grid_search([1, 2]),
              },
          ),
          # You can even grid search various datasets in Tune.
          # "datasets": {
          #     "train": tune.grid_search(
          #         [ds1, ds2]
          #     ),
          # },
          "params": {
              "objective": "binary:logistic",
              "tree_method": "approx",
              "eval_metric": ["logloss", "error"],
              "eta": tune.loguniform(1e-4, 1e-1),
              "subsample": tune.uniform(0.5, 1.0),
              "max_depth": tune.randint(1, 9),
          },
      }
      tuner = Tuner(trainable=trainer, param_space=param_space,
          run_config=RunConfig(name="my_tune_run"))
      results = tuner.fit()
  
  To retry a failed tune run, you can then do
  
  .. code-block:: python
  
      tuner = Tuner.restore(results.experiment_path, trainable=trainer)
      tuner.fit()
  
  ``results.experiment_path`` can be retrieved from the
  :ref:`ResultGrid object <tune-analysis-docs>`. It can
  also be easily seen in the log output from your first run.
class_docstr_tok: ["Tuner","is","the","recommended","way","of","launching","hyperparameter","tuning","jobs","with","Ray","Tune",".","Args",":","trainable",":","The","trainable","to","be","tuned",".","param_space",":","Search","space","of","the","tuning","job",".","One","thing","to","note","is","that","both","preprocessor","and","dataset","can","be","tuned","here",".","tune_config",":","Tuning","algorithm","specific","configs",".","Refer","to","ray.tune.tune_config.TuneConfig","for","more","info",".","run_config",":","Runtime","configuration","that","is","specific","to","individual","trials",".","If","passed",",","this","will","overwrite","the","run","config","passed","to","the","Trainer",",","if","applicable",".","Refer","to","ray.train.RunConfig","for","more","info",".","Usage","pattern",":","..","code-block",":",":","python","from","sklearn.datasets","import","load_breast_cancer","from","ray","import","tune","from","ray.data","import","from_pandas","from","ray.train","import","RunConfig",",","ScalingConfig","from","ray.train.xgboost","import","XGBoostTrainer","from","ray.tune.tuner","import","Tuner","def","get_dataset","(",")",":","data_raw","=","load_breast_cancer","(","as_frame=True",")","dataset_df","=","data_raw","[","``","data","''","]","dataset_df","[","``","target","''","]","=","data_raw","[","``","target","''","]","dataset","=","from_pandas","(","dataset_df",")","return","dataset","trainer","=","XGBoostTrainer","(","label_column=","''","target","''",",","params=","{","}",",","datasets=","{","``","train","''",":","get_dataset","(",")","}",",",")","param_space","=","{","``","scaling_config","''",":","ScalingConfig","(","num_workers=tune.grid_search","(","[","2",",","4","]",")",",","resources_per_worker=","{","``","CPU","''",":","tune.grid_search","(","[","1",",","2","]",")",",","}",",",")",",","#","You","can","even","grid","search","various","datasets","in","Tune",".","#","``","datasets","''",":","{","#","``","train","''",":","tune.grid_search","(","#","[","ds1",",","ds2","]","#",")",",","#","}",",","``","params","''",":","{","``","objective","''",":","``","binary",":","logistic","''",",","``","tree_method","''",":","``","approx","''",",","``","eval_metric","''",":","[","``","logloss","''",",","``","error","''","]",",","``","eta","''",":","tune.loguniform","(","1e-4",",","1e-1",")",",","``","subsample","''",":","tune.uniform","(","0.5",",","1.0",")",",","``","max_depth","''",":","tune.randint","(","1",",","9",")",",","}",",","}","tuner","=","Tuner","(","trainable=trainer",",","param_space=param_space",",","run_config=RunConfig","(","name=","''","my_tune_run","''",")",")","results","=","tuner.fit","(",")","To","retry","a","failed","tune","run",",","you","can","then","do","..","code-block",":",":","python","tuner","=","Tuner.restore","(","results.experiment_path",",","trainable=trainer",")","tuner.fit","(",")","``","results.experiment_path","``","can","be","retrieved","from","the",":","ref",":","`","ResultGrid","object","<","tune-analysis-docs",">","`",".","It","can","also","be","easily","seen","in","the","log","output","from","your","first","run","."]
docstr: Restores Tuner after a previously failed run.
  
  All trials from the existing run will be added to the result table. The
  argument flags control how existing but unfinished or errored trials are
  resumed.
  
  Finished trials are always added to the overview table. They will not be
  resumed.
  
  Unfinished trials can be controlled with the ``resume_unfinished`` flag.
  If ``True`` (default), they will be continued. If ``False``, they will
  be added as terminated trials (even if they were only created and never
  trained).
  
  Errored trials can be controlled with the ``resume_errored`` and
  ``restart_errored`` flags. The former will resume errored trials from
  their latest checkpoints. The latter will restart errored trials from
  scratch and prevent loading their last checkpoints.
  
  .. note::
  
      Restoring an experiment from a path that's pointing to a *different*
      location than the original experiment path is supported.
      However, Ray Tune assumes that the full experiment directory is available
      (including checkpoints) so that it's possible to resume trials from their
      latest state.
  
      For example, if the original experiment path was run locally,
      then the results are uploaded to cloud storage, Ray Tune expects the full
      contents to be available in cloud storage if attempting to resume
      via ``Tuner.restore("s3://...")``. The restored run will continue
      writing results to the same cloud storage location.
  
  Args:
      path: The local or remote path of the experiment directory
          for an interrupted or failed run.
          Note that an experiment where all trials finished will not be resumed.
          This information could be easily located near the end of the
          console output of previous run.
      trainable: The trainable to use upon resuming the experiment.
          This should be the same trainable that was used to initialize
          the original Tuner.
      param_space: The same `param_space` that was passed to
          the original Tuner. This can be optionally re-specified due
          to the `param_space` potentially containing Ray object
          references (tuning over Datasets or tuning over
          several `ray.put` object references). **Tune expects the
          `param_space` to be unmodified**, and the only part that
          will be used during restore are the updated object references.
          Changing the hyperparameter search space then resuming is NOT
          supported by this API.
      resume_unfinished: If True, will continue to run unfinished trials.
      resume_errored: If True, will re-schedule errored trials and try to
          restore from their latest checkpoints.
      restart_errored: If True, will re-schedule errored trials but force
          restarting them from scratch (no checkpoint will be loaded).
      storage_filesystem: Custom ``pyarrow.fs.FileSystem``
          corresponding to the ``path``. This may be necessary if the original
          experiment passed in a custom filesystem.
docstr_tok: ["Restores","Tuner","after","a","previously","failed","run",".","All","trials","from","the","existing","run","will","be","added","to","the","result","table",".","The","argument","flags","control","how","existing","but","unfinished","or","errored","trials","are","resumed",".","Finished","trials","are","always","added","to","the","overview","table",".","They","will","not","be","resumed",".","Unfinished","trials","can","be","controlled","with","the","``","resume_unfinished","``","flag",".","If","``","True","``","(","default",")",",","they","will","be","continued",".","If","``","False","``",",","they","will","be","added","as","terminated","trials","(","even","if","they","were","only","created","and","never","trained",")",".","Errored","trials","can","be","controlled","with","the","``","resume_errored","``","and","``","restart_errored","``","flags",".","The","former","will","resume","errored","trials","from","their","latest","checkpoints",".","The","latter","will","restart","errored","trials","from","scratch","and","prevent","loading","their","last","checkpoints",".","..","note",":",":","Restoring","an","experiment","from","a","path","that","'s","pointing","to","a","*","different","*","location","than","the","original","experiment","path","is","supported",".","However",",","Ray","Tune","assumes","that","the","full","experiment","directory","is","available","(","including","checkpoints",")","so","that","it","'s","possible","to","resume","trials","from","their","latest","state",".","For","example",",","if","the","original","experiment","path","was","run","locally",",","then","the","results","are","uploaded","to","cloud","storage",",","Ray","Tune","expects","the","full","contents","to","be","available","in","cloud","storage","if","attempting","to","resume","via","``","Tuner.restore","(","``","s3",":","\/\/","...","''",")","``",".","The","restored","run","will","continue","writing","results","to","the","same","cloud","storage","location",".","Args",":","path",":","The","local","or","remote","path","of","the","experiment","directory","for","an","interrupted","or","failed","run",".","Note","that","an","experiment","where","all","trials","finished","will","not","be","resumed",".","This","information","could","be","easily","located","near","the","end","of","the","console","output","of","previous","run",".","trainable",":","The","trainable","to","use","upon","resuming","the","experiment",".","This","should","be","the","same","trainable","that","was","used","to","initialize","the","original","Tuner",".","param_space",":","The","same","`","param_space","`","that","was","passed","to","the","original","Tuner",".","This","can","be","optionally","re-specified","due","to","the","`","param_space","`","potentially","containing","Ray","object","references","(","tuning","over","Datasets","or","tuning","over","several","`","ray.put","`","object","references",")",".","*","*","Tune","expects","the","`","param_space","`","to","be","unmodified","*","*",",","and","the","only","part","that","will","be","used","during","restore","are","the","updated","object","references",".","Changing","the","hyperparameter","search","space","then","resuming","is","NOT","supported","by","this","API",".","resume_unfinished",":","If","True",",","will","continue","to","run","unfinished","trials",".","resume_errored",":","If","True",",","will","re-schedule","errored","trials","and","try","to","restore","from","their","latest","checkpoints",".","restart_errored",":","If","True",",","will","re-schedule","errored","trials","but","force","restarting","them","from","scratch","(","no","checkpoint","will","be","loaded",")",".","storage_filesystem",":","Custom","``","pyarrow.fs.FileSystem","``","corresponding","to","the","``","path","``",".","This","may","be","necessary","if","the","original","experiment","passed","in","a","custom","filesystem","."]
code: def restore(
      cls,
      path: str,
      trainable: Union[str, Callable, Type[Trainable], "BaseTrainer"],
      resume_unfinished: bool = True,
      resume_errored: bool = False,
      restart_errored: bool = False,
      param_space: Optional[Dict[str, Any]] = None,
      storage_filesystem: Optional[pyarrow.fs.FileSystem] = None,
  ) -> "Tuner":
      """Restores Tuner after a previously failed run.
  
      All trials from the existing run will be added to the result table. The
      argument flags control how existing but unfinished or errored trials are
      resumed.
  
      Finished trials are always added to the overview table. They will not be
      resumed.
  
      Unfinished trials can be controlled with the ``resume_unfinished`` flag.
      If ``True`` (default), they will be continued. If ``False``, they will
      be added as terminated trials (even if they were only created and never
      trained).
  
      Errored trials can be controlled with the ``resume_errored`` and
      ``restart_errored`` flags. The former will resume errored trials from
      their latest checkpoints. The latter will restart errored trials from
      scratch and prevent loading their last checkpoints.
  
      .. note::
  
          Restoring an experiment from a path that's pointing to a *different*
          location than the original experiment path is supported.
          However, Ray Tune assumes that the full experiment directory is available
          (including checkpoints) so that it's possible to resume trials from their
          latest state.
  
          For example, if the original experiment path was run locally,
          then the results are uploaded to cloud storage, Ray Tune expects the full
          contents to be available in cloud storage if attempting to resume
          via ``Tuner.restore("s3://...")``. The restored run will continue
          writing results to the same cloud storage location.
  
      Args:
          path: The local or remote path of the experiment directory
              for an interrupted or failed run.
              Note that an experiment where all trials finished will not be resumed.
              This information could be easily located near the end of the
              console output of previous run.
          trainable: The trainable to use upon resuming the experiment.
              This should be the same trainable that was used to initialize
              the original Tuner.
          param_space: The same `param_space` that was passed to
              the original Tuner. This can be optionally re-specified due
              to the `param_space` potentially containing Ray object
              references (tuning over Datasets or tuning over
              several `ray.put` object references). **Tune expects the
              `param_space` to be unmodified**, and the only part that
              will be used during restore are the updated object references.
              Changing the hyperparameter search space then resuming is NOT
              supported by this API.
          resume_unfinished: If True, will continue to run unfinished trials.
          resume_errored: If True, will re-schedule errored trials and try to
              restore from their latest checkpoints.
          restart_errored: If True, will re-schedule errored trials but force
              restarting them from scratch (no checkpoint will be loaded).
          storage_filesystem: Custom ``pyarrow.fs.FileSystem``
              corresponding to the ``path``. This may be necessary if the original
              experiment passed in a custom filesystem.
      """
      # TODO(xwjiang): Add some comments to clarify the config behavior across
      #  retored runs.
      #  For example, is callbacks supposed to be automatically applied
      #  when a Tuner is restored and fit again?
  
      resume_config = _ResumeConfig(
          resume_unfinished=resume_unfinished,
          resume_errored=resume_errored,
          restart_errored=restart_errored,
      )
  
      if not ray.util.client.ray.is_connected():
          tuner_internal = TunerInternal(
              restore_path=path,
              resume_config=resume_config,
              trainable=trainable,
              param_space=param_space,
              storage_filesystem=storage_filesystem,
          )
          return Tuner(_tuner_internal=tuner_internal)
      else:
          tuner_internal = _force_on_current_node(
              ray.remote(num_cpus=0)(TunerInternal)
          ).remote(
              restore_path=path,
              resume_config=resume_config,
              trainable=trainable,
              param_space=param_space,
              storage_filesystem=storage_filesystem,
          )
          return Tuner(_tuner_internal=tuner_internal)
  
imports: import logging
  import os
  from typing import Any, Callable, Dict, Optional, Type, Union, TYPE_CHECKING
  import pyarrow.fs
  import ray
  from ray.air.config import RunConfig
  from ray.air._internal.usage import AirEntrypoint
  from ray.air.util.node import _force_on_current_node
  from ray.train._internal.storage import _exists_at_fs_path, get_fs_and_path
  from ray.tune import TuneError
  from ray.tune.execution.experiment_state import _ResumeConfig
  from ray.tune.experimental.output import get_air_verbosity
  from ray.tune.result_grid import ResultGrid
  from ray.tune.trainable import Trainable
  from ray.tune.impl.tuner_internal import TunerInternal, _TUNER_PKL
  from ray.tune.tune_config import TuneConfig
  from ray.tune.progress_reporter import _prepare_progress_reporter_for_ray_client, _stream_client_output
  from ray.util import PublicAPI
label_desc: Use image node_id 2 for calling the Tuner obj's underlying member method code with example usage: obj.restore(cls, path, trainable, resume_unfinished, resume_errored, restart_errored, param_space, storage_filesystem) and returns: Tuner, Tuner