dgenerate-ultralytics-headless 8.3.134__py3-none-any.whl

ultralytics/hub/__init__.py

@@ -0,0 +1,168 @@
+# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
+
+import requests
+
+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.utils import LOGGER, SETTINGS, checks
+
+__all__ = (
+    "PREFIX",
+    "HUB_WEB_ROOT",
+    "HUBTrainingSession",
+    "login",
+    "logout",
+    "reset_model",
+    "export_fmts_hub",
+    "export_model",
+    "get_export",
+    "check_dataset",
+    "events",
+)
+
+
+def login(api_key: str = 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.
+
+    Args:
+        api_key (str, optional): API key to use for authentication. If not provided, it will be retrieved from SETTINGS
+            or HUB_API_KEY environment variable.
+        save (bool, optional): Whether to save the API key to SETTINGS if authentication is successful.
+
+    Returns:
+        (bool): True if authentication is successful, False otherwise.
+    """
+    checks.check_requirements("hub-sdk>=0.0.12")
+    from hub_sdk import HUBClient
+
+    api_key_url = f"{HUB_WEB_ROOT}/settings?tab=api+keys"  # set the redirect URL
+    saved_key = SETTINGS.get("api_key")
+    active_key = api_key or saved_key
+    credentials = {"api_key": active_key} if active_key and active_key != "" else None  # set credentials
+
+    client = HUBClient(credentials)  # initialize HUBClient
+
+    if client.authenticated:
+        # Successfully authenticated with HUB
+
+        if save and client.api_key != saved_key:
+            SETTINGS.update({"api_key": client.api_key})  # update settings with valid API key
+
+        # Set message based on whether key was provided or retrieved from settings
+        log_message = (
+            "New authentication successful ✅" if client.api_key == api_key or not credentials else "Authenticated ✅"
+        )
+        LOGGER.info(f"{PREFIX}{log_message}")
+
+        return True
+    else:
+        # Failed to authenticate with HUB
+        LOGGER.info(f"{PREFIX}Get API key from {api_key_url} and then run 'yolo login API_KEY'")
+        return False
+
+
+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()
+    """
+    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."""
+    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")
+        return
+    LOGGER.warning(f"{PREFIX}Model reset failure {r.status_code} {r.reason}")
+
+
+def export_fmts_hub():
+    """Returns a list of HUB-supported export formats."""
+    from ultralytics.engine.exporter import export_formats
+
+    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.
+
+    Args:
+        model_id (str): The ID of the model to export. An empty string will use the default model.
+        format (str): The format to export the model to. Must be one of the supported formats returned by
+            export_fmts_hub().
+
+    Raises:
+        AssertionError: If the specified format is not supported or if the export request fails.
+
+    Examples:
+        >>> from ultralytics import hub
+        >>> hub.export_model(model_id="your_model_id", format="torchscript")
+    """
+    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}
+    )
+    assert r.status_code == 200, f"{PREFIX}{format} export failure {r.status_code} {r.reason}"
+    LOGGER.info(f"{PREFIX}{format} export started ✅")
+
+
+def get_export(model_id: str = "", format: str = "torchscript"):
+    """
+    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().
+
+    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")
+    """
+    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",
+        json={"apiKey": Auth().api_key, "modelId": model_id, "format": format},
+        headers={"x-api-key": Auth().api_key},
+    )
+    assert r.status_code == 200, f"{PREFIX}{format} get_export failure {r.status_code} {r.reason}"
+    return r.json()
+
+
+def check_dataset(path: str, task: str) -> None:
+    """
+    Check HUB dataset Zip file for errors before upload.
+
+    Args:
+        path (str): Path to data.zip (with data.yaml inside data.zip).
+        task (str): Dataset task. Options are 'detect', 'segment', 'pose', 'classify', 'obb'.
+
+    Examples:
+        >>> from ultralytics.hub import check_dataset
+        >>> check_dataset("path/to/coco8.zip", task="detect")  # detect dataset
+        >>> check_dataset("path/to/coco8-seg.zip", task="segment")  # segment dataset
+        >>> check_dataset("path/to/coco8-pose.zip", task="pose")  # pose dataset
+        >>> check_dataset("path/to/dota8.zip", task="obb")  # OBB dataset
+        >>> check_dataset("path/to/imagenet10.zip", task="classify")  # classification dataset
+
+    Note:
+        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.
+    """
+    HUBDatasetStats(path=path, task=task).get_json()
+    LOGGER.info(f"Checks completed correctly ✅. Upload this dataset to {HUB_WEB_ROOT}/datasets/.")

