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

ultralytics/hub/session.py

@@ -1,14 +1,15 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
+from __future__ import annotations
+
 import shutil
 import threading
 import time
 from http import HTTPStatus
 from pathlib import Path
+from typing import Any
 from urllib.parse import parse_qs, urlparse
 
-import requests
-
 from ultralytics import __version__
 from ultralytics.hub.utils import HELP_MSG, HUB_WEB_ROOT, PREFIX
 from ultralytics.utils import IS_COLAB, LOGGER, SETTINGS, TQDM, checks, emojis
@@ -18,8 +19,7 @@ AGENT_NAME = f"python-{__version__}-colab" if IS_COLAB else f"python-{__version_
 
 
 class HUBTrainingSession:
-    """
-    HUB training session for Ultralytics HUB YOLO models. Handles model initialization, heartbeats, and checkpointing.
+    """HUB training session for Ultralytics HUB YOLO models.
 
     This class encapsulates the functionality for interacting with Ultralytics HUB during model training, including
     model creation, metrics tracking, and checkpoint uploading.
@@ -27,28 +27,28 @@ class HUBTrainingSession:
     Attributes:
         model_id (str): Identifier for the YOLO model being trained.
         model_url (str): URL for the model in Ultralytics HUB.
-        rate_limits (dict): Rate limits for different API calls (in seconds).
-        timers (dict): Timers for rate limiting.
-        metrics_queue (dict): Queue for the model's metrics.
-        metrics_upload_failed_queue (dict): Queue for metrics that failed to upload.
-        model (dict): Model data fetched from Ultralytics HUB.
+        rate_limits (dict[str, int]): Rate limits for different API calls in seconds.
+        timers (dict[str, Any]): Timers for rate limiting.
+        metrics_queue (dict[str, Any]): Queue for the model's metrics.
+        metrics_upload_failed_queue (dict[str, Any]): Queue for metrics that failed to upload.
+        model (Any): Model data fetched from Ultralytics HUB.
         model_file (str): Path to the model file.
-        train_args (dict): Arguments for training the model.
-        client (HUBClient): Client for interacting with Ultralytics HUB.
+        train_args (dict[str, Any]): Arguments for training the model.
+        client (Any): Client for interacting with Ultralytics HUB.
         filename (str): Filename of the model.
 
     Examples:
+        Create a training session with a model URL
         >>> session = HUBTrainingSession("https://hub.ultralytics.com/models/example-model")
         >>> session.upload_metrics()
     """
 
-    def __init__(self, identifier):
-        """
-        Initialize the HUBTrainingSession with the provided model identifier.
+    def __init__(self, identifier: str):
+        """Initialize the HUBTrainingSession with the provided model identifier.
 
         Args:
-            identifier (str): Model identifier used to initialize the HUB training session.
-                It can be a URL string or a model key with specific format.
+            identifier (str): Model identifier used to initialize the HUB training session. It can be a URL string or a
+                model key with specific format.
 
         Raises:
             ValueError: If the provided model identifier is invalid.
@@ -90,16 +90,15 @@ class HUBTrainingSession:
                 )
 
     @classmethod
-    def create_session(cls, identifier, args=None):
-        """
-        Create an authenticated HUBTrainingSession or return None.
+    def create_session(cls, identifier: str, args: dict[str, Any] | None = None):
+        """Create an authenticated HUBTrainingSession or return None.
 
         Args:
             identifier (str): Model identifier used to initialize the HUB training session.
-            args (dict, optional): Arguments for creating a new model if identifier is not a HUB model URL.
+            args (dict[str, Any], optional): Arguments for creating a new model if identifier is not a HUB model URL.
 
         Returns:
-            (HUBTrainingSession | None): An authenticated session or None if creation fails.
+            session (HUBTrainingSession | None): An authenticated session or None if creation fails.
         """
         try:
             session = cls(identifier)
@@ -111,9 +110,8 @@ class HUBTrainingSession:
         except (PermissionError, ModuleNotFoundError, AssertionError):
             return None
 
-    def load_model(self, model_id):
-        """
-        Load an existing model from Ultralytics HUB using the provided model identifier.
+    def load_model(self, model_id: str):
+        """Load an existing model from Ultralytics HUB using the provided model identifier.
 
         Args:
             model_id (str): The identifier of the model to load.
@@ -137,12 +135,12 @@ class HUBTrainingSession:
         self.model.start_heartbeat(self.rate_limits["heartbeat"])
         LOGGER.info(f"{PREFIX}View model at {self.model_url} 🚀")
 
