Vai al contenuto

Riferimento per hub_sdk/modules/datasets.py

Nota

Questo file è disponibile all'indirizzo https://github.com/ultralytics/ hub-sdk/blob/main/ hub_sdk/modules/datasets .py. Se riscontri un problema, contribuisci a risolverlo inviando una Pull Request 🛠️. Grazie 🙏!



hub_sdk.modules.datasets.Datasets

Basi: CRUDClient

Una classe che rappresenta un client per interagire con i Dataset attraverso operazioni CRUD. Questa classe estende la classe CRUDClient e fornisce metodi specifici per lavorare con i Dataset.

Attributi:

Nome Tipo Descrizione
hub_client DatasetUpload

Un'istanza di DatasetUpload utilizzata per interagire con il caricamento dei modelli.

id (str, None)

L'identificatore unico del set di dati, se disponibile.

data dict

Un dizionario per memorizzare i dati del dataset.

Nota

L'attributo "id" viene impostato durante l'inizializzazione e può essere utilizzato per identificare in modo univoco un set di dati. L'attributo "data" viene utilizzato per memorizzare i dati del set di dati recuperati dall'API.

Codice sorgente in hub_sdk/modules/datasets.py
class Datasets(CRUDClient):
    """
    A class representing a client for interacting with Datasets through CRUD operations. This class extends the
    CRUDClient class and provides specific methods for working with Datasets.

    Attributes:
        hub_client (DatasetUpload): An instance of DatasetUpload used for interacting with model uploads.
        id (str, None): The unique identifier of the dataset, if available.
        data (dict): A dictionary to store dataset data.

    Note:
        The 'id' attribute is set during initialization and can be used to uniquely identify a dataset.
        The 'data' attribute is used to store dataset data fetched from the API.
    """

    def __init__(self, dataset_id: Optional[str] = None, headers: Optional[Dict[str, Any]] = None):
        """
        Initialize a Datasets client.

        Args:
            dataset_id (str): Unique id of the dataset.
            headers (dict, optional): Headers to include in HTTP requests.
        """
        super().__init__("datasets", "dataset", headers)
        self.hub_client = DatasetUpload(headers)
        self.id = dataset_id
        self.data = {}
        if dataset_id:
            self.get_data()

    def get_data(self) -> None:
        """
        Retrieves data for the current dataset instance.

        If a valid dataset ID has been set, it sends a request to fetch the dataset data and stores it in the instance.
        If no dataset ID has been set, it logs an error message.

        Returns:
            (None): The method does not return a value.
        """
        if self.id:
            resp = super().read(self.id).json()
            self.data = resp.get("data", {})
            self.logger.debug("Dataset id is %s", self.id)
        else:
            self.logger.error("No dataset id has been set. Update the dataset id or create a dataset.")

    def create_dataset(self, dataset_data: dict) -> None:
        """
        Creates a new dataset with the provided data and sets the dataset ID for the current instance.

        Args:
            dataset_data (dict): A dictionary containing the data for creating the dataset.

        Returns:
            (None): The method does not return a value.
        """
        resp = super().create(dataset_data).json()
        self.id = resp.get("data", {}).get("id")
        self.get_data()

    def delete(self, hard: bool = False) -> Optional[Response]:
        """
        Delete the dataset resource represented by this instance.

        Args:
            hard (bool, optional): If True, perform a hard delete.

        Note:
            The 'hard' parameter determines whether to perform a soft delete (default) or a hard delete.
            In a soft delete, the dataset might be marked as deleted but retained in the system.
            In a hard delete, the dataset is permanently removed from the system.

        Returns:
            (Optional[Response]): Response object from the delete request, or None if delete fails.
        """
        return super().delete(self.id, hard)

    def update(self, data: dict) -> Optional[Response]:
        """
        Update the dataset resource represented by this instance.

        Args:
            data (dict): The updated data for the dataset resource.

        Returns:
            (Optional[Response]): Response object from the update request, or None if update fails.
        """
        return super().update(self.id, data)

    def upload_dataset(self, file: str = None) -> Optional[Response]:
        """
        Uploads a dataset file to the hub.

        Args:
            file (str, optional): The path to the dataset file to upload.

        Returns:
            (Optional[Response]): Response object from the upload request, or None if upload fails.
        """
        return self.hub_client.upload_dataset(self.id, file)

    def get_download_link(self, type: str) -> Optional[str]:
        """
        Get dataset download link.

        Args:
            type (str):

        Returns:
            (Optional[str]): Return download link or None if the link is not available.
        """
        try:
            payload = {"collection": "datasets", "docId": self.id, "object": type}
            endpoint = f"{HUB_FUNCTIONS_ROOT}/v1/storage"
            response = self.post(endpoint, json=payload)
            json = response.json()
            return json.get("data", {}).get("url")
        except Exception as e:
            self.logger.error(f"Failed to download file file for {self.name}: %s", e)
            raise e

