Skip to content

Reference for hub_sdk/hub_client.py

Note

This file is available at https://github.com/ultralytics/hub-sdk/blob/main/hub_sdk/hub_client.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!


hub_sdk.hub_client.HUBClient

HUBClient(credentials: Optional[Dict] = None)

Bases: Auth

A client class for interacting with a HUB service, extending authentication capabilities.

Attributes:

Name Type Description
authenticated bool

Indicates whether the client is authenticated.

api_key str

The API key for authentication.

id_token str

The identity token for authentication.

Parameters:

Name Type Description Default
credentials dict

A dictionary containing authentication credentials. If None, the client will attempt to retrieve the API key from the environment variable "HUB_API_KEY".

None
Source code in hub_sdk/hub_client.py
def __init__(self, credentials: Optional[Dict] = None):
    """
    Initializes the HUBClient instance.

    Args:
        credentials (dict, optional): A dictionary containing authentication credentials.
                        If None, the client will attempt to retrieve the API key
                        from the environment variable "HUB_API_KEY".
    """
    super().__init__()
    self.authenticated = False
    if not credentials:
        self.api_key = os.environ.get("HUB_API_KEY")  # Safely retrieve the API key from an environment variable.
        credentials = {"api_key": self.api_key}

    self.login(**credentials)

dataset

dataset(dataset_id: str = None) -> Datasets

Returns an instance of the Datasets class for interacting with datasets.

Parameters:

Name Type Description Default
dataset_id str

The identifier of the dataset. If provided, returns an instance associated with the specified dataset_id.

None

Returns:

Type Description
Datasets

An instance of the Datasets class.

Source code in hub_sdk/hub_client.py
@require_authentication
def dataset(self, dataset_id: str = None) -> Datasets:
    """
    Returns an instance of the Datasets class for interacting with datasets.

    Args:
        dataset_id (str, optional): The identifier of the dataset. If provided,
            returns an instance associated with the specified dataset_id.

    Returns:
        (Datasets): An instance of the Datasets class.
    """
    return Datasets(dataset_id, self.get_auth_header())

dataset_list

dataset_list(
    page_size: Optional[int] = 10, public: Optional[bool] = None
) -> DatasetList

Returns a DatasetList instance for interacting with a list of datasets.

Parameters:

Name Type Description Default
page_size int

The number of datasets per page.

10
public bool

Pass true to retrieve list of Public dataset list.

None

Returns:

Type Description
DatasetList

An instance of the DatasetList class.

Source code in hub_sdk/hub_client.py
@require_authentication
def dataset_list(self, page_size: Optional[int] = 10, public: Optional[bool] = None) -> DatasetList:
    """
    Returns a DatasetList instance for interacting with a list of datasets.

    Args:
        page_size (int, optional): The number of datasets per page.
        public (bool, optional): Pass true to retrieve list of Public dataset list.

    Returns:
        (DatasetList): An instance of the DatasetList class.
    """
    return DatasetList(page_size, public, self.get_auth_header())

login

login(api_key=None, id_token=None, email=None, password=None)

Logs in the client using provided authentication credentials.

Parameters:

Name Type Description Default
api_key str

The API key for authentication.

None
id_token str

The identity token for authentication.

None
email str

User's email.

None
password str

User's password.

None
Source code in hub_sdk/hub_client.py
def login(self, api_key=None, id_token=None, email=None, password=None):
    """
    Logs in the client using provided authentication credentials.

    Args:
        api_key (str, optional): The API key for authentication.
        id_token (str, optional): The identity token for authentication.
        email (str, optional): User's email.
        password (str, optional): User's password.
    """
    self.api_key = api_key
    self.id_token = id_token
    if (
        (self.api_key or self.id_token)
        and self.authenticate()
        or not self.api_key
        and not self.id_token
        and email
        and password
        and self.authorize(email, password)
    ):
        self.authenticated = True

model

model(model_id: Optional[str] = None) -> Models

Returns an instance of the Models class for interacting with models.

Parameters:

Name Type Description Default
model_id str

The identifier of the model. If provided, returns an instance associated with the specified model_id.

None

Returns:

Type Description
Models

An instance of the Models class.

Source code in hub_sdk/hub_client.py
def model(self, model_id: Optional[str] = None) -> Models:
    """
    Returns an instance of the Models class for interacting with models.

    Args:
        model_id (str, optional): The identifier of the model. If provided,
            returns an instance associated with the specified model_id.

    Returns:
        (Models): An instance of the Models class.
    """
    return Models(model_id, self.get_auth_header())