-    def create_model(self, model_args):
-        """
-        Initialize a HUB training session with the specified model arguments.
+    def create_model(self, model_args: dict[str, Any]):
+        """Initialize a HUB training session with the specified model arguments.
 
         Args:
-            model_args (dict): Arguments for creating the model, including batch size, epochs, image size, etc.
+            model_args (dict[str, Any]): Arguments for creating the model, including batch size, epochs, image size,
+                etc.
 
         Returns:
             (None): If the model could not be created.
@@ -182,9 +180,8 @@ class HUBTrainingSession:
         LOGGER.info(f"{PREFIX}View model at {self.model_url} 🚀")
 
     @staticmethod
-    def _parse_identifier(identifier):
-        """
-        Parse the given identifier to determine the type and extract relevant components.
+    def _parse_identifier(identifier: str):
+        """Parse the given identifier to determine the type and extract relevant components.
 
         The method supports different identifier formats:
             - A HUB model URL https://hub.ultralytics.com/models/MODEL
@@ -195,13 +192,15 @@ class HUBTrainingSession:
             identifier (str): The identifier string to be parsed.
 
         Returns:
-            (tuple): A tuple containing the API key, model ID, and filename as applicable.
+            api_key (str | None): Extracted API key if present.
+            model_id (str | None): Extracted model ID if present.
+            filename (str | None): Extracted filename if present.
 
         Raises:
             HUBModelError: If the identifier format is not recognized.
         """
         api_key, model_id, filename = None, None, None
-        if str(identifier).endswith((".pt", ".yaml")):
+        if identifier.endswith((".pt", ".yaml")):
             filename = identifier
         elif identifier.startswith(f"{HUB_WEB_ROOT}/models/"):
             parsed_url = urlparse(identifier)
@@ -213,12 +212,11 @@ class HUBTrainingSession:
         return api_key, model_id, filename
 
     def _set_train_args(self):
-        """
-        Initialize training arguments and create a model entry on the Ultralytics HUB.
+        """Initialize training arguments and create a model entry on the Ultralytics HUB.
 
-        This method sets up training arguments based on the model's state and updates them with any additional
-        arguments provided. It handles different states of the model, such as whether it's resumable, pretrained,
-        or requires specific file setup.
+        This method sets up training arguments based on the model's state and updates them with any additional arguments
+        provided. It handles different states of the model, such as whether it's resumable, pretrained, or requires
+        specific file setup.
 
         Raises:
             ValueError: If the model is already trained, if required dataset information is missing, or if there are
@@ -247,17 +245,16 @@ class HUBTrainingSession:
     def request_queue(
         self,
         request_func,
-        retry=3,
-        timeout=30,
-        thread=True,
-        verbose=True,
-        progress_total=None,
-        stream_response=None,
+        retry: int = 3,
+        timeout: int = 30,
+        thread: bool = True,
+        verbose: bool = True,
+        progress_total: int | None = None,
+        stream_response: bool | None = None,
         *args,
         **kwargs,
     ):
-        """
-        Attempt to execute `request_func` with retries, timeout handling, optional threading, and progress tracking.
+        """Execute request_func with retries, timeout handling, optional threading, and progress tracking.
 
         Args:
             request_func (callable): The function to execute.
@@ -275,7 +272,7 @@ class HUBTrainingSession:
         """
 
         def retry_request():
-            """Attempt to call `request_func` with retries, timeout, and optional threading."""
+            """Attempt to call request_func with retries, timeout, and optional threading."""
             t0 = time.time()  # Record the start time for the timeout
             response = None
             for i in range(retry + 1):
@@ -327,16 +324,8 @@ class HUBTrainingSession:
             return retry_request()
 
     @staticmethod
-    def _should_retry(status_code):
-        """
-        Determine if a request should be retried based on the HTTP status code.
-
-        Args:
-            status_code (int): The HTTP status code from the response.
-
-        Returns:
-            (bool): True if the request should be retried, False otherwise.
-        """
+    def _should_retry(status_code: int) -> bool:
+        """Determine if a request should be retried based on the HTTP status code."""
         retry_codes = {
             HTTPStatus.REQUEST_TIMEOUT,
             HTTPStatus.BAD_GATEWAY,
@@ -344,9 +333,8 @@ class HUBTrainingSession:
         }
         return status_code in retry_codes
 
-    def _get_failure_message(self, response: requests.Response, retry: int, timeout: int):
-        """
-        Generate a retry message based on the response status code.
+    def _get_failure_message(self, response, retry: int, timeout: int) -> str:
+        """Generate a retry message based on the response status code.
 
         Args:
             response (requests.Response): The HTTP response object.
