ultralytics 8.3.143__py3-none-any.whl → 8.3.145__py3-none-any.whl

ultralytics/utils/callbacks/dvc.py

@@ -36,7 +36,7 @@ def _log_images(path: Path, prefix: str = "") -> None:
 
     Args:
         path (Path): Path to the image file to be logged.
-        prefix (str): Optional prefix to add to the image name when logging.
+        prefix (str, optional): Optional prefix to add to the image name when logging.
 
     Examples:
         >>> from pathlib import Path
@@ -77,11 +77,8 @@ def _log_confusion_matrix(validator) -> None:
     the matrix into lists of target and prediction labels.
 
     Args:
-        validator (BaseValidator): The validator object containing the confusion matrix and class names.
-            Must have attributes: confusion_matrix.matrix, confusion_matrix.task, and names.
-
-    Returns:
-        None
+        validator (BaseValidator): The validator object containing the confusion matrix and class names. Must have
+            attributes: confusion_matrix.matrix, confusion_matrix.task, and names.
     """
     targets = []
     preds = []
@@ -99,7 +96,7 @@ def _log_confusion_matrix(validator) -> None:
 
 
 def on_pretrain_routine_start(trainer) -> None:
-    """Initializes DVCLive logger for training metadata during pre-training routine."""
+    """Initialize DVCLive logger for training metadata during pre-training routine."""
     try:
         global live
         live = dvclive.Live(save_dvc_exp=True, cache_images=True)
@@ -109,18 +106,18 @@ def on_pretrain_routine_start(trainer) -> None:
 
 
 def on_pretrain_routine_end(trainer) -> None:
-    """Logs plots related to the training process at the end of the pretraining routine."""
+    """Log plots related to the training process at the end of the pretraining routine."""
     _log_plots(trainer.plots, "train")
 
 
 def on_train_start(trainer) -> None:
-    """Logs the training parameters if DVCLive logging is active."""
+    """Log the training parameters if DVCLive logging is active."""
     if live:
         live.log_params(trainer.args)
 
 
 def on_train_epoch_start(trainer) -> None:
-    """Sets the global variable _training_epoch value to True at the start of training each epoch."""
+    """Set the global variable _training_epoch value to True at the start of training each epoch."""
     global _training_epoch
     _training_epoch = True
 

ultralytics/utils/callbacks/mlflow.py

@@ -55,14 +55,11 @@ def on_pretrain_routine_end(trainer):
     Args:
         trainer (ultralytics.engine.trainer.BaseTrainer): The training object with arguments and parameters to log.
 
-    Global:
-        mlflow: The imported mlflow module to use for logging.
-
     Environment Variables:
         MLFLOW_TRACKING_URI: The URI for MLflow tracking. If not set, defaults to 'runs/mlflow'.
         MLFLOW_EXPERIMENT_NAME: The name of the MLflow experiment. If not set, defaults to trainer.args.project.
         MLFLOW_RUN: The name of the MLflow run. If not set, defaults to trainer.args.name.
-        MLFLOW_KEEP_RUN_ACTIVE: Boolean indicating whether to keep the MLflow run active after the end of training.
+        MLFLOW_KEEP_RUN_ACTIVE: Boolean indicating whether to keep the MLflow run active after training ends.
     """
     global mlflow
 
@@ -107,7 +104,7 @@ def on_fit_epoch_end(trainer):
 
 
 def on_train_end(trainer):
-    """Log model artifacts at the end of the training."""
+    """Log model artifacts at the end of training."""
     if not mlflow:
         return
     mlflow.log_artifact(str(trainer.best.parent))  # log save_dir/weights directory with best.pt and last.pt

ultralytics/utils/callbacks/neptune.py

@@ -23,7 +23,7 @@ def _log_scalars(scalars: dict, step: int = 0) -> None:
 
     Args:
         scalars (dict): Dictionary of scalar values to log to NeptuneAI.
-        step (int): The current step or iteration number for logging.
+        step (int, optional): The current step or iteration number for logging.
 
     Examples:
         >>> metrics = {"mAP": 0.85, "loss": 0.32}
@@ -55,13 +55,7 @@ def _log_images(imgs_dict: dict, group: str = "") -> None:
 
 
 def _log_plot(title: str, plot_path: str) -> None:
-    """
-    Log plots to the NeptuneAI experiment logger.
-
-    Args:
-        title (str): Title of the plot.
-        plot_path (str): Path to the saved image file.
-    """
+    """Log plots to the NeptuneAI experiment logger."""
     import matplotlib.image as mpimg
     import matplotlib.pyplot as plt
 
@@ -73,7 +67,7 @@ def _log_plot(title: str, plot_path: str) -> None:
 
 
 def on_pretrain_routine_start(trainer) -> None:
