Exemplo n.º 1
0
    def test_config_init(self):
        config1 = ParselmouthConfig(
            ParselmouthProviders.google_dfp_premium,
            config_path=self.config_path,
        )
        self.assertDictEqual(self.credentials, config1.get_credentials_arguments())

        config2 = ParselmouthConfig(
            ParselmouthProviders.google_dfp_premium,
            client_id='ID',
            client_secret='SECRET',
            refresh_token='REFRESH_TOKEN',
            network_code='NETWORK_CODE',
            application_name='APPLICATION_NAME',
        )
        self.assertDictEqual(self.credentials, config2.get_credentials_arguments())
Exemplo n.º 2
0
    def test_config_init(self):
        config1 = ParselmouthConfig(
            ParselmouthProviders.google_dfp_premium,
            config_path=self.config_path,
        )
        self.assertDictEqual(self.credentials,
                             config1.get_credentials_arguments())

        config2 = ParselmouthConfig(
            ParselmouthProviders.google_dfp_premium,
            client_id='ID',
            client_secret='SECRET',
            refresh_token='REFRESH_TOKEN',
            network_code='NETWORK_CODE',
            application_name='APPLICATION_NAME',
        )
        self.assertDictEqual(self.credentials,
                             config2.get_credentials_arguments())
Exemplo n.º 3
0
class Parselmouth(object):
    """
    Base Interface Class
    """

    ProviderInterfaceMap = {
        ParselmouthProviders.google_dfp_premium: DFPInterface,
        ParselmouthProviders.google_dfp_small_business: DFPInterface,
    }
    """
    dict, mapping between ad service providers and their implementations
    NOTES:
        * This should probably be hosted elsewhere...
        * This doesn't serve much purpose right now since all we support
            is DFP...
    """

    def __init__(self,
                 config=None,
                 provider_name=None,
                 network_timeout=60 * 10,
                 **kwargs):
        """
        Constructor

        Authenticates a provider client for the given domain.

        @param config: parselmouth.config.ParselmouthConfig
        @param provider_name: any(parselmouth.constants.ParseltoungProvider)
        @param network_timeout: int, number seconds before timing out a request
            the given ad provider service
        """
        self._network_timeout = network_timeout
        self.provider_config = config
        # Load the provider configuration
        if self.provider_config and not isinstance(self.provider_config, ParselmouthConfig):
            raise ParselmouthException(
                "Invalid config.  Config should be of type ParselmouthConfig",
            )
        elif not self.provider_config:
            self.provider_config = ParselmouthConfig(provider_name, **kwargs)

        # Get interface for given provider
        self.provider_name = self.provider_config.provider_name
        provider_interface_class = self.get_ad_service_interface_for_provider(
            self.provider_name
        )

        self.provider = provider_interface_class(
            **self.provider_config.get_credentials_arguments()
        )
        self.tree_builder = TreeBuilder(
            self.provider_name,
            self.provider,
        )

        # Attempt to access the network to check proper configuration
        try:
            self.get_network_timezone()
        except Exception as e:
            raise ParselmouthException("Provider not configured correctly. {}".format(str(e)))

    def __str__(self):
        """
        Human readable representation of this object

        @return: str
        """

        return (
            "{class_name}("
                "provider={provider},"
                "provider_config={provider_config}"
            ")"
        ).format(
            class_name=self.__class__.__name__,
            provider=self.provider,
            provider_config=self.provider_config,
        )

    @classmethod
    def get_ad_service_interface_for_provider(cls, provider_name):
        """
        Staticmethod, returns the interface class for a given ad service
        provider name

        @param provider_name: str, one of enum
            parselmouth.constants.ParselmouthProviders
        @return: descendant of
            parselmouth.adapters.abstract_interface.AbstractInterface
        """
        client_interface = cls.ProviderInterfaceMap.get(provider_name)
        if not client_interface:
            raise ValueError(
                "There is no interface defined for provider: %s" %
                provider_name
            )
        return client_interface

    @classmethod
    def get_ad_service_config_interface_for_provider(cls, provider_name):
        """
        Staticmethod, returns the config interface for a given ad
        service provider name

        @param provider_name: str, one of enum
            parselmouth.constants.ParselmouthProviders
        @return: child(parselmouth.config.ParselmouthConfig)
        """
        config_interface = cls.ProviderConfigInterfaceMap.get(provider_name)
        if not config_interface:
            raise ValueError(
                "There is no config interface defined for provider: %s" %
                provider_name
            )
        return config_interface

    def get_network_timezone(self):
        """
        Get the DFP network timezone for
        the host this client is connected to

        @return: pytz.timezone
        """
        with Timeout(self._network_timeout):
            return self.provider.get_network_timezone()

    def get_advertisers(self):
        """
        Queries dfp for all advertisers within their account

        @return: list(dict), returns a list of company dictionaries
        """
        with Timeout(self._network_timeout):
            return self.provider.get_advertisers()

    def get_campaign(self, campaign_id, include_line_items=False):
        """
        Return a campaign object given an id

        @param campaign_id: str, id of the campaign to return
        @param include_line_items: bool, include line item data as well
        @return: parselmouth.delivery.Campaign
        """
        with Timeout(self._network_timeout):
            campaign = self.provider.get_campaign(campaign_id)

        if include_line_items:
            campaign.line_items = self.get_campaign_line_items(campaign)

        return campaign

    def get_campaigns(self, **kwargs):
        """
        Get campaigns on optional filters

        @param order: str, PQL key to sort on (default=ID)
        @param limit: int, number of PQL results to return
        @param offset: int, page in a stream of PQL results to return
        @param filter_kwargs: dict, keyword arguments on which to filter
            PQL results
        @return: L{parselmouth.delivery.Campaign}
        """
        with Timeout(self._network_timeout):
            return self.provider.get_campaigns(**kwargs)

    def get_line_item(self, line_item_id):
        """
        Return a line item object given an id

        @param line_item_id: str, id of the LineItem to return
        @return: parselmouth.delivery.LineItem
        """
        attempt = 1
        response = None
        while not response and attempt <= MAX_REQUEST_ATTEMPTS:
            try:
                with Timeout(self._network_timeout):
                    response = self.provider.get_line_item(line_item_id)
            except ParselmouthNetworkError:
                logging.exception("Got network error on attempt %s" % attempt)
                attempt += 1

        if not response:
            raise ParselmouthException(
                'Could not fetch a line item in {0} attempts'.format(
                    MAX_REQUEST_ATTEMPTS
                )
            )

        return response

    def get_line_items(self, **kwargs):
        """
        Get line items on optional filters

        @param order: str, PQL key to sort on (default=ID)
        @param limit: int, number of PQL results to return
        @param offset: int, page in a stream of PQL results to return
        @param filter_kwargs: dict, keyword arguments on which to filter
            PQL results
        @return: L{parselmouth.delivery.LineItem}
        """
        with Timeout(self._network_timeout):
            return self.provider.get_line_items(**kwargs)

    def get_campaign_line_items(self, campaign):
        """
        Get line items on optional filters

        @param campaign: Campaign|str,
        @return: L{parselmouth.delivery.LineItem}
        """
        with Timeout(self._network_timeout):
            return self.provider.get_campaign_line_items(campaign)

    def get_line_item_available_inventory(self,
                                          line_item,
                                          use_start=False,
                                          preserve_id=False):
        """
        Get number of impressions available for line item.
        NOTE: The following fields are required within a line item to
        perform an availability check:
            type, cost_type, end, targeting.inventory

        @param line_item: LineItem
        @param use_start: bool, if False, checks availability from right
            now
        @param preserve_id: bool, communicate the id of the line item
            being forecasted to DFP. This is used in the case where we
            want to get a forecast on a line item in flight. This way, a
            domain doesn't need to have enough spare inventory to
            accommodate the two line items simultaneously. NOTE: If this
            is true then use_start is necessarily true.
        @return: int|None, number of available impressions
        """
        with Timeout(self._network_timeout):
            return self.provider.get_line_item_available_inventory(
                line_item, use_start, preserve_id
            )

    def get_creative(self, creative_id):
        """
        Return a creative object given an id

        @param creative_id: str, id of the campaign to return
        @return: parselmouth.delivery.Creative
        """
        return self.provider.get_creative(creative_id)

    def get_creatives(self, **kwargs):
        """
        Get creatives on optional filters

        @param order: str, PQL key to sort on (default=ID)
        @param limit: int, number of PQL results to return
        @param offset: int, page in a stream of PQL results to return
        @param filter_kwargs: dict, keyword arguments on which to filter
            PQL results
        @return: L{parselmouth.delivery.Creative}
        """
        with Timeout(self._network_timeout):
            return self.provider.get_creatives(**kwargs)

    def get_line_item_creatives(self, line_item):
        """
        Return the creatives associated with a given line item

        @param line_item: str|int|parselmouth.delivery.LineItem,
            either the id of the lineitem or an object with the id
        @return: list(parselmouth.delivery.Creative)
        """
        with Timeout(self._network_timeout):
            return self.provider.get_line_item_creatives(line_item)

    def get_line_item_report(self,
                             start,
                             end,
                             columns=[ParselmouthReportMetrics.ad_impressions]):
        """
        Get the number of impressions served by DFP
        for all line items between the two datetimes.

        Note: These datetimes are assumed to be in the timezone
        of the host and will be aligned to day

        Note: This API has a strange behavior where the date
        inputs only allow for a calendar day.
        This means start=1/1, end=1/1 will query against
        the entire day of 1/1

        @param start: datetime,
        @param end: datetime,
        @param columns: list(str), list of columns to include
        @return: list(dict)
        """
        with Timeout(self._network_timeout):
            return self.provider.get_line_item_report(
                start, end, columns,
            )

    def get_custom_target_by_name(self, name, parent_name):
        """
        Get a custom target by its name

        @param name: name of custom target
        @param parent_name: name of parent target
        @return: Custom|None
        """

        with Timeout(self._network_timeout):
            targets = self.provider.get_custom_targets(
                key_name=parent_name, value_name=name,
            )

        if targets and len(targets) > 1:
            raise ParselmouthException('Given name is not unique')
        elif targets:
            return targets[0]
        else:
            return None

    def construct_tree(self, target_type):
        """
        Get all data of type target_type from ad provider,
        and build a tree

        @param taget_type: parselmouthTargetTypes
        @return: NodeTree
        """
        return self.tree_builder.construct_tree(target_type)

    def update_line_item(self, line_item):
        """
        Update a Line Item for a provider

        @param line_item: parselmouth.delivery.LineItem
        """
        with Timeout(self._network_timeout):
            self.update_line_items([line_item])

    def update_line_items(self, line_items):
        """
        Update multiple Line Item for a provider

        @param line_items: L{parselmouth.delivery.LineItem}
        """
        with Timeout(self._network_timeout):
            self.provider.update_line_items(line_items)

    def create_custom_target(self, key, value):
        """
        Add a custom target to this domain's ad service provider

        @param key: parselmouth.targeting.Custom
        @param value: parselmouth.targeting.Custom
        @return: list(parselmouth.targeting.Custom)
        """
        with Timeout(self._network_timeout):
            return self.provider.create_custom_target(key, value)
Exemplo n.º 4
0
class Parselmouth(object):
    """
    Base Interface Class
    """

    ProviderInterfaceMap = {
        ParselmouthProviders.google_dfp_premium: DFPInterface,
        ParselmouthProviders.google_dfp_small_business: DFPInterface,
    }
    """
    dict, mapping between ad service providers and their implementations
    NOTES:
        * This should probably be hosted elsewhere...
        * This doesn't serve much purpose right now since all we support
            is DFP...
    """

    def __init__(self,
                 config=None,
                 provider_name=None,
                 network_timeout=60 * 10,
                 **kwargs):
        """
        Constructor

        Authenticates a provider client for the given domain.

        @param config: parselmouth.config.ParselmouthConfig
        @param provider_name: any(parselmouth.constants.ParseltoungProvider)
        @param network_timeout: int, number seconds before timing out a request
            the given ad provider service
        """
        self._network_timeout = network_timeout
        self.provider_config = config
        # Load the provider configuration
        if self.provider_config and not isinstance(self.provider_config, ParselmouthConfig):
            raise ParselmouthException(
                "Invalid config.  Config should be of type ParselmouthConfig",
            )
        elif not self.provider_config:
            self.provider_config = ParselmouthConfig(provider_name, **kwargs)

        # Get interface for given provider
        self.provider_name = self.provider_config.provider_name
        provider_interface_class = self.get_ad_service_interface_for_provider(
            self.provider_name
        )

        self.provider = provider_interface_class(
            **self.provider_config.get_credentials_arguments()
        )
        self.tree_builder = TreeBuilder(
            self.provider_name,
            self.provider,
        )

        # Attempt to access the network to check proper configuration
        try:
            self.get_network_timezone()
        except Exception as e:
            raise ParselmouthException(
                "Provider not configured correctly. Got error: '{}'".format(
                    str(e)
                )
            )

    def __str__(self):
        """
        Human readable representation of this object

        @return: str
        """

        return (
            "{class_name}("
                "provider={provider},"
                "provider_config={provider_config}"
            ")"
        ).format(
            class_name=self.__class__.__name__,
            provider=self.provider,
            provider_config=self.provider_config,
        )

    @classmethod
    def get_ad_service_interface_for_provider(cls, provider_name):
        """
        Staticmethod, returns the interface class for a given ad service
        provider name

        @param provider_name: str, one of enum
            parselmouth.constants.ParselmouthProviders
        @return: descendant of
            parselmouth.adapters.abstract_interface.AbstractInterface
        """
        client_interface = cls.ProviderInterfaceMap.get(provider_name)
        if not client_interface:
            raise ValueError(
                "There is no interface defined for provider: %s" %
                provider_name
            )
        return client_interface

    @classmethod
    def get_ad_service_config_interface_for_provider(cls, provider_name):
        """
        Staticmethod, returns the config interface for a given ad
        service provider name

        @param provider_name: str, one of enum
            parselmouth.constants.ParselmouthProviders
        @return: child(parselmouth.config.ParselmouthConfig)
        """
        config_interface = cls.ProviderConfigInterfaceMap.get(provider_name)
        if not config_interface:
            raise ValueError(
                "There is no config interface defined for provider: %s" %
                provider_name
            )
        return config_interface

    def get_network_timezone(self):
        """
        Get the DFP network timezone for
        the host this client is connected to

        @return: pytz.timezone
        """
        with Timeout(self._network_timeout):
            return self.provider.get_network_timezone()

    def get_advertisers(self):
        """
        Queries dfp for all advertisers within their account

        @return: list(dict), returns a list of company dictionaries
        """
        with Timeout(self._network_timeout):
            return self.provider.get_advertisers()

    def get_campaign(self, campaign_id, include_line_items=False):
        """
        Return a campaign object given an id

        @param campaign_id: str, id of the campaign to return
        @param include_line_items: bool, include line item data as well
        @return: parselmouth.delivery.Campaign
        """
        with Timeout(self._network_timeout):
            campaign = self.provider.get_campaign(campaign_id)

        if include_line_items:
            campaign.line_items = self.get_campaign_line_items(campaign)

        return campaign

    def get_campaigns(self, **kwargs):
        """
        Get campaigns on optional filters

        @param order: str, PQL key to sort on (default=ID)
        @param limit: int, number of PQL results to return
        @param offset: int, page in a stream of PQL results to return
        @param filter_kwargs: dict, keyword arguments on which to filter
            PQL results
        @return: L{parselmouth.delivery.Campaign}
        """
        with Timeout(self._network_timeout):
            return self.provider.get_campaigns(**kwargs)

    def get_line_item(self, line_item_id):
        """
        Return a line item object given an id

        @param line_item_id: str, id of the LineItem to return
        @return: parselmouth.delivery.LineItem
        """
        attempt = 1
        response = None
        while not response and attempt <= MAX_REQUEST_ATTEMPTS:
            try:
                with Timeout(self._network_timeout):
                    response = self.provider.get_line_item(line_item_id)
            except ParselmouthNetworkError:
                logging.exception("Got network error on attempt %s" % attempt)
                attempt += 1

        if not response:
            raise ParselmouthException(
                'Could not fetch a line item in {0} attempts'.format(
                    MAX_REQUEST_ATTEMPTS
                )
            )

        return response

    def get_line_items(self, **kwargs):
        """
        Get line items on optional filters

        @param order: str, PQL key to sort on (default=ID)
        @param limit: int, number of PQL results to return
        @param offset: int, page in a stream of PQL results to return
        @param filter_kwargs: dict, keyword arguments on which to filter
            PQL results
        @return: L{parselmouth.delivery.LineItem}
        """
        with Timeout(self._network_timeout):
            return self.provider.get_line_items(**kwargs)

    def get_campaign_line_items(self, campaign):
        """
        Get line items on optional filters

        @param campaign: Campaign|str,
        @return: L{parselmouth.delivery.LineItem}
        """
        with Timeout(self._network_timeout):
            return self.provider.get_campaign_line_items(campaign)

    def get_line_item_available_inventory(self,
                                          line_item,
                                          use_start=False,
                                          preserve_id=False):
        """
        Get number of impressions available for line item.
        NOTE: The following fields are required within a line item to
        perform an availability check:
            type, cost_type, end, targeting.inventory

        @param line_item: LineItem
        @param use_start: bool, if False, checks availability from right
            now
        @param preserve_id: bool, communicate the id of the line item
            being forecasted to DFP. This is used in the case where we
            want to get a forecast on a line item in flight. This way, a
            domain doesn't need to have enough spare inventory to
            accommodate the two line items simultaneously. NOTE: If this
            is true then use_start is necessarily true.
        @return: int|None, number of available impressions
        """
        with Timeout(self._network_timeout):
            return self.provider.get_line_item_available_inventory(
                line_item, use_start, preserve_id
            )

    def get_creative(self, creative_id):
        """
        Return a creative object given an id

        @param creative_id: str, id of the campaign to return
        @return: parselmouth.delivery.Creative
        """
        return self.provider.get_creative(creative_id)

    def get_creatives(self, **kwargs):
        """
        Get creatives on optional filters

        @param order: str, PQL key to sort on (default=ID)
        @param limit: int, number of PQL results to return
        @param offset: int, page in a stream of PQL results to return
        @param filter_kwargs: dict, keyword arguments on which to filter
            PQL results
        @return: L{parselmouth.delivery.Creative}
        """
        with Timeout(self._network_timeout):
            return self.provider.get_creatives(**kwargs)

    def get_line_item_creatives(self, line_item):
        """
        Return the creatives associated with a given line item

        @param line_item: str|int|parselmouth.delivery.LineItem,
            either the id of the lineitem or an object with the id
        @return: list(parselmouth.delivery.Creative)
        """
        with Timeout(self._network_timeout):
            return self.provider.get_line_item_creatives(line_item)

    def get_line_item_report(self,
                             start,
                             end,
                             columns=[ParselmouthReportMetrics.ad_impressions]):
        """
        Get the number of impressions served by DFP
        for all line items between the two datetimes.

        Note: These datetimes are assumed to be in the timezone
        of the host and will be aligned to day

        Note: This API has a strange behavior where the date
        inputs only allow for a calendar day.
        This means start=1/1, end=1/1 will query against
        the entire day of 1/1

        @param start: datetime,
        @param end: datetime,
        @param columns: list(str), list of columns to include
        @return: list(dict)
        """
        with Timeout(self._network_timeout):
            return self.provider.get_line_item_report(
                start, end, columns,
            )

    def get_custom_target_by_name(self, name, parent_name):
        """
        Get a custom target by its name

        @param name: name of custom target
        @param parent_name: name of parent target
        @return: Custom|None
        """

        with Timeout(self._network_timeout):
            targets = self.provider.get_custom_targets(
                key_name=parent_name, value_name=name,
            )

        if targets and len(targets) > 1:
            raise ParselmouthException('Given name is not unique')
        elif targets:
            return targets[0]
        else:
            return None

    def construct_tree(self, target_type):
        """
        Get all data of type target_type from ad provider,
        and build a tree

        @param taget_type: parselmouthTargetTypes
        @return: NodeTree
        """
        return self.tree_builder.construct_tree(target_type)

    def update_line_item(self, line_item):
        """
        Update a Line Item for a provider

        @param line_item: parselmouth.delivery.LineItem
        """
        with Timeout(self._network_timeout):
            self.update_line_items([line_item])

    def update_line_items(self, line_items):
        """
        Update multiple Line Item for a provider

        @param line_items: L{parselmouth.delivery.LineItem}
        """
        with Timeout(self._network_timeout):
            self.provider.update_line_items(line_items)

    def create_custom_target(self, key, value):
        """
        Add a custom target to this domain's ad service provider

        @param key: parselmouth.targeting.Custom
        @param value: parselmouth.targeting.Custom
        @return: list(parselmouth.targeting.Custom)
        """
        with Timeout(self._network_timeout):
            return self.provider.create_custom_target(key, value)