@@ -382,8 +370,7 @@ class HUBTrainingSession:
         map: float = 0.0,
         final: bool = False,
     ) -> None:
-        """
-        Upload a model checkpoint to Ultralytics HUB.
+        """Upload a model checkpoint to Ultralytics HUB.
 
         Args:
             epoch (int): The current training epoch.
@@ -422,25 +409,14 @@ class HUBTrainingSession:
         )
 
     @staticmethod
-    def _show_upload_progress(content_length: int, response: requests.Response) -> None:
-        """
-        Display a progress bar to track the upload progress of a file download.
-
-        Args:
-            content_length (int): The total size of the content to be downloaded in bytes.
-            response (requests.Response): The response object from the file download request.
-        """
+    def _show_upload_progress(content_length: int, response) -> None:
+        """Display a progress bar to track the upload progress of a file download."""
         with TQDM(total=content_length, unit="B", unit_scale=True, unit_divisor=1024) as pbar:
             for data in response.iter_content(chunk_size=1024):
                 pbar.update(len(data))
 
     @staticmethod
-    def _iterate_content(response: requests.Response) -> None:
-        """
-        Process the streamed HTTP response data.
-
-        Args:
-            response (requests.Response): The response object from the file download request.
-        """
+    def _iterate_content(response) -> None:
+        """Process the streamed HTTP response data."""
         for _ in response.iter_content(chunk_size=1024):
             pass  # Do nothing with data chunks

ultralytics/hub/utils.py

@@ -1,32 +1,17 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
 import os
-import platform
-import random
 import threading
 import time
-from pathlib import Path
+from typing import Any
 
-import requests
-
-from ultralytics import __version__
 from ultralytics.utils import (
-    ARGV,
-    ENVIRONMENT,
     IS_COLAB,
-    IS_GIT_DIR,
-    IS_PIP_PACKAGE,
     LOGGER,
-    ONLINE,
-    RANK,
-    SETTINGS,
-    TESTS_RUNNING,
     TQDM,
     TryExcept,
     colorstr,
-    get_git_origin_url,
 )
-from ultralytics.utils.downloads import GITHUB_ASSETS_NAMES
 
 HUB_API_ROOT = os.environ.get("ULTRALYTICS_HUB_API", "https://api.ultralytics.com")
 HUB_WEB_ROOT = os.environ.get("ULTRALYTICS_HUB_WEB", "https://hub.ultralytics.com")
@@ -35,9 +20,8 @@ PREFIX = colorstr("Ultralytics HUB: ")
 HELP_MSG = "If this issue persists please visit https://github.com/ultralytics/hub/issues for assistance."
 
 
-def request_with_credentials(url: str) -> any:
-    """
-    Make an AJAX request with cookies attached in a Google Colab environment.
+def request_with_credentials(url: str) -> Any:
+    """Make an AJAX request with cookies attached in a Google Colab environment.
 
     Args:
         url (str): The URL to make the request to.
@@ -50,8 +34,8 @@ def request_with_credentials(url: str) -> any:
     """
     if not IS_COLAB:
         raise OSError("request_with_credentials() must run in a Colab environment")
-    from google.colab import output  # noqa
-    from IPython import display  # noqa
+    from google.colab import output
+    from IPython import display
 
     display.display(
         display.Javascript(
@@ -76,9 +60,8 @@ def request_with_credentials(url: str) -> any:
     return output.eval_js("_hub_tmp")
 
 
-def requests_with_progress(method, url, **kwargs):
-    """
-    Make an HTTP request using the specified method and URL, with an optional progress bar.
+def requests_with_progress(method: str, url: str, **kwargs):
+    """Make an HTTP request using the specified method and URL, with an optional progress bar.
 
     Args:
         method (str): The HTTP method to use (e.g. 'GET', 'POST').
@@ -93,6 +76,8 @@ def requests_with_progress(method, url, **kwargs):
           content length.
         - If 'progress' is a number then progress bar will display assuming content length = progress.
     """
+    import requests  # scoped as slow import
+
     progress = kwargs.pop("progress", False)
     if not progress:
         return requests.request(method, url, **kwargs)
@@ -108,9 +93,18 @@ def requests_with_progress(method, url, **kwargs):
     return response
 
 
-def smart_request(method, url, retry=3, timeout=30, thread=True, code=-1, verbose=True, progress=False, **kwargs):
-    """
-    Make an HTTP request using the 'requests' library, with exponential backoff retries up to a specified timeout.
+def smart_request(
+    method: str,
+    url: str,
+    retry: int = 3,
+    timeout: int = 30,
+    thread: bool = True,
+    code: int = -1,
+    verbose: bool = True,
+    progress: bool = False,
+    **kwargs,
+):
+    """Make an HTTP request using the 'requests' library, with exponential backoff retries up to a specified timeout.
 
     Args:
         method (str): The HTTP method to use for the request. Choices are 'post' and 'get'.
@@ -124,7 +118,8 @@ def smart_request(method, url, retry=3, timeout=30, thread=True, code=-1, verbos
         **kwargs (Any): Keyword arguments to be passed to the requests function specified in method.
 
     Returns:
-        (requests.Response): The HTTP response object. If the request is executed in a separate thread, returns None.
+        (requests.Response | None): The HTTP response object. If the request is executed in a separate thread, returns
+            None.
     """
     retry_codes = (408, 500)  # retry only these codes
 
@@ -165,84 +160,3 @@ def smart_request(method, url, retry=3, timeout=30, thread=True, code=-1, verbos
         threading.Thread(target=func, args=args, kwargs=kwargs, daemon=True).start()
     else:
         return func(*args, **kwargs)
-
-
-class Events:
-    """
-    A class for collecting anonymous event analytics.
-
-    Event analytics are enabled when sync=True in settings and disabled when sync=False. Run 'yolo settings' to see and
-    update settings.
-
-    Attributes:
-        url (str): The URL to send anonymous events.
-        rate_limit (float): The rate limit in seconds for sending events.
-        metadata (dict): A dictionary containing metadata about the environment.
-        enabled (bool): A flag to enable or disable Events based on certain conditions.
-    """
-
-    url = "https://www.google-analytics.com/mp/collect?measurement_id=G-X8NCJYTQXM&api_secret=QLQrATrNSwGRFRLE-cbHJw"
-
-    def __init__(self):
-        """Initialize the Events object with default values for events, rate_limit, and metadata."""
-        self.events = []  # events list
-        self.rate_limit = 30.0  # rate limit (seconds)
-        self.t = 0.0  # rate limit timer (seconds)
-        self.metadata = {
-            "cli": Path(ARGV[0]).name == "yolo",
-            "install": "git" if IS_GIT_DIR else "pip" if IS_PIP_PACKAGE else "other",
-            "python": ".".join(platform.python_version_tuple()[:2]),  # i.e. 3.10
-            "version": __version__,
-            "env": ENVIRONMENT,
-            "session_id": round(random.random() * 1e15),
-            "engagement_time_msec": 1000,
-        }
-        self.enabled = (
-            SETTINGS["sync"]
-            and RANK in {-1, 0}
-            and not TESTS_RUNNING
-            and ONLINE
-            and (IS_PIP_PACKAGE or get_git_origin_url() == "https://github.com/ultralytics/ultralytics.git")
-        )
-
-    def __call__(self, cfg):
-        """
-        Attempt to add a new event to the events list and send events if the rate limit is reached.
-
-        Args:
-            cfg (IterableSimpleNamespace): The configuration object containing mode and task information.
-        """
-        if not self.enabled:
-            # Events disabled, do nothing
-            return
-
-        # Attempt to add to events
-        if len(self.events) < 25:  # Events list limited to 25 events (drop any events past this)
-            params = {
-                **self.metadata,
-                "task": cfg.task,
-                "model": cfg.model if cfg.model in GITHUB_ASSETS_NAMES else "custom",
-            }
-            if cfg.mode == "export":
-                params["format"] = cfg.format
-            self.events.append({"name": cfg.mode, "params": params})
-
-        # Check rate limit
-        t = time.time()
-        if (t - self.t) < self.rate_limit:
-            # Time is under rate limiter, wait to send
-            return
-
-        # Time is over rate limiter, send now
-        data = {"client_id": SETTINGS["uuid"], "events": self.events}  # SHA-256 anonymized UUID hash and events list
-
-        # POST equivalent to requests.post(self.url, json=data)
-        smart_request("post", self.url, json=data, retry=0, verbose=False)
-
-        # Reset events and rate limit timer
-        self.events = []
-        self.t = t
-
-
-# Run below code on hub/utils init -------------------------------------------------------------------------------------
-events = Events()

ultralytics/models/__init__.py

@@ -6,4 +6,4 @@ from .rtdetr import RTDETR
 from .sam import SAM
 from .yolo import YOLO, YOLOE, YOLOWorld
 
-__all__ = "YOLO", "RTDETR", "SAM", "FastSAM", "NAS", "YOLOWorld", "YOLOE"  # allow simpler import
+__all__ = "NAS", "RTDETR", "SAM", "YOLO", "YOLOE", "FastSAM", "YOLOWorld"  # allow simpler import

ultralytics/models/fastsam/__init__.py

@@ -4,4 +4,4 @@ from .model import FastSAM
 from .predict import FastSAMPredictor
 from .val import FastSAMValidator
 
-__all__ = "FastSAMPredictor", "FastSAM", "FastSAMValidator"
+__all__ = "FastSAM", "FastSAMPredictor", "FastSAMValidator"

ultralytics/models/fastsam/model.py

@@ -1,6 +1,9 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
+from __future__ import annotations
+
 from pathlib import Path
+from typing import Any
 
 from ultralytics.engine.model import Model
 
@@ -9,44 +12,59 @@ from .val import FastSAMValidator
 
 
 class FastSAM(Model):
-    """
-    FastSAM model interface for segment anything tasks.
+    """FastSAM model interface for segment anything tasks.
 
-    This class extends the base Model class to provide specific functionality for the FastSAM (Fast Segment Anything Model)
-    implementation, allowing for efficient and accurate image segmentation.
+    This class extends the base Model class to provide specific functionality for the FastSAM (Fast Segment Anything
+    Model) implementation, allowing for efficient and accurate image segmentation with optional prompting support.
 
     Attributes:
         model (str): Path to the pre-trained FastSAM model file.
         task (str): The task type, set to "segment" for FastSAM models.
 
+    Methods:
+        predict: Perform segmentation prediction on image or video source with optional prompts.
+        task_map: Returns mapping of segment task to predictor and validator classes.
+
     Examples:
+        Initialize FastSAM model and run prediction
         >>> from ultralytics import FastSAM
-        >>> model = FastSAM("last.pt")
+        >>> model = FastSAM("FastSAM-x.pt")
         >>> results = model.predict("ultralytics/assets/bus.jpg")
+
+        Run prediction with bounding box prompts
+        >>> results = model.predict("image.jpg", bboxes=[[100, 100, 200, 200]])
     """
 
-    def __init__(self, model="FastSAM-x.pt"):
+    def __init__(self, model: str = "FastSAM-x.pt"):
         """Initialize the FastSAM model with the specified pre-trained weights."""
         if str(model) == "FastSAM.pt":
             model = "FastSAM-x.pt"
         assert Path(model).suffix not in {".yaml", ".yml"}, "FastSAM models only support pre-trained models."
         super().__init__(model=model, task="segment")
 
-    def predict(self, source, stream=False, bboxes=None, points=None, labels=None, texts=None, **kwargs):
-        """
-        Perform segmentation prediction on image or video source.
+    def predict(
+        self,
+        source,
+        stream: bool = False,
+        bboxes: list | None = None,
+        points: list | None = None,
+        labels: list | None = None,
+        texts: list | None = None,
+        **kwargs: Any,
+    ):
+        """Perform segmentation prediction on image or video source.
 
-        Supports prompted segmentation with bounding boxes, points, labels, and texts. The method packages these
-        prompts and passes them to the parent class predict method.
+        Supports prompted segmentation with bounding boxes, points, labels, and texts. The method packages these prompts
+        and passes them to the parent class predict method for processing.
 
         Args:
-            source (str | PIL.Image | numpy.ndarray): Input source for prediction, can be a file path, URL, PIL image,
-                or numpy array.
+            source (str | PIL.Image | np.ndarray): Input source for prediction, can be a file path, URL, PIL image, or
+                numpy array.
             stream (bool): Whether to enable real-time streaming mode for video inputs.
-            bboxes (list): Bounding box coordinates for prompted segmentation in format [[x1, y1, x2, y2], ...].
-            points (list): Point coordinates for prompted segmentation in format [[x, y], ...].
-            labels (list): Class labels for prompted segmentation.
-            texts (list): Text prompts for segmentation guidance.
+            bboxes (list, optional): Bounding box coordinates for prompted segmentation in format [[x1, y1, x2, y2]].
+            points (list, optional): Point coordinates for prompted segmentation in format [[x, y]].
+            labels (list, optional): Class labels for prompted segmentation.
+            texts (list, optional): Text prompts for segmentation guidance.
             **kwargs (Any): Additional keyword arguments passed to the predictor.
 
         Returns:
@@ -56,6 +74,6 @@ class FastSAM(Model):
         return super().predict(source, stream, prompts=prompts, **kwargs)
 
     @property
-    def task_map(self):
+    def task_map(self) -> dict[str, dict[str, Any]]:
         """Returns a dictionary mapping segment task to corresponding predictor and validator classes."""
         return {"segment": {"predictor": FastSAMPredictor, "validator": FastSAMValidator}}