ultralytics 8.3.142__py3-none-any.whl → 8.3.144__py3-none-any.whl

ultralytics/utils/__init__.py

@@ -139,7 +139,8 @@ class TQDM(rich.tqdm if TQDM_RICH else tqdm.tqdm):
     A custom TQDM progress bar class that extends the original tqdm functionality.
 
     This class modifies the behavior of the original tqdm progress bar based on global settings and provides
-    additional customization options.
+    additional customization options for Ultralytics projects. The progress bar is automatically disabled when
+    VERBOSE is False or when explicitly disabled.
 
     Attributes:
         disable (bool): Whether to disable the progress bar. Determined by the global VERBOSE setting and
@@ -148,7 +149,8 @@ class TQDM(rich.tqdm if TQDM_RICH else tqdm.tqdm):
             explicitly set.
 
     Methods:
-        __init__: Initializes the TQDM object with custom settings.
+        __init__: Initialize the TQDM object with custom settings.
+        __iter__: Return self as iterator to satisfy Iterable interface.
 
     Examples:
         >>> from ultralytics.utils import TQDM
@@ -159,9 +161,7 @@ class TQDM(rich.tqdm if TQDM_RICH else tqdm.tqdm):
 
     def __init__(self, *args, **kwargs):
         """
-        Initializes a custom TQDM progress bar.
-
-        This class extends the original tqdm class to provide customized behavior for Ultralytics projects.
+        Initialize a custom TQDM progress bar with Ultralytics-specific settings.
 
         Args:
             *args (Any): Variable length argument list to be passed to the original tqdm constructor.
@@ -192,17 +192,17 @@ class DataExportMixin:
     Mixin class for exporting validation metrics or prediction results in various formats.
 
     This class provides utilities to export performance metrics (e.g., mAP, precision, recall) or prediction results
-    from classification, object detection, segmentation, or pose estimation tasks into various formats, Pandas DataFrame
-    CSV, XML, HTML, JSON and SQLite (SQL)
+    from classification, object detection, segmentation, or pose estimation tasks into various formats: Pandas
+    DataFrame, CSV, XML, HTML, JSON and SQLite (SQL).
 
     Methods:
-        to_df(): Convert summary to a Pandas DataFrame.
-        to_csv(): Export results as a CSV string.
-        to_xml(): Export results as an XML string (requires `lxml`).
-        to_html(): Export results as an HTML table.
-        to_json(): Export results as a JSON string.
-        tojson(): Deprecated alias for `to_json()`.
-        to_sql(): Export results to an SQLite database.
+        to_df: Convert summary to a Pandas DataFrame.
+        to_csv: Export results as a CSV string.
+        to_xml: Export results as an XML string (requires `lxml`).
+        to_html: Export results as an HTML table.
+        to_json: Export results as a JSON string.
+        tojson: Deprecated alias for `to_json()`.
+        to_sql: Export results to an SQLite database.
 
     Examples:
         >>> model = YOLO("yolov8n.pt")
@@ -218,8 +218,8 @@ class DataExportMixin:
         Create a pandas DataFrame from the prediction results summary or validation metrics.
 
         Args:
-            normalize (bool, optional): Normalize numerical values for easier comparison. Defaults to False.
-            decimals (int, optional): Decimal places to round floats. Defaults to 5.
+            normalize (bool, optional): Normalize numerical values for easier comparison.
+            decimals (int, optional): Decimal places to round floats.
 
         Returns:
             (DataFrame): DataFrame containing the summary data.
@@ -233,8 +233,8 @@ class DataExportMixin:
         Export results to CSV string format.
 
         Args:
-           normalize (bool, optional): Normalize numeric values. Defaults to False.
-           decimals (int, optional): Decimal precision. Defaults to 5.
+           normalize (bool, optional): Normalize numeric values.
+           decimals (int, optional): Decimal precision.
 
         Returns:
            (str): CSV content as string.
@@ -246,13 +246,13 @@ class DataExportMixin:
         Export results to XML format.
 
         Args:
-            normalize (bool, optional): Normalize numeric values. Defaults to False.
-            decimals (int, optional): Decimal precision. Defaults to 5.
+            normalize (bool, optional): Normalize numeric values.
+            decimals (int, optional): Decimal precision.
 
         Returns:
             (str): XML string.
 
-        Note:
+        Notes:
             Requires `lxml` package to be installed.
         """
         from ultralytics.utils.checks import check_requirements
@@ -266,9 +266,9 @@ class DataExportMixin:
         Export results to HTML table format.
 
         Args:
-            normalize (bool, optional): Normalize numeric values. Defaults to False.
-            decimals (int, optional): Decimal precision. Defaults to 5.
-            index (bool, optional): Whether to include index column in the HTML table. Defaults to False.
+            normalize (bool, optional): Normalize numeric values.
+            decimals (int, optional): Decimal precision.
+            index (bool, optional): Whether to include index column in the HTML table.
 
         Returns:
             (str): HTML representation of the results.
@@ -286,8 +286,8 @@ class DataExportMixin:
         Export results to JSON format.
 
         Args:
-            normalize (bool, optional): Normalize numeric values. Defaults to False.
-            decimals (int, optional): Decimal precision. Defaults to 5.
+            normalize (bool, optional): Normalize numeric values.
+            decimals (int, optional): Decimal precision.
 
         Returns:
             (str): JSON-formatted string of the results.
@@ -299,10 +299,10 @@ class DataExportMixin:
         Save results to an SQLite database.
 
         Args:
-            normalize (bool, optional): Normalize numeric values. Defaults to False.
-            decimals (int, optional): Decimal precision. Defaults to 5.
-            table_name (str, optional): Name of the SQL table. Defaults to "results".
-            db_path (str, optional): SQLite database file path. Defaults to "results.db".
+            normalize (bool, optional): Normalize numeric values.
+            decimals (int, optional): Decimal precision.
+            table_name (str, optional): Name of the SQL table.
+            db_path (str, optional): SQLite database file path.
         """
         df = self.to_df(normalize, decimals)
         if df.empty or df.columns.empty:  # Exit if df is None or has no columns (i.e., no schema)
@@ -348,9 +348,9 @@ class SimpleClass:
     showing all their non-callable attributes. It's useful for debugging and introspection of object states.
 
     Methods:
-        __str__: Returns a human-readable string representation of the object.
-        __repr__: Returns a machine-readable string representation of the object.
-        __getattr__: Provides a custom attribute access error message with helpful information.
+        __str__: Return a human-readable string representation of the object.
+        __repr__: Return a machine-readable string representation of the object.
+        __getattr__: Provide a custom attribute access error message with helpful information.
 
     Examples:
         >>> class MyClass(SimpleClass):
@@ -389,7 +389,7 @@ class SimpleClass:
         return self.__str__()
 
     def __getattr__(self, attr):
-        """Custom attribute access error message with helpful information."""
+        """Provide a custom attribute access error message with helpful information."""
         name = self.__class__.__name__
         raise AttributeError(f"'{name}' object has no attribute '{attr}'. See valid attributes below.\n{self.__doc__}")
 
@@ -403,10 +403,10 @@ class IterableSimpleNamespace(SimpleNamespace):
     configuration parameters.
 
     Methods:
-        __iter__: Returns an iterator of key-value pairs from the namespace's attributes.
-        __str__: Returns a human-readable string representation of the object.
-        __getattr__: Provides a custom attribute access error message with helpful information.
-        get: Retrieves the value of a specified key, or a default value if the key doesn't exist.
+        __iter__: Return an iterator of key-value pairs from the namespace's attributes.
+        __str__: Return a human-readable string representation of the object.
+        __getattr__: Provide a custom attribute access error message with helpful information.
+        get: Retrieve the value of a specified key, or a default value if the key doesn't exist.
 
     Examples:
         >>> cfg = IterableSimpleNamespace(a=1, b=2, c=3)
@@ -438,7 +438,7 @@ class IterableSimpleNamespace(SimpleNamespace):
         return "\n".join(f"{k}={v}" for k, v in vars(self).items())
 
     def __getattr__(self, attr):
-        """Custom attribute access error message with helpful information."""
+        """Provide a custom attribute access error message with helpful information."""
         name = self.__class__.__name__
         raise AttributeError(
             f"""