model_list

model_list(
    page_size: Optional[int] = 10, public: Optional[bool] = None
) -> ModelList

Returns a ModelList instance for interacting with a list of models.

Parameters:

Name Type Description Default
page_size int

The number of models per page.

10
public bool

Pass true to retrieve list of Public models list.

None

Returns:

Type Description
ModelList

An instance of the ModelList class.

Source code in hub_sdk/hub_client.py
@require_authentication
def model_list(self, page_size: Optional[int] = 10, public: Optional[bool] = None) -> ModelList:
    """
    Returns a ModelList instance for interacting with a list of models.

    Args:
        page_size (int, optional): The number of models per page.
        public (bool, optional): Pass true to retrieve list of Public models list.

    Returns:
        (ModelList): An instance of the ModelList class.
    """
    return ModelList(page_size, public, self.get_auth_header())

project

project(project_id: Optional[str] = None) -> Projects

Returns an instance of the Projects class for interacting with Projects.

Parameters:

Name Type Description Default
project_id str

The identifier of the project. If provided, returns an instance associated with the specified project_id.

None

Returns:

Type Description
Projects

An instance of the Projects class.

Source code in hub_sdk/hub_client.py
@require_authentication
def project(self, project_id: Optional[str] = None) -> Projects:
    """
    Returns an instance of the Projects class for interacting with Projects.

    Args:
        project_id (str, optional): The identifier of the project. If provided,
            returns an instance associated with the specified project_id.

    Returns:
        (Projects): An instance of the Projects class.
    """
    return Projects(project_id, self.get_auth_header())

project_list

project_list(
    page_size: Optional[int] = 10, public: Optional[bool] = None
) -> ProjectList

Returns a ProjectList instance for interacting with a list of projects.

Parameters:

Name Type Description Default
page_size int

The number of projects per page.

10
public bool

Pass true to retrieve list of Public models list.

None

Returns:

Type Description
ProjectList

An instance of the ProjectList class.

Source code in hub_sdk/hub_client.py
@require_authentication
def project_list(self, page_size: Optional[int] = 10, public: Optional[bool] = None) -> ProjectList:
    """
    Returns a ProjectList instance for interacting with a list of projects.

    Args:
        page_size (int, optional): The number of projects per page.
        public (bool, optional): Pass true to retrieve list of Public models list.

    Returns:
        (ProjectList): An instance of the ProjectList class.
    """
    return ProjectList(page_size, public, self.get_auth_header())

team

team(arg)

Returns an instance of the Teams class for interacting with teams.

Source code in hub_sdk/hub_client.py
@require_authentication
def team(self, arg):
    """Returns an instance of the Teams class for interacting with teams."""
    raise Exception("Coming Soon")

team_list

team_list(page_size=None, public=None)

Fetches a list of team members with optional pagination.

Source code in hub_sdk/hub_client.py
@require_authentication
def team_list(self, page_size=None, public=None):
    """Fetches a list of team members with optional pagination."""
    raise Exception("Coming Soon")

user

user(user_id: Optional[str] = None) -> Users

Returns an instance of the Users class for interacting with Projects.

Parameters:

Name Type Description Default
user_id str

The identifier of the user. If provided, returns an instance associated with the specified user_id.

None

Returns:

Type Description
Users

An instance of the Projects class.

Source code in hub_sdk/hub_client.py
@require_authentication
def user(self, user_id: Optional[str] = None) -> Users:
    """
    Returns an instance of the Users class for interacting with Projects.

    Args:
        user_id (str, optional): The identifier of the user. If provided,
            returns an instance associated with the specified user_id.

    Returns:
        (Users): An instance of the Projects class.
    """
    return Users(user_id, self.get_auth_header())





hub_sdk.hub_client.require_authentication

require_authentication(func) -> callable

A decorator function to ensure that the wrapped method can only be executed if the client is authenticated.

Parameters:

Name Type Description Default
func callable

The method to be wrapped.

required

Returns:

Type Description
callable

The wrapped method.

Source code in hub_sdk/hub_client.py
def require_authentication(func) -> callable:
    """
    A decorator function to ensure that the wrapped method can only be executed if the client is authenticated.

    Args:
        func (callable): The method to be wrapped.

    Returns:
        (callable): The wrapped method.
    """

    def wrapper(self, *args, **kwargs):
        """Decorator to ensure a method is called only if the user is authenticated."""
        if not self.authenticated and not kwargs.get("public"):
            raise PermissionError("Access Denied: Authentication required.")
        return func(self, *args, **kwargs)

    return wrapper