์ฝ˜ํ…์ธ ๋กœ ๊ฑด๋„ˆ๋›ฐ๊ธฐ

์ฐธ์กฐ hub_sdk/base/api_client.py

์ฐธ๊ณ 

์ด ํŒŒ์ผ์€ https://github.com/ultralytics/ hub-sdk/blob/main/ hub_sdk/base/api_client .py์—์„œ ํ™•์ธํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ฌธ์ œ๋ฅผ ๋ฐœ๊ฒฌํ•˜๋ฉด ํ’€ ๋ฆฌํ€˜์ŠคํŠธ (๐Ÿ› ๏ธ)๋ฅผ ์ œ์ถœํ•˜์—ฌ ๋ฌธ์ œ๋ฅผ ํ•ด๊ฒฐํ•˜๋„๋ก ๋„์™€์ฃผ์„ธ์š”. ๊ฐ์‚ฌํ•ฉ๋‹ˆ๋‹ค ๐Ÿ™!



hub_sdk.base.api_client.APIClientError

๊ธฐ์ง€: Exception

API ํด๋ผ์ด์–ธํŠธ ์˜ค๋ฅ˜์— ๋Œ€ํ•œ ์‚ฌ์šฉ์ž ์ง€์ • ์˜ˆ์™ธ ํด๋ž˜์Šค.

์†์„ฑ:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช…
message str

์‚ฌ๋žŒ์ด ์ฝ์„ ์ˆ˜ ์žˆ๋Š” ์˜ค๋ฅ˜ ๋ฉ”์‹œ์ง€์ž…๋‹ˆ๋‹ค.

status_code int

์˜ค๋ฅ˜์™€ ๊ด€๋ จ๋œ HTTP ์ƒํƒœ ์ฝ”๋“œ(์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ)์ž…๋‹ˆ๋‹ค.

์˜ ์†Œ์Šค ์ฝ”๋“œ hub_sdk/base/api_client.py
class APIClientError(Exception):
    """
    Custom exception class for API client errors.

    Attributes:
        message (str): A human-readable error message.
        status_code (int): The HTTP status code associated with the error, if available.
    """

    def __init__(self, message: str, status_code: Optional[int] = None):
        """
        Initialize the APIClientError instance.

        Args:
            message (str): A human-readable error message.
            status_code (int, optional): The HTTP status code associated with the error, if available.
        """
        super().__init__(message)
        self.status_code = status_code
        self.message = message

    def __str__(self) -> str:
        return f"{self.__class__.__name__}: {self.args[0]}"

__init__(message, status_code=None)

APIClientError ์ธ์Šคํ„ด์Šค๋ฅผ ์ดˆ๊ธฐํ™”ํ•ฉ๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช… ๊ธฐ๋ณธ๊ฐ’
message str

์‚ฌ๋žŒ์ด ์ฝ์„ ์ˆ˜ ์žˆ๋Š” ์˜ค๋ฅ˜ ๋ฉ”์‹œ์ง€์ž…๋‹ˆ๋‹ค.

ํ•„์ˆ˜
status_code int

์˜ค๋ฅ˜์™€ ๊ด€๋ จ๋œ HTTP ์ƒํƒœ ์ฝ”๋“œ(์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ)์ž…๋‹ˆ๋‹ค.

None
์˜ ์†Œ์Šค ์ฝ”๋“œ hub_sdk/base/api_client.py
def __init__(self, message: str, status_code: Optional[int] = None):
    """
    Initialize the APIClientError instance.

    Args:
        message (str): A human-readable error message.
        status_code (int, optional): The HTTP status code associated with the error, if available.
    """
    super().__init__(message)
    self.status_code = status_code
    self.message = message



hub_sdk.base.api_client.APIClient

์ง€์ •๋œ ๊ธฐ๋ณธ URL์— ์š”์ฒญ์„ ํ•˜๊ธฐ ์œ„ํ•œ API ํด๋ผ์ด์–ธํŠธ๋ฅผ ๋‚˜ํƒ€๋ƒ…๋‹ˆ๋‹ค.