__init__(dataset_id=None, headers=None)

Inizializza un client Datasets.

Parametri:

Nome Tipo Descrizione Predefinito
dataset_id str

Id univoco del set di dati.

None
headers dict

Intestazioni da includere nelle richieste HTTP.

None
Codice sorgente in hub_sdk/modules/datasets.py
def __init__(self, dataset_id: Optional[str] = None, headers: Optional[Dict[str, Any]] = None):
    """
    Initialize a Datasets client.

    Args:
        dataset_id (str): Unique id of the dataset.
        headers (dict, optional): Headers to include in HTTP requests.
    """
    super().__init__("datasets", "dataset", headers)
    self.hub_client = DatasetUpload(headers)
    self.id = dataset_id
    self.data = {}
    if dataset_id:
        self.get_data()

create_dataset(dataset_data)

Crea un nuovo dataset con i dati forniti e imposta l'ID del dataset per l'istanza corrente.

Parametri:

Nome Tipo Descrizione Predefinito
dataset_data dict

Un dizionario contenente i dati per la creazione del set di dati.

richiesto

Restituzione:

Tipo Descrizione
None

Il metodo non restituisce un valore.

Codice sorgente in hub_sdk/modules/datasets.py
def create_dataset(self, dataset_data: dict) -> None:
    """
    Creates a new dataset with the provided data and sets the dataset ID for the current instance.

    Args:
        dataset_data (dict): A dictionary containing the data for creating the dataset.

    Returns:
        (None): The method does not return a value.
    """
    resp = super().create(dataset_data).json()
    self.id = resp.get("data", {}).get("id")
    self.get_data()

delete(hard=False)

Elimina la risorsa dataset rappresentata da questa istanza.

Parametri:

Nome Tipo Descrizione Predefinito
hard bool

Se Vero, esegui una cancellazione definitiva.

False
Nota

Il parametro "hard" determina se eseguire una cancellazione soft (predefinita) o una cancellazione hard. In una cancellazione morbida, il set di dati potrebbe essere contrassegnato come eliminato ma conservato nel sistema. In un'eliminazione definitiva, il set di dati viene rimosso in modo permanente dal sistema.

Restituzione:

Tipo Descrizione
Optional[Response]

Oggetto di risposta della richiesta di cancellazione, oppure Nessuno se la cancellazione fallisce.

Codice sorgente in hub_sdk/modules/datasets.py
def delete(self, hard: bool = False) -> Optional[Response]:
    """
    Delete the dataset resource represented by this instance.

    Args:
        hard (bool, optional): If True, perform a hard delete.

    Note:
        The 'hard' parameter determines whether to perform a soft delete (default) or a hard delete.
        In a soft delete, the dataset might be marked as deleted but retained in the system.
        In a hard delete, the dataset is permanently removed from the system.

    Returns:
        (Optional[Response]): Response object from the delete request, or None if delete fails.
    """
    return super().delete(self.id, hard)

get_data()

Recupera i dati dell'istanza del dataset corrente.

Se è stato impostato un ID dataset valido, invia una richiesta per recuperare i dati del dataset e li memorizza nell'istanza. Se non è stato impostato alcun ID del dataset, viene visualizzato un messaggio di errore.

Restituzione:

Tipo Descrizione
None

Il metodo non restituisce un valore.