-    """Callback function called before the training routine starts."""
+    """Initialize NeptuneAI run and log hyperparameters before training starts."""
     try:
         global run
         run = neptune.init_run(
@@ -87,7 +81,7 @@ def on_pretrain_routine_start(trainer) -> None:
 
 
 def on_train_epoch_end(trainer) -> None:
-    """Callback function called at end of each training epoch."""
+    """Log training metrics and learning rate at the end of each training epoch."""
     _log_scalars(trainer.label_loss_items(trainer.tloss, prefix="train"), trainer.epoch + 1)
     _log_scalars(trainer.lr, trainer.epoch + 1)
     if trainer.epoch == 1:
@@ -95,7 +89,7 @@ def on_train_epoch_end(trainer) -> None:
 
 
 def on_fit_epoch_end(trainer) -> None:
-    """Callback function called at end of each fit (train+val) epoch."""
+    """Log model info and validation metrics at the end of each fit epoch."""
     if run and trainer.epoch == 0:
         from ultralytics.utils.torch_utils import model_info_for_loggers
 
@@ -104,14 +98,14 @@ def on_fit_epoch_end(trainer) -> None:
 
 
 def on_val_end(validator) -> None:
-    """Callback function called at end of each validation."""
+    """Log validation images at the end of validation."""
     if run:
         # Log val_labels and val_pred
         _log_images({f.stem: str(f) for f in validator.save_dir.glob("val*.jpg")}, "Validation")
 
 
 def on_train_end(trainer) -> None:
-    """Callback function called at end of training."""
+    """Log final results, plots, and model weights at the end of training."""
     if run:
         # Log final results, CM matrix + PR plots
         files = [

ultralytics/utils/callbacks/raytune.py

@@ -14,7 +14,7 @@ except (ImportError, AssertionError):
 
 def on_fit_epoch_end(trainer):
     """
-    Reports training metrics to Ray Tune at epoch end when a Ray session is active.
+    Report training metrics to Ray Tune at epoch end when a Ray session is active.
 
     Captures metrics from the trainer object and sends them to Ray Tune with the current epoch number,
     enabling hyperparameter tuning optimization. Only executes when within an active Ray Tune session.

ultralytics/utils/callbacks/tensorboard.py

@@ -31,7 +31,7 @@ def _log_scalars(scalars: dict, step: int = 0) -> None:
         step (int): Global step value to record with the scalar values. Used for x-axis in TensorBoard graphs.
 
     Examples:
-        >>> # Log training metrics
+        Log training metrics
         >>> metrics = {"loss": 0.5, "accuracy": 0.95}
         >>> _log_scalars(metrics, step=100)
     """
@@ -49,9 +49,8 @@ def _log_tensorboard_graph(trainer) -> None:
     approach for models like RTDETR that may require special handling.
 
     Args:
-        trainer (BaseTrainer): The trainer object containing the model to visualize. Must have attributes:
-            - model: PyTorch model to visualize
-            - args: Configuration arguments with 'imgsz' attribute
+        trainer (ultralytics.engine.trainer.BaseTrainer): The trainer object containing the model to visualize.
+            Must have attributes model and args with imgsz.
 
     Notes:
         This function requires TensorBoard integration to be enabled and the global WRITER to be initialized.
@@ -110,13 +109,13 @@ def on_train_start(trainer) -> None:
 
 
 def on_train_epoch_end(trainer) -> None:
-    """Logs scalar statistics at the end of a training epoch."""
+    """Log scalar statistics at the end of a training epoch."""
     _log_scalars(trainer.label_loss_items(trainer.tloss, prefix="train"), trainer.epoch + 1)
     _log_scalars(trainer.lr, trainer.epoch + 1)
 
 
 def on_fit_epoch_end(trainer) -> None:
-    """Logs epoch metrics at end of training epoch."""
+    """Log epoch metrics at end of training epoch."""
     _log_scalars(trainer.metrics, trainer.epoch + 1)
 
 

ultralytics/utils/callbacks/wb.py

@@ -27,9 +27,9 @@ def _custom_table(x, y, classes, title="Precision Recall Curve", x_title="Recall
         x (list): Values for the x-axis; expected to have length N.
         y (list): Corresponding values for the y-axis; also expected to have length N.
         classes (list): Labels identifying the class of each point; length N.
-        title (str): Title for the plot; defaults to 'Precision Recall Curve'.
-        x_title (str): Label for the x-axis; defaults to 'Recall'.
-        y_title (str): Label for the y-axis; defaults to 'Precision'.
+        title (str, optional): Title for the plot.
+        x_title (str, optional): Label for the x-axis.
+        y_title (str, optional): Label for the y-axis.
 
     Returns:
         (wandb.Object): A wandb object suitable for logging, showcasing the crafted metric visualization.
@@ -64,13 +64,13 @@ def _plot_curve(
     Args:
         x (np.ndarray): Data points for the x-axis with length N.
         y (np.ndarray): Corresponding data points for the y-axis with shape (C, N), where C is the number of classes.
-        names (list): Names of the classes corresponding to the y-axis data; length C.
-        id (str): Unique identifier for the logged data in wandb.
-        title (str): Title for the visualization plot.
-        x_title (str): Label for the x-axis.
-        y_title (str): Label for the y-axis.
-        num_x (int): Number of interpolated data points for visualization.
-        only_mean (bool): Flag to indicate if only the mean curve should be plotted.
+        names (list, optional): Names of the classes corresponding to the y-axis data; length C.
+        id (str, optional): Unique identifier for the logged data in wandb.
+        title (str, optional): Title for the visualization plot.
+        x_title (str, optional): Label for the x-axis.
+        y_title (str, optional): Label for the y-axis.
+        num_x (int, optional): Number of interpolated data points for visualization.
+        only_mean (bool, optional): Flag to indicate if only the mean curve should be plotted.
 
     Notes:
         The function leverages the '_custom_table' function to generate the actual visualization.
@@ -111,9 +111,9 @@ def _log_plots(plots, step):
         step (int): The step/epoch at which to log the plots in the WandB run.
 
     Notes:
-        - The function uses a shallow copy of the plots dictionary to prevent modification during iteration
-        - Plots are identified by their stem name (filename without extension)
-        - Each plot is logged as a WandB Image object
+        The function uses a shallow copy of the plots dictionary to prevent modification during iteration.
+        Plots are identified by their stem name (filename without extension).
+        Each plot is logged as a WandB Image object.
     """
     for name, params in plots.copy().items():  # shallow copy to prevent plots dict changing during iteration
         timestamp = params["timestamp"]
@@ -123,7 +123,7 @@ def _log_plots(plots, step):
 
 
 def on_pretrain_routine_start(trainer):
-    """Initiate and start wandb project if module is present."""
+    """Initialize and start wandb project if module is present."""
     if not wb.run:
         wb.init(
             project=str(trainer.args.project).replace("/", "-") if trainer.args.project else "Ultralytics",

ultralytics/utils/checks.py

@@ -58,7 +58,8 @@ def parse_requirements(file_path=ROOT.parent / "requirements.txt", package=""):
         package (str, optional): Python package to use instead of requirements.txt file.
 
     Returns:
-        (List[SimpleNamespace]): List of parsed requirements as SimpleNamespace objects with `name` and `specifier` attributes.
+        requirements (List[SimpleNamespace]): List of parsed requirements as SimpleNamespace objects with `name` and
+            `specifier` attributes.
 
     Examples:
         >>> from ultralytics.utils.checks import parse_requirements
@@ -89,7 +90,7 @@ def parse_version(version="0.0.0") -> tuple:
         version (str): Version string, i.e. '2.0.1+cpu'
 
     Returns:
-        (Tuple[int, int, int]): Tuple of integers representing the numeric part of the version, i.e. (2, 0, 1)
+        (tuple): Tuple of integers representing the numeric part of the version, i.e. (2, 0, 1)
     """
     try:
         return tuple(map(int, re.findall(r"\d+", version)[:3]))  # '2.0.1+cpu' -> (2, 0, 1)
@@ -167,7 +168,7 @@ def check_imgsz(imgsz, stride=32, min_dim=1, max_dim=2, floor=0):
 
 @functools.lru_cache
 def check_uv():
-    """Check if uv is installed and can run successfully."""
+    """Check if uv package manager is installed and can run successfully."""
     try:
         return subprocess.run(["uv", "-V"], capture_output=True).returncode == 0
     except FileNotFoundError:
@@ -265,7 +266,7 @@ def check_version(
 
 def check_latest_pypi_version(package_name="ultralytics"):
     """
-    Returns the latest version of a PyPI package without downloading or installing it.
+    Return the latest version of a PyPI package without downloading or installing it.
 
     Args:
         package_name (str): The name of the package to find the latest version for.
@@ -286,7 +287,7 @@ def check_latest_pypi_version(package_name="ultralytics"):
 
 def check_pip_update_available():
     """
-    Checks if a new version of the ultralytics package is available on PyPI.
+    Check if a new version of the ultralytics package is available on PyPI.
 
     Returns:
         (bool): True if an update is available, False otherwise.
@@ -360,9 +361,9 @@ def check_requirements(requirements=ROOT.parent / "requirements.txt", exclude=()
     Check if installed dependencies meet Ultralytics YOLO models requirements and attempt to auto-update if needed.
 
     Args:
-        requirements (Union[Path, str, List[str]]): Path to a requirements.txt file, a single package requirement as a
+        requirements (Path | str | List[str]): Path to a requirements.txt file, a single package requirement as a
             string, or a list of package requirements as strings.
-        exclude (Tuple[str]): Tuple of package names to exclude from checking.
+        exclude (tuple): Tuple of package names to exclude from checking.
         install (bool): If True, attempt to auto-update packages that don't meet requirements.
         cmds (str): Additional commands to pass to the pip install command when auto-updating.
 
@@ -432,7 +433,7 @@ def check_requirements(requirements=ROOT.parent / "requirements.txt", exclude=()
 
 def check_torchvision():
     """
-    Checks the installed versions of PyTorch and Torchvision to ensure they're compatible.
+    Check the installed versions of PyTorch and Torchvision to ensure they're compatible.
 
     This function checks the installed versions of PyTorch and Torchvision, and warns if they're incompatible according
     to the compatibility table based on: https://github.com/pytorch/vision#installation.
@@ -470,7 +471,7 @@ def check_suffix(file="yolo11n.pt", suffix=".pt", msg=""):
 
     Args:
         file (str | List[str]): File or list of files to check.
-        suffix (str | Tuple[str]): Acceptable suffix or tuple of suffixes.
+        suffix (str | tuple): Acceptable suffix or tuple of suffixes.
         msg (str): Additional message to display in case of error.
     """
     if file and suffix:
@@ -531,7 +532,7 @@ def check_file(file, suffix="", download=True, download_dir=".", hard=True):
 
     Args:
         file (str): File name or path.
-        suffix (str | Tuple[str]): Acceptable suffix or tuple of suffixes to validate against the file.
+        suffix (str | tuple): Acceptable suffix or tuple of suffixes to validate against the file.
         download (bool): Whether to download the file if it doesn't exist locally.
         download_dir (str): Directory to download the file to.
         hard (bool): Whether to raise an error if the file is not found.
@@ -571,7 +572,7 @@ def check_yaml(file, suffix=(".yaml", ".yml"), hard=True):
 
     Args:
         file (str | Path): File name or path.
-        suffix (Tuple[str]): Tuple of acceptable YAML file suffixes.
+        suffix (tuple): Tuple of acceptable YAML file suffixes.
         hard (bool): Whether to raise an error if the file is not found or multiple files are found.
 
     Returns:
@@ -720,13 +721,13 @@ def collect_system_info():
 
 def check_amp(model):
     """
-    Checks the PyTorch Automatic Mixed Precision (AMP) functionality of a YOLO11 model.
+    Check the PyTorch Automatic Mixed Precision (AMP) functionality of a YOLO model.
 
     If the checks fail, it means there are anomalies with AMP on the system that may cause NaN losses or zero-mAP
     results, so AMP will be disabled during training.
 
     Args:
-        model (nn.Module): A YOLO11 model instance.
+        model (torch.nn.Module): A YOLO model instance.
 
     Returns:
         (bool): Returns True if the AMP functionality works correctly with YOLO11 model, else False.

ultralytics/utils/dist.py

@@ -34,8 +34,8 @@ def generate_ddp_file(trainer):
     The file contains the necessary configuration to initialize the trainer in a distributed environment.
 
     Args:
-        trainer (object): The trainer object containing training configuration and arguments.
-                         Must have args attribute and be a class instance.
+        trainer (ultralytics.engine.trainer.BaseTrainer): The trainer containing training configuration and arguments.
+            Must have args attribute and be a class instance.
 
     Returns:
         (str): Path to the generated temporary DDP file.
@@ -76,13 +76,13 @@ if __name__ == "__main__":
     return file.name
 
 
-def generate_ddp_command(world_size, trainer):
+def generate_ddp_command(world_size: int, trainer):
     """
     Generate command for distributed training.
 
     Args:
         world_size (int): Number of processes to spawn for distributed training.
-        trainer (object): The trainer object containing configuration for distributed training.
+        trainer (ultralytics.engine.trainer.BaseTrainer): The trainer containing configuration for distributed training.
 
     Returns:
         cmd (List[str]): The command to execute for distributed training.
@@ -107,7 +107,7 @@ def ddp_cleanup(trainer, file):
     as a temporary file for DDP training, and deletes it if so.
 
     Args:
-        trainer (object): The trainer object used for distributed training.
+        trainer (ultralytics.engine.trainer.BaseTrainer): The trainer used for distributed training.
         file (str): Path to the file that might need to be deleted.
 
     Examples: