class_docstr: Iterates over all batches in the dataloader (one epoch) that the user returns in their
  :meth:`~lightning.pytorch.core.LightningModule.train_dataloader` method.
  
  Its main responsibilities are calling the ``*_epoch_{start,end}`` hooks, accumulating outputs if the user request
  them in one of these hooks, and running validation at the requested interval.
  
  The validation is carried out by yet another loop,
  :class:`~lightning.pytorch.loops._EvaluationLoop`.
  
  In the ``run()`` method, the training epoch loop could in theory simply call the
  ``LightningModule.training_step`` already and perform the optimization.
  However, Lightning has built-in support for automatic optimization with multiple optimizers.
  For this reason there are actually two more loops nested under
  :class:`~lightning.pytorch.loops._TrainingEpochLoop`.
  
  Args:
      min_steps: The minimum number of steps (batches) to process
      max_steps: The maximum number of steps (batches) to process
class_docstr_tok: ["Iterates","over","all","batches","in","the","dataloader","(","one","epoch",")","that","the","user","returns","in","their",":","meth",":","`","~lightning.pytorch.core.LightningModule.train_dataloader","`","method",".","Its","main","responsibilities","are","calling","the","``","*","_epoch_","{","start",",","end","}","``","hooks",",","accumulating","outputs","if","the","user","request","them","in","one","of","these","hooks",",","and","running","validation","at","the","requested","interval",".","The","validation","is","carried","out","by","yet","another","loop",",",":","class",":","`","~lightning.pytorch.loops._EvaluationLoop","`",".","In","the","``","run","(",")","``","method",",","the","training","epoch","loop","could","in","theory","simply","call","the","``","LightningModule.training_step","``","already","and","perform","the","optimization",".","However",",","Lightning","has","built-in","support","for","automatic","optimization","with","multiple","optimizers",".","For","this","reason","there","are","actually","two","more","loops","nested","under",":","class",":","`","~lightning.pytorch.loops._TrainingEpochLoop","`",".","Args",":","min_steps",":","The","minimum","number","of","steps","(","batches",")","to","process","max_steps",":","The","maximum","number","of","steps","(","batches",")","to","process"]
docstr: Runs a single training batch.
  
  Raises:
      StopIteration: When the epoch is canceled by the user returning -1
docstr_tok: ["Runs","a","single","training","batch",".","Raises",":","StopIteration",":","When","the","epoch","is","canceled","by","the","user","returning","-1"]
code: def advance(self, data_fetcher: _DataFetcher) -> None:
      """Runs a single training batch.
  
      Raises:
          StopIteration: When the epoch is canceled by the user returning -1
  
      """
      if self.restarting and self._should_check_val_fx(data_fetcher):
          # skip training and run validation in `on_advance_end`
          return
      # we are going to train first so the val loop does not need to restart
      self.val_loop.restarting = False
  
      if using_dataloader_iter := isinstance(
          data_fetcher, _DataLoaderIterDataFetcher
      ):
          dataloader_iter = next(data_fetcher)
          # hook's batch_idx and dataloader_idx arguments correctness cannot be guaranteed in this setting
          batch = data_fetcher._batch
          batch_idx = data_fetcher._batch_idx
      else:
          dataloader_iter = None
          batch, _, __ = next(data_fetcher)
          # TODO: we should instead use the batch_idx returned by the fetcher, however, that will require saving the
          # fetcher state so that the batch_idx is correct after restarting
          batch_idx = self.batch_idx + 1
      # Note: `is_last_batch` is not yet determined if data fetcher is a `_DataLoaderIterDataFetcher`
      self.batch_progress.is_last_batch = data_fetcher.done
  
      trainer = self.trainer
      if not using_dataloader_iter:
          batch = trainer.precision_plugin.convert_input(batch)
          batch = trainer.lightning_module._on_before_batch_transfer(
              batch, dataloader_idx=0
          )
          batch = call._call_strategy_hook(
              trainer, "batch_to_device", batch, dataloader_idx=0
          )
  
      self.batch_progress.increment_ready()
      trainer._logger_connector.on_batch_start(batch)
  
      batch_output: _BATCH_OUTPUTS_TYPE = None  # for mypy
      if batch is None and not using_dataloader_iter:
          self._warning_cache.warn(
              "train_dataloader yielded None. If this was on purpose, ignore this warning..."
          )
      else:
          # hook
          call._call_callback_hooks(
              trainer, "on_train_batch_start", batch, batch_idx
          )
          response = call._call_lightning_module_hook(
              trainer, "on_train_batch_start", batch, batch_idx
          )
          call._call_strategy_hook(
              trainer, "on_train_batch_start", batch, batch_idx
          )
          if response == -1:
              self.batch_progress.increment_processed()
              raise StopIteration
  
          self.batch_progress.increment_started()
  
          kwargs = (
              self._build_kwargs(OrderedDict(), batch, batch_idx)
              if not using_dataloader_iter
              else OrderedDict(any=dataloader_iter)
          )
          with trainer.profiler.profile("run_training_batch"):
              if trainer.lightning_module.automatic_optimization:
                  # in automatic optimization, there can only be one optimizer
                  batch_output = self.automatic_optimization.run(
                      trainer.optimizers[0], batch_idx, kwargs
                  )
              else:
                  batch_output = self.manual_optimization.run(kwargs)
  
      self.batch_progress.increment_processed()
  
      # update non-plateau LR schedulers
      # update epoch-interval ones only when we are at the end of training epoch
      self.update_lr_schedulers("step", update_plateau_schedulers=False)
      if self._num_ready_batches_reached():
          self.update_lr_schedulers(
              "epoch", update_plateau_schedulers=False
          )
  
      if using_dataloader_iter:
          # update the hook kwargs now that the step method might have consumed the iterator
          batch = data_fetcher._batch
          batch_idx = data_fetcher._batch_idx
          # update `is_last_batch` again after dataloader_iter was fetched in `training_step()`
          self.batch_progress.is_last_batch = data_fetcher.done
  
      call._call_callback_hooks(
          trainer, "on_train_batch_end", batch_output, batch, batch_idx
      )
      call._call_lightning_module_hook(
          trainer, "on_train_batch_end", batch_output, batch, batch_idx
      )
      trainer._logger_connector.on_batch_end()
  
      self.batch_progress.increment_completed()
  
      # -----------------------------------------
      # SAVE METRICS TO LOGGERS AND PROGRESS_BAR
      # -----------------------------------------
      trainer._logger_connector.update_train_step_metrics()
  
imports: import math
  from collections import OrderedDict
  from typing import Any, Dict, Optional, Union
  from typing_extensions import override
  import lightning.pytorch
  from lightning.pytorch import loops
  from lightning.pytorch.loops.fetchers import _DataFetcher, _DataLoaderIterDataFetcher
  from lightning.pytorch.loops.optimization import _AutomaticOptimization, _ManualOptimization
  from lightning.pytorch.loops.optimization.automatic import _OUTPUTS_TYPE
  from lightning.pytorch.loops.optimization.manual import _OUTPUTS_TYPE
  from lightning.pytorch.loops.progress import _BatchProgress, _SchedulerProgress
  from lightning.pytorch.loops.utilities import _is_max_limit_reached
  from lightning.pytorch.trainer import call
  from lightning.pytorch.trainer.connectors.logger_connector.result import _ResultCollection
  from lightning.pytorch.trainer.states import RunningStage, TrainerFn
  from lightning.pytorch.utilities.exceptions import MisconfigurationException, SIGTERMException
  from lightning.pytorch.utilities.rank_zero import WarningCache, rank_zero_warn
  from lightning.pytorch.utilities.signature_utils import is_param_in_hook_signature
label_desc: Use image node_id 13 for calling the _TrainingEpochLoop obj's underlying member method code with example usage: obj.advance(data_fetcher) without return types