digital-analytics-toolkit 0.1.0__py3-none-any.whl

digital_analytics_toolkit/gtm_functions.py

@@ -0,0 +1,468 @@
+from googleapiclient.discovery import build
+import pandas as pd
+
+def get_accounts(creds):
+    """
+    Retrieve all Google Tag Manager (GTM) accounts accessible to the
+    authenticated user.
+
+    Args:
+        creds: Google OAuth2 credentials used to authenticate with the
+            GTM API.
+
+    Returns:
+        list[dict]: A list of GTM account resources. Returns an empty list
+        if no accounts are found.
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+    response = service.accounts().list().execute()
+    return response.get("account", [])
+
+def get_containers(creds, account_id):
+    """
+    Retrieve all GTM containers accessible to the authenticated user.
+
+    Args:
+        creds: Google OAuth2 credentials used to authenticate with the
+            GTM API.
+        account_id (str): The GTM account ID.
+
+    Returns:
+        DataFrame: A DataFrame containing the GTM container resources.
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+    parent = f"accounts/{account_id}"
+    response = service.accounts().containers().list(parent=parent).execute()
+    containers = pd.DataFrame(response.get("container", []))
+    return containers.loc[:, ["path", "accountId", "containerId", "name", "publicId", "usageContext", "fingerprint", "tagManagerUrl"]]
+
+def get_container_type(creds, account_id, container_id):
+    """
+    Retrieve the type of a specific GTM container.
+
+    Args:
+        creds: Google OAuth2 credentials used to authenticate with the
+            GTM API.
+        account_id (str): The GTM account ID.
+        container_id (str): The GTM container ID.
+        
+    Returns:
+        str: The type of the container.
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+    parent = f"accounts/{account_id}/containers/{container_id}"
+    response = service.accounts().containers().get(path=parent).execute()
+    return response.get("usageContext")[0]
+
+def get_workspaces(creds, account_id, container_id):
+    """
+    Retrieve workspace information for a specific GTM container.
+
+    Args:
+        creds: Google OAuth2 credentials used to authenticate with the
+            GTM API.
+        account_id (str): The GTM account ID.
+        container_id (str): The GTM container ID.
+
+    Returns:
+        str | None: The workspace ID of the last workspace returned by the
+        API response. Returns ``None`` if no workspaces are found.
+
+    Note:
+        Although the API may return multiple workspaces, this function
+        currently returns only the last workspace ID from the response.
+
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+    parent = f"accounts/{account_id}/containers/{container_id}"
+    response = service.accounts().containers().workspaces().list(
+        parent=parent
+    ).execute()
+
+    for w in response.get("workspace", []):
+        workspace_id = w.get("workspaceId")
+
+    # Workspaces are returned under key "workspace"
+    return workspace_id
+
+def getLatestVersionHeader(creds, account_id, container_id):
+    """
+    Retrieve the latest GTM container version header.
+
+    Args:
+        creds: Google OAuth2 credentials.
+        account_id (str): GTM account ID.
+        container_id (str): GTM container ID.
+
+    Returns:
+        dict: Latest container version header.
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+
+    parent = f"accounts/{account_id}/containers/{container_id}"
+
+    response = (
+        service.accounts()
+        .containers()
+        .version_headers()
+        .latest(parent=parent)
+        .execute()
+    )
+
+    return response
+
+def get_tags(creds, account_id, container_id, workspace_id):
+    """
+    Retrieve all tags from a specific Google Tag Manager (GTM) workspace.
+
+    Args:
+        creds: Google OAuth2 credentials used to authenticate with the GTM API.
+        account_id (str): The GTM account ID.
+        container_id (str): The GTM container ID.
+        workspace_id (str): The GTM workspace ID.
+
+    Returns:
+        list[dict]: A list of GTM tag resources. Returns an empty list
+        if no tags are found in the workspace.
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+    parent = f"accounts/{account_id}/containers/{container_id}/workspaces/{workspace_id}"
+    response = service.accounts().containers().workspaces().tags().list(
+        parent=parent
+    ).execute()
+
+    # Tags are returned under key "tag"
+    return response.get("tag", [])
+
+def get_variables(creds, account_id, container_id, workspace_id):
+    """
+    Retrieve all variables from a specific Google Tag Manager (GTM) workspace.
+
+    Args:
+        creds: Google OAuth2 credentials used to authenticate with the
+            GTM API.
+        account_id (str): The GTM account ID.
+        container_id (str): The GTM container ID.
+        workspace_id (str): The GTM workspace ID.
+
+    Returns:
+        list[dict]: A list of GTM variable resources. Returns an empty list
+        if no variables are found in the workspace.
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+    parent = f"accounts/{account_id}/containers/{container_id}/workspaces/{workspace_id}"
+    response = service.accounts().containers().workspaces().variables().list(
+        parent=parent
+    ).execute()
+
+    # Variables are returned under key "variable"
+    return response.get("variable", [])
+
+def get_triggers(creds, account_id, container_id, workspace_id):
+    """
+    Retrieve all triggers from a specific Google Tag Manager (GTM) workspace.
+    Args:
+        creds: Google OAuth2 credentials used to authenticate with the
+            GTM API.
+        account_id (str): The GTM account ID.
+        container_id (str): The GTM container ID.
+        workspace_id (str): The GTM workspace ID.
+    Returns:
+        list[dict]: A list of GTM trigger resources. Returns an empty list
+        if no triggers are found in the workspace.
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+    parent = f"accounts/{account_id}/containers/{container_id}/workspaces/{workspace_id}"
+    response = service.accounts().containers().workspaces().triggers().list(
+        parent=parent
+    ).execute()
+
+    # Triggers are returned under key "trigger"
+    return response.get("trigger", [])
+
+
+from googleapiclient.discovery import build
+
+def get_built_in_variables(creds, account_id, container_id, workspace_id):
+    """
+    Retrieve all enabled built-in variables from a specific GTM workspace.
+
+    Args:
+        creds: Google OAuth2 credentials.
+        account_id (str): GTM account ID.
+        container_id (str): GTM container ID.
+        workspace_id (str): GTM workspace ID.
+
+    Returns:
+        list[dict]: A list of built-in variable resources.
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+
+    parent = (
+        f"accounts/{account_id}"
+        f"/containers/{container_id}"
+        f"/workspaces/{workspace_id}"
+    )
+
+    response = (
+        service.accounts()
+        .containers()
+        .workspaces()
+        .built_in_variables()
+        .list(parent=parent)
+        .execute()
+    )
+
+    return response.get("builtInVariable", [])
+
+
+from googleapiclient.discovery import build
+
+def get_custom_templates(creds, account_id, container_id, workspace_id):
+    """
+    Retrieve all custom templates from a specific GTM workspace.
+
+    Args:
+        creds: Google OAuth2 credentials.
+        account_id (str): GTM account ID.
+        container_id (str): GTM container ID.
+        workspace_id (str): GTM workspace ID.
+
+    Returns:
+        list[dict]: A list of custom template resources.
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+
+    parent = (
+        f"accounts/{account_id}"
+        f"/containers/{container_id}"
+        f"/workspaces/{workspace_id}"
+    )
+
+    response = (
+        service.accounts()
+        .containers()
+        .workspaces()
+        .templates()
+        .list(parent=parent)
+        .execute()
+    )
+
+    return response.get("template", [])
+
+def _as_id_list(ids):
+    """
+    Normalize a single ID or list of IDs into a list.
+    Args:
+        ids (str | list[str]): A single resource ID or list of IDs.
+    Returns:
+        list[str]: A list of resource IDs.
+    """
+    return [ids] if isinstance(ids, str) else list(ids)
+
+
+def delete_tags(creds, account_id, container_id, workspace_id, tag_ids):
+    """
+    Delete one or more tags from a GTM workspace.
+    Args:
+        creds: Google OAuth2 credentials.
+        account_id (str): GTM account ID.
+        container_id (str): GTM container ID.
+        workspace_id (str): GTM workspace ID.
+        tag_ids (str | list[str]): A single tag ID or list of tag IDs to delete.
+    Returns:
+        dict: {"deleted": [...], "failed": [{"id": ..., "error": ...}, ...]}
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+    parent = (
+        f"accounts/{account_id}"
+        f"/containers/{container_id}"
+        f"/workspaces/{workspace_id}"
+    )
+
+    results = {"deleted": [], "failed": []}
+    for tag_id in _as_id_list(tag_ids):
+        path = f"{parent}/tags/{tag_id}"
+        try:
+            service.accounts().containers().workspaces().tags().delete(
+                path=path
+            ).execute()
+            results["deleted"].append(tag_id)
+        except Exception as e:
+            results["failed"].append({"id": tag_id, "error": str(e)})
+
+    return results
+
+
+def delete_triggers(creds, account_id, container_id, workspace_id, trigger_ids):
+    """
+    Delete one or more triggers from a GTM workspace.
+    Args:
+        creds: Google OAuth2 credentials.
+        account_id (str): GTM account ID.
+        container_id (str): GTM container ID.
+        workspace_id (str): GTM workspace ID.
+        trigger_ids (str | list[str]): A single trigger ID or list of trigger IDs to delete.
+    Returns:
+        dict: {"deleted": [...], "failed": [{"id": ..., "error": ...}, ...]}
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+    parent = (
+        f"accounts/{account_id}"
+        f"/containers/{container_id}"
+        f"/workspaces/{workspace_id}"
+    )
+
+    results = {"deleted": [], "failed": []}
+    for trigger_id in _as_id_list(trigger_ids):
+        path = f"{parent}/triggers/{trigger_id}"
+        try:
+            service.accounts().containers().workspaces().triggers().delete(
+                path=path
+            ).execute()
+            results["deleted"].append(trigger_id)
+        except Exception as e:
+            results["failed"].append({"id": trigger_id, "error": str(e)})
+
+    return results
+
+def delete_templates(creds, account_id, container_id, workspace_id, template_ids):
+    """
+    Delete one or more templates from a GTM workspace.
+    Args:
+        creds: Google OAuth2 credentials.
+        account_id (str): GTM account ID.
+        container_id (str): GTM container ID.
+        workspace_id (str): GTM workspace ID.
+        template_ids (str | list[str]): A single template ID or list of template IDs to delete.
+    Returns:
+        dict: {"deleted": [...], "failed": [{"id": ..., "error": ...}, ...]}
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+    parent = (
+        f"accounts/{account_id}"
+        f"/containers/{container_id}"
+        f"/workspaces/{workspace_id}"
+    )
+
+    results = {"deleted": [], "failed": []}
+    for template_id in _as_id_list(template_ids):
+        path = f"{parent}/templates/{template_id}"
+        try:
+            service.accounts().containers().workspaces().templates().delete(
+                path=path
+            ).execute()
+            results["deleted"].append(template_id)
+        except Exception as e:
+            results["failed"].append({"id": template_id, "error": str(e)})
+
+    return results
+
+def create_version(creds, account_id, container_id, workspace_id, name=None, notes=None):
+    """
+    Create a container version from a GTM workspace (snapshot of pending changes).
+    Args:
+        creds: Google OAuth2 credentials.
+        account_id (str): GTM account ID.
+        container_id (str): GTM container ID.
+        workspace_id (str): GTM workspace ID.
+        name (str, optional): Name for the new version.
+        notes (str, optional): Notes describing the changes in this version.
+    Returns:
+        dict: The created ContainerVersion resource, e.g.
+              {"containerVersion": {...}, "compilerError": bool, "syncStatus": {...}}
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+    path = (
+        f"accounts/{account_id}"
+        f"/containers/{container_id}"
+        f"/workspaces/{workspace_id}"
+    )
+
+    body = {}
+    if name:
+        body["name"] = name
+    if notes:
+        body["notes"] = notes
+
+    response = (
+        service.accounts()
+        .containers()
+        .workspaces()
+        .create_version(path=path, body=body)
+        .execute()
+    )
+    return response
+
+
+def publish_version(creds, account_id, container_id, version_id, fingerprint=None):
+    """
+    Publish a specific GTM container version, making it live.
+    Args:
+        creds: Google OAuth2 credentials.
+        account_id (str): GTM account ID.
+        container_id (str): GTM container ID.
+        version_id (str): GTM container version ID to publish.
+        fingerprint (str, optional): Version fingerprint for optimistic concurrency
+                                      control (prevents accidental overwrite of a
+                                      version that changed since you fetched it).
+    Returns:
+        dict: The published ContainerVersion resource.
+    """
+    service = build("tagmanager", "v2", credentials=creds)
+    path = (
+        f"accounts/{account_id}"
+        f"/containers/{container_id}"
+        f"/versions/{version_id}"
+    )
+
+    request = service.accounts().containers().versions().publish(path=path)
+    if fingerprint:
+        request = service.accounts().containers().versions().publish(
+            path=path, fingerprint=fingerprint
+        )
+
+    response = request.execute()
+    return response
+
+
+def publish_workspace(creds, account_id, container_id, workspace_id, name=None, notes=None):
+    """
+    Create a version from a workspace and immediately publish it — a convenience
+    wrapper combining create_version + publish_version.
+    Args:
+        creds: Google OAuth2 credentials.
+        account_id (str): GTM account ID.
+        container_id (str): GTM container ID.
+        workspace_id (str): GTM workspace ID.
+        name (str, optional): Name for the new version.
+        notes (str, optional): Notes describing the changes in this version.
+    Returns:
+        dict: {"version": {...}, "compilerError": bool, "published": {...}}
+    Raises:
+        RuntimeError: If the created version has a compiler error, publish is
+                      skipped and the version response is returned for inspection.
+    """
+    version_response = create_version(
+        creds, account_id, container_id, workspace_id, name=name, notes=notes
+    )
+
+    if version_response.get("compilerError"):
+        raise RuntimeError(
+            "Version created but contains a compiler error — publish aborted. "
+            f"Inspect version details: {version_response}"
+        )
+
+    container_version = version_response["containerVersion"]
+    version_id = container_version["containerVersionId"]
+    fingerprint = container_version.get("fingerprint")
+
+    published = publish_version(
+        creds, account_id, container_id, version_id, fingerprint=fingerprint
+    )
+
+    return {
+        "version": container_version,
+        "compilerError": False,
+        "published": published,
+    }

digital_analytics_toolkit/utils.py

@@ -0,0 +1,94 @@
+# funnelreporting/utils.py
+
+# Common functions can be written here and called in other class functions to remove redundancy
+
+from google.oauth2 import service_account
+from google.analytics.data_v1beta import BetaAnalyticsDataClient, GetMetadataRequest, MetricType
+import pandas as pd
+from google.cloud import bigquery
+from typing import Optional
+
+def get_dimension_metric(service_account_file:str,property_id:str,file_name:str):
+    '''
+     Args:
+    ----------
+    service_account_file: str 
+        API service account JSON key file.
+    
+    property_id: str
+        Property ID of the Google Analytics Property from which report needs to be generated.
+    '''
+    credentials = service_account.Credentials.from_service_account_file(service_account_file)
+    client = BetaAnalyticsDataClient(credentials=credentials)
+    request = GetMetadataRequest(name=f"properties/{property_id}/metadata")
+    response = client.get_metadata(request)
+
+    output =[]
+    for dimension in response.dimensions:
+        output.append({"Type": "Dimension", "API_Name": f"{dimension.api_name}", "UI_Name": f"{dimension.ui_name}", "Description": f"{dimension.description}", "Custom_definition": f"{dimension.custom_definition}", "Metric_type": "N/A"})
+
+    for metric in response.metrics:
+        output.append({"Type": "Metric", "API_Name": f"{metric.api_name}", "UI_Name": f"{metric.ui_name}", "Description": f"{metric.description}", "Custom_definition": f"{metric.custom_definition}", "Metric_type": f"{MetricType(metric.type_).name}"})
+
+    df = pd.DataFrame(output)
+    df.to_csv(f"{file_name}.csv",index=False)
+
+def get_from_bigquery(project_id:str,dataset_id:str,table_id:str,service_account_file:Optional[str] = None, OAuth_creds:Optional[str] = None) -> pd.DataFrame:
+    '''
+     Args:
+    --------
+    project_id: str
+        Google Cloud Project ID where the BigQuery table is located.
+    
+    dataset_id: str
+        BigQuery dataset ID where the table is located.
+    
+    table_id: str
+        BigQuery table ID from where the data needs to be extracted.
+    service_account_file: str 
+        API service account JSON key file.
+    
+    --------
+    Returns:
+    pd.DataFrame
+    '''
+    if service_account_file != None:
+        credentials = service_account.Credentials.from_service_account_file(
+            service_account_file,
+            scopes=["https://www.googleapis.com/auth/cloud-platform"]
+        )
+    elif OAuth_creds != None:
+        credentials = OAuth_creds
+    client = bigquery.Client(credentials=credentials, project=project_id)
+    query = f"SELECT * FROM `{project_id}.{dataset_id}.{table_id}`"
+    query_job = client.query(query)
+    results = query_job.result().to_dataframe()
+    return results
+    
+def get_ga4_data_from_bq(project_id: str,query: str, service_account_file:Optional[str] = None, OAuth_creds:Optional[str] = None) -> pd.DataFrame:
+    '''
+    Args:
+    --------
+    project_id: str
+        Google Cloud Project ID where the BigQuery table is located.
+    query: str
+        SQL query to execute.
+    service_account: str
+        Path to service account json file
+    OAuth_creds:
+        OAuth creds
+    --------
+    Returns:
+    pd.DataFrame
+    '''
+    if service_account_file != None:
+        credentials = service_account.Credentials.from_service_account_file(
+            service_account_file,
+            scopes=["https://www.googleapis.com/auth/cloud-platform"]
+        )
+    elif OAuth_creds != None:
+        credentials = OAuth_creds
+    client = bigquery.Client(credentials=credentials, project=project_id)
+    query_job = client.query(query)
+    results = query_job.result().to_dataframe()
+    return results