ultralytics/hub/auth.py

@@ -0,0 +1,137 @@
+# 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
+
+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.
+
+    The class supports different methods of authentication:
+    1. Directly using an API key.
+    2. Authenticating using browser cookies (specifically in Google Colab).
+    3. Prompting the user to enter an API key.
+
+    Attributes:
+        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.
+    """
+
+    id_token = api_key = model_key = False
+
+    def __init__(self, api_key: str = "", verbose: bool = False):
+        """
+        Initialize Auth class and authenticate user.
+
+        Handles API key validation, Google Colab authentication, and new key requests. Updates SETTINGS upon successful
+        authentication.
+
+        Args:
+            api_key (str): API key or combined key_id format.
+            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]
+
+        # Set API key attribute as value passed or SETTINGS API key if none passed
+        self.api_key = api_key or SETTINGS.get("api_key", "")
+
+        # If an API key is provided
+        if self.api_key:
+            # If the provided API key matches the API key in the SETTINGS
+            if self.api_key == SETTINGS.get("api_key"):
+                # Log that the user is already logged in
+                if verbose:
+                    LOGGER.info(f"{PREFIX}Authenticated ✅")
+                return
+            else:
+                # Attempt to authenticate with the provided API key
+                success = self.authenticate()
+        # If the API key is not provided and the environment is a Google Colab notebook
+        elif IS_COLAB:
+            # Attempt to authenticate using browser cookies
+            success = self.auth_with_cookies()
+        else:
+            # Request an API key
+            success = self.request_api_key()
+
+        # Update SETTINGS with the new API key after successful authentication
+        if success:
+            SETTINGS.update({"api_key": self.api_key})
+            # Log that the new login was successful
+            if verbose:
+                LOGGER.info(f"{PREFIX}New authentication successful ✅")
+        elif verbose:
+            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."""
+        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
+            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.
+
+        Returns:
+            (bool): True if authentication is successful, False otherwise.
+        """
+        try:
+            if header := self.get_auth_header():
+                r = requests.post(f"{HUB_API_ROOT}/v1/auth", headers=header)
+                if not r.json().get("success", False):
+                    raise ConnectionError("Unable to authenticate.")
+                return True
+            raise ConnectionError("User has not authenticated locally.")
+        except ConnectionError:
+            self.id_token = self.api_key = False  # reset invalid
+            LOGGER.warning(f"{PREFIX}Invalid API key")
+            return False
+
+    def auth_with_cookies(self) -> bool:
+        """
+        Attempt to fetch authentication via cookies and set id_token.
+
+        User must be logged in to HUB and running in a supported browser.
+
+        Returns:
+            (bool): True if authentication is successful, False otherwise.
+        """
+        if not IS_COLAB:
+            return False  # Currently only works with Colab
+        try:
+            authn = request_with_credentials(f"{HUB_API_ROOT}/v1/auth/auto")
+            if authn.get("success", False):
+                self.id_token = authn.get("data", {}).get("idToken", None)
+                self.authenticate()
+                return True
+            raise ConnectionError("Unable to fetch browser authentication details.")
+        except ConnectionError:
+            self.id_token = False  # reset invalid
+            return False
+
+    def get_auth_header(self):
+        """
+        Get the authentication header for making API requests.
+
+        Returns:
+            (dict | None): The authentication header if id_token or API key is set, None otherwise.
+        """
+        if self.id_token:
+            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

@@ -0,0 +1,176 @@
+# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
+
+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.
+
+    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.
+
+    Methods:
+        tier1: Returns a list of tier 1 GCP regions.
+        tier2: Returns a list of tier 2 GCP regions.
+        lowest_latency: Determines the GCP region(s) with the lowest network latency.
+
+    Examples:
+        >>> from ultralytics.hub.google import GCPRegions
+        >>> regions = GCPRegions()
+        >>> lowest_latency_region = regions.lowest_latency(verbose=True, attempts=3)
+        >>> print(f"Lowest latency region: {lowest_latency_region[0][0]}")
+    """
+
+    def __init__(self):
+        """Initializes 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"),
+            "asia-northeast1": (1, "Tokyo", "Japan"),
+            "asia-northeast2": (1, "Osaka", "Japan"),
+            "asia-northeast3": (2, "Seoul", "South Korea"),
+            "asia-south1": (2, "Mumbai", "India"),
+            "asia-south2": (2, "Delhi", "India"),
+            "asia-southeast1": (2, "Jurong West", "Singapore"),
+            "asia-southeast2": (2, "Jakarta", "Indonesia"),
+            "australia-southeast1": (2, "Sydney", "Australia"),
+            "australia-southeast2": (2, "Melbourne", "Australia"),
+            "europe-central2": (2, "Warsaw", "Poland"),
+            "europe-north1": (1, "Hamina", "Finland"),
+            "europe-southwest1": (1, "Madrid", "Spain"),
+            "europe-west1": (1, "St. Ghislain", "Belgium"),
+            "europe-west10": (2, "Berlin", "Germany"),
+            "europe-west12": (2, "Turin", "Italy"),
+            "europe-west2": (2, "London", "United Kingdom"),
+            "europe-west3": (2, "Frankfurt", "Germany"),
+            "europe-west4": (1, "Eemshaven", "Netherlands"),
+            "europe-west6": (2, "Zurich", "Switzerland"),
+            "europe-west8": (1, "Milan", "Italy"),
+            "europe-west9": (1, "Paris", "France"),
+            "me-central1": (2, "Doha", "Qatar"),
+            "me-west1": (1, "Tel Aviv", "Israel"),
+            "northamerica-northeast1": (2, "Montreal", "Canada"),
+            "northamerica-northeast2": (2, "Toronto", "Canada"),
+            "southamerica-east1": (2, "São Paulo", "Brazil"),
+            "southamerica-west1": (2, "Santiago", "Chile"),
+            "us-central1": (1, "Iowa", "United States"),
+            "us-east1": (1, "South Carolina", "United States"),
+            "us-east4": (1, "Northern Virginia", "United States"),
+            "us-east5": (1, "Columbus", "United States"),
+            "us-south1": (1, "Dallas", "United States"),
+            "us-west1": (1, "Oregon", "United States"),
+            "us-west2": (2, "Los Angeles", "United States"),
+            "us-west3": (2, "Salt Lake City", "United States"),
+            "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."""
+        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."""
+        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.
+
+        Args:
+                region (str): The GCP region identifier to ping (e.g., 'us-central1').
+                attempts (int): 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.
+
+        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")
+        """
+        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
+                if latency != float("inf"):
+                    latencies.append(latency)
+            except requests.RequestException:
+                pass
+        if not latencies:
+            return region, float("inf"), float("inf"), float("inf"), float("inf")
+
+        std_dev = statistics.stdev(latencies) if len(latencies) > 1 else 0
+        return region, statistics.mean(latencies), std_dev, min(latencies), max(latencies)
+
+    def lowest_latency(
+        self,
+        top: int = 1,
+        verbose: bool = False,
+        tier: Optional[int] = None,
+        attempts: int = 1,
+    ) -> List[Tuple[str, float, float, float, float]]:
+        """
+        Determines 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.
+
+        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).
+
+        Examples:
+            >>> regions = GCPRegions()
+            >>> results = regions.lowest_latency(top=3, verbose=True, tier=1, attempts=2)
+            >>> print(results[0][0])  # Print the name of the lowest latency region
+        """
+        if verbose:
+            print(f"Testing GCP regions for latency (with {attempts} {'retry' if attempts == 1 else 'attempts'})...")
+
+        regions_to_test = [k for k, v in self.regions.items() if v[0] == tier] if tier else list(self.regions.keys())
+        with concurrent.futures.ThreadPoolExecutor(max_workers=50) as executor:
+            results = list(executor.map(lambda r: self._ping_region(r, attempts), regions_to_test))
+
+        sorted_results = sorted(results, key=lambda x: x[1])
+
+        if verbose:
+            print(f"{'Region':<25} {'Location':<35} {'Tier':<5} Latency (ms)")
+            for region, mean, std, min_, max_ in sorted_results:
+                tier, city, country = self.regions[region]
+                location = f"{city}, {country}"
+                if mean == float("inf"):
+                    print(f"{region:<25} {location:<35} {tier:<5} Timeout")
+                else:
+                    print(f"{region:<25} {location:<35} {tier:<5} {mean:.0f} ± {std:.0f} ({min_:.0f} - {max_:.0f})")
+            print(f"\nLowest latency region{'s' if top > 1 else ''}:")
+            for region, mean, std, min_, max_ in sorted_results[:top]:
+                tier, city, country = self.regions[region]
+                location = f"{city}, {country}"
+                print(f"{region} ({location}, {mean:.0f} ± {std:.0f} ms ({min_:.0f} - {max_:.0f}))")
+
+        return sorted_results[:top]
+
+
+# Usage example
+if __name__ == "__main__":
+    regions = GCPRegions()
+    top_3_latency_tier1 = regions.lowest_latency(top=3, verbose=True, tier=1, attempts=3)