PrintiPy Reference

def __init__(self, api_token: str, shop_id: Optional[Union[str, int]] = None):
    """
    Entrypoint needed to access all [Printify APIs](https://developers.printify.com/)

    Args:
        api_token (str): Every instance of PrintiPy requires an API Token. Follow
        [these steps](https://help.printify.com/hc/en-us/articles/4483626447249-How-can-I-generate-an-API-token-)
        to generate a token
        shop_id (Optional[str]): The ID of a specific Printify shop. If none is given, some APIs will still
        work (as they do not require a Shop) while others will require a Shop ID to be passed upon a function call
    """
    self.shops = PrintiPyShop(api_token=api_token)
    self.catalog = PrintiPyCatalog(api_token=api_token)
    self.products = PrintiPyProducts(api_token=api_token, shop_id=shop_id)
    self.orders = PrintiPyOrders(api_token=api_token, shop_id=shop_id)
    self.artwork = PrintiPyArtwork(api_token=api_token)
    self.webhooks = PrintiPyWebhooks(api_token=api_token, shop_id=shop_id)

def archive_artwork(self, image_id: str) -> True:
    """
    Archives a specific artwork/image for an account in Printify

    Examples:
        >>> from printipy.api import PrintiPy
        >>> from printipy.data_objects import Shop
        >>> api = PrintiPy(api_token='...')
        >>> artworks = api.artwork.get_artwork_uploads()
        >>> api.artwork.archive_artwork(artworks[0].id)

    Raises:
        InvalidScopeException: If the API keys isn't permitted to perform this operation
        InvalidRequestException: If the Artwork ID does not exist in Printify
        PrintifyException: If Printify returned an error - usually contains information regarding malformed input
    """
    # post / v1 / uploads / {image_id} / archive.json
    archive_artwork_url = f'{self.api_url}/v1/uploads/{image_id}/archive.json'
    self._post(archive_artwork_url)
    return True

def get_artwork(self, image_id: str) -> Artwork:
    """
    Pulls information for a speciic artwork/image for an account in Printify.

    Examples:
        >>> from printipy.api import PrintiPy
        >>> api = PrintiPy(api_token='...')
        >>> artwork = api.artwork.get_artwork(image_id='...')

    Args:
        image_id: The ID of the specific artwork for an account in Printify.
    Returns:
        Artwork `printipy.data_objects.Artwork` object

    Raises:
        ParseException: If unable to parse Printify's response
        InvalidScopeException: If the API keys isn't permitted to perform this operation
    """
    # GET / v1 / uploads / {image_id}.json
    artwork_url = f'{self.api_url}/v1/uploads/{image_id}.json'
    artwork_information = self._get(artwork_url)
    return self._parse(Artwork, artwork_information)

def get_artwork_uploads(self, max_pages: int = 1) -> List[Artwork]:
    """
    Pulls artwork/image information for an account in Printify.

    Examples:
        >>> from printipy.api import PrintiPy
        >>> api = PrintiPy(api_token='...')
        >>> artworks = api.artwork.get_artwork_uploads()

    Args:
        max_pages: Printify's API is paginated for requests. This will set the maximum number of pages to ingest.
    Returns:
        List of artwork `printipy.data_objects.Artwork` object

    Raises:
        ParseException: If unable to parse Printify's response
        InvalidScopeException: If the API keys isn't permitted to perform this operation
        InvalidRequestException: If the Artwork ID does not exist in Printify
        PrintifyException: If Printify returned an error - usually contains information regarding malformed input
    """
    # GET / v1 / uploads.json
    initial_url = f'{self.api_url}/v1/uploads.json'
    artwork_url = deepcopy(initial_url)
    all_artworks = []
    for _ in range(max_pages):
        if artwork_url is None:
            break
        artwork_information = self._get(artwork_url)
        all_artworks.extend(self._parse(Artwork, artwork_information['data']))
        artwork_url = self._get_next_page_url(initial_url, artwork_information)
    return all_artworks

def upload_artwork(self, filename: Optional[str] = None, url: Optional[str] = None) -> Artwork:
    """
    Uploads a new image/artwork to an account in Printify

    Examples:
        Using a local file
        >>> from printipy.api import PrintiPy
        >>> from printipy.data_objects import Shop
        >>> api = PrintiPy(api_token='...')
        >>> filename = '...'
        >>> artwork = api.artwork.upload_artwork(filename=filename)

        Using a URL
        >>> from printipy.api import PrintiPy
        >>> from printipy.data_objects import Shop
        >>> api = PrintiPy(api_token='...')
        >>> url = '...'
        >>> artwork = api.artwork.upload_artwork(url=url)

    Raises:
        InvalidScopeException: If the API keys isn't permitted to perform this operation
        InvalidRequestException: If the artwork isn't transmissible to Printify
        PrintifyException: If Printify returned an error - usually contains information regarding malformed input
        PrintiPyException: If neither or both filename and url are presented. Only one must be given.
    """
    if filename and url:
        raise PrintiPyException("Must provide a local filename or url for upload, not both.")

    # POST / v1 / uploads / images.json
    upload_artwork_url = f'{self.api_url}/v1/uploads/images.json'
    if url:
        artwork_data = {
            "file_name": url.split('/')[-1],
            "url": url,
        }
    elif filename:
        with open(filename, 'rb') as f:
            b64data = base64.b64encode(f.read())
        artwork_data = {
            "file_name": os.path.basename(filename),
            "contents": b64data.decode('utf-8'),
        }
    else:
        raise PrintiPyException("Must provide at least a local filename or url for upload.")

    artwork_information = self._post(upload_artwork_url, data=artwork_data)
    return self._parse(Artwork, artwork_information)

def get_blueprint(self, blueprint_id: Union[str, int]) -> Blueprint:
    """
    Pulls a specific blueprint from Printify.

    Examples:
        >>> from printipy.api import PrintiPy
        >>> api = PrintiPy(api_token='...')
        >>> blueprint = api.catalog.get_blueprint('...')

    Returns:
        Blueprint `printipy.data_objects.Blueprint` object

    Raises:
        ParseException: If unable to parse Printify's response
        InvalidScopeException: If the API keys isn't permitted to perform this operation
        InvalidRequestException: If the Blueprint ID does not exist in Printify
    """
    # GET / v1 / catalog / blueprints / {blueprint_id}.json
    blueprint_url = f'{self.api_url}/v1/catalog/blueprints/{blueprint_id}.json'
    blueprint_information = self._get(blueprint_url)
    return self._parse(Blueprint, blueprint_information)

def get_blueprints(self) -> List[Blueprint]:
    """
    Pulls a list of all blueprints available from Printify.

    Examples:
        >>> from printipy.api import PrintiPy
        >>> api = PrintiPy(api_token='...')
        >>> blueprints = api.catalog.get_blueprints()

    Returns:
        List of `printipy.data_objects.Blueprint` objects

    Raises:
        ParseException: If unable to parse Printify's response
        InvalidScopeException: If the API keys isn't permitted to perform this operation
    """
    blueprint_url = f'{self.api_url}/v1/catalog/blueprints.json'
    blueprint_information = self._get(blueprint_url)
    return self._parse(Blueprint, blueprint_information)

def get_print_provider(self, print_provider_id: Union[str, int]) -> PrintProvider:
    """
    Pulls a specific print provider from Printify.

    Examples:
        >>> from printipy.api import PrintiPy
        >>> api = PrintiPy(api_token='...')
        >>> print_provider = api.catalog.get_print_provider('...')

    Returns:
        Print Provider `printipy.data_objects.PrintProvider` object

    Raises:
        ParseException: If unable to parse Printify's response
        InvalidScopeException: If the API keys isn't permitted to perform this operation
        InvalidRequestException: If the Print Provider ID does not exist in Printify
        PrintifyException: If Printify returned an error - usually contains information regarding malformed input
    """
    # GET / v1 / catalog / print_providers / {print_provider_id}.json
    print_provider_url = f'{self.api_url}/v1/catalog/print_providers/{print_provider_id}.json'
    print_provider_information = self._get(print_provider_url)
    return self._parse(PrintProvider, print_provider_information)

def get_print_providers(self) -> List[PrintProvider]:
    """
    Pulls a list of all print providers from Printify.

    Examples:
        >>> from printipy.api import PrintiPy
        >>> api = PrintiPy(api_token='...')
        >>> print_providers = api.catalog.get_print_providers()

    Returns:
        List of `printipy.data_objects.PrintProvider` objects

    Raises:
        ParseException: If unable to parse Printify's response
        InvalidScopeException: If the API keys isn't permitted to perform this operation
        PrintifyException: If Printify returned an error - usually contains information regarding malformed input
    """
    # GET / v1 / catalog / print_providers.json
    print_providers_url = f'{self.api_url}/v1/catalog/print_providers.json'
    print_provider_information = self._get(print_providers_url)
    return self._parse(PrintProvider, print_provider_information)

def get_print_providers_for_blueprint(self, blueprint_id: Union[str, int]) -> List[PrintProvider]:
    """
    Pulls a list of print providers for a given blueprint from Printify.

    Examples:
        >>> from printipy.api import PrintiPy
        >>> api = PrintiPy(api_token='...')
        >>> blueprint = api.catalog.get_blueprint('...')
        >>> print_providers = api.catalog.get_print_providers_for_blueprint(blueprint.id)

    Returns:
        List of `printipy.data_objects.PrintProvider` objects

    Raises:
        ParseException: If unable to parse Printify's response
        InvalidScopeException: If the API keys isn't permitted to perform this operation
        InvalidRequestException: If the Blueprint ID does not exist in Printify
        PrintifyException: If Printify returned an error - usually contains information regarding malformed input
    """
    # GET / v1 / catalog / blueprints / {blueprint_id} / print_providers.json
    print_providers_url = f'{self.api_url}/v1/catalog/blueprints/{blueprint_id}/print_providers.json'
    print_provider_information = self._get(print_providers_url)
    return self._parse(PrintProvider, print_provider_information)

def get_shipping_info(self, blueprint_id: Union[str, int], print_provider_id: Union[str, int]) -> ShippingInfo:
    """
    Pulls a shipping information a given blueprint and print provider from Printify.

    Examples:
        >>> from printipy.api import PrintiPy
        >>> api = PrintiPy(api_token='...')
        >>> blueprint = api.catalog.get_blueprint('...')
        >>> print_providers = api.catalog.get_print_providers_for_blueprint(blueprint.id)
        >>> shipping_info = api.catalog.get_shipping_info(blueprint.id, print_providers[0].id)

    Returns:
        Shipping information `printipy.data_objects.ShippingInfo` object

    Raises:
        ParseException: If unable to parse Printify's response
        InvalidScopeException: If the API keys isn't permitted to perform this operation
        InvalidRequestException: If the Blueprint ID or Print Provider ID does not exist in Printify
        PrintifyException: If Printify returned an error - usually contains information regarding malformed input
    """
    # GET / v1 / catalog / blueprints / {blueprint_id} / print_providers / {print_provider_id} / shipping.json
    shipping_url = f'{self.api_url}/v1/catalog/blueprints/{blueprint_id}/' \
                   f'print_providers/{print_provider_id}/shipping.json'
    shipping_information = self._get(shipping_url)
    return self._parse(ShippingInfo, shipping_information)

def get_variants(self, blueprint_id: Union[str, int], print_provider_id: Union[str, int]) -> PrintProviderVariants:
    """
    Pulls a list of variants for a given blueprint and print provider from Printify.

    Examples:
        >>> from printipy.api import PrintiPy
        >>> api = PrintiPy(api_token='...')
        >>> blueprint = api.catalog.get_blueprint('...')
        >>> print_providers = api.catalog.get_print_providers_for_blueprint(blueprint.id)
        >>> variants = api.catalog.get_variants(blueprint.id, print_providers[0].id)

    Returns:
        Variant `printipy.data_objects.PrintProviderVariants` object

    Raises:
        ParseException: If unable to parse Printify's response
        InvalidScopeException: If the API keys isn't permitted to perform this operation
        InvalidRequestException: If the Blueprint ID or Print Provider ID does not exist in Printify
        PrintifyException: If Printify returned an error - usually contains information regarding malformed input
    """
    # GET / v1 / catalog / blueprints / {blueprint_id} / print_providers / {print_provider_id} / variants.json
    variants_url = f'{self.api_url}/v1/catalog/blueprints/{blueprint_id}/' \
                   f'print_providers/{print_provider_id}/variants.json'
    variant_information = self._get(variants_url)
    return self._parse(PrintProviderVariants, variant_information)

def delete_shop(self, shop: Shop) -> None:
    """
    Deletes a shop from a Printify account

    Examples:
        By pass in data pulled from `printipy.api.PrintiPyShop.get_shops`
        >>> from printipy.api import PrintiPy
        >>> api = PrintiPy(api_token='...', shop_id='...')
        >>> shops = api.shops.get_shops()
        >>> api.shops.delete_shop(shops[0])

        By passing in specific shop information
        >>> from printipy.api import PrintiPy
        >>> from printipy.data_objects import Shop
        >>> api = PrintiPy(api_token='...', shop_id='...')
        >>> api.shops.delete_shop(shop)

    Args:
        shop (Shop): A Shop to delete. Pull all shops using :func:`get_shops <printipy.api.PrintiPyShop.get_shops>`

    Raises:
        InvalidScopeException: If the API keys isn't permitted to perform this operation
        PrintifyException: If Printify returned an error - usually contains information regarding malformed input
    """
    delete_url = f'{self.api_url}/v1/shops/{shop.id}/connection.json'
    self._delete(delete_url)

def get_shops(self) -> List[Shop]:
    """
    Pulls a list of shops for a Printify account. Returns empty list if no shops exist for account.

    Examples:
        >>> from printipy.api import PrintiPy
        >>> api = PrintiPy(api_token='...', shop_id='...')
        >>> shops = api.shops.get_shops()

    Returns:
        List of `printipy.data_objects.Shop` objects

    Raises:
        ParseException: If unable to parse Printify's response
        InvalidScopeException: If the API keys isn't permitted to perform this operation
        PrintifyException: If Printify returned an error - usually contains information regarding malformed input
    """
    shops_url = f'{self.api_url}/v1/shops.json'
    shop_information = self._get(shops_url)
    return self._parse(Shop, shop_information)