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

ultralytics/utils/downloads.py

@@ -6,6 +6,7 @@ import subprocess
 from itertools import repeat
 from multiprocessing.pool import ThreadPool
 from pathlib import Path
+from typing import List, Tuple
 from urllib import parse, request
 
 import torch
@@ -41,21 +42,20 @@ GITHUB_ASSETS_NAMES = frozenset(
 GITHUB_ASSETS_STEMS = frozenset(k.rpartition(".")[0] for k in GITHUB_ASSETS_NAMES)
 
 
-def is_url(url, check=False):
+def is_url(url, check: bool = False) -> bool:
     """
-    Validates if the given string is a URL and optionally checks if the URL exists online.
+    Validate if the given string is a URL and optionally check if the URL exists online.
 
     Args:
         url (str): The string to be validated as a URL.
         check (bool, optional): If True, performs an additional check to see if the URL exists online.
-            Defaults to False.
 
     Returns:
-        (bool): Returns True for a valid URL. If 'check' is True, also returns True if the URL exists online.
-            Returns False otherwise.
+        (bool): True for a valid URL. If 'check' is True, also returns True if the URL exists online.
 
     Examples:
         >>> valid = is_url("https://www.example.com")
+        >>> valid_and_exists = is_url("https://www.example.com", check=True)
     """
     try:
         url = str(url)
@@ -71,10 +71,10 @@ def is_url(url, check=False):
 
 def delete_dsstore(path, files_to_delete=(".DS_Store", "__MACOSX")):
     """
-    Delete all ".DS_store" files in a specified directory.
+    Delete all specified system files in a directory.
 
     Args:
-        path (str, optional): The directory path where the ".DS_store" files should be deleted.
+        path (str | Path): The directory path where the files should be deleted.
         files_to_delete (tuple): The files to be deleted.
 
     Examples:
@@ -92,16 +92,17 @@ def delete_dsstore(path, files_to_delete=(".DS_Store", "__MACOSX")):
             f.unlink()
 
 
-def zip_directory(directory, compress=True, exclude=(".DS_Store", "__MACOSX"), progress=True):
+def zip_directory(directory, compress: bool = True, exclude=(".DS_Store", "__MACOSX"), progress: bool = True) -> Path:
     """
-    Zips the contents of a directory, excluding files containing strings in the exclude list. The resulting zip file is
-    named after the directory and placed alongside it.
+    Zip the contents of a directory, excluding specified files.
+
+    The resulting zip file is named after the directory and placed alongside it.
 
     Args:
         directory (str | Path): The path to the directory to be zipped.
-        compress (bool): Whether to compress the files while zipping. Default is True.
-        exclude (tuple, optional): A tuple of filename strings to be excluded. Defaults to ('.DS_Store', '__MACOSX').
-        progress (bool, optional): Whether to display a progress bar. Defaults to True.
+        compress (bool): Whether to compress the files while zipping.
+        exclude (tuple, optional): A tuple of filename strings to be excluded.
+        progress (bool, optional): Whether to display a progress bar.
 
     Returns:
         (Path): The path to the resulting zip file.
@@ -117,7 +118,7 @@ def zip_directory(directory, compress=True, exclude=(".DS_Store", "__MACOSX"), p
     if not directory.is_dir():
         raise FileNotFoundError(f"Directory '{directory}' does not exist.")
 
-    # Unzip with progress bar
+    # Zip with progress bar
     files_to_zip = [f for f in directory.rglob("*") if f.is_file() and all(x not in f.name for x in exclude)]
     zip_file = directory.with_suffix(".zip")
     compression = ZIP_DEFLATED if compress else ZIP_STORED
@@ -128,9 +129,15 @@ def zip_directory(directory, compress=True, exclude=(".DS_Store", "__MACOSX"), p
     return zip_file  # return path to zip file
 
 
-def unzip_file(file, path=None, exclude=(".DS_Store", "__MACOSX"), exist_ok=False, progress=True):
+def unzip_file(
+    file,
+    path=None,
+    exclude=(".DS_Store", "__MACOSX"),
+    exist_ok: bool = False,
+    progress: bool = True,
+) -> Path:
     """
-    Unzips a *.zip file to the specified path, excluding files containing strings in the exclude list.
+    Unzip a *.zip file to the specified path, excluding specified files.
 
     If the zipfile does not contain a single top-level directory, the function will create a new
     directory with the same name as the zipfile (without the extension) to extract its contents.
@@ -138,17 +145,17 @@ def unzip_file(file, path=None, exclude=(".DS_Store", "__MACOSX"), exist_ok=Fals
 
     Args:
         file (str | Path): The path to the zipfile to be extracted.
-        path (str | Path, optional): The path to extract the zipfile to. Defaults to None.
-        exclude (tuple, optional): A tuple of filename strings to be excluded. Defaults to ('.DS_Store', '__MACOSX').
-        exist_ok (bool, optional): Whether to overwrite existing contents if they exist. Defaults to False.
-        progress (bool, optional): Whether to display a progress bar. Defaults to True.
-
-    Raises:
-        BadZipFile: If the provided file does not exist or is not a valid zipfile.
+        path (str | Path, optional): The path to extract the zipfile to.
+        exclude (tuple, optional): A tuple of filename strings to be excluded.
+        exist_ok (bool, optional): Whether to overwrite existing contents if they exist.
+        progress (bool, optional): Whether to display a progress bar.
 
     Returns:
         (Path): The path to the directory where the zipfile was extracted.
 
+    Raises:
+        BadZipFile: If the provided file does not exist or is not a valid zipfile.
+
     Examples:
         >>> from ultralytics.utils.downloads import unzip_file
         >>> directory = unzip_file("path/to/file.zip")
@@ -191,15 +198,20 @@ def unzip_file(file, path=None, exclude=(".DS_Store", "__MACOSX"), exist_ok=Fals
     return path  # return unzip dir
 
 
-def check_disk_space(url="https://ultralytics.com/assets/coco8.zip", path=Path.cwd(), sf=1.5, hard=True):
+def check_disk_space(
+    url: str = "https://ultralytics.com/assets/coco8.zip",
+    path=Path.cwd(),
+    sf: float = 1.5,
+    hard: bool = True,
+) -> bool:
     """
     Check if there is sufficient disk space to download and store a file.
 
     Args:
-        url (str, optional): The URL to the file. Defaults to 'https://ultralytics.com/assets/coco8.zip'.
+        url (str, optional): The URL to the file.
         path (str | Path, optional): The path or drive to check the available free space on.
-        sf (float, optional): Safety factor, the multiplier for the required free space. Defaults to 1.5.
-        hard (bool, optional): Whether to throw an error or not on insufficient disk space. Defaults to True.
+        sf (float, optional): Safety factor, the multiplier for the required free space.
+        hard (bool, optional): Whether to throw an error or not on insufficient disk space.
 
     Returns:
         (bool): True if there is sufficient disk space, False otherwise.
@@ -231,16 +243,16 @@ def check_disk_space(url="https://ultralytics.com/assets/coco8.zip", path=Path.c
     return False
 
 
-def get_google_drive_file_info(link):
+def get_google_drive_file_info(link: str) -> Tuple[str, str]:
     """
-    Retrieves the direct download link and filename for a shareable Google Drive file link.
+    Retrieve the direct download link and filename for a shareable Google Drive file link.
 
     Args:
         link (str): The shareable link of the Google Drive file.
 
     Returns:
-        (str): Direct download URL for the Google Drive file.
-        (str): Original filename of the Google Drive file. If filename extraction fails, returns None.
+        url (str): Direct download URL for the Google Drive file.
+        filename (str | None): Original filename of the Google Drive file. If filename extraction fails, returns None.
 
     Examples:
         >>> from ultralytics.utils.downloads import get_google_drive_file_info
@@ -275,16 +287,16 @@ def safe_download(
     url,
     file=None,
     dir=None,
-    unzip=True,
-    delete=False,
-    curl=False,
-    retry=3,
-    min_bytes=1e0,
-    exist_ok=False,
-    progress=True,
+    unzip: bool = True,
+    delete: bool = False,
+    curl: bool = False,
+    retry: int = 3,
+    min_bytes: float = 1e0,
+    exist_ok: bool = False,
+    progress: bool = True,
 ):
     """
-    Downloads files from a URL, with options for retrying, unzipping, and deleting the downloaded file.
+    Download files from a URL with options for retrying, unzipping, and deleting the downloaded file.
 
     Args:
         url (str): The URL of the file to be downloaded.
@@ -292,14 +304,14 @@ def safe_download(
             If not provided, the file will be saved with the same name as the URL.
         dir (str | Path, optional): The directory to save the downloaded file.
             If not provided, the file will be saved in the current working directory.
-        unzip (bool, optional): Whether to unzip the downloaded file. Default: True.
-        delete (bool, optional): Whether to delete the downloaded file after unzipping. Default: False.
-        curl (bool, optional): Whether to use curl command line tool for downloading. Default: False.
-        retry (int, optional): The number of times to retry the download in case of failure. Default: 3.
+        unzip (bool, optional): Whether to unzip the downloaded file.
+        delete (bool, optional): Whether to delete the downloaded file after unzipping.
+        curl (bool, optional): Whether to use curl command line tool for downloading.
+        retry (int, optional): The number of times to retry the download in case of failure.
         min_bytes (float, optional): The minimum number of bytes that the downloaded file should have, to be considered
-            a successful download. Default: 1E0.
-        exist_ok (bool, optional): Whether to overwrite existing contents during unzipping. Defaults to False.
-        progress (bool, optional): Whether to display a progress bar during the download. Default: True.
+            a successful download.
+        exist_ok (bool, optional): Whether to overwrite existing contents during unzipping.
+        progress (bool, optional): Whether to display a progress bar during the download.
 
     Returns:
         (Path | str): The path to the downloaded file or extracted directory.
@@ -376,19 +388,24 @@ def safe_download(
     return f
 
 
-def get_github_assets(repo="ultralytics/assets", version="latest", retry=False):
+def get_github_assets(
+    repo: str = "ultralytics/assets",
+    version: str = "latest",
+    retry: bool = False,
+) -> Tuple[str, List[str]]:
     """
-    Retrieve the specified version's tag and assets from a GitHub repository. If the version is not specified, the
-    function fetches the latest release assets.
+    Retrieve the specified version's tag and assets from a GitHub repository.
+
+    If the version is not specified, the function fetches the latest release assets.
 
     Args:
-        repo (str, optional): The GitHub repository in the format 'owner/repo'. Defaults to 'ultralytics/assets'.
-        version (str, optional): The release version to fetch assets from. Defaults to 'latest'.
-        retry (bool, optional): Flag to retry the request in case of a failure. Defaults to False.
+        repo (str, optional): The GitHub repository in the format 'owner/repo'.
+        version (str, optional): The release version to fetch assets from.
+        retry (bool, optional): Flag to retry the request in case of a failure.
 
     Returns:
-        (str): The release tag.
-        (List[str]): A list of asset names.
+        tag (str): The release tag.
+        assets (List[str]): A list of asset names.
 
     Examples:
         >>> tag, assets = get_github_assets(repo="ultralytics/assets", version="latest")
@@ -408,14 +425,14 @@ def get_github_assets(repo="ultralytics/assets", version="latest", retry=False):
     return data["tag_name"], [x["name"] for x in data["assets"]]  # tag, assets i.e. ['yolo11n.pt', 'yolov8s.pt', ...]
 
 
-def attempt_download_asset(file, repo="ultralytics/assets", release="v8.3.0", **kwargs):
+def attempt_download_asset(file, repo: str = "ultralytics/assets", release: str = "v8.3.0", **kwargs) -> str:
     """
     Attempt to download a file from GitHub release assets if it is not found locally.
 
     Args:
         file (str | Path): The filename or file path to be downloaded.
-        repo (str, optional): The GitHub repository in the format 'owner/repo'. Defaults to 'ultralytics/assets'.
-        release (str, optional): The specific release version to be downloaded. Defaults to 'v8.3.0'.
+        repo (str, optional): The GitHub repository in the format 'owner/repo'.
+        release (str, optional): The specific release version to be downloaded.
         **kwargs (Any): Additional keyword arguments for the download process.
 
     Returns:
@@ -459,20 +476,30 @@ def attempt_download_asset(file, repo="ultralytics/assets", release="v8.3.0", **
         return str(file)
 
 
-def download(url, dir=Path.cwd(), unzip=True, delete=False, curl=False, threads=1, retry=3, exist_ok=False):
+def download(
+    url,
+    dir=Path.cwd(),
+    unzip: bool = True,
+    delete: bool = False,
+    curl: bool = False,
+    threads: int = 1,
+    retry: int = 3,
+    exist_ok: bool = False,
+):
     """
-    Downloads files from specified URLs to a given directory. Supports concurrent downloads if multiple threads are
-    specified.
+    Download files from specified URLs to a given directory.
+
+    Supports concurrent downloads if multiple threads are specified.
 
     Args:
         url (str | List[str]): The URL or list of URLs of the files to be downloaded.
-        dir (Path, optional): The directory where the files will be saved. Defaults to the current working directory.
-        unzip (bool, optional): Flag to unzip the files after downloading. Defaults to True.
-        delete (bool, optional): Flag to delete the zip files after extraction. Defaults to False.
-        curl (bool, optional): Flag to use curl for downloading. Defaults to False.
-        threads (int, optional): Number of threads to use for concurrent downloads. Defaults to 1.
-        retry (int, optional): Number of retries in case of download failure. Defaults to 3.
-        exist_ok (bool, optional): Whether to overwrite existing contents during unzipping. Defaults to False.
+        dir (Path, optional): The directory where the files will be saved.
+        unzip (bool, optional): Flag to unzip the files after downloading.
+        delete (bool, optional): Flag to delete the zip files after extraction.
+        curl (bool, optional): Flag to use curl for downloading.
+        threads (int, optional): Number of threads to use for concurrent downloads.
+        retry (int, optional): Number of retries in case of download failure.
+        exist_ok (bool, optional): Whether to overwrite existing contents during unzipping.
 
     Examples:
         >>> download("https://ultralytics.com/assets/example.zip", dir="path/to/dir", unzip=True)

ultralytics/utils/errors.py

@@ -18,13 +18,13 @@ class HUBModelError(Exception):
 
     Examples:
         >>> try:
-        >>> # Code that might fail to find a model
-        >>>     raise HUBModelError("Custom model not found message")
-        >>> except HUBModelError as e:
-        >>>     print(e)  # Displays the emoji-enhanced error message
+        ...     # Code that might fail to find a model
+        ...     raise HUBModelError("Custom model not found message")
+        ... except HUBModelError as e:
+        ...     print(e)  # Displays the emoji-enhanced error message
     """
 
-    def __init__(self, message="Model not found. Please check model URL and try again."):
+    def __init__(self, message: str = "Model not found. Please check model URL and try again."):
         """
         Initialize a HUBModelError exception.
 

ultralytics/utils/export.py

@@ -2,6 +2,7 @@
 
 import json
 from pathlib import Path
+from typing import Dict, List, Optional, Tuple, Union
 
 import torch
 
@@ -9,28 +10,28 @@ from ultralytics.utils import IS_JETSON, LOGGER
 
 
 def export_onnx(
-    torch_model,
-    im,
-    onnx_file,
-    opset=14,
-    input_names=["images"],
-    output_names=["output0"],
-    dynamic=False,
-):
+    torch_model: torch.nn.Module,
+    im: torch.Tensor,
+    onnx_file: str,
+    opset: int = 14,
+    input_names: List[str] = ["images"],
+    output_names: List[str] = ["output0"],
+    dynamic: Union[bool, Dict] = False,
+) -> None:
     """
-    Exports a PyTorch model to ONNX format.
+    Export a PyTorch model to ONNX format.
 
     Args:
         torch_model (torch.nn.Module): The PyTorch model to export.
         im (torch.Tensor): Example input tensor for the model.
         onnx_file (str): Path to save the exported ONNX file.
         opset (int): ONNX opset version to use for export.
-        input_names (list): List of input tensor names.
-        output_names (list): List of output tensor names.
-        dynamic (bool | dict, optional): Whether to enable dynamic axes. Defaults to False.
+        input_names (List[str]): List of input tensor names.
+        output_names (List[str]): List of output tensor names.
+        dynamic (bool | Dict, optional): Whether to enable dynamic axes.
 
     Notes:
-        - Setting `do_constant_folding=True` may cause issues with DNN inference for torch>=1.12.
+        Setting `do_constant_folding=True` may cause issues with DNN inference for torch>=1.12.
     """
     torch.onnx.export(
         torch_model,
@@ -46,44 +47,44 @@ def export_onnx(
 
 
 def export_engine(
-    onnx_file,
-    engine_file=None,
-    workspace=None,
-    half=False,
-    int8=False,
-    dynamic=False,
-    shape=(1, 3, 640, 640),
-    dla=None,
+    onnx_file: str,
+    engine_file: Optional[str] = None,
+    workspace: Optional[int] = None,
+    half: bool = False,
+    int8: bool = False,
+    dynamic: bool = False,
+    shape: Tuple[int, int, int, int] = (1, 3, 640, 640),
+    dla: Optional[int] = None,
     dataset=None,
-    metadata=None,
-    verbose=False,
-    prefix="",
-):
+    metadata: Optional[Dict] = None,
+    verbose: bool = False,
+    prefix: str = "",
+) -> None:
     """
-    Exports a YOLO model to TensorRT engine format.
+    Export a YOLO model to TensorRT engine format.
 
     Args:
         onnx_file (str): Path to the ONNX file to be converted.
         engine_file (str, optional): Path to save the generated TensorRT engine file.
-        workspace (int, optional): Workspace size in GB for TensorRT. Defaults to None.
-        half (bool, optional): Enable FP16 precision. Defaults to False.
-        int8 (bool, optional): Enable INT8 precision. Defaults to False.
-        dynamic (bool, optional): Enable dynamic input shapes. Defaults to False.
-        shape (tuple, optional): Input shape (batch, channels, height, width). Defaults to (1, 3, 640, 640).
-        dla (int, optional): DLA core to use (Jetson devices only). Defaults to None.
-        dataset (ultralytics.data.build.InfiniteDataLoader, optional): Dataset for INT8 calibration. Defaults to None.
-        metadata (dict, optional): Metadata to include in the engine file. Defaults to None.
-        verbose (bool, optional): Enable verbose logging. Defaults to False.
-        prefix (str, optional): Prefix for log messages. Defaults to "".
+        workspace (int, optional): Workspace size in GB for TensorRT.
+        half (bool, optional): Enable FP16 precision.
+        int8 (bool, optional): Enable INT8 precision.
+        dynamic (bool, optional): Enable dynamic input shapes.
+        shape (Tuple[int, int, int, int], optional): Input shape (batch, channels, height, width).
+        dla (int, optional): DLA core to use (Jetson devices only).
+        dataset (ultralytics.data.build.InfiniteDataLoader, optional): Dataset for INT8 calibration.
+        metadata (Dict, optional): Metadata to include in the engine file.
+        verbose (bool, optional): Enable verbose logging.
+        prefix (str, optional): Prefix for log messages.
 
     Raises:
         ValueError: If DLA is enabled on non-Jetson devices or required precision is not set.
         RuntimeError: If the ONNX file cannot be parsed.
 
     Notes:
-        - TensorRT version compatibility is handled for workspace size and engine building.
-        - INT8 calibration requires a dataset and generates a calibration cache.
-        - Metadata is serialized and written to the engine file if provided.
+        TensorRT version compatibility is handled for workspace size and engine building.
+        INT8 calibration requires a dataset and generates a calibration cache.
+        Metadata is serialized and written to the engine file if provided.
     """
     import tensorrt as trt  # noqa
 
@@ -151,12 +152,24 @@ def export_engine(
 
         class EngineCalibrator(trt.IInt8Calibrator):
             """
-            Custom INT8 calibrator for TensorRT.
+            Custom INT8 calibrator for TensorRT engine optimization.
 
-            Args:
-                dataset (object): Dataset for calibration.
+            This calibrator provides the necessary interface for TensorRT to perform INT8 quantization calibration
+            using a dataset. It handles batch generation, caching, and calibration algorithm selection.
+
+            Attributes:
+                dataset: Dataset for calibration.
+                data_iter: Iterator over the calibration dataset.
+                algo (trt.CalibrationAlgoType): Calibration algorithm type.
                 batch (int): Batch size for calibration.
-                cache (str, optional): Path to save the calibration cache. Defaults to "".
+                cache (Path): Path to save the calibration cache.
+
+            Methods:
+                get_algorithm: Get the calibration algorithm to use.
+                get_batch_size: Get the batch size to use for calibration.
+                get_batch: Get the next batch to use for calibration.
+                read_calibration_cache: Use existing cache instead of calibrating again.
+                write_calibration_cache: Write calibration cache to disk.
             """
 
             def __init__(
@@ -164,6 +177,7 @@ def export_engine(
                 dataset,  # ultralytics.data.build.InfiniteDataLoader
                 cache: str = "",
             ) -> None:
+                """Initialize the INT8 calibrator with dataset and cache path."""
                 trt.IInt8Calibrator.__init__(self)
                 self.dataset = dataset
                 self.data_iter = iter(dataset)
@@ -179,22 +193,22 @@ def export_engine(
                 """Get the batch size to use for calibration."""
                 return self.batch or 1
 
-            def get_batch(self, names) -> list:
+            def get_batch(self, names) -> Optional[List[int]]:
                 """Get the next batch to use for calibration, as a list of device memory pointers."""
                 try:
                     im0s = next(self.data_iter)["img"] / 255.0
                     im0s = im0s.to("cuda") if im0s.device.type == "cpu" else im0s
                     return [int(im0s.data_ptr())]
                 except StopIteration:
-                    # Return [] or None, signal to TensorRT there is no calibration data remaining
+                    # Return None to signal to TensorRT there is no calibration data remaining
                     return None
 
-            def read_calibration_cache(self) -> bytes:
+            def read_calibration_cache(self) -> Optional[bytes]:
                 """Use existing cache instead of calibrating again, otherwise, implicitly return None."""
                 if self.cache.exists() and self.cache.suffix == ".cache":
                     return self.cache.read_bytes()
 
-            def write_calibration_cache(self, cache) -> None:
+            def write_calibration_cache(self, cache: bytes) -> None:
                 """Write calibration cache to disk."""
                 _ = self.cache.write_bytes(cache)
 

ultralytics/utils/files.py

@@ -8,6 +8,7 @@ import tempfile
 from contextlib import contextmanager
 from datetime import datetime
 from pathlib import Path
+from typing import Union
 
 
 class WorkingDirectory(contextlib.ContextDecorator):
@@ -38,22 +39,22 @@ class WorkingDirectory(contextlib.ContextDecorator):
         >>>     pass
     """
 
-    def __init__(self, new_dir):
-        """Sets the working directory to 'new_dir' upon instantiation for use with context managers or decorators."""
+    def __init__(self, new_dir: Union[str, Path]):
+        """Initialize the WorkingDirectory context manager with the target directory."""
         self.dir = new_dir  # new dir
         self.cwd = Path.cwd().resolve()  # current dir
 
     def __enter__(self):
-        """Changes the current working directory to the specified directory upon entering the context."""
+        """Change the current working directory to the specified directory upon entering the context."""
         os.chdir(self.dir)
 
     def __exit__(self, exc_type, exc_val, exc_tb):  # noqa
-        """Restores the original working directory when exiting the context."""
+        """Restore the original working directory when exiting the context."""
         os.chdir(self.cwd)
 
 
 @contextmanager
-def spaces_in_path(path):
+def spaces_in_path(path: Union[str, Path]):
     """
     Context manager to handle paths with spaces in their names.
 
@@ -64,7 +65,8 @@ def spaces_in_path(path):
         path (str | Path): The original path that may contain spaces.
 
     Yields:
-        (Path | str): Temporary path with spaces replaced by underscores if spaces were present, otherwise the original path.
+        (Path | str): Temporary path with spaces replaced by underscores if spaces were present, otherwise the
+            original path.
 
     Examples:
         >>> with spaces_in_path('/path/with spaces') as new_path:
@@ -82,7 +84,6 @@ def spaces_in_path(path):
 
             # Copy file/directory
             if path.is_dir():
-                # tmp_path.mkdir(parents=True, exist_ok=True)
                 shutil.copytree(path, tmp_path)
             elif path.is_file():
                 tmp_path.parent.mkdir(parents=True, exist_ok=True)
@@ -104,7 +105,7 @@ def spaces_in_path(path):
         yield path
 
 
-def increment_path(path, exist_ok=False, sep="", mkdir=False):
+def increment_path(path: Union[str, Path], exist_ok: bool = False, sep: str = "", mkdir: bool = False) -> Path:
     """
     Increment a file or directory path, i.e., runs/exp --> runs/exp{sep}2, runs/exp{sep}3, ... etc.
 
@@ -114,9 +115,9 @@ def increment_path(path, exist_ok=False, sep="", mkdir=False):
 
     Args:
         path (str | Path): Path to increment.
-        exist_ok (bool): If True, the path will not be incremented and returned as-is.
-        sep (str): Separator to use between the path and the incrementation number.
-        mkdir (bool): Create a directory if it does not exist.
+        exist_ok (bool, optional): If True, the path will not be incremented and returned as-is.
+        sep (str, optional): Separator to use between the path and the incrementation number.
+        mkdir (bool, optional): Create a directory if it does not exist.
 
     Returns:
         (Path): Incremented path.
@@ -152,20 +153,20 @@ def increment_path(path, exist_ok=False, sep="", mkdir=False):
     return path
 
 
-def file_age(path=__file__):
+def file_age(path: Union[str, Path] = __file__) -> int:
     """Return days since the last modification of the specified file."""
     dt = datetime.now() - datetime.fromtimestamp(Path(path).stat().st_mtime)  # delta
     return dt.days  # + dt.seconds / 86400  # fractional days
 
 
-def file_date(path=__file__):
-    """Returns the file modification date in 'YYYY-M-D' format."""
+def file_date(path: Union[str, Path] = __file__) -> str:
+    """Return the file modification date in 'YYYY-M-D' format."""
     t = datetime.fromtimestamp(Path(path).stat().st_mtime)
     return f"{t.year}-{t.month}-{t.day}"
 
 
-def file_size(path):
-    """Returns the size of a file or directory in megabytes (MB)."""
+def file_size(path: Union[str, Path]) -> float:
+    """Return the size of a file or directory in megabytes (MB)."""
     if isinstance(path, (str, Path)):
         mb = 1 << 20  # bytes to MiB (1024 ** 2)
         path = Path(path)
@@ -176,20 +177,20 @@ def file_size(path):
     return 0.0
 
 
-def get_latest_run(search_dir="."):
-    """Returns the path to the most recent 'last.pt' file in the specified directory for resuming training."""
+def get_latest_run(search_dir: str = ".") -> str:
+    """Return the path to the most recent 'last.pt' file in the specified directory for resuming training."""
     last_list = glob.glob(f"{search_dir}/**/last*.pt", recursive=True)
     return max(last_list, key=os.path.getctime) if last_list else ""
 
 
-def update_models(model_names=("yolo11n.pt",), source_dir=Path("."), update_names=False):
+def update_models(model_names: tuple = ("yolo11n.pt",), source_dir: Path = Path("."), update_names: bool = False):
     """
     Update and re-save specified YOLO models in an 'updated_models' subdirectory.
 
     Args:
-        model_names (Tuple[str, ...]): Model filenames to update.
-        source_dir (Path): Directory containing models and target subdirectory.
-        update_names (bool): Update model names from a data YAML.
+        model_names (tuple, optional): Model filenames to update.
+        source_dir (Path, optional): Directory containing models and target subdirectory.
+        update_names (bool, optional): Update model names from a data YAML.
 
     Examples:
         Update specified YOLO models and save them in 'updated_models' subdirectory: