dgenerate-ultralytics-headless 8.3.137__py3-none-any.whl → 8.3.224__py3-none-any.whl

ultralytics/engine/validator.py

@@ -29,19 +29,19 @@ from pathlib import Path
 
 import numpy as np
 import torch
+import torch.distributed as dist
 
 from ultralytics.cfg import get_cfg, get_save_dir
 from ultralytics.data.utils import check_cls_dataset, check_det_dataset
 from ultralytics.nn.autobackend import AutoBackend
-from ultralytics.utils import LOGGER, TQDM, callbacks, colorstr, emojis
+from ultralytics.utils import LOGGER, RANK, TQDM, callbacks, colorstr, emojis
 from ultralytics.utils.checks import check_imgsz
 from ultralytics.utils.ops import Profile
-from ultralytics.utils.torch_utils import de_parallel, select_device, smart_inference_mode
+from ultralytics.utils.torch_utils import attempt_compile, select_device, smart_inference_mode, unwrap_model
 
 
 class BaseValidator:
-    """
-    A base class for creating validators.
+    """A base class for creating validators.
 
     This class provides the foundation for validation processes, including model evaluation, metric computation, and
     result visualization.
@@ -49,7 +49,6 @@ class BaseValidator:
     Attributes:
         args (SimpleNamespace): Configuration for the validator.
         dataloader (DataLoader): Dataloader to use for validation.
-        pbar (tqdm): Progress bar to update during validation.
         model (nn.Module): Model to validate.
         data (dict): Data dictionary containing dataset information.
         device (torch.device): Device to use for validation.
@@ -62,11 +61,13 @@ class BaseValidator:
         nc (int): Number of classes.
         iouv (torch.Tensor): IoU thresholds from 0.50 to 0.95 in spaces of 0.05.
         jdict (list): List to store JSON validation results.
-        speed (dict): Dictionary with keys 'preprocess', 'inference', 'loss', 'postprocess' and their respective
-            batch processing times in milliseconds.
+        speed (dict): Dictionary with keys 'preprocess', 'inference', 'loss', 'postprocess' and their respective batch
+            processing times in milliseconds.
         save_dir (Path): Directory to save results.
         plots (dict): Dictionary to store plots for visualization.
         callbacks (dict): Dictionary to store various callback functions.
+        stride (int): Model stride for padding calculations.
+        loss (torch.Tensor): Accumulated loss during training validation.
 
     Methods:
         __call__: Execute validation process, running inference on dataloader and computing performance metrics.
@@ -81,30 +82,28 @@ class BaseValidator:
         update_metrics: Update metrics based on predictions and batch.
         finalize_metrics: Finalize and return all metrics.
         get_stats: Return statistics about the model's performance.
-        check_stats: Check statistics.
         print_results: Print the results of the model's predictions.
         get_desc: Get description of the YOLO model.
-        on_plot: Register plots (e.g. to be consumed in callbacks).
+        on_plot: Register plots for visualization.
         plot_val_samples: Plot validation samples during training.
         plot_predictions: Plot YOLO model predictions on batch images.
         pred_to_json: Convert predictions to JSON format.
         eval_json: Evaluate and return JSON format of prediction statistics.
     """
 
-    def __init__(self, dataloader=None, save_dir=None, pbar=None, args=None, _callbacks=None):
-        """
-        Initialize a BaseValidator instance.
+    def __init__(self, dataloader=None, save_dir=None, args=None, _callbacks=None):
+        """Initialize a BaseValidator instance.
 
         Args:
             dataloader (torch.utils.data.DataLoader, optional): Dataloader to be used for validation.
             save_dir (Path, optional): Directory to save results.
-            pbar (tqdm.tqdm, optional): Progress bar for displaying progress.
             args (SimpleNamespace, optional): Configuration for the validator.
             _callbacks (dict, optional): Dictionary to store various callback functions.
         """
+        import torchvision  # noqa (import here so torchvision import time not recorded in postprocess time)
+
         self.args = get_cfg(overrides=args)
         self.dataloader = dataloader
-        self.pbar = pbar
         self.stride = None
         self.data = None
         self.device = None
@@ -122,7 +121,7 @@ class BaseValidator:
         self.save_dir = save_dir or get_save_dir(self.args)
         (self.save_dir / "labels" if self.args.save_txt else self.save_dir).mkdir(parents=True, exist_ok=True)
         if self.args.conf is None:
-            self.args.conf = 0.001  # default conf=0.001
+            self.args.conf = 0.01 if self.args.task == "obb" else 0.001  # reduce OBB val memory usage
         self.args.imgsz = check_imgsz(self.args.imgsz, max_dim=1)
 
         self.plots = {}
@@ -130,15 +129,14 @@ class BaseValidator:
 
     @smart_inference_mode()
     def __call__(self, trainer=None, model=None):
-        """
-        Execute validation process, running inference on dataloader and computing performance metrics.
+        """Execute validation process, running inference on dataloader and computing performance metrics.
 
         Args:
             trainer (object, optional): Trainer object that contains the model to validate.
             model (nn.Module, optional): Model to validate if not using a trainer.
 
         Returns:
-            stats (dict): Dictionary containing validation statistics.
+            (dict): Dictionary containing validation statistics.
         """
         self.training = trainer is not None
         augment = self.args.augment and (not self.training)
@@ -148,8 +146,9 @@ class BaseValidator:
             # Force FP16 val during training
             self.args.half = self.device.type != "cpu" and trainer.amp
             model = trainer.ema.ema or trainer.model
+            if trainer.args.compile and hasattr(model, "_orig_mod"):
+                model = model._orig_mod  # validate non-compiled original model to avoid issues
             model = model.half() if self.args.half else model.float()
-            # self.model = model
             self.loss = torch.zeros_like(trainer.loss_items, device=trainer.device)
             self.args.plots &= trainer.stopper.possible_stop or (trainer.epoch == trainer.epochs - 1)
             model.eval()
@@ -158,24 +157,21 @@ class BaseValidator:
                 LOGGER.warning("validating an untrained model YAML will result in 0 mAP.")
             callbacks.add_integration_callbacks(self)
             model = AutoBackend(
-                weights=model or self.args.model,
-                device=select_device(self.args.device, self.args.batch),
+                model=model or self.args.model,
+                device=select_device(self.args.device) if RANK == -1 else torch.device("cuda", RANK),
                 dnn=self.args.dnn,
                 data=self.args.data,
                 fp16=self.args.half,
             )
-            # self.model = model
             self.device = model.device  # update device
             self.args.half = model.fp16  # update half
-            stride, pt, jit, engine = model.stride, model.pt, model.jit, model.engine
+            stride, pt, jit = model.stride, model.pt, model.jit
             imgsz = check_imgsz(self.args.imgsz, stride=stride)
-            if engine:
-                self.args.batch = model.batch_size
-            elif not (pt or jit or getattr(model, "dynamic", False)):
+            if not (pt or jit or getattr(model, "dynamic", False)):
                 self.args.batch = model.metadata.get("batch", 1)  # export.py models default to batch-size 1
                 LOGGER.info(f"Setting batch={self.args.batch} input of shape ({self.args.batch}, 3, {imgsz}, {imgsz})")
 
-            if str(self.args.data).split(".")[-1] in {"yaml", "yml"}:
+            if str(self.args.data).rsplit(".", 1)[-1] in {"yaml", "yml"}:
                 self.data = check_det_dataset(self.args.data)
             elif self.args.task == "classify":
                 self.data = check_cls_dataset(self.args.data, split=self.args.split)
@@ -184,12 +180,14 @@ class BaseValidator:
 
             if self.device.type in {"cpu", "mps"}:
                 self.args.workers = 0  # faster CPU val as time dominated by inference, not dataloading
-            if not (pt or getattr(model, "dynamic", False)):
+            if not (pt or (getattr(model, "dynamic", False) and not model.imx)):
                 self.args.rect = False
             self.stride = model.stride  # used in get_dataloader() for padding
             self.dataloader = self.dataloader or self.get_dataloader(self.data.get(self.args.split), self.args.batch)
 
             model.eval()
+            if self.args.compile:
+                model = attempt_compile(model, device=self.device)
             model.warmup(imgsz=(1 if pt else self.args.batch, self.data["channels"], imgsz, imgsz))  # warmup
 
         self.run_callbacks("on_val_start")
@@ -200,7 +198,7 @@ class BaseValidator:
             Profile(device=self.device),
         )
         bar = TQDM(self.dataloader, desc=self.get_desc(), total=len(self.dataloader))
-        self.init_metrics(de_parallel(model))
+        self.init_metrics(unwrap_model(model))
         self.jdict = []  # empty before each val
         for batch_i, batch in enumerate(bar):
             self.run_callbacks("on_val_batch_start")
@@ -223,22 +221,34 @@ class BaseValidator:
                 preds = self.postprocess(preds)
 
             self.update_metrics(preds, batch)
-            if self.args.plots and batch_i < 3:
+            if self.args.plots and batch_i < 3 and RANK in {-1, 0}:
                 self.plot_val_samples(batch, batch_i)
                 self.plot_predictions(batch, preds, batch_i)
 
             self.run_callbacks("on_val_batch_end")
-        stats = self.get_stats()
-        self.check_stats(stats)
-        self.speed = dict(zip(self.speed.keys(), (x.t / len(self.dataloader.dataset) * 1e3 for x in dt)))
-        self.finalize_metrics()
-        self.print_results()
-        self.run_callbacks("on_val_end")
+
+        stats = {}
+        self.gather_stats()
+        if RANK in {-1, 0}:
+            stats = self.get_stats()
+            self.speed = dict(zip(self.speed.keys(), (x.t / len(self.dataloader.dataset) * 1e3 for x in dt)))
+            self.finalize_metrics()
+            self.print_results()
+            self.run_callbacks("on_val_end")
+
         if self.training:
             model.float()
-            results = {**stats, **trainer.label_loss_items(self.loss.cpu() / len(self.dataloader), prefix="val")}
+            # Reduce loss across all GPUs
+            loss = self.loss.clone().detach()
+            if trainer.world_size > 1:
+                dist.reduce(loss, dst=0, op=dist.ReduceOp.AVG)
+            if RANK > 0:
+                return
+            results = {**stats, **trainer.label_loss_items(loss.cpu() / len(self.dataloader), prefix="val")}
             return {k: round(float(v), 5) for k, v in results.items()}  # return results as 5 decimal place floats
         else:
+            if RANK > 0:
+                return stats
             LOGGER.info(
                 "Speed: {:.1f}ms preprocess, {:.1f}ms inference, {:.1f}ms loss, {:.1f}ms postprocess per image".format(
                     *tuple(self.speed.values())
@@ -256,14 +266,13 @@ class BaseValidator:
     def match_predictions(
         self, pred_classes: torch.Tensor, true_classes: torch.Tensor, iou: torch.Tensor, use_scipy: bool = False
     ) -> torch.Tensor:
-        """
-        Match predictions to ground truth objects using IoU.
+        """Match predictions to ground truth objects using IoU.
 
         Args:
             pred_classes (torch.Tensor): Predicted class indices of shape (N,).
             true_classes (torch.Tensor): Target class indices of shape (M,).
             iou (torch.Tensor): An NxM tensor containing the pairwise IoU values for predictions and ground truth.
-            use_scipy (bool): Whether to use scipy for matching (more precise).
+            use_scipy (bool, optional): Whether to use scipy for matching (more precise).
 
         Returns:
             (torch.Tensor): Correct tensor of shape (N, 10) for 10 IoU thresholds.
@@ -292,7 +301,6 @@ class BaseValidator:
                     if matches.shape[0] > 1:
                         matches = matches[iou[matches[:, 0], matches[:, 1]].argsort()[::-1]]
                         matches = matches[np.unique(matches[:, 1], return_index=True)[1]]
-                        # matches = matches[matches[:, 2].argsort()[::-1]]
                         matches = matches[np.unique(matches[:, 0], return_index=True)[1]]
                     correct[matches[:, 1].astype(int), i] = True
         return torch.tensor(correct, dtype=torch.bool, device=pred_classes.device)
@@ -330,7 +338,7 @@ class BaseValidator:
         """Update metrics based on predictions and batch."""
         pass
 
-    def finalize_metrics(self, *args, **kwargs):
+    def finalize_metrics(self):
         """Finalize and return all metrics."""
         pass
 
@@ -338,8 +346,8 @@ class BaseValidator:
         """Return statistics about the model's performance."""
         return {}
 
-    def check_stats(self, stats):
-        """Check statistics."""
+    def gather_stats(self):
+        """Gather statistics from all the GPUs during DDP training to GPU 0."""
         pass
 
     def print_results(self):
@@ -356,10 +364,9 @@ class BaseValidator:
         return []
 
     def on_plot(self, name, data=None):
-        """Register plots (e.g. to be consumed in callbacks)."""
+        """Register plots for visualization."""
         self.plots[Path(name)] = {"data": data, "timestamp": time.time()}
 
-    # TODO: may need to put these following functions into callback
     def plot_val_samples(self, batch, ni):
         """Plot validation samples during training."""
         pass

ultralytics/hub/__init__.py

@@ -1,31 +1,29 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
-import requests
+from __future__ import annotations
 
 from ultralytics.data.utils import HUBDatasetStats
 from ultralytics.hub.auth import Auth
 from ultralytics.hub.session import HUBTrainingSession
-from ultralytics.hub.utils import HUB_API_ROOT, HUB_WEB_ROOT, PREFIX, events
+from ultralytics.hub.utils import HUB_API_ROOT, HUB_WEB_ROOT, PREFIX
 from ultralytics.utils import LOGGER, SETTINGS, checks
 
 __all__ = (
-    "PREFIX",
     "HUB_WEB_ROOT",
+    "PREFIX",
     "HUBTrainingSession",
-    "login",
-    "logout",
-    "reset_model",
+    "check_dataset",
     "export_fmts_hub",
     "export_model",
     "get_export",
-    "check_dataset",
-    "events",
+    "login",
+    "logout",
+    "reset_model",
 )
 
 
-def login(api_key: str = None, save: bool = True) -> bool:
-    """
-    Log in to the Ultralytics HUB API using the provided API key.
+def login(api_key: str | None = None, save: bool = True) -> bool:
+    """Log in to the Ultralytics HUB API using the provided API key.
 
     The session is not stored; a new session is created when needed using the saved SETTINGS or the HUB_API_KEY
     environment variable if successfully authenticated.
@@ -68,19 +66,15 @@ def login(api_key: str = None, save: bool = True) -> bool:
 
 
 def logout():
-    """
-    Log out of Ultralytics HUB by removing the API key from the settings file. To log in again, use 'yolo login'.
-
-    Examples:
-        >>> from ultralytics import hub
-        >>> hub.logout()
-    """
+    """Log out of Ultralytics HUB by removing the API key from the settings file."""
     SETTINGS["api_key"] = ""
     LOGGER.info(f"{PREFIX}logged out ✅. To log in again, use 'yolo login'.")
 
 
 def reset_model(model_id: str = ""):
     """Reset a trained model to an untrained state."""
+    import requests  # scoped as slow import
+
     r = requests.post(f"{HUB_API_ROOT}/model-reset", json={"modelId": model_id}, headers={"x-api-key": Auth().api_key})
     if r.status_code == 200:
         LOGGER.info(f"{PREFIX}Model reset successfully")
@@ -89,15 +83,14 @@ def reset_model(model_id: str = ""):
 
 
 def export_fmts_hub():
-    """Returns a list of HUB-supported export formats."""
+    """Return a list of HUB-supported export formats."""
     from ultralytics.engine.exporter import export_formats
 
-    return list(export_formats()["Argument"][1:]) + ["ultralytics_tflite", "ultralytics_coreml"]
+    return [*list(export_formats()["Argument"][1:]), "ultralytics_tflite", "ultralytics_coreml"]
 
 
 def export_model(model_id: str = "", format: str = "torchscript"):
-    """
-    Export a model to a specified format for deployment via the Ultralytics HUB API.
+    """Export a model to a specified format for deployment via the Ultralytics HUB API.
 
     Args:
         model_id (str): The ID of the model to export. An empty string will use the default model.
@@ -111,6 +104,8 @@ def export_model(model_id: str = "", format: str = "torchscript"):
         >>> from ultralytics import hub
         >>> hub.export_model(model_id="your_model_id", format="torchscript")
     """
+    import requests  # scoped as slow import
+
     assert format in export_fmts_hub(), f"Unsupported export format '{format}', valid formats are {export_fmts_hub()}"
     r = requests.post(
         f"{HUB_API_ROOT}/v1/models/{model_id}/export", json={"format": format}, headers={"x-api-key": Auth().api_key}
@@ -120,20 +115,24 @@ def export_model(model_id: str = "", format: str = "torchscript"):
 
 
 def get_export(model_id: str = "", format: str = "torchscript"):
-    """
-    Retrieve an exported model in the specified format from Ultralytics HUB using the model ID.
+    """Retrieve an exported model in the specified format from Ultralytics HUB using the model ID.
 
     Args:
         model_id (str): The ID of the model to retrieve from Ultralytics HUB.
         format (str): The export format to retrieve. Must be one of the supported formats returned by export_fmts_hub().
 
+    Returns:
+        (dict): JSON response containing the exported model information.
+
     Raises:
         AssertionError: If the specified format is not supported or if the API request fails.
 
     Examples:
         >>> from ultralytics import hub
-        >>> hub.get_export(model_id="your_model_id", format="torchscript")
+        >>> result = hub.get_export(model_id="your_model_id", format="torchscript")
     """
+    import requests  # scoped as slow import
+
     assert format in export_fmts_hub(), f"Unsupported export format '{format}', valid formats are {export_fmts_hub()}"
     r = requests.post(
         f"{HUB_API_ROOT}/get-export",
@@ -145,8 +144,7 @@ def get_export(model_id: str = "", format: str = "torchscript"):
 
 
 def check_dataset(path: str, task: str) -> None:
-    """
-    Check HUB dataset Zip file for errors before upload.
+    """Check HUB dataset Zip file for errors before upload.
 
     Args:
         path (str): Path to data.zip (with data.yaml inside data.zip).
@@ -160,7 +158,7 @@ def check_dataset(path: str, task: str) -> None:
         >>> check_dataset("path/to/dota8.zip", task="obb")  # OBB dataset
         >>> check_dataset("path/to/imagenet10.zip", task="classify")  # classification dataset
 
-    Note:
+    Notes:
         Download *.zip files from https://github.com/ultralytics/hub/tree/main/example_datasets
         i.e. https://github.com/ultralytics/hub/raw/main/example_datasets/coco8.zip for coco8.zip.
     """

ultralytics/hub/auth.py

@@ -1,7 +1,5 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
-import requests
-
 from ultralytics.hub.utils import HUB_API_ROOT, HUB_WEB_ROOT, PREFIX, request_with_credentials
 from ultralytics.utils import IS_COLAB, LOGGER, SETTINGS, emojis
 
@@ -9,8 +7,7 @@ API_KEY_URL = f"{HUB_WEB_ROOT}/settings?tab=api+keys"
 
 
 class Auth:
-    """
-    Manages authentication processes including API key handling, cookie-based authentication, and header generation.
+    """Manages authentication processes including API key handling, cookie-based authentication, and header generation.
 
     The class supports different methods of authentication:
     1. Directly using an API key.
@@ -21,13 +18,25 @@ class Auth:
         id_token (str | bool): Token used for identity verification, initialized as False.
         api_key (str | bool): API key for authentication, initialized as False.
         model_key (bool): Placeholder for model key, initialized as False.
+
+    Methods:
+        authenticate: Attempt to authenticate with the server using either id_token or API key.
+        auth_with_cookies: Attempt to fetch authentication via cookies and set id_token.
+        get_auth_header: Get the authentication header for making API requests.
+        request_api_key: Prompt the user to input their API key.
+
+    Examples:
+        Initialize Auth with an API key
+        >>> auth = Auth(api_key="your_api_key_here")
+
+        Initialize Auth without API key (will prompt for input)
+        >>> auth = Auth()
     """
 
     id_token = api_key = model_key = False
 
     def __init__(self, api_key: str = "", verbose: bool = False):
-        """
-        Initialize Auth class and authenticate user.
+        """Initialize Auth class and authenticate user.
 
         Handles API key validation, Google Colab authentication, and new key requests. Updates SETTINGS upon successful
         authentication.
@@ -37,7 +46,7 @@ class Auth:
             verbose (bool): Enable verbose logging.
         """
         # Split the input API key in case it contains a combined key_model and keep only the API key part
-        api_key = api_key.split("_")[0]
+        api_key = api_key.split("_", 1)[0]
 
         # Set API key attribute as value passed or SETTINGS API key if none passed
         self.api_key = api_key or SETTINGS.get("api_key", "")
@@ -71,24 +80,32 @@ class Auth:
             LOGGER.info(f"{PREFIX}Get API key from {API_KEY_URL} and then run 'yolo login API_KEY'")
 
     def request_api_key(self, max_attempts: int = 3) -> bool:
-        """Prompt the user to input their API key."""
+        """Prompt the user to input their API key.
+
+        Args:
+            max_attempts (int): Maximum number of authentication attempts.
+
+        Returns:
+            (bool): True if authentication is successful, False otherwise.
+        """
         import getpass
 
         for attempts in range(max_attempts):
             LOGGER.info(f"{PREFIX}Login. Attempt {attempts + 1} of {max_attempts}")
             input_key = getpass.getpass(f"Enter API key from {API_KEY_URL} ")
-            self.api_key = input_key.split("_")[0]  # remove model id if present
+            self.api_key = input_key.split("_", 1)[0]  # remove model id if present
             if self.authenticate():
                 return True
         raise ConnectionError(emojis(f"{PREFIX}Failed to authenticate ❌"))
 
     def authenticate(self) -> bool:
-        """
-        Attempt to authenticate with the server using either id_token or API key.
+        """Attempt to authenticate with the server using either id_token or API key.
 
         Returns:
             (bool): True if authentication is successful, False otherwise.
         """
+        import requests  # scoped as slow import
+
         try:
             if header := self.get_auth_header():
                 r = requests.post(f"{HUB_API_ROOT}/v1/auth", headers=header)
@@ -102,8 +119,7 @@ class Auth:
             return False
 
     def auth_with_cookies(self) -> bool:
-        """
-        Attempt to fetch authentication via cookies and set id_token.
+        """Attempt to fetch authentication via cookies and set id_token.
 
         User must be logged in to HUB and running in a supported browser.
 
@@ -124,8 +140,7 @@ class Auth:
             return False
 
     def get_auth_header(self):
-        """
-        Get the authentication header for making API requests.
+        """Get the authentication header for making API requests.
 
         Returns:
             (dict | None): The authentication header if id_token or API key is set, None otherwise.
@@ -134,4 +149,3 @@ class Auth:
             return {"authorization": f"Bearer {self.id_token}"}
         elif self.api_key:
             return {"x-api-key": self.api_key}
-        # else returns None

ultralytics/hub/google/__init__.py

@@ -1,22 +1,20 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
+from __future__ import annotations
+
 import concurrent.futures
 import statistics
 import time
-from typing import List, Optional, Tuple
-
-import requests
 
 
 class GCPRegions:
-    """
-    A class for managing and analyzing Google Cloud Platform (GCP) regions.
+    """A class for managing and analyzing Google Cloud Platform (GCP) regions.
 
-    This class provides functionality to initialize, categorize, and analyze GCP regions based on their
-    geographical location, tier classification, and network latency.
+    This class provides functionality to initialize, categorize, and analyze GCP regions based on their geographical
+    location, tier classification, and network latency.
 
     Attributes:
-        regions (Dict[str, Tuple[int, str, str]]): A dictionary of GCP regions with their tier, city, and country.
+        regions (dict[str, tuple[int, str, str]]): A dictionary of GCP regions with their tier, city, and country.
 
     Methods:
         tier1: Returns a list of tier 1 GCP regions.
@@ -31,7 +29,7 @@ class GCPRegions:
     """
 
     def __init__(self):
-        """Initializes the GCPRegions class with predefined Google Cloud Platform regions and their details."""
+        """Initialize the GCPRegions class with predefined Google Cloud Platform regions and their details."""
         self.regions = {
             "asia-east1": (1, "Taiwan", "China"),
             "asia-east2": (2, "Hong Kong", "China"),
@@ -73,41 +71,42 @@ class GCPRegions:
             "us-west4": (2, "Las Vegas", "United States"),
         }
 
-    def tier1(self) -> List[str]:
-        """Returns a list of GCP regions classified as tier 1 based on predefined criteria."""
+    def tier1(self) -> list[str]:
+        """Return a list of GCP regions classified as tier 1 based on predefined criteria."""
         return [region for region, info in self.regions.items() if info[0] == 1]
 
-    def tier2(self) -> List[str]:
-        """Returns a list of GCP regions classified as tier 2 based on predefined criteria."""
+    def tier2(self) -> list[str]:
+        """Return a list of GCP regions classified as tier 2 based on predefined criteria."""
         return [region for region, info in self.regions.items() if info[0] == 2]
 
     @staticmethod
-    def _ping_region(region: str, attempts: int = 1) -> Tuple[str, float, float, float, float]:
-        """
-        Ping a specified GCP region and measure network latency statistics.
+    def _ping_region(region: str, attempts: int = 1) -> tuple[str, float, float, float, float]:
+        """Ping a specified GCP region and measure network latency statistics.
 
         Args:
-                region (str): The GCP region identifier to ping (e.g., 'us-central1').
-                attempts (int): Number of ping attempts to make for calculating statistics.
+            region (str): The GCP region identifier to ping (e.g., 'us-central1').
+            attempts (int, optional): Number of ping attempts to make for calculating statistics.
 
         Returns:
-                region (str): The GCP region identifier that was pinged.
-                mean_latency (float): Mean latency in milliseconds, or infinity if all pings failed.
-                min_latency (float): Minimum latency in milliseconds, or infinity if all pings failed.
-                max_latency (float): Maximum latency in milliseconds, or infinity if all pings failed.
-                std_dev (float): Standard deviation of latencies in milliseconds, or infinity if all pings failed.
+            region (str): The GCP region identifier that was pinged.
+            mean_latency (float): Mean latency in milliseconds, or infinity if all pings failed.
+            std_dev (float): Standard deviation of latencies in milliseconds, or infinity if all pings failed.
+            min_latency (float): Minimum latency in milliseconds, or infinity if all pings failed.
+            max_latency (float): Maximum latency in milliseconds, or infinity if all pings failed.
 
         Examples:
-                >>> region, mean, min_lat, max_lat, std = GCPRegions._ping_region("us-central1", attempts=3)
-                >>> print(f"Region {region} has mean latency: {mean:.2f}ms")
+            >>> region, mean, std, min_lat, max_lat = GCPRegions._ping_region("us-central1", attempts=3)
+            >>> print(f"Region {region} has mean latency: {mean:.2f}ms")
         """
+        import requests  # scoped as slow import
+
         url = f"https://{region}-docker.pkg.dev"
         latencies = []
         for _ in range(attempts):
             try:
                 start_time = time.time()
                 _ = requests.head(url, timeout=5)
-                latency = (time.time() - start_time) * 1000  # convert latency to milliseconds
+                latency = (time.time() - start_time) * 1000  # Convert latency to milliseconds
                 if latency != float("inf"):
                     latencies.append(latency)
             except requests.RequestException:
@@ -122,21 +121,20 @@ class GCPRegions:
         self,
         top: int = 1,
         verbose: bool = False,
-        tier: Optional[int] = None,
+        tier: int | None = None,
         attempts: int = 1,
-    ) -> List[Tuple[str, float, float, float, float]]:
-        """
-        Determines the GCP regions with the lowest latency based on ping tests.
+    ) -> list[tuple[str, float, float, float, float]]:
+        """Determine the GCP regions with the lowest latency based on ping tests.
 
         Args:
-            top (int): Number of top regions to return.
-            verbose (bool): If True, prints detailed latency information for all tested regions.
-            tier (int | None): Filter regions by tier (1 or 2). If None, all regions are tested.
-            attempts (int): Number of ping attempts per region.
+            top (int, optional): Number of top regions to return.
+            verbose (bool, optional): If True, prints detailed latency information for all tested regions.
+            tier (int | None, optional): Filter regions by tier (1 or 2). If None, all regions are tested.
+            attempts (int, optional): Number of ping attempts per region.
 
         Returns:
-            (List[Tuple[str, float, float, float, float]]): List of tuples containing region information and
-            latency statistics. Each tuple contains (region, mean_latency, std_dev, min_latency, max_latency).
+            (list[tuple[str, float, float, float, float]]): List of tuples containing region information and latency
+                statistics. Each tuple contains (region, mean_latency, std_dev, min_latency, max_latency).
 
         Examples:
             >>> regions = GCPRegions()