์†์„ฑ:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช…
base_url str

API์˜ ๊ธฐ๋ณธ URL์ž…๋‹ˆ๋‹ค.

headers (dict, None)

๊ฐ ์š”์ฒญ์— ํฌํ•จ๋  ํ—ค๋”์ž…๋‹ˆ๋‹ค.

logger Logger

๋กœ๊น… ๋ชฉ์ ์˜ ๋กœ๊ฑฐ ์ธ์Šคํ„ด์Šค์ž…๋‹ˆ๋‹ค.

์˜ ์†Œ์Šค ์ฝ”๋“œ hub_sdk/base/api_client.py
class APIClient:
    """
    Represents an API client for making requests to a specified base URL.

    Attributes:
        base_url (str): The base URL for the API.
        headers (dict, None): Headers to be included in each request.
        logger (logging.Logger): An instance of the logger for logging purposes.
    """

    def __init__(self, base_url: str, headers: Optional[Dict] = None):
        """
        Initialize an instance of the APIClient class.

        Args:
            base_url (str): The base URL for the API.
            headers (dict, optional): Headers to be included in each request.
        """
        self.base_url = base_url
        self.headers = headers
        self.logger = logger

    def _make_request(
        self,
        method: str,
        endpoint: str,
        data: Optional[Dict] = None,
        json: Optional[Dict] = None,
        params: Optional[Dict] = None,
        files: Optional[Dict] = None,
        stream: bool = False,
    ) -> Optional[requests.Response]:
        """
        Make an HTTP request to the API.

        Args:
            method (str): The HTTP method to use for the request (e.g., "GET", "POST").
            endpoint (str): The endpoint to append to the base URL for the request.
            data (dict, optional): Data to be sent in the request's body.
            json (dict, optional): JSON data to be sent in the request's body.
            params (dict, optional): Query parameters for the request.
            files (dict, optional): Files to be sent as part of the form data.
            stream (bool, optional): Whether to stream the response content.

        Returns:
            (Optional[requests.Response]): The response object from the HTTP request, None if it fails and
        HUB_EXCEPTIONS off.

        Raises:
            (APIClientError): If an error occurs during the request, this exception is raised with an appropriate
        message based on the HTTP status code.
        """
        # Overwrite the base url if a http url is submitted
        url = endpoint if endpoint.startswith("http") else self.base_url + endpoint

        kwargs = {"params": params, "files": files, "headers": self.headers, "stream": stream}

        # Determine the request data based on 'data' or 'json_data'
        if json is not None:
            kwargs["json"] = json
        else:
            kwargs["data"] = data

        try:
            response = requests.request(method, url, **kwargs)

            response.raise_for_status()
            return response
        except requests.exceptions.RequestException as e:
            status_code = None
            # To handle Timeout and ConnectionError exceptions
            if hasattr(e, "response") and e.response:
                status_code = e.response.status_code

            error_msg = ErrorHandler(status_code).handle()
            self.logger.error(error_msg)

            if not HUB_EXCEPTIONS:
                raise APIClientError(error_msg, status_code=status_code) from e

    def get(self, endpoint: str, params=None) -> Optional[requests.Response]:
        """
        Make a GET request to the API.

        Args:
            endpoint (str): The endpoint to append to the base URL for the request.
            params (dict, optional): Query parameters for the request.

        Returns:
            (Optional[requests.Response]): The response object from the HTTP GET request, None if it fails.
        """
        return self._make_request("GET", endpoint, params=params)

    def post(
        self,
        endpoint: str,
        data: Optional[Dict] = None,
        json: Optional[Dict] = None,
        files: Optional[Dict] = None,
        stream=False,
    ) -> Optional[requests.Response]:
        """
        Make a POST request to the API.

        Args:
            endpoint (str): The endpoint to append to the base URL for the request.
            data (dict, optional): Data to be sent in the request's body.
            json (dict, optional): JSON data to be sent in the request's body.
            files (dict, optional): Files to be included in the request, if any.
            stream (bool, optional): If True, the response content will be streamed.

        Returns:
            (Optional[requests.Response]): The response object from the HTTP POST request.
        """
        return self._make_request("POST", endpoint, data=data, json=json, files=files, stream=stream)

    def put(
        self, endpoint: str, data: Optional[Dict] = None, json: Optional[Dict] = None
    ) -> Optional[requests.Response]:
        """
        Make a PUT request to the API.

        Args:
            endpoint (str): The endpoint to append to the base URL for the request.
            data (Optional[Dict], optional): Data to be sent in the request's body.
            json (Optional[Dict], optional): JSON data to be sent in the request's body

        Returns:
            (Optional[requests.Response]): The response object from the HTTP PUT request.
        """
        return self._make_request("PUT", endpoint, data=data, json=json)

    def delete(self, endpoint: str, params: Optional[Dict] = None) -> Optional[requests.Response]:
        """
        Make a DELETE request to the API.

        Args:
            endpoint (str): The endpoint to append to the base URL for the request.
            params (dict, optional): Parameters to include in the request.

        Returns:
            (Optional[requests.Response]): The response object from the HTTP DELETE request, or None if it fails.
        """
        return self._make_request("DELETE", endpoint, params=params)

    def patch(
        self, endpoint: str, data: Optional[Dict] = None, json: Optional[Dict] = None
    ) -> Optional[requests.Response]:
        """
        Make a PATCH request to the API.

        Args:
            endpoint (str): The endpoint to append to the base URL for the request.
            data (dict, optional): Data to be sent in the request's body.
            json (dict, optional): JSON data to be sent in the request's body.

        Returns:
            (Optional[requests.Response]): The response object from the HTTP PATCH request, or None if it fails.
        """
        return self._make_request("PATCH", endpoint, data=data, json=json)

__init__(base_url, headers=None)

APIClient ํด๋ž˜์Šค์˜ ์ธ์Šคํ„ด์Šค๋ฅผ ์ดˆ๊ธฐํ™”ํ•ฉ๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช… ๊ธฐ๋ณธ๊ฐ’
base_url str

API์˜ ๊ธฐ๋ณธ URL์ž…๋‹ˆ๋‹ค.

ํ•„์ˆ˜
headers dict

๊ฐ ์š”์ฒญ์— ํฌํ•จ๋  ํ—ค๋”์ž…๋‹ˆ๋‹ค.

None
์˜ ์†Œ์Šค ์ฝ”๋“œ hub_sdk/base/api_client.py
def __init__(self, base_url: str, headers: Optional[Dict] = None):
    """
    Initialize an instance of the APIClient class.

    Args:
        base_url (str): The base URL for the API.
        headers (dict, optional): Headers to be included in each request.
    """
    self.base_url = base_url
    self.headers = headers
    self.logger = logger

delete(endpoint, params=None)

API์— ์‚ญ์ œ ์š”์ฒญ์„ ํ•ฉ๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช… ๊ธฐ๋ณธ๊ฐ’
endpoint str

์š”์ฒญ์˜ ๊ธฐ๋ณธ URL์— ์ถ”๊ฐ€ํ•  ์—”๋“œํฌ์ธํŠธ์ž…๋‹ˆ๋‹ค.

ํ•„์ˆ˜
params dict

์š”์ฒญ์— ํฌํ•จํ•  ๋งค๊ฐœ๋ณ€์ˆ˜์ž…๋‹ˆ๋‹ค.

None

๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค:

์œ ํ˜• ์„ค๋ช…
Optional[Response]

HTTP DELETE ์š”์ฒญ์˜ ์‘๋‹ต ๊ฐ์ฒด์ด๊ฑฐ๋‚˜, ์‹คํŒจํ•˜๋ฉด None์ž…๋‹ˆ๋‹ค.

์˜ ์†Œ์Šค ์ฝ”๋“œ hub_sdk/base/api_client.py
def delete(self, endpoint: str, params: Optional[Dict] = None) -> Optional[requests.Response]:
    """
    Make a DELETE request to the API.

    Args:
        endpoint (str): The endpoint to append to the base URL for the request.
        params (dict, optional): Parameters to include in the request.

    Returns:
        (Optional[requests.Response]): The response object from the HTTP DELETE request, or None if it fails.
    """
    return self._make_request("DELETE", endpoint, params=params)

get(endpoint, params=None)

API์— GET ์š”์ฒญ์„ ํ•ฉ๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช… ๊ธฐ๋ณธ๊ฐ’
endpoint str

์š”์ฒญ์˜ ๊ธฐ๋ณธ URL์— ์ถ”๊ฐ€ํ•  ์—”๋“œํฌ์ธํŠธ์ž…๋‹ˆ๋‹ค.

ํ•„์ˆ˜
params dict

์š”์ฒญ์— ๋Œ€ํ•œ ์ฟผ๋ฆฌ ๋งค๊ฐœ๋ณ€์ˆ˜์ž…๋‹ˆ๋‹ค.

None

๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค:

์œ ํ˜• ์„ค๋ช…
Optional[Response]

HTTP GET ์š”์ฒญ์˜ ์‘๋‹ต ๊ฐ์ฒด(์‹คํŒจํ•˜๋ฉด ์—†์Œ)์ž…๋‹ˆ๋‹ค.

์˜ ์†Œ์Šค ์ฝ”๋“œ hub_sdk/base/api_client.py
def get(self, endpoint: str, params=None) -> Optional[requests.Response]:
    """
    Make a GET request to the API.

    Args:
        endpoint (str): The endpoint to append to the base URL for the request.
        params (dict, optional): Query parameters for the request.

    Returns:
        (Optional[requests.Response]): The response object from the HTTP GET request, None if it fails.
    """
    return self._make_request("GET", endpoint, params=params)

patch(endpoint, data=None, json=None)

API์— PATCH ์š”์ฒญ์„ ํ•ฉ๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช… ๊ธฐ๋ณธ๊ฐ’
endpoint str

์š”์ฒญ์˜ ๊ธฐ๋ณธ URL์— ์ถ”๊ฐ€ํ•  ์—”๋“œํฌ์ธํŠธ์ž…๋‹ˆ๋‹ค.

ํ•„์ˆ˜
data dict

์š”์ฒญ ๋ณธ๋ฌธ์— ์ „์†กํ•  ๋ฐ์ดํ„ฐ์ž…๋‹ˆ๋‹ค.

None
json dict

์š”์ฒญ ๋ณธ๋ฌธ์— ์ „์†กํ•  JSON ๋ฐ์ดํ„ฐ์ž…๋‹ˆ๋‹ค.

None

๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค:

์œ ํ˜• ์„ค๋ช…
Optional[Response]

HTTP PATCH ์š”์ฒญ์˜ ์‘๋‹ต ๊ฐ์ฒด์ด๊ฑฐ๋‚˜, ์‹คํŒจํ•œ ๊ฒฝ์šฐ None์ž…๋‹ˆ๋‹ค.

์˜ ์†Œ์Šค ์ฝ”๋“œ hub_sdk/base/api_client.py
def patch(
    self, endpoint: str, data: Optional[Dict] = None, json: Optional[Dict] = None
) -> Optional[requests.Response]:
    """
    Make a PATCH request to the API.

    Args:
        endpoint (str): The endpoint to append to the base URL for the request.
        data (dict, optional): Data to be sent in the request's body.
        json (dict, optional): JSON data to be sent in the request's body.

    Returns:
        (Optional[requests.Response]): The response object from the HTTP PATCH request, or None if it fails.
    """
    return self._make_request("PATCH", endpoint, data=data, json=json)

post(endpoint, data=None, json=None, files=None, stream=False)

API์— POST ์š”์ฒญ์„ ํ•ฉ๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช… ๊ธฐ๋ณธ๊ฐ’
endpoint str

์š”์ฒญ์˜ ๊ธฐ๋ณธ URL์— ์ถ”๊ฐ€ํ•  ์—”๋“œํฌ์ธํŠธ์ž…๋‹ˆ๋‹ค.

ํ•„์ˆ˜
data dict

์š”์ฒญ ๋ณธ๋ฌธ์— ์ „์†กํ•  ๋ฐ์ดํ„ฐ์ž…๋‹ˆ๋‹ค.

None
json dict

์š”์ฒญ ๋ณธ๋ฌธ์— ์ „์†กํ•  JSON ๋ฐ์ดํ„ฐ์ž…๋‹ˆ๋‹ค.

None
files dict

์š”์ฒญ์— ํฌํ•จํ•  ํŒŒ์ผ(์žˆ๋Š” ๊ฒฝ์šฐ)์ž…๋‹ˆ๋‹ค.

None
stream bool

True๋ฅผ ์„ ํƒํ•˜๋ฉด ์‘๋‹ต ์ฝ˜ํ…์ธ ๊ฐ€ ์ŠคํŠธ๋ฆฌ๋ฐ๋ฉ๋‹ˆ๋‹ค.

False

๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค:

์œ ํ˜• ์„ค๋ช…
Optional[Response]

HTTP POST ์š”์ฒญ์˜ ์‘๋‹ต ๊ฐ์ฒด์ž…๋‹ˆ๋‹ค.

์˜ ์†Œ์Šค ์ฝ”๋“œ hub_sdk/base/api_client.py
def post(
    self,
    endpoint: str,
    data: Optional[Dict] = None,
    json: Optional[Dict] = None,
    files: Optional[Dict] = None,
    stream=False,
) -> Optional[requests.Response]:
    """
    Make a POST request to the API.

    Args:
        endpoint (str): The endpoint to append to the base URL for the request.
        data (dict, optional): Data to be sent in the request's body.
        json (dict, optional): JSON data to be sent in the request's body.
        files (dict, optional): Files to be included in the request, if any.
        stream (bool, optional): If True, the response content will be streamed.

    Returns:
        (Optional[requests.Response]): The response object from the HTTP POST request.
    """
    return self._make_request("POST", endpoint, data=data, json=json, files=files, stream=stream)

put(endpoint, data=None, json=None)

API์— PUT ์š”์ฒญ์„ ํ•ฉ๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜:

์ด๋ฆ„ ์œ ํ˜• ์„ค๋ช… ๊ธฐ๋ณธ๊ฐ’
endpoint str

์š”์ฒญ์˜ ๊ธฐ๋ณธ URL์— ์ถ”๊ฐ€ํ•  ์—”๋“œํฌ์ธํŠธ์ž…๋‹ˆ๋‹ค.

ํ•„์ˆ˜
data Optional[Dict]

์š”์ฒญ ๋ณธ๋ฌธ์— ์ „์†กํ•  ๋ฐ์ดํ„ฐ์ž…๋‹ˆ๋‹ค.

None
json Optional[Dict]

์š”์ฒญ ๋ณธ๋ฌธ์— ์ „์†กํ•  JSON ๋ฐ์ดํ„ฐ

None

๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค:

์œ ํ˜• ์„ค๋ช…
Optional[Response]

HTTP PUT ์š”์ฒญ์˜ ์‘๋‹ต ๊ฐ์ฒด์ž…๋‹ˆ๋‹ค.

์˜ ์†Œ์Šค ์ฝ”๋“œ hub_sdk/base/api_client.py
def put(
    self, endpoint: str, data: Optional[Dict] = None, json: Optional[Dict] = None
) -> Optional[requests.Response]:
    """
    Make a PUT request to the API.

    Args:
        endpoint (str): The endpoint to append to the base URL for the request.
        data (Optional[Dict], optional): Data to be sent in the request's body.
        json (Optional[Dict], optional): JSON data to be sent in the request's body

    Returns:
        (Optional[requests.Response]): The response object from the HTTP PUT request.
    """
    return self._make_request("PUT", endpoint, data=data, json=json)