diff --git a/docs/pinterest/README.md b/docs/pinterest/README.md index f0e550a..b436077 100644 --- a/docs/pinterest/README.md +++ b/docs/pinterest/README.md @@ -10,6 +10,8 @@ - [`ads.ads`](./ads.ads.md#module-adsads): Ads high level model - [`ads.audiences`](./ads.audiences.md#module-adsaudiences): High level module class for Audience object - [`ads.campaigns`](./ads.campaigns.md#module-adscampaigns): Campaign Class for Pinterest Python SDK +- [`ads.conversion_events`](./ads.conversion_events.md#module-adsconversion_events): Conversion Event Class for Pinterest Python SDK +- [`ads.conversion_tags`](./ads.conversion_tags.md#module-adsconversion_tags): Conversion Class for Pinterest Python SDK - [`ads.customer_lists`](./ads.customer_lists.md#module-adscustomer_lists): High level module class for Customer List object - [`ads.keywords`](./ads.keywords.md#module-adskeywords): High level module class for Keyword object - [`client`](./client.md#module-client): Pinterest Client @@ -31,6 +33,8 @@ - [`ads.Ad`](./ads.ads.md#class-ad): Ad model used to view, create, update its attributes - [`audiences.Audience`](./ads.audiences.md#class-audience): High level model class to manage audiences for an AdAccount - [`campaigns.Campaign`](./ads.campaigns.md#class-campaign): Campaign model used to view, create, update its attributes and list its different entities. +- [`conversion_events.Conversion`](./ads.conversion_events.md#class-conversion): Conversion Event Model used to send conversion events to Pinterest API +- [`conversion_tags.ConversionTag`](./ads.conversion_tags.md#class-conversiontag): Conversion Tag model used to view, create, update its attributes and list its different entities - [`customer_lists.CustomerList`](./ads.customer_lists.md#class-customerlist): High level model class to manage customer_lists for an CustomerList - [`keywords.Keyword`](./ads.keywords.md#class-keyword): High level model class to manage keywords - [`client.PinterestSDKClient`](./client.md#class-pinterestsdkclient): Wrapper API client for SDK high level models @@ -45,4 +49,5 @@ - [`error_handling.verify_api_response`](./utils.error_handling.md#function-verify_api_response): Verify that there are no errors in `response` received from api - [`load_json_config.load_json_config`](./utils.load_json_config.md#function-load_json_config): Parse a config.json file and then load all the variables found as environment variables. +- [`load_json_config.load_json_config_from_single_env_var`](./utils.load_json_config.md#function-load_json_config_from_single_env_var): Parse PINTEREST_JSON_ENV_VARIABLES environment variable to split long JSON string into - [`refresh_access_token.get_new_access_token`](./utils.refresh_access_token.md#function-get_new_access_token): Function used to retrieve a new access token for a user using the refresh token. diff --git a/docs/pinterest/ads.ad_accounts.md b/docs/pinterest/ads.ad_accounts.md index 4e3c6f6..8e57a69 100644 --- a/docs/pinterest/ads.ad_accounts.md +++ b/docs/pinterest/ads.ad_accounts.md @@ -40,6 +40,14 @@ Initialize an object of an AdAccount. +--- + +#### property created_time + + + + + --- #### property currency @@ -80,11 +88,19 @@ Initialize an object of an AdAccount. +--- + +#### property updated_time + + + + + --- - + ### classmethod `create` @@ -119,7 +135,7 @@ Keyword Args: Any valid keyword arguments or query parameters for endpoint. --- - + ### method `list_audiences` @@ -153,7 +169,7 @@ Get a list of the audiences in the AdAccount, filtered by the specified argument --- - + ### method `list_campaigns` @@ -192,7 +208,7 @@ Keyword Args: Any valid keyword arguments or query parameters for endpoint. --- - + ### method `list_customer_lists` diff --git a/docs/pinterest/ads.ad_groups.md b/docs/pinterest/ads.ad_groups.md index e2b94d3..e5f3e35 100644 --- a/docs/pinterest/ads.ad_groups.md +++ b/docs/pinterest/ads.ad_groups.md @@ -161,6 +161,14 @@ Initialize an AdGroup object. +--- + +#### property optimization_goal_metadata + + + + + --- #### property pacing_delivery_type @@ -237,7 +245,7 @@ Initialize an AdGroup object. --- - + ### classmethod `create` @@ -329,7 +337,7 @@ to ad campaigns. Some types of campaigns (e.g. budget optimization) have limits --- - + ### method `disable_auto_targeting` @@ -347,7 +355,7 @@ Disable auto-targeting for ad group. Also known as + ### classmethod `get_all` @@ -405,7 +413,7 @@ List ad groups based on provided campaign IDs or ad group IDs.(campaign_ids or a --- - + ### method `list_ads` @@ -441,7 +449,7 @@ Get list of ads under current AdGroup with specified arguments --- - + ### method `update_fields` diff --git a/docs/pinterest/ads.ads.md b/docs/pinterest/ads.ads.md index 97c9ecf..fbed9ba 100644 --- a/docs/pinterest/ads.ads.md +++ b/docs/pinterest/ads.ads.md @@ -258,7 +258,7 @@ Initialize an Ad object. --- - + ### classmethod `create` @@ -323,7 +323,7 @@ Create a new ad. Request must contain ad_group_id, creative_type, and the source --- - + ### classmethod `get_all` @@ -374,7 +374,7 @@ List ads that meet the filters provided: --- - + ### method `update_fields` diff --git a/docs/pinterest/ads.campaigns.md b/docs/pinterest/ads.campaigns.md index 4e2faf5..9a92d4c 100644 --- a/docs/pinterest/ads.campaigns.md +++ b/docs/pinterest/ads.campaigns.md @@ -142,6 +142,14 @@ Initialize a Campaign object. +--- + +#### property summary_status + + + + + --- #### property tracking_urls @@ -170,7 +178,7 @@ Initialize a Campaign object. --- - + ### method `activate` @@ -188,7 +196,7 @@ Activate a paused or archived campaign --- - + ### method `archive` @@ -206,7 +214,7 @@ Archive an active or paused campaign --- - + ### classmethod `create` @@ -298,7 +306,7 @@ Keyword Args: Any valid keyword arguments or query parameters for endpoint. --- - + ### classmethod `get_all` @@ -340,7 +348,7 @@ Keyword Args: Any valid keyword arguments or query parameters for endpoint. --- - + ### method `get_daily_budget` @@ -358,7 +366,7 @@ Get the current daily spend cap budget of the campaign. --- - + ### method `get_lifetime_budget` @@ -376,7 +384,7 @@ Get the current life time spend cap budget of the campaign. --- - + ### method `list_ad_groups` @@ -407,7 +415,7 @@ List ad groups directed related to campaign. This method makes a synchronous HTT --- - + ### method `pause` @@ -425,7 +433,7 @@ Pause an active or archived campaign --- - + ### method `set_daily_budget` @@ -449,7 +457,7 @@ Set new daily spend cap budget for the campaign. --- - + ### method `set_lifetime_budget` @@ -473,7 +481,7 @@ Set new life time spend cap budget for the campaign. --- - + ### method `update_fields` diff --git a/docs/pinterest/ads.conversion_events.md b/docs/pinterest/ads.conversion_events.md new file mode 100644 index 0000000..167bfd4 --- /dev/null +++ b/docs/pinterest/ads.conversion_events.md @@ -0,0 +1,99 @@ + + + + +# module `ads.conversion_events` +Conversion Event Class for Pinterest Python SDK + + + +--- + + + +## class `Conversion` +Conversion Event Model used to send conversion events to Pinterest API + + + + +--- + + + +### classmethod `create_conversion_event` + +```python +create_conversion_event( + event_name: 'str', + action_source: 'str', + event_time: 'int', + event_id: 'str', + user_data: 'dict', + custom_data: 'dict', + event_source_url: 'str' = None, + partner_name: 'str' = None, + app_id: 'str' = None, + app_name: 'str' = None, + app_version: 'str' = None, + device_brand: 'str' = None, + device_carrier: 'str' = None, + device_model: 'str' = None, + device_type: 'str' = None, + os_version: 'str' = None, + language: 'str' = None, + **kwargs +) → ConversionEventsData +``` + +Create Conversion Event Data to be sent. + + + +**Args:** + + - `event_name` (str): The type of the user event, Enum: "add_to_cart", "checkout", "custom", "lead", "page_visit", "search", "signup", "view_category", "watch_video" + - `action_source` (str): The source indicating where the conversion event occurred, Enum: "app_adroid", "app_ios", "web", "offline" + - `event_time` (int): The time when the event happened. Unix timestamp in seconds + - `event_id` (str): The unique id string that identifies this event and can be used for deduping between events ingested via both the conversion API and Pinterest tracking + - `user_data` (dict): Object containing customer information data. Note, it is required at least one of 1) em, 2) hashed_maids or 3) pair client_ip_address + client_user_agent. + - `custom_data` (dict): Object containing other custom data. + - `event_source_url` (str, optional): URL of the web conversion event + - `partner_name` (str, optional): The third party partner name responsible to send the event to Conversion API on behalf of the adverstiser. Only send this field if Pinterest has worked directly with you to define a value for partner_name. + - `app_id` (str, optional): The app store app ID. + - `app_name` (str, optional): Name of the app. + - `app_version` (str, optional): Version of the app. + - `device_brand` (str, optional): Brand of the user device. + - `device_carrier` (str, optional): User device's model carrier. + - `device_model` (str, optional): Model of the user device. + - `device_type` (str, optional): Type of the user device. + - `os_version` (str, optional): Version of the device operating system. + - `language` (str, optional): Two-character ISO-639-1 language code indicating the user's language. + + + +**Returns:** + + - `ConversionEventsData`: ConversionEventData to be sent + +--- + + + +### classmethod `send_conversion_events` + +```python +send_conversion_events( + ad_account_id: 'str', + conversion_events: 'list[ConversionEventsData]', + test: 'bool' = False, + client: 'PinterestSDKClient' = None, + **kwargs +) → tuple(int, int, list[ConversionApiResponseEvents]) +``` + +Send conversion events to Pinterest API for Conversions. + +Note: Highly recommend to use create_client_with_token (with Conversion Access Token) to create different client for this functionality. + + diff --git a/docs/pinterest/ads.conversion_tags.md b/docs/pinterest/ads.conversion_tags.md new file mode 100644 index 0000000..6666fd9 --- /dev/null +++ b/docs/pinterest/ads.conversion_tags.md @@ -0,0 +1,271 @@ + + + + +# module `ads.conversion_tags` +Conversion Class for Pinterest Python SDK + + + +--- + + + +## class `ConversionTag` +Conversion Tag model used to view, create, update its attributes and list its different entities + + + +### method `__init__` + +```python +__init__( + ad_account_id: 'str', + conversion_tag_id: 'str', + client: 'PinterestSDKClient' = None, + **kwargs +) → None +``` + +Initialize Conversion Tag Object. + + + +**Args:** + + - `ad_account_id` (str): ConversionTag's Ad Account ID + - `conversion_tag_id` (str): ConversionTag ID, must be associated with Ad Account ID provided + - `client` (PinterestSDKClient, optional): PinterestSDKClient Object. Uses the default client, if not provided. + + +--- + +#### property ad_account_id + + + + + +--- + +#### property code_snippet + + + + + +--- + +#### property configs + + + + + +--- + +#### property enhanced_match_status + + + + + +--- + +#### property id + + + + + +--- + +#### property last_fired_time_ms + + + + + +--- + +#### property name + + + + + +--- + +#### property status + + + + + +--- + +#### property version + + + + + + + +--- + + + +### classmethod `create` + +```python +create( + ad_account_id: 'str', + name: 'str', + aem_enabled: 'bool' = None, + md_frequency: 'float' = None, + aem_fnln_enabled: 'bool' = None, + aem_ph_enabled: 'bool' = None, + aem_ge_enabled: 'bool' = None, + aem_db_enabled: 'bool' = None, + aem_loc_enabled: 'bool' = None, + client: 'PinterestSDKClient' = None, + **kwargs +) → ConversionTag +``` + +Create a conversion tag, also known as Pinterest tag with the option to enable enhance match.

+ +The Pinterest Tag tracks actions people take on the ad account’ s website after they view the ad account's ad on Pinterest. The advertiser needs to customize this tag to track conversions.

+ +For more information, see:

+ +Set up the Pinterest tag

+ +Pinterest Tag

+ +Enhanced match" + + + +**Args:** + + - `ad_account_id` (str): ConversionTag's Ad Account ID + - `name` (str): ConversionTag name + - `aem_enabled` (bool=False, Nullable): Whether Automatic Enhanced Match email is enabled. See Enhanced match for more information. + + + - `md_frequency` (float=1.0, Nullable): Metadata ingestion frequency. + - `aem_fnln_enabled` (bool=False, Nullable): Whether Automatic Enhanced Match name is enabled. See Enhanced match for more information. + + + - `aem_ph_enabled` (bool=False, Nullable): Whether Automatic Enhanced Match phone is enabled. See Enhanced match for more information. + + + - `aem_ge_enabled` (bool=False, Nullable): Whether Automatic Enhanced Match gender is enabled. See Enhanced match for more information. + + + - `aem_db_enabled` (bool=False, Nullable): Whether Automatic Enhanced Match birthdate is enabled. See Enhanced match for more information. + + + - `aem_loc_enabled` (bool=False, Nullable): Whether Automatic Enhanced Match location is enabled. See Enhanced match for more information. + + + +**Returns:** + + - `ConversionTag`: ConversionTag Object + +--- + + + +### classmethod `get_all` + +```python +get_all( + ad_account_id: 'str', + filter_deleted: 'bool' = False, + client: 'PinterestSDKClient' = None, + **kwargs +) → list[ConversionTag] +``` + +Get a list of ConversionTag, filter by specified arguments + + + +**Args:** + + - `ad_account_id` (str): Unique identifier of an ad account. + - `filter_deleted` (bool=False, optional): Filter out deleted tags. + - `client` (_type_, optional): PinterestSDKClient Object. Uses the default client, if not provided. + + + +**Returns:** + + - `list[ConversionTag]`: List of ConversionTags + +--- + + + +### classmethod `get_ocpm_eligible_conversion_tag_events` + +```python +get_ocpm_eligible_conversion_tag_events( + ad_account_id: 'str', + client: 'PinterestSDKClient' = None, + **kwargs +) → tuple[str, list[ConversionEventResponse]] +``` + +Get OCPM eligible conversion tag events for an Ad Account. + + + +**Args:** + + - `ad_account_id` (str): Ad Account ID + - `client` (PinterestSDKClient, optional): PinterestSDKClient Object. Uses the default client, if not provided. + + + +**Returns:** + + - `list[ConversionEventResponse]`: List of ConversionTagEvent + +--- + + + +### classmethod `get_page_visit_conversion_tag_events` + +```python +get_page_visit_conversion_tag_events( + ad_account_id: 'str', + page_size: 'int' = None, + order: 'str' = 'ASCENDING', + bookmark: 'str' = None, + client: 'PinterestSDKClient' = None, + **kwargs +) → tuple[list[ConversionEventResponse], Bookmark] +``` + +Get page visit conversion tag events for an ad account. + + + +**Args:** + + - `ad_account` (str): Ad Account ID + - `client` (PinterestSDKClient, optional): PinterestSDKClient Object. Uses the default client, if not provided. + + + +**Returns:** + + - `list[ConversionEventResponse]`: List of ConversionTagEvent + + diff --git a/docs/pinterest/organic.boards.md b/docs/pinterest/organic.boards.md index 296e088..4b1ba75 100644 --- a/docs/pinterest/organic.boards.md +++ b/docs/pinterest/organic.boards.md @@ -419,8 +419,7 @@ Keyword Args: Any valid keyword arguments or query parameters for endpoint. list_pins( section_id: 'str' = None, page_size: 'int' = None, - bookmark: 'str' = None, - **kwargs + bookmark: 'str' = None ) → tuple[list[Pin], Bookmark] ``` diff --git a/docs/pinterest/organic.pins.md b/docs/pinterest/organic.pins.md index addad14..c8b5df2 100644 --- a/docs/pinterest/organic.pins.md +++ b/docs/pinterest/organic.pins.md @@ -9,12 +9,12 @@ Pin Class for Pinterest Python SDK --- - + ## class `Pin` Pin model used to view, create, update its attributes and list its different entities. - + ### method `__init__` @@ -152,7 +152,7 @@ By default, the "operation user_account" is the token user_account. Optional: Bu --- - + ### classmethod `create` @@ -212,7 +212,7 @@ Keyword Args: Any valid keyword arguments or query parameters for endpoint. --- - + ### classmethod `delete` @@ -240,7 +240,7 @@ Delete a Pin owned by the "operation user_account". --- - + ### method `save` diff --git a/docs/pinterest/utils.base_model.md b/docs/pinterest/utils.base_model.md index 061594d..ba5fe1c 100644 --- a/docs/pinterest/utils.base_model.md +++ b/docs/pinterest/utils.base_model.md @@ -9,12 +9,12 @@ Pinterest Base Model --- - + ## class `PinterestBaseModel` Base Model for all other Higher Level Models in the Python Client - + ### method `__init__` diff --git a/docs/pinterest/utils.bookmark.md b/docs/pinterest/utils.bookmark.md index 67039cb..677ca0d 100644 --- a/docs/pinterest/utils.bookmark.md +++ b/docs/pinterest/utils.bookmark.md @@ -45,7 +45,7 @@ Initialize a Bookmark object. --- - + ### method `get_bookmark_token` diff --git a/docs/pinterest/utils.load_json_config.md b/docs/pinterest/utils.load_json_config.md index 7800ae2..6a6cb6a 100644 --- a/docs/pinterest/utils.load_json_config.md +++ b/docs/pinterest/utils.load_json_config.md @@ -19,3 +19,16 @@ load_json_config() Parse a config.json file and then load all the variables found as environment variables. +--- + + + +## function `load_json_config_from_single_env_var` + +```python +load_json_config_from_single_env_var() +``` + +Parse PINTEREST_JSON_ENV_VARIABLES environment variable to split long JSON string into individual environment variables. + + diff --git a/docs/pinterest/utils.sdk_exceptions.md b/docs/pinterest/utils.sdk_exceptions.md index f563d5c..1cea340 100644 --- a/docs/pinterest/utils.sdk_exceptions.md +++ b/docs/pinterest/utils.sdk_exceptions.md @@ -19,7 +19,7 @@ Raises an exception for Model's Errors ### method `__init__` ```python -__init__(status=None, reason=None, http_resp=None) +__init__(status=None, reason=None, http_resp=None, body=None) ``` diff --git a/docs/utils/README.md b/docs/utils/README.md index 4c57256..4a08596 100644 --- a/docs/utils/README.md +++ b/docs/utils/README.md @@ -11,4 +11,4 @@ python3 docs/utils/script.py ## Documentation guide -If you make change to this package, you have to regenerate doc, especially changes that add or remove module, you have to update `MODULES` and `IGNORED_FILES` under `script.py` \ No newline at end of file +When making change that add or remove module, you have to update `MODULES` and `IGNORED_FILES_INDEXING` accordingly and `IGNORE_MODULES` if needed. \ No newline at end of file diff --git a/docs/utils/python-sdk-doc.yaml b/docs/utils/python-sdk-doc.yaml index 485bb35..531d11c 100644 --- a/docs/utils/python-sdk-doc.yaml +++ b/docs/utils/python-sdk-doc.yaml @@ -9,7 +9,7 @@ info: url: https://spdx.org/licenses/MIT termsOfService: https://developers.pinterest.com/terms/ title: Pinterest Python SDK - version: 0.1.4 + version: 0.2.0 openapi: 3.0.3 paths: /test: @@ -45,9 +45,10 @@ tags: \ account. \n

  • client (PinterestSDKClient, optional):\ \ PinterestSDKClient Object. Defaults to default_api_client.
    • \n\ \n
    \n

    property country

    \n
    \n

    property\ - \ currency

    \n
    \n

    property id

    \n
    \n

    property\ - \ name

    \n
    \n

    property owner

    \n
    \n

    property\ - \ permissions

    \n
    \n

    \n

    \n

    property currency

    \n
    \n

    property\ + \ id

    \n
    \n

    property name

    \n
    \n

    property\ + \ owner

    \n
    \n

    property permissions

    \n
    \n

    property\ + \ updated_time

    \n
    \n

    \n

    classmethod create

    \n

    python\n\ create(\n name: 'str',\n owner_user_id: 'str',\n country: 'str',\n \ @@ -66,7 +67,7 @@ tags: \ (PinterestSDKClient): PinterestSDKClient Object \n\n

    Keyword Args:\ \ Any valid keyword arguments or query parameters for endpoint.

    \n

    Returns:

    \n\ \n
    \n\ -

    \n

    method list_audiences

    \n

    python\n\ list_audiences(\n entity_statuses: 'list[str]' = None,\n page_size: 'int'\ @@ -85,7 +86,7 @@ tags: \ Cursor used to fetch the next page of items. Defaults to None. \n\n\

    Returns:

    \n\n
    \n

    \n\n

    \n

    \n

    method list_campaigns

    \n

    python\n\ list_campaigns(\n campaign_ids: 'list[str]' = None,\n entity_statuses: 'list[str]'\ @@ -111,7 +112,7 @@ tags:

    Keyword Args: Any valid keyword arguments or query parameters for endpoint.\ \

    \n

    Returns:

    \n
      \n
    • list[Campaign]:\ \ List of Campaign Objects
      • \n
    • Bookmark: Bookmark\ - \ for pagination if present, else None.
      • \n
    \n
    \n

    \n\n

    \n

    \n

    method list_customer_lists

    \n

    python\n\ list_customer_lists(\n page_size: 'int' = None,\n order: 'str' = None,\n\ @@ -156,12 +157,13 @@ tags: \ dca_assets\n

    \n

    property end_time

    \n
    \n

    property\ \ feed_profile_id

    \n
    \n

    property id

    \n
    \n

    property\ \ lifetime_frequency_cap

    \n
    \n

    property name

    \n\n

    property pacing_delivery_type

    \n
    \n

    property\ - \ placement_group

    \n
    \n

    property start_time

    \n
    \n\ -

    property status

    \n
    \n

    property summary_status

    \n\ -
    \n

    property targeting_spec

    \n
    \n

    property\ - \ tracking_urls

    \n
    \n

    property type

    \n
    \n

    property\ - \ updated_time

    \n
    \n

    \n

    property optimization_goal_metadata

    \n
    \n

    property\ + \ pacing_delivery_type

    \n
    \n

    property placement_group

    \n\ +
    \n

    property start_time

    \n
    \n

    property\ + \ status

    \n
    \n

    property summary_status

    \n
    \n

    property\ + \ targeting_spec

    \n
    \n

    property tracking_urls

    \n\n

    property type

    \n
    \n

    property updated_time

    \n\ +
    \n

    \n

    classmethod create

    \n

    python\n\ create(\n ad_account_id: 'str',\n name: 'str',\n campaign_id: 'str',\n\ @@ -223,21 +225,21 @@ tags: \ target=\"_blank\">\"expanded targeting\". Defaults to None. \n

  • client\ \ (PinterestSDKClient, optional): PinterestSDKClient Object. Defaults to default_api_client.\ \
    • \n\n

    Returns:

    \n
      \n
    • AdGroup:\ - \ AdGroup Object
      • \n
    \n
    \n

    \n\n

    \n

    \n

    method disable_auto_targeting

    \n

    python\n\ disable_auto_targeting()

    \n

    Disable auto-targeting for ad group. Also\ \ known as \"\ expanded targeting\".

    \n

    Returns:

    \n
      \n
    • bool:\ \ true if ad group disable auto_targeting_enabled
      • \n
    \n
    \n

    \n

    method enable_auto_targeting

    \n

    python\n\ enable_auto_targeting()

    \n

    Enable auto-targeting for ad group. Also\ \ known as \"\ expanded targeting\".

    \n

    Returns:

    \n
      \n
    • bool:\ \ true if ad group enable auto_targeting_enabled
      • \n
    \n
    \n

    \n

    classmethod get_all

    \n

    python\n\ get_all(\n ad_account_id: 'str',\n campaign_ids: 'list[str]' = None,\n \ @@ -259,7 +261,7 @@ tags: \ (PinterestSDKClient, optional): description. Defaults to default_api_client.\ \ \n\n

    Returns:

    \n
      \n
    • tuple[list[AdGroup],\ \ Bookmark]: description
      • \n
    \n
    \n

    \n

    method list_ads

    \n

    python\n\ list_ads(\n ad_ids: 'list[str]' = None,\n entity_statuses: 'list[str]' =\ @@ -279,7 +281,7 @@ tags: \ Cursor used to fetch the next page of items. Defaults to None. \n\n\

    Returns:

    \n
      \n
    • list[Ad]: List\ \ of Ads
      • \n
    • Bookmark: Bookmark object
      • \n
    \n\ -
    \n

    \n

    \n

    method update_fields

    \n

    python\n\ update_fields(**kwargs) \u2192 bool

    \n

    Update adgroup fields using\ @@ -320,7 +322,7 @@ tags: \ summary_status\n

    \n

    property tracking_urls

    \n\n

    property type

    \n
    \n

    property updated_time

    \n\
    \n

    property view_tracking_url

    \n
    \n

    \n

    classmethod create

    \n

    python\n\ create(\n ad_account_id: 'str',\n ad_group_id: 'str',\n creative_type:\ @@ -372,7 +374,7 @@ tags: \ URL for ad impressions. Defaults to None. \n

  • client\ \ (PinterestSDKClient, optional): PinterestSDKClient Object. Defaults to default_api_client.\ \
    • \n\n

    Returns:

    \n
      \n
    • Ad:\ - \ The newly created Ad.
      • \n
    \n
    \n

    \n\n

    \n

    \n

    classmethod get_all

    \n

    python\n\ get_all(\n ad_account_id: 'str',\n campaign_ids: 'list[str]' = None,\n \ @@ -404,7 +406,7 @@ tags: \ \n

  • client (ApiClient): ApiClient Object
    • \n\ \n

    Returns:

    \n
      \n
    • list[Ad]:\ \ List of Ad Objects
      • \n
    • Bookmark: Bookmark for pagination\ - \ if present, else None.
      • \n
    \n
    \n

    \n\n

    \n

    \n

    method update_fields

    \n

    python\n\ update_fields(**kwargs) \u2192 bool

    \n

    Update Ad fields suing any\ @@ -543,21 +545,21 @@ tags: \ lifetime_spend_cap\n

    \n

    property name

    \n
    \n\

    property objective_type

    \n
    \n

    property order_line_id

    \n\
    \n

    property start_time

    \n
    \n

    property\ - \ status

    \n
    \n

    property tracking_urls

    \n
    \n

    property\ - \ type

    \n
    \n

    property updated_time

    \n
    \n

    \n

    \n

    property summary_status

    \n
    \n

    property\ + \ tracking_urls

    \n
    \n

    property type

    \n
    \n

    property\ + \ updated_time

    \n
    \n

    \n

    method activate

    \n

    python\n\ activate() \u2192 bool

    \n

    Activate a paused or archived campaign

    \n\

    Returns:

    \n
      \n
    • bool: If campaign\ \ status was successfully changed to 'ACTIVE'
      • \n
    \n
    \n

    \n

    method archive

    \n

    python\n\ archive() \u2192 bool

    \n

    Archive an active or paused campaign

    \n\

    Returns:

    \n
      \n
    • bool: If campaign\ \ status was successfully changed to 'ARCHIVED'
      • \n
    \n
    \n

    \n

    classmethod create

    \n

    python\n\ create(\n ad_account_id: 'str',\n name: 'str',\n objective_type: 'str',\n\ @@ -623,7 +625,7 @@ tags: \ optional): PinterestSDKClient Object, uses the default client, if not provided.\ \ \n\n

    Keyword Args: Any valid keyword arguments or query parameters\ \ for endpoint.

    \n

    Returns:

    \n
      \n
    • Campaign:\ - \ Campaign Object
      • \n
    \n
    \n

    \n\n

    \n

    \n

    classmethod get_all

    \n

    python\n\ get_all(\n ad_account_id: 'str',\n campaign_ids: 'list[str]' = None,\n \ @@ -648,17 +650,17 @@ tags: \ Object \n\n

    Keyword Args: Any valid keyword arguments or query parameters\ \ for endpoint.

    \n

    Returns:

    \n
      \n
    • list[Campaign]:\ \ List of Campaign Objects
      • \n
    • Bookmark: Bookmark\ - \ for pagination if present, else None.
      • \n
    \n
    \n

    \n\n

    \n

    \n

    method get_daily_budget

    \n

    python\n\ get_daily_budget() \u2192 float

    \n

    Get the current daily spend cap\ \ budget of the campaign.

    \n

    Returns:

    \n
      \n
    • float:\ - \ Current daily spend cap budget
      • \n
    \n
    \n

    \n\n

    \n

    \n

    method get_lifetime_budget

    \n

    python\n\ get_lifetime_budget() \u2192 float

    \n

    Get the current life time spend\ \ cap budget of the campaign.

    \n

    Returns:

    \n
      \n
    • float:\ - \ Current life time spend cap budget
      • \n
    \n
    \n

    \n\n

    \n

    \n

    method list_ad_groups

    \n

    python\n\ list_ad_groups(\n page_size: 'int' = 25,\n order: 'str' = 'ASCENDING',\n\ @@ -672,12 +674,12 @@ tags: \ description. Defaults to None. \n

  • entity_statuses\ \ (str, optional): description. Defaults to None.
    • \n\n

    Returns:

    \n\
      \n
    • tuple[list[AdGroup], Bookmark]: description\ - \
      • \n
    \n
    \n

    \n\n

    \n

    \n

    method pause

    \n

    python\npause()\ \ \u2192 bool

    \n

    Pause an active or archived campaign

    \n

    Returns:

    \n\
      \n
    • bool: If campaign status was successfully changed\ - \ to 'PAUSED'
      • \n
    \n
    \n

    \n\n

    \n

    \n

    method set_daily_budget

    \n

    python\n\ set_daily_budget(new_spend_cap: 'int') \u2192 bool

    \n

    Set new daily\ @@ -685,7 +687,7 @@ tags:

  • new_spend_cap (int): The new campaign daily spending\ \ cap.
    • \n\n

    Returns:

    \n
      \n
    • bool:\ \ If the daily budget was changed successfully
      • \n
    \n
    \n

    \n

    method set_lifetime_budget

    \n

    python\n\ set_lifetime_budget(new_spend_cap: 'int') \u2192 bool

    \n

    Set new life\ @@ -693,7 +695,7 @@ tags:

      \n
    • new_spend_cap (int): The new campaign total spending\ \ cap.
      • \n
    \n

    Returns:

    \n
      \n
    • bool:\ \ If the lifetime budget was changed successfully
      • \n
    \n
    \n

    \n

    method update_fields

    \n

    python\n\ update_fields(**kwargs) \u2192 bool

    \n

    Update the campaign fields\ @@ -702,6 +704,155 @@ tags: \ If campaign fields were successfully updated \n" name: campaigns x-traitTag: false +- description: "\n\n

    \n

    module ads.conversion_events

    \n

    Conversion\ + \ Event Class for Pinterest Python SDK

    \n
    \n

    \n

    class Conversion

    \n

    Conversion Event\ + \ Model used to send conversion events to Pinterest API

    \n
    \n

    \n

    classmethod create_conversion_event

    \n\ +

    python\ncreate_conversion_event(\n event_name: 'str',\n action_source:\ + \ 'str',\n event_time: 'int',\n event_id: 'str',\n user_data: 'dict',\n\ + \ custom_data: 'dict',\n event_source_url: 'str' = None,\n partner_name:\ + \ 'str' = None,\n app_id: 'str' = None,\n app_name: 'str' = None,\n app_version:\ + \ 'str' = None,\n device_brand: 'str' = None,\n device_carrier: 'str' =\ + \ None,\n device_model: 'str' = None,\n device_type: 'str' = None,\n \ + \ os_version: 'str' = None,\n language: 'str' = None,\n **kwargs\n) \u2192\ + \ ConversionEventsData

    \n

    Create Conversion Event Data to be sent.\ + \

    \n

    Args:

    \n
      \n
    • event_name\ + \ (str): The type of the user event, Enum: \"add_to_cart\", \"checkout\", \"\ + custom\", \"lead\", \"page_visit\", \"search\", \"signup\", \"view_category\"\ + , \"watch_video\"
      • \n
    • action_source (str): The source\ + \ indicating where the conversion event occurred, Enum: \"app_adroid\", \"app_ios\"\ + , \"web\", \"offline\"
      • \n
    • event_time (int): The time\ + \ when the event happened. Unix timestamp in seconds
      • \n
    • event_id\ + \ (str): The unique id string that identifies this event and can be used for\ + \ deduping between events ingested via both the conversion API and Pinterest\ + \ tracking
      • \n
    • user_data (dict): Object containing\ + \ customer information data. Note, it is required at least one of 1) em, 2) hashed_maids\ + \ or 3) pair client_ip_address + client_user_agent.
      • \n
    • custom_data\ + \ (dict): Object containing other custom data.
      • \n
    • event_source_url\ + \ (str, optional): URL of the web conversion event
      • \n
    • partner_name\ + \ (str, optional): The third party partner name responsible to send the event\ + \ to Conversion API on behalf of the adverstiser. Only send this field if Pinterest\ + \ has worked directly with you to define a value for partner_name.
      • \n
    • app_id\ + \ (str, optional): The app store app ID.
      • \n
    • app_name\ + \ (str, optional): Name of the app.
      • \n
    • app_version\ + \ (str, optional): Version of the app.
      • \n
    • device_brand\ + \ (str, optional): Brand of the user device.
      • \n
    • device_carrier\ + \ (str, optional): User device's model carrier.
      • \n
    • device_model\ + \ (str, optional): Model of the user device.
      • \n
    • device_type\ + \ (str, optional): Type of the user device.
      • \n
    • os_version\ + \ (str, optional): Version of the device operating system.
      • \n
    • language\ + \ (str, optional): Two-character ISO-639-1 language code indicating the user's\ + \ language.
      • \n
    \n

    Returns:

    \n
      \n
    • ConversionEventsData:\ + \ ConversionEventData to be sent
      • \n
    \n
    \n

    \n

    classmethod send_conversion_events

    \n\ +

    python\nsend_conversion_events(\n ad_account_id: 'str',\n conversion_events:\ + \ 'list[ConversionEventsData]',\n test: 'bool' = False,\n client: 'PinterestSDKClient'\ + \ = None,\n **kwargs\n) \u2192 tuple(int, int, list[ConversionApiResponseEvents])

    \n\ +

    Send conversion events to Pinterest API for Conversions.

    \n

    Note: Highly\ + \ recommend to use create_client_with_token (with Conversion Access Token) to\ + \ create different client for this functionality.

    " + name: conversion_events + x-traitTag: false +- description: "\n\n

    \n

    module ads.conversion_tags

    \n

    Conversion\ + \ Class for Pinterest Python SDK

    \n
    \n

    \n

    class ConversionTag

    \n

    Conversion\ + \ Tag model used to view, create, update its attributes and list its different\ + \ entities

    \n

    \n

    method __init__

    \n

    python\n\ + __init__(\n ad_account_id: 'str',\n conversion_tag_id: 'str',\n client:\ + \ 'PinterestSDKClient' = None,\n **kwargs\n) \u2192 None

    \n

    Initialize\ + \ Conversion Tag Object.

    \n

    Args:

    \n
      \n
    • ad_account_id\ + \ (str): ConversionTag's Ad Account ID
      • \n
    • conversion_tag_id\ + \ (str): ConversionTag ID, must be associated with Ad Account ID provided
      • \n\ +
    • client (PinterestSDKClient, optional): PinterestSDKClient\ + \ Object. Uses the default client, if not provided.
      • \n
    \n
    \n

    property\ + \ ad_account_id

    \n
    \n

    property code_snippet

    \n
    \n\ +

    property configs

    \n
    \n

    property enhanced_match_status

    \n\ +
    \n

    property id

    \n
    \n

    property last_fired_time_ms

    \n\ +
    \n

    property name

    \n
    \n

    property status

    \n\ +
    \n

    property version

    \n
    \n

    \n

    classmethod create

    \n

    python\n\ + create(\n ad_account_id: 'str',\n name: 'str',\n aem_enabled: 'bool'\ + \ = None,\n md_frequency: 'float' = None,\n aem_fnln_enabled: 'bool' = None,\n\ + \ aem_ph_enabled: 'bool' = None,\n aem_ge_enabled: 'bool' = None,\n aem_db_enabled:\ + \ 'bool' = None,\n aem_loc_enabled: 'bool' = None,\n client: 'PinterestSDKClient'\ + \ = None,\n **kwargs\n) \u2192 ConversionTag

    \n

    Create a conversion\ + \ tag, also known as Pinterest tag with the option to enable enhance match.

    \ + \

    \n

    The Pinterest Tag tracks actions people take on the ad account\u2019\ + \ s website after they view the ad account's ad on Pinterest. The advertiser\ + \ needs to customize this tag to track conversions.

    \n

    For more\ + \ information, see:

    \n

    Set up the Pinterest tag

    \n

    Pinterest Tag

    \n

    Enhanced\ + \ match\"

    \n

    Args:

    \n
      \n
    • ad_account_id\ + \ (str): ConversionTag's Ad Account ID
      • \n
    • name (str):\ + \ ConversionTag name
      • \n
    • \n

      aem_enabled (bool=False,\ + \ Nullable): Whether Automatic Enhanced Match email is enabled. See \ + \ Enhanced match for more information.

      \n
      • \n
    • \n

      md_frequency\ + \ (float=1.0, Nullable): Metadata ingestion frequency.

      \n
      • \n
    • \n

      aem_fnln_enabled\ + \ (bool=False, Nullable): Whether Automatic Enhanced Match name is enabled. See\ + \ Enhanced match for more information.

      \n
      • \n
    • \n

      aem_ph_enabled\ + \ (bool=False, Nullable): Whether Automatic Enhanced Match phone is enabled.\ + \ See Enhanced match for more information.

      \n
      • \n
    • \n

      aem_ge_enabled\ + \ (bool=False, Nullable): Whether Automatic Enhanced Match gender is enabled.\ + \ See Enhanced match for more information.

      \n
      • \n
    • \n

      aem_db_enabled\ + \ (bool=False, Nullable): Whether Automatic Enhanced Match birthdate is enabled.\ + \ See Enhanced match for more information.

      \n
      • \n
    • \n

      aem_loc_enabled\ + \ (bool=False, Nullable): Whether Automatic Enhanced Match location is enabled.\ + \ See Enhanced match for more information.

      \n
      • \n
    \n

    Returns:

    \n\ +
      \n
    • ConversionTag: ConversionTag Object
      • \n
    \n\ +
    \n

    \n

    classmethod get_all

    \n

    python\n\ + get_all(\n ad_account_id: 'str',\n filter_deleted: 'bool' = False,\n \ + \ client: 'PinterestSDKClient' = None,\n **kwargs\n) \u2192 list[ConversionTag]

    \n\ +

    Get a list of ConversionTag, filter by specified arguments

    \n

    Args:

    \n\ +
      \n
    • ad_account_id (str): Unique identifier of an ad\ + \ account.
      • \n
    • filter_deleted (bool=False, optional):\ + \ Filter out deleted tags.
      • \n
    • client (type,\ + \ optional): PinterestSDKClient Object. Uses the default client, if not provided.\ + \
      • \n
    \n

    Returns:

    \n
      \n
    • list[ConversionTag]:\ + \ List of ConversionTags
      • \n
    \n
    \n

    \n

    classmethod get_ocpm_eligible_conversion_tag_events

    \n\ +

    python\nget_ocpm_eligible_conversion_tag_events(\n ad_account_id:\ + \ 'str',\n client: 'PinterestSDKClient' = None,\n **kwargs\n) \u2192 tuple[str,\ + \ list[ConversionEventResponse]]

    \n

    Get OCPM eligible conversion tag\ + \ events for an Ad Account.

    \n

    Args:

    \n
      \n
    • ad_account_id\ + \ (str): Ad Account ID
      • \n
    • client (PinterestSDKClient,\ + \ optional): PinterestSDKClient Object. Uses the default client, if not provided.\ + \
      • \n
    \n

    Returns:

    \n
      \n
    • list[ConversionEventResponse]:\ + \ List of ConversionTagEvent
      • \n
    \n
    \n

    \n

    classmethod get_page_visit_conversion_tag_events

    \n\ +

    python\nget_page_visit_conversion_tag_events(\n ad_account_id: 'str',\n\ + \ page_size: 'int' = None,\n order: 'str' = 'ASCENDING',\n bookmark:\ + \ 'str' = None,\n client: 'PinterestSDKClient' = None,\n **kwargs\n) \u2192\ + \ tuple[list[ConversionEventResponse], Bookmark]

    \n

    Get page visit\ + \ conversion tag events for an ad account.

    \n

    Args:

    \n\ +
      \n
    • ad_account (str): Ad Account ID
      • \n
    • client\ + \ (PinterestSDKClient, optional): PinterestSDKClient Object. Uses the default\ + \ client, if not provided.
      • \n
    \n

    Returns:

    \n
      \n\ +
    • list[ConversionEventResponse]: List of ConversionTagEvent\ + \
      • \n
    " + name: conversion_tags + x-traitTag: false - description: "\n\n

    \n

    module ads.customer_lists

    \n

    High\ @@ -1050,19 +1201,19 @@ tags: >

    \n

    method list_pins

    \n

    python\n\ list_pins(\n section_id: 'str' = None,\n page_size: 'int' = None,\n bookmark:\ - \ 'str' = None,\n **kwargs\n) \u2192 tuple[list[Pin], Bookmark]

    \n\ -

    Get a list of the Pins on a board owned by the \"operation user_account\" -\ - \ or on a group board that has been shared with this account.

    \n
      \n
    • By\ - \ default, the \"operation user_account\" is the token user_account.
      • \n
    \n\ -

    Args:

    \n
      \n
    • section_id (str,\ - \ optional): Unique identifier of a board section. If not passed in, all pins\ - \ under the board will be listed.
      • \n
    • page_size (int[1..100],\ - \ optional): Maximum number of items to include in a single page of the response.\ - \ See documentation on Pagination for more information. Defaults to None which\ - \ will return default page size campaigns.
      • \n
    • bookmark\ - \ (str, optional): Cursor used to fetch the next page of items. Defaults to None.\ - \
      • \n
    \n

    Keyword Args: Any valid keyword arguments or query parameters\ - \ for endpoint.

    \n

    Returns:

    \n
      \n
    • list[Pin]:\ + \ 'str' = None\n) \u2192 tuple[list[Pin], Bookmark]

      \n

      Get a list\ + \ of the Pins on a board owned by the \"operation user_account\" - or on a group\ + \ board that has been shared with this account.

      \n
        \n
      • By default, the\ + \ \"operation user_account\" is the token user_account.
        • \n
      \n

      Args:

      \n\ +
        \n
      • section_id (str, optional): Unique identifier of\ + \ a board section. If not passed in, all pins under the board will be listed.\ + \
        • \n
      • page_size (int[1..100], optional): Maximum number\ + \ of items to include in a single page of the response. See documentation on\ + \ Pagination for more information. Defaults to None which will return default\ + \ page size campaigns.
        • \n
      • bookmark (str, optional):\ + \ Cursor used to fetch the next page of items. Defaults to None.
        • \n
      \n\ +

      Keyword Args: Any valid keyword arguments or query parameters for endpoint.\ + \

      \n

      Returns:

      \n
        \n
      • list[Pin]:\ \ List of Pin Objects
        • \n
      • Bookmark: Bookmark for\ \ pagination if present, else None.
        • \n
      \n
      \n

      \n\n

      \n

      module organic.pins

      \n

      Pin Class\ - \ for Pinterest Python SDK

      \n
      \n

      \n

      \n

      \n

      class Pin

      \n

      Pin model used to view,\ \ create, update its attributes and list its different entities.

      \n

      \n

      method __init__

      \n

      python\n\ __init__(\n pin_id: 'str',\n ad_account_id: 'str' = None,\n client: 'PinterestSDKClient'\ @@ -1144,7 +1295,7 @@ tags: \ dominant_color\n

      \n

      property id

      \n
      \n

      property\ \ link

      \n
      \n

      property media

      \n
      \n

      property\ \ media_source

      \n
      \n

      property parent_pin_id

      \n
      \n\ -

      property title

      \n
      \n

      property title\n

      \n

      \n

      classmethod create

      \n

      python\n\ create(\n board_id: 'str',\n media_source: 'dict',\n link: 'str' = None,\n\ @@ -1185,7 +1336,7 @@ tags: \ Object, uses the default client, if not provided.

      • \n
    \n

    Keyword Args:\ \ Any valid keyword arguments or query parameters for endpoint.

    \n

    Returns:

    \n\
      \n
    • Pin: Pin object
      • \n
    \n
    \n

    \n

    classmethod delete

    \n

    python\n\ delete(pin_id: 'str', client: 'PinterestSDKClient' = None) \u2192 bool

    \n\ @@ -1195,7 +1346,7 @@ tags:
  • client (PinterestSDKClient, optional): PinterestSDKClient\ \ Object. Uses the default client, if not provided.
    • \n\n

    Returns:

    \n\
      \n
    • bool: If the pin was deleted successfully.
      • \n\ -
    \n
    \n

    \n

    \n

    \n

    method save

    \n

    python\nsave(board_id:\ \ 'str', board_section_id: 'str' = None) \u2192 None

    \n

    Save a pin\ @@ -1211,11 +1362,11 @@ tags: - description: "\n\n

    \n

    module utils.base_model

    \n

    Pinterest\ - \ Base Model

    \n
    \n

    \n

    \n

    \n

    class PinterestBaseModel

    \n

    Base\ \ Model for all other Higher Level Models in the Python Client

    \n

    \n

    method __init__

    \n

    python\n\ __init__(\n _id: str,\n generated_api: object,\n generated_api_get_fn:\ @@ -1241,7 +1392,7 @@ tags: \ (str): The model's function which returns a bookmark. \n

  • model_fn_args\ \ (dict): Arguments passed to the function.
    • \n
  • client\ \ (PinterestSDKClient): Client used to make the SDK call.
    • \n\n
    \n\ -

    \n

    method get_bookmark_token

    \n

    python\n\ get_bookmark_token() \u2192 str

    \n

    Returns the bookmark pagination\ @@ -1292,7 +1443,21 @@ tags: load_json_config()

    Parse a config.json file and then load all the variables found as environment - variables.

    ' + variables.

    + +
    + +

    + +

    function load_json_config_from_single_env_var

    + +

    python + + load_json_config_from_single_env_var()

    + +

    Parse PINTEREST_JSON_ENV_VARIABLES environment variable to split long JSON + string into individual environment variables.

    ' name: load_json_config x-traitTag: false - description: "\n\n

    python - __init__(status=None, reason=None, http_resp=None)

    ' + __init__(status=None, reason=None, http_resp=None, body=None)

    ' name: sdk_exceptions x-traitTag: false x-tagGroups: @@ -1349,6 +1514,8 @@ x-tagGroups: - ads - audiences - campaigns + - conversion_events + - conversion_tags - customer_lists - keywords - name: pinterest.client diff --git a/docs/utils/script.py b/docs/utils/script.py index 04f1537..a34a63c 100644 --- a/docs/utils/script.py +++ b/docs/utils/script.py @@ -44,6 +44,7 @@ def remove_old_doc(): files = next(os.walk("docs/pinterest"), (None, None, []))[2] for file in files: os.remove(f"docs/pinterest/{file}") + def generate_new_doc(): """ Use lazydoc to generate new doc at: docs/pinterest @@ -113,6 +114,7 @@ def check_index(num_file: int, index: dict): if num_file != num_file_indexed: raise Exception("Cound't index all file, please double check") + def create_file_index() -> dict: """ Create file index: index[module_name] = list[file_name] @@ -160,6 +162,7 @@ def create_file_index() -> dict: return return_index + def truncate_md_extension(file: str) -> str: """Truncate .md file extension @@ -171,6 +174,7 @@ def truncate_md_extension(file: str) -> str: """ return file[:-3] + def append_doc_to_spec_file(index: dict): """ Accord to index file, append docs to spec skeleton spec and overwrite it to python-sdk-doc.yaml @@ -184,6 +188,10 @@ def append_doc_to_spec_file(index: dict): spec_path = PROJECT_PATH + '/docs/utils/skeleton-spec.yaml' spec = yaml.load(open(spec_path, 'r'), Loader=yaml.FullLoader) + # Update version + from pinterest.version import __version__ + spec['info']['version'] = __version__ + # Appending md doc into skeleton spec spec['tags'] = [] spec['x-tagGroups'] = []