Codice sorgente in hub_sdk/modules/datasets.py
def get_data(self) -> None:
    """
    Retrieves data for the current dataset instance.

    If a valid dataset ID has been set, it sends a request to fetch the dataset data and stores it in the instance.
    If no dataset ID has been set, it logs an error message.

    Returns:
        (None): The method does not return a value.
    """
    if self.id:
        resp = super().read(self.id).json()
        self.data = resp.get("data", {})
        self.logger.debug("Dataset id is %s", self.id)
    else:
        self.logger.error("No dataset id has been set. Update the dataset id or create a dataset.")

Ottieni il link per il download del set di dati.

Parametri:

Nome Tipo Descrizione Predefinito
type str
richiesto

Restituzione:

Tipo Descrizione
Optional[str]

Restituisce il link per il download o Nessuno se il link non è disponibile.

Codice sorgente in hub_sdk/modules/datasets.py
def get_download_link(self, type: str) -> Optional[str]:
    """
    Get dataset download link.

    Args:
        type (str):

    Returns:
        (Optional[str]): Return download link or None if the link is not available.
    """
    try:
        payload = {"collection": "datasets", "docId": self.id, "object": type}
        endpoint = f"{HUB_FUNCTIONS_ROOT}/v1/storage"
        response = self.post(endpoint, json=payload)
        json = response.json()
        return json.get("data", {}).get("url")
    except Exception as e:
        self.logger.error(f"Failed to download file file for {self.name}: %s", e)
        raise e

update(data)

Aggiorna la risorsa dataset rappresentata da questa istanza.

Parametri:

Nome Tipo Descrizione Predefinito
data dict

I dati aggiornati per la risorsa del dataset.

richiesto

Restituzione:

Tipo Descrizione
Optional[Response]

Oggetto di risposta della richiesta di aggiornamento, oppure Nessuno se l'aggiornamento fallisce.

Codice sorgente in hub_sdk/modules/datasets.py
def update(self, data: dict) -> Optional[Response]:
    """
    Update the dataset resource represented by this instance.

    Args:
        data (dict): The updated data for the dataset resource.

    Returns:
        (Optional[Response]): Response object from the update request, or None if update fails.
    """
    return super().update(self.id, data)

upload_dataset(file=None)

Carica un file di dati sul sito hub.

Parametri:

Nome Tipo Descrizione Predefinito
file str

Il percorso del file di dati da caricare.

None

Restituzione:

Tipo Descrizione
Optional[Response]

Oggetto di risposta della richiesta di caricamento, oppure Nessuno se il caricamento fallisce.

Codice sorgente in hub_sdk/modules/datasets.py
def upload_dataset(self, file: str = None) -> Optional[Response]:
    """
    Uploads a dataset file to the hub.

    Args:
        file (str, optional): The path to the dataset file to upload.

    Returns:
        (Optional[Response]): Response object from the upload request, or None if upload fails.
    """
    return self.hub_client.upload_dataset(self.id, file)



hub_sdk.modules.datasets.DatasetList

Basi: PaginatedList

Codice sorgente in hub_sdk/modules/datasets.py
class DatasetList(PaginatedList):
    def __init__(self, page_size=None, public=None, headers=None):
        """
        Initialize a Dataset instance.

        Args:
            page_size (int, optional): The number of items to request per page.
            public (bool, optional): Whether the items should be publicly accessible.
            headers (dict, optional): Headers to be included in API requests.
        """
        base_endpoint = "datasets"
        if public:
            base_endpoint = f"public/{base_endpoint}"
        super().__init__(base_endpoint, "dataset", page_size, headers)

__init__(page_size=None, public=None, headers=None)

Inizializza un'istanza di Dataset.

Parametri:

Nome Tipo Descrizione Predefinito
page_size int

Il numero di elementi da richiedere per pagina.

None
public bool

Se gli articoli devono essere accessibili al pubblico.

None
headers dict

Intestazioni da includere nelle richieste API.

None
Codice sorgente in hub_sdk/modules/datasets.py
def __init__(self, page_size=None, public=None, headers=None):
    """
    Initialize a Dataset instance.

    Args:
        page_size (int, optional): The number of items to request per page.
        public (bool, optional): Whether the items should be publicly accessible.
        headers (dict, optional): Headers to be included in API requests.
    """
    base_endpoint = "datasets"
    if public:
        base_endpoint = f"public/{base_endpoint}"
    super().__init__(base_endpoint, "dataset", page_size, headers)