@@ -460,7 +460,7 @@ def plt_settings(rcparams=None, backend="Agg"):
 
     Args:
         rcparams (dict, optional): Dictionary of rc parameters to set.
-        backend (str, optional): Name of the backend to use. Defaults to 'Agg'.
+        backend (str, optional): Name of the backend to use.
 
     Returns:
         (Callable): Decorated function with temporarily set rc parameters and backend.
@@ -484,7 +484,7 @@ def plt_settings(rcparams=None, backend="Agg"):
         """Decorator to apply temporary rc parameters and backend to a function."""
 
         def wrapper(*args, **kwargs):
-            """Sets rc parameters and backend, calls the original function, and restores the settings."""
+            """Set rc parameters and backend, call the original function, and restore the settings."""
             import matplotlib.pyplot as plt  # scope for faster 'import ultralytics'
 
             original_backend = plt.get_backend()
@@ -510,15 +510,15 @@ def plt_settings(rcparams=None, backend="Agg"):
 
 def set_logging(name="LOGGING_NAME", verbose=True):
     """
-    Sets up logging with UTF-8 encoding and configurable verbosity.
+    Set up logging with UTF-8 encoding and configurable verbosity.
 
     This function configures logging for the Ultralytics library, setting the appropriate logging level and
     formatter based on the verbosity flag and the current process rank. It handles special cases for Windows
     environments where UTF-8 encoding might not be the default.
 
     Args:
-        name (str): Name of the logger. Defaults to "LOGGING_NAME".
-        verbose (bool): Flag to set logging level to INFO if True, ERROR otherwise. Defaults to True.
+        name (str): Name of the logger.
+        verbose (bool): Flag to set logging level to INFO if True, ERROR otherwise.
 
     Returns:
         (logging.Logger): Configured logger object.
@@ -618,7 +618,7 @@ class ThreadingLocked:
 
         @wraps(f)
         def decorated(*args, **kwargs):
-            """Applies thread-safety to the decorated function or method."""
+            """Apply thread-safety to the decorated function or method."""
             with self.lock:
                 return f(*args, **kwargs)
 
@@ -767,7 +767,7 @@ DEFAULT_CFG = IterableSimpleNamespace(**DEFAULT_CFG_DICT)
 
 def read_device_model() -> str:
     """
-    Reads the device model information from the system and caches it for quick access.
+    Read the device model information from the system and cache it for quick access.
 
     Returns:
         (str): Kernel release information.
@@ -816,7 +816,7 @@ def is_jupyter():
     Returns:
         (bool): True if running inside a Jupyter Notebook, False otherwise.
 
-    Note:
+    Notes:
         - Only works on Colab and Kaggle, other environments like Jupyterlab and Paperspace are not reliably detectable.
         - "get_ipython" in globals() method suffers false positives when IPython package installed manually.
     """
@@ -849,7 +849,7 @@ def is_docker() -> bool:
 
 def is_raspberrypi() -> bool:
     """
-    Determines if the Python environment is running on a Raspberry Pi.
+    Determine if the Python environment is running on a Raspberry Pi.
 
     Returns:
         (bool): True if running on a Raspberry Pi, False otherwise.
@@ -859,7 +859,7 @@ def is_raspberrypi() -> bool:
 
 def is_jetson() -> bool:
     """
-    Determines if the Python environment is running on an NVIDIA Jetson device.
+    Determine if the Python environment is running on an NVIDIA Jetson device.
 
     Returns:
         (bool): True if running on an NVIDIA Jetson device, False otherwise.
@@ -887,7 +887,7 @@ def is_online() -> bool:
 
 def is_pip_package(filepath: str = __name__) -> bool:
     """
-    Determines if the file at the given filepath is part of a pip package.
+    Determine if the file at the given filepath is part of a pip package.
 
     Args:
         filepath (str): The filepath to check.
@@ -919,7 +919,7 @@ def is_dir_writeable(dir_path: Union[str, Path]) -> bool:
 
 def is_pytest_running():
     """
-    Determines whether pytest is currently running or not.
+    Determine whether pytest is currently running or not.
 
     Returns:
         (bool): True if pytest is running, False otherwise.
@@ -939,7 +939,7 @@ def is_github_action_running() -> bool:
 
 def get_git_dir():
     """
-    Determines whether the current file is part of a git repository and if so, returns the repository root directory.
+    Determine whether the current file is part of a git repository and if so, return the repository root directory.
 
     Returns:
         (Path | None): Git root directory if found or None if not found.
@@ -951,7 +951,7 @@ def get_git_dir():
 
 def is_git_dir():
     """
-    Determines whether the current file is part of a git repository.
+    Determine whether the current file is part of a git repository.
 
     Returns:
         (bool): True if current file is part of a git repository.
@@ -961,7 +961,7 @@ def is_git_dir():
 
 def get_git_origin_url():
     """
-    Retrieves the origin URL of a git repository.
+    Retrieve the origin URL of a git repository.
 
     Returns:
         (str | None): The origin URL of the git repository or None if not git directory.
@@ -976,7 +976,7 @@ def get_git_origin_url():
 
 def get_git_branch():
     """
-    Returns the current git branch name. If not in a git repository, returns None.
+    Return the current git branch name. If not in a git repository, return None.
 
     Returns:
         (str | None): The current git branch name or None if not a git directory.
@@ -991,7 +991,7 @@ def get_git_branch():
 
 def get_default_args(func):
     """
-    Returns a dictionary of default arguments for a function.
+    Return a dictionary of default arguments for a function.
 
     Args:
         func (callable): The function to inspect.
@@ -1069,8 +1069,7 @@ SETTINGS_FILE = USER_CONFIG_DIR / "settings.json"
 
 def colorstr(*input):
     r"""
-    Colors a string based on the provided color and style arguments. Utilizes ANSI escape codes.
-    See https://en.wikipedia.org/wiki/ANSI_escape_code for more details.
+    Color a string based on the provided color and style arguments using ANSI escape codes.
 
     This function can be called in two ways:
         - colorstr('color', 'style', 'your string')
@@ -1082,18 +1081,22 @@ def colorstr(*input):
         *input (str | Path): A sequence of strings where the first n-1 strings are color and style arguments,
                       and the last string is the one to be colored.
 
-    Supported Colors and Styles:
-        Basic Colors: 'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'
-        Bright Colors: 'bright_black', 'bright_red', 'bright_green', 'bright_yellow',
-                       'bright_blue', 'bright_magenta', 'bright_cyan', 'bright_white'
-        Misc: 'end', 'bold', 'underline'
-
     Returns:
         (str): The input string wrapped with ANSI escape codes for the specified color and style.
 
+    Notes:
+        Supported Colors and Styles:
+        - Basic Colors: 'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'
+        - Bright Colors: 'bright_black', 'bright_red', 'bright_green', 'bright_yellow',
+                       'bright_blue', 'bright_magenta', 'bright_cyan', 'bright_white'
+        - Misc: 'end', 'bold', 'underline'
+
     Examples:
         >>> colorstr("blue", "bold", "hello world")
         >>> "\033[34m\033[1mhello world\033[0m"
+
+    References:
+        https://en.wikipedia.org/wiki/ANSI_escape_code
     """
     *args, string = input if len(input) > 1 else ("blue", "bold", input[0])  # color arguments, string
     colors = {
@@ -1122,7 +1125,7 @@ def colorstr(*input):
 
 def remove_colorstr(input_string):
     """
-    Removes ANSI escape codes from a string, effectively un-coloring it.
+    Remove ANSI escape codes from a string, effectively un-coloring it.
 
     Args:
         input_string (str): The string to remove color and style from.
@@ -1140,7 +1143,14 @@ def remove_colorstr(input_string):
 
 class TryExcept(contextlib.ContextDecorator):
     """
-    Ultralytics TryExcept class. Use as @TryExcept() decorator or 'with TryExcept():' context manager.
+    Ultralytics TryExcept class for handling exceptions gracefully.
+
+    This class can be used as a decorator or context manager to catch exceptions and optionally print warning messages.
+    It allows code to continue execution even when exceptions occur, which is useful for non-critical operations.
+
+    Attributes:
+        msg (str): Optional message to display when an exception occurs.
+        verbose (bool): Whether to print the exception message.
 
     Examples:
         As a decorator:
@@ -1161,11 +1171,11 @@ class TryExcept(contextlib.ContextDecorator):
         self.verbose = verbose
 
     def __enter__(self):
-        """Executes when entering TryExcept context, initializes instance."""
+        """Execute when entering TryExcept context, initialize instance."""
         pass
 
     def __exit__(self, exc_type, value, traceback):
-        """Defines behavior when exiting a 'with' block, prints error message if necessary."""
+        """Define behavior when exiting a 'with' block, print error message if necessary."""
         if self.verbose and value:
             LOGGER.warning(f"{self.msg}{': ' if self.msg else ''}{value}")
         return True
@@ -1175,8 +1185,13 @@ class Retry(contextlib.ContextDecorator):
     """
     Retry class for function execution with exponential backoff.
 
-    Can be used as a decorator to retry a function on exceptions, up to a specified number of times with an
-    exponentially increasing delay between retries.
+    This decorator can be used to retry a function on exceptions, up to a specified number of times with an
+    exponentially increasing delay between retries. It's useful for handling transient failures in network
+    operations or other unreliable processes.
+
+    Attributes:
+        times (int): Maximum number of retry attempts.
+        delay (int): Initial delay between retries in seconds.
 
     Examples:
         Example usage as a decorator:
@@ -1196,7 +1211,7 @@ class Retry(contextlib.ContextDecorator):
         """Decorator implementation for Retry with exponential backoff."""
 
         def wrapped_func(*args, **kwargs):
-            """Applies retries to the decorated function or method."""
+            """Apply retries to the decorated function or method."""
             self._attempts = 0
             while self._attempts < self.times:
                 try:
@@ -1213,7 +1228,7 @@ class Retry(contextlib.ContextDecorator):
 
 def threaded(func):
     """
-    Multi-threads a target function by default and returns the thread or function result.
+    Multi-thread a target function by default and return the thread or function result.
 
     This decorator provides flexible execution of the target function, either in a separate thread or synchronously.
     By default, the function runs in a thread, but this can be controlled via the 'threaded=False' keyword argument
@@ -1235,7 +1250,7 @@ def threaded(func):
     """
 
     def wrapper(*args, **kwargs):
-        """Multi-threads a given function based on 'threaded' kwarg and returns the thread or function result."""
+        """Multi-thread a given function based on 'threaded' kwarg and return the thread or function result."""
         if kwargs.pop("threaded", True):  # run in thread
             thread = threading.Thread(target=func, args=args, kwargs=kwargs, daemon=True)
             thread.start()
@@ -1288,7 +1303,7 @@ def set_sentry():
             hint (dict): A dictionary containing additional information about the error.
 
         Returns:
-            dict: The modified event or None if the event should not be sent to Sentry.
+            (dict | None): The modified event or None if the event should not be sent to Sentry.
         """
         if "exc_info" in hint:
             exc_type, exc_value, _ = hint["exc_info"]
@@ -1321,19 +1336,19 @@ class JSONDict(dict):
     A dictionary-like class that provides JSON persistence for its contents.
 
     This class extends the built-in dictionary to automatically save its contents to a JSON file whenever they are
-    modified. It ensures thread-safe operations using a lock.
+    modified. It ensures thread-safe operations using a lock and handles JSON serialization of Path objects.
 
     Attributes:
         file_path (Path): The path to the JSON file used for persistence.
         lock (threading.Lock): A lock object to ensure thread-safe operations.
 
     Methods:
-        _load: Loads the data from the JSON file into the dictionary.
-        _save: Saves the current state of the dictionary to the JSON file.
-        __setitem__: Stores a key-value pair and persists it to disk.
-        __delitem__: Removes an item and updates the persistent storage.
-        update: Updates the dictionary and persists changes.
-        clear: Clears all entries and updates the persistent storage.
+        _load: Load the data from the JSON file into the dictionary.
+        _save: Save the current state of the dictionary to the JSON file.
+        __setitem__: Store a key-value pair and persist it to disk.
+        __delitem__: Remove an item and update the persistent storage.
+        update: Update the dictionary and persist changes.
+        clear: Clear all entries and update the persistent storage.
 
     Examples:
         >>> json_dict = JSONDict("data.json")
@@ -1414,7 +1429,8 @@ class SettingsManager(JSONDict):
     SettingsManager class for managing and persisting Ultralytics settings.
 
     This class extends JSONDict to provide JSON persistence for settings, ensuring thread-safe operations and default
-    values. It validates settings on initialization and provides methods to update or reset settings.
+    values. It validates settings on initialization and provides methods to update or reset settings. The settings
+    include directories for datasets, weights, and runs, as well as various integration flags.
 
     Attributes:
         file (Path): The path to the JSON file used for persistence.
@@ -1423,9 +1439,9 @@ class SettingsManager(JSONDict):
         help_msg (str): A help message for users on how to view and update settings.
 
     Methods:
-        _validate_settings: Validates the current settings and resets if necessary.
-        update: Updates settings, validating keys and types.
-        reset: Resets the settings to default and saves them.
+        _validate_settings: Validate the current settings and reset if necessary.
+        update: Update settings, validating keys and types.
+        reset: Reset the settings to default and save them.
 
     Examples:
         Initialize and update settings:
@@ -1436,7 +1452,7 @@ class SettingsManager(JSONDict):
     """
 
     def __init__(self, file=SETTINGS_FILE, version="0.0.6"):
-        """Initializes the SettingsManager with default settings and loads user settings."""
+        """Initialize the SettingsManager with default settings and load user settings."""
         import hashlib
         import uuid
 
@@ -1505,11 +1521,11 @@ class SettingsManager(JSONDict):
             )
 
     def __setitem__(self, key, value):
-        """Updates one key: value pair."""
+        """Update one key: value pair."""
         self.update({key: value})
 
     def update(self, *args, **kwargs):
-        """Updates settings, validating keys and types."""
+        """Update settings, validating keys and types."""
         for arg in args:
             if isinstance(arg, dict):
                 kwargs.update(arg)
@@ -1524,7 +1540,7 @@ class SettingsManager(JSONDict):
         super().update(*args, **kwargs)
 
     def reset(self):
-        """Resets the settings to default and saves them."""
+        """Reset the settings to default and save them."""
         self.clear()
         self.update(self.defaults)
 

ultralytics/utils/autobatch.py

@@ -3,6 +3,7 @@
 
 import os
 from copy import deepcopy
+from typing import Union
 
 import numpy as np
 import torch
@@ -11,7 +12,13 @@ from ultralytics.utils import DEFAULT_CFG, LOGGER, colorstr
 from ultralytics.utils.torch_utils import autocast, profile_ops
 
 
-def check_train_batch_size(model, imgsz=640, amp=True, batch=-1, max_num_obj=1):
+def check_train_batch_size(
+    model: torch.nn.Module,
+    imgsz: int = 640,
+    amp: bool = True,
+    batch: Union[int, float] = -1,
+    max_num_obj: int = 1,
+) -> int:
     """
     Compute optimal YOLO training batch size using the autobatch() function.
 
@@ -19,7 +26,7 @@ def check_train_batch_size(model, imgsz=640, amp=True, batch=-1, max_num_obj=1):
         model (torch.nn.Module): YOLO model to check batch size for.
         imgsz (int, optional): Image size used for training.
         amp (bool, optional): Use automatic mixed precision if True.
-        batch (float, optional): Fraction of GPU memory to use. If -1, use default.
+        batch (int | float, optional): Fraction of GPU memory to use. If -1, use default.
         max_num_obj (int, optional): The maximum number of objects from dataset.
 
     Returns:
@@ -35,7 +42,13 @@ def check_train_batch_size(model, imgsz=640, amp=True, batch=-1, max_num_obj=1):
         )
 
 
-def autobatch(model, imgsz=640, fraction=0.60, batch_size=DEFAULT_CFG.batch, max_num_obj=1):
+def autobatch(
+    model: torch.nn.Module,
+    imgsz: int = 640,
+    fraction: float = 0.60,
+    batch_size: int = DEFAULT_CFG.batch,
+    max_num_obj: int = 1,
+) -> int:
     """
     Automatically estimate the best YOLO batch size to use a fraction of the available CUDA memory.