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

digital_analytics_toolkit/ga4_audience.py

@@ -0,0 +1,576 @@
+"""
+ga4_audience.py
+================
+
+A friendly Python wrapper around the GA4 Admin API's
+``properties.audiences.create`` endpoint.
+
+Docs this wrapper is based on:
+- https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.audiences/create
+- https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.audiences  (Audience resource + all nested types)
+
+It uses Google's official client library (``google-analytics-admin``), which
+implements the same v1alpha ``Audience`` resource described in the REST docs,
+so you get retries / auth handling for free instead of hand-rolling HTTP calls.
+
+Install:
+    pip install google-analytics-admin google-auth
+
+--------------------------------------------------------------------------
+QUICK START
+--------------------------------------------------------------------------
+
+    from ga4_audience import GA4AudienceClient
+
+    client = GA4AudienceClient(credentials_path="service_account.json")
+
+    audience = client.create_audience(
+        property_id="123456789",
+        display_name="7-Day Purchasers",
+        description="Users who purchased in the last session, evaluated across all sessions.",
+        membership_duration_days=30,
+        include_conditions=[
+            {"type": "event", "event_name": "purchase"},
+        ],
+    )
+    print(audience.name)
+
+--------------------------------------------------------------------------
+CONDITION SPEC MINI-LANGUAGE
+--------------------------------------------------------------------------
+
+Conditions are expressed as plain Python dicts so callers don't need to know
+the underlying protobuf classes. Leaf condition types:
+
+    {"type": "string", "field_name": "deviceCategory", "match_type": "EXACT",
+     "value": "mobile", "case_sensitive": False}
+
+    {"type": "in_list", "field_name": "country",
+     "values": ["India", "United States"], "case_sensitive": False}
+
+    {"type": "numeric", "field_name": "sessionCount", "operation": "GREATER_THAN",
+     "value": 5}
+
+    {"type": "between", "field_name": "sessionCount", "from_value": 1, "to_value": 10}
+
+    {"type": "event", "event_name": "purchase",
+     "parameters": [{"type": "numeric", "field_name": "sessionCount", "operation": "GREATER_THAN",
+     "value": 5}}
+
+Any leaf dict may additionally include:
+    "at_any_point_in_time": bool   (only valid with scope=ACROSS_ALL_SESSIONS)
+    "in_any_n_day_period": int     (only valid with scope=ACROSS_ALL_SESSIONS, <=60)
+
+--------------------------------------------------------------------------
+HOW AND / OR NESTING ACTUALLY WORKS (GA4 API restriction)
+--------------------------------------------------------------------------
+
+The GA4 API's AudienceFilterExpression is NOT a freely-nestable AND/OR tree.
+The real rules (straight from the API docs) are:
+
+  - The top-level expression of a simple filter MUST be an and_group.
+  - That and_group's children MUST each be an or_group (never a bare leaf).
+  - An or_group's children MUST be leaves (a single condition or a "not") --
+    it can never contain a nested and_group or or_group.
+  - not_expression can only wrap a single leaf dimension/metric condition.
+  - Inside an event's "parameters", the rules are different again: it's a
+    single flat and_group of leaves only -- OR is not allowed there at all.
+
+This wrapper handles all of that bookkeeping for you automatically:
+
+    include_conditions=[
+        cond_A,                       # -> AND'ed automatically
+        {"or": [cond_B, cond_C]},     # -> AND'ed with the above, B/C OR'ed together
+        {"not": cond_D},              # -> AND'ed, D negated
+    ]
+
+Every item you put in ``include_conditions`` / ``exclude_conditions`` is
+AND'ed together automatically -- you do NOT need (and cannot use) an
+explicit {"and": [...]} wrapper; just add more list items instead. Each
+item can be a plain leaf condition, a {"not": cond} negation, or an
+{"or": [cond, cond, ...]} group of leaves (which cannot itself contain
+nested "and"/"or"). Event "parameters" lists follow the stricter flat-AND
+rule above (no "or" inside them).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from numbers import Number
+from typing import Any, Dict, List, Optional, Union
+
+from google.analytics.admin_v1alpha import (
+    Audience,
+    AudienceDimensionOrMetricFilter,
+    AudienceEventFilter,
+    AudienceEventTrigger,
+    AudienceFilterClause,
+    AudienceFilterExpression,
+    AudienceFilterExpressionList,
+    AudienceFilterScope,
+    AudienceSimpleFilter,
+    AnalyticsAdminServiceClient,
+    CreateAudienceRequest,
+)
+from google.oauth2 import service_account
+from google.oauth2.credentials import Credentials as UserCredentials
+
+_SCOPES = ["https://www.googleapis.com/auth/analytics.edit"]
+
+_SCOPE_MAP = {
+    "WITHIN_SAME_EVENT": AudienceFilterScope.AUDIENCE_FILTER_SCOPE_WITHIN_SAME_EVENT,
+    "WITHIN_SAME_SESSION": AudienceFilterScope.AUDIENCE_FILTER_SCOPE_WITHIN_SAME_SESSION,
+    "ACROSS_ALL_SESSIONS": AudienceFilterScope.AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS,
+}
+
+_LOG_CONDITION_MAP = {
+    "AUDIENCE_JOINED": AudienceEventTrigger.LogCondition.AUDIENCE_JOINED,
+    "AUDIENCE_MEMBERSHIP_RENEWED": AudienceEventTrigger.LogCondition.AUDIENCE_MEMBERSHIP_RENEWED,
+}
+
+_EXCLUSION_MODE_MAP = {
+    "EXCLUDE_TEMPORARILY": Audience.AudienceExclusionDurationMode.EXCLUDE_TEMPORARILY,
+    "EXCLUDE_PERMANENTLY": Audience.AudienceExclusionDurationMode.EXCLUDE_PERMANENTLY,
+}
+
+_MATCH_TYPE_MAP = {
+    "EXACT": AudienceDimensionOrMetricFilter.StringFilter.MatchType.EXACT,
+    "BEGINS_WITH": AudienceDimensionOrMetricFilter.StringFilter.MatchType.BEGINS_WITH,
+    "ENDS_WITH": AudienceDimensionOrMetricFilter.StringFilter.MatchType.ENDS_WITH,
+    "CONTAINS": AudienceDimensionOrMetricFilter.StringFilter.MatchType.CONTAINS,
+    "FULL_REGEXP": AudienceDimensionOrMetricFilter.StringFilter.MatchType.FULL_REGEXP,
+}
+
+_OPERATION_MAP = {
+    "EQUAL": AudienceDimensionOrMetricFilter.NumericFilter.Operation.EQUAL,
+    "LESS_THAN": AudienceDimensionOrMetricFilter.NumericFilter.Operation.LESS_THAN,
+    "GREATER_THAN": AudienceDimensionOrMetricFilter.NumericFilter.Operation.GREATER_THAN,
+}
+
+
+class GA4AudienceError(ValueError):
+    """Raised when a condition spec or argument is invalid."""
+
+
+# --------------------------------------------------------------------------
+# Auth / client construction
+# --------------------------------------------------------------------------
+
+def build_admin_client(
+    credentials_path: Optional[str] = None,
+    credentials_info: Optional[Dict[str, Any]] = None,
+    access_token: Optional[str] = None,
+) -> AnalyticsAdminServiceClient:
+    """Build an AnalyticsAdminServiceClient from one of three credential sources.
+
+    Exactly one of the following should be provided:
+      - credentials_path: path to a service-account JSON key file
+      - credentials_info: a dict already containing service-account JSON key data
+      - access_token: a short-lived OAuth2 access token (e.g. from a user's
+        existing OAuth flow) with the analytics.edit scope
+
+    Returns
+    -------
+    AnalyticsAdminServiceClient
+    """
+    provided = [credentials_path, credentials_info, access_token]
+    if sum(p is not None for p in provided) != 1:
+        raise GA4AudienceError(
+            "Provide exactly one of credentials_path, credentials_info, or access_token."
+        )
+
+    if credentials_path is not None:
+        creds = service_account.Credentials.from_service_account_file(
+            credentials_path, scopes=_SCOPES
+        )
+    elif credentials_info is not None:
+        creds = service_account.Credentials.from_service_account_info(
+            credentials_info, scopes=_SCOPES
+        )
+    else:
+        creds = UserCredentials(token=access_token, scopes=_SCOPES)
+
+    return AnalyticsAdminServiceClient(credentials=creds)
+
+
+# --------------------------------------------------------------------------
+# Condition-spec -> protobuf translation
+# --------------------------------------------------------------------------
+
+def _numeric_value(value: Union[int, float]):
+    if isinstance(value, bool):
+        raise GA4AudienceError("Numeric filter value cannot be a bool.")
+    if isinstance(value, int):
+        return AudienceDimensionOrMetricFilter.NumericValue(int64_value=value)
+    if isinstance(value, Number):
+        return AudienceDimensionOrMetricFilter.NumericValue(double_value=float(value))
+    raise GA4AudienceError(f"Numeric filter value must be a number, got {value!r}.")
+
+
+def _build_dimension_or_metric_filter(spec: Dict[str, Any]) -> AudienceDimensionOrMetricFilter:
+    field_name = spec.get("field_name")
+    if not field_name:
+        raise GA4AudienceError(f"Condition missing 'field_name': {spec}")
+
+    kwargs: Dict[str, Any] = {"field_name": field_name}
+    if "at_any_point_in_time" in spec:
+        kwargs["at_any_point_in_time"] = spec["at_any_point_in_time"]
+    if "in_any_n_day_period" in spec:
+        n = spec["in_any_n_day_period"]
+        if n > 60:
+            raise GA4AudienceError("'in_any_n_day_period' cannot exceed 60 days.")
+        kwargs["in_any_n_day_period"] = n
+
+    cond_type = spec["type"]
+
+    if cond_type == "string":
+        match_type = spec.get("match_type", "EXACT").upper()
+        if match_type not in _MATCH_TYPE_MAP:
+            raise GA4AudienceError(f"Unknown match_type '{match_type}'.")
+        kwargs["string_filter"] = AudienceDimensionOrMetricFilter.StringFilter(
+            match_type=_MATCH_TYPE_MAP[match_type],
+            value=spec["value"],
+            case_sensitive=spec.get("case_sensitive", False),
+        )
+
+    elif cond_type == "in_list":
+        values = spec.get("values")
+        if not values:
+            raise GA4AudienceError("'in_list' condition requires a non-empty 'values' list.")
+        kwargs["in_list_filter"] = AudienceDimensionOrMetricFilter.InListFilter(
+            values=values,
+            case_sensitive=spec.get("case_sensitive", False),
+        )
+
+    elif cond_type == "numeric":
+        operation = spec.get("operation", "EQUAL").upper()
+        if operation not in _OPERATION_MAP:
+            raise GA4AudienceError(f"Unknown operation '{operation}'.")
+        kwargs["numeric_filter"] = AudienceDimensionOrMetricFilter.NumericFilter(
+            operation=_OPERATION_MAP[operation],
+            value=_numeric_value(spec["value"]),
+        )
+
+    elif cond_type == "between":
+        kwargs["between_filter"] = AudienceDimensionOrMetricFilter.BetweenFilter(
+            from_value=_numeric_value(spec["from_value"]),
+            to_value=_numeric_value(spec["to_value"]),
+        )
+
+    else:
+        raise GA4AudienceError(
+            f"Unknown leaf condition type '{cond_type}'. Expected one of: "
+            "string, in_list, numeric, between, event, and, or, not."
+        )
+
+    return AudienceDimensionOrMetricFilter(**kwargs)
+
+
+def _build_leaf_expression(spec: Dict[str, Any], allow_event: bool) -> AudienceFilterExpression:
+    """Build a single leaf AudienceFilterExpression: dimension_or_metric_filter,
+    event_filter, or not_expression(dimension_or_metric_filter).
+
+    A "leaf" is anything that's legal *inside* an or_group (or inside an
+    event's parameter and_group, when allow_event=False). It can never be an
+    'and' or 'or' group itself -- those are only legal one level up.
+    """
+    if not isinstance(spec, dict):
+        raise GA4AudienceError(f"Condition must be a dict, got {spec!r}.")
+
+    if "and" in spec or "or" in spec:
+        raise GA4AudienceError(
+            "'and'/'or' cannot appear here -- this position only accepts a single "
+            "leaf condition (string/in_list/numeric/between/event) or a 'not' wrapper."
+        )
+
+    if "not" in spec:
+        inner = spec["not"]
+        if "and" in inner or "or" in inner or "not" in inner or inner.get("type") == "event":
+            raise GA4AudienceError(
+                "A 'not' expression can only wrap a single leaf dimension/metric condition "
+                "(not another 'and'/'or'/'not'/event)."
+            )
+        return AudienceFilterExpression(
+            not_expression=AudienceFilterExpression(
+                dimension_or_metric_filter=_build_dimension_or_metric_filter(inner)
+            )
+        )
+
+    cond_type = spec.get("type")
+    if cond_type == "event":
+        if not allow_event:
+            raise GA4AudienceError(
+                "Nested event filters are not supported inside event parameters."
+            )
+        return AudienceFilterExpression(event_filter=_build_event_filter(spec))
+
+    return AudienceFilterExpression(dimension_or_metric_filter=_build_dimension_or_metric_filter(spec))
+
+
+def _build_event_filter(spec: Dict[str, Any]) -> AudienceEventFilter:
+    event_name = spec.get("event_name")
+    if not event_name:
+        raise GA4AudienceError(f"'event' condition missing 'event_name': {spec}")
+
+    kwargs: Dict[str, Any] = {"event_name": event_name}
+
+    params = spec.get("parameters")
+    if params:
+        # Per the API docs: event_parameter_filter_expression must be a single
+        # and_group whose children are dimension_or_metric_filter / not_expression
+        # ONLY -- no or_group, no event_filter (ANDs of ORs are not supported here).
+        for p in params:
+            if "or" in p:
+                raise GA4AudienceError(
+                    "Event parameter filters must be a flat AND of conditions -- 'or' "
+                    "is not supported inside event parameters (GA4 API restriction)."
+                )
+        kwargs["event_parameter_filter_expression"] = AudienceFilterExpression(
+            and_group=AudienceFilterExpressionList(
+                filter_expressions=[_build_leaf_expression(p, allow_event=False) for p in params]
+            )
+        )
+
+    return AudienceEventFilter(**kwargs)
+
+
+def _build_top_level_and_child(spec: Dict[str, Any]) -> AudienceFilterExpression:
+    """Build one child of the top-level and_group.
+
+    Per the API, the top-level and_group may ONLY contain or_group children.
+    So every item the caller puts in include_conditions/exclude_conditions
+    becomes its own or_group -- a singleton [leaf] for a plain condition, or
+    the actual OR'd list for an {"or": [...]} spec.
+    """
+    if not isinstance(spec, dict):
+        raise GA4AudienceError(f"Condition must be a dict, got {spec!r}.")
+
+    if "and" in spec:
+        raise GA4AudienceError(
+            "'and' is not a valid combinator here: items in include_conditions / "
+            "exclude_conditions are already AND'ed together automatically -- just "
+            "add them as separate list entries instead of wrapping in {'and': [...]}."
+        )
+
+    if "or" in spec:
+        children = spec["or"]
+        if not children:
+            raise GA4AudienceError("'or' condition requires a non-empty list.")
+        for c in children:
+            if "and" in c or "or" in c:
+                raise GA4AudienceError(
+                    "An 'or' group cannot itself contain nested 'and'/'or' groups "
+                    "(GA4 API restriction)."
+                )
+        leaf_exprs = [_build_leaf_expression(c, allow_event=True) for c in children]
+    else:
+        # A plain leaf or a 'not' -- wrap as a singleton or_group, since the
+        # top-level and_group can only directly contain or_group children.
+        leaf_exprs = [_build_leaf_expression(spec, allow_event=True)]
+
+    return AudienceFilterExpression(
+        or_group=AudienceFilterExpressionList(filter_expressions=leaf_exprs)
+    )
+
+
+def _build_filter_clause(
+    conditions: List[Dict[str, Any]],
+    clause_type: str,
+    scope: str,
+) -> AudienceFilterClause:
+    if scope not in _SCOPE_MAP:
+        raise GA4AudienceError(f"scope must be one of {list(_SCOPE_MAP)}, got '{scope}'.")
+    if clause_type not in ("INCLUDE", "EXCLUDE"):
+        raise GA4AudienceError("clause_type must be 'INCLUDE' or 'EXCLUDE'.")
+    if not conditions:
+        raise GA4AudienceError("conditions list cannot be empty.")
+
+    # Top level of a simple filter's expression must be an and_group, and per
+    # the API, and_group may only contain or_group children (never bare leaves).
+    top_expression = AudienceFilterExpression(
+        and_group=AudienceFilterExpressionList(
+            filter_expressions=[_build_top_level_and_child(c) for c in conditions]
+        )
+    )
+
+    return AudienceFilterClause(
+        clause_type=(
+            AudienceFilterClause.AudienceClauseType.INCLUDE
+            if clause_type == "INCLUDE"
+            else AudienceFilterClause.AudienceClauseType.EXCLUDE
+        ),
+        simple_filter=AudienceSimpleFilter(
+            scope=_SCOPE_MAP[scope],
+            filter_expression=top_expression,
+        ),
+    )
+
+
+# --------------------------------------------------------------------------
+# High level client
+# --------------------------------------------------------------------------
+
+@dataclass
+class GA4AudienceClient:
+    """Convenience wrapper for creating GA4 Audiences.
+
+    Provide credentials via ONE of `credentials_path`, `credentials_info`,
+    `access_token`, or pass a pre-built `admin_client`.
+    Note: Currently And Group & Or Group are not working
+    """
+
+    credentials_path: Optional[str] = None
+    credentials_info: Optional[Dict[str, Any]] = None
+    access_token: Optional[str] = None
+    admin_client: Optional[AnalyticsAdminServiceClient] = None
+
+    def __post_init__(self):
+        if self.admin_client is None:
+            self.admin_client = build_admin_client(
+                credentials_path=self.credentials_path,
+                credentials_info=self.credentials_info,
+                access_token=self.access_token,
+            )
+
+    def create_audience(
+        self,
+        property_id: Union[str, int],
+        display_name: str,
+        description: str,
+        membership_duration_days: int = 30,
+        include_conditions: Optional[List[Dict[str, Any]]] = None,
+        exclude_conditions: Optional[List[Dict[str, Any]]] = None,
+        scope: str = "ACROSS_ALL_SESSIONS",
+        exclusion_duration_mode: Optional[str] = None,
+        event_trigger: Optional[Dict[str, str]] = None,
+        dry_run: bool = False,
+    ) -> Audience:
+        """Create a GA4 Audience.
+
+        Parameters
+        ----------
+        property_id : the numeric GA4 property id (e.g. "123456789" or 123456789)
+        display_name : required, shown in the GA4 UI
+        description : required
+        membership_duration_days : how long a user stays in the audience (max 540)
+        include_conditions : list of condition-spec dicts (see module docstring),
+            ANDed together into one INCLUDE filter clause. At least one of
+            include_conditions/exclude_conditions is required.
+        exclude_conditions : same shape, becomes an EXCLUDE filter clause
+        scope : one of "WITHIN_SAME_EVENT", "WITHIN_SAME_SESSION",
+            "ACROSS_ALL_SESSIONS" (default). Applies to include AND exclude clauses.
+            Use WITHIN_SAME_EVENT/SESSION scope if your conditions must all be true
+            in a single event/session.
+        exclusion_duration_mode : "EXCLUDE_TEMPORARILY" or "EXCLUDE_PERMANENTLY",
+            required by the API if exclude_conditions is set.
+        event_trigger : optional dict {"event_name": str, "log_condition":
+            "AUDIENCE_JOINED" | "AUDIENCE_MEMBERSHIP_RENEWED"} to log an event
+            when a user joins.
+        dry_run : if True, builds and returns the Audience request payload
+            without calling the API (useful for testing/inspection).
+
+        Returns
+        -------
+        google.analytics.admin_v1alpha.types.Audience
+            The created Audience (with `.name` populated), or -- if dry_run --
+            the Audience object that *would* be sent.
+        """
+        if not display_name:
+            raise GA4AudienceError("display_name is required.")
+        if not description:
+            raise GA4AudienceError("description is required.")
+        if not (1 <= membership_duration_days <= 540):
+            raise GA4AudienceError("membership_duration_days must be between 1 and 540.")
+        if not include_conditions and not exclude_conditions:
+            raise GA4AudienceError("Provide at least one of include_conditions / exclude_conditions.")
+        if exclude_conditions and not exclusion_duration_mode:
+            raise GA4AudienceError(
+                "exclusion_duration_mode is required when exclude_conditions is set "
+                "('EXCLUDE_TEMPORARILY' or 'EXCLUDE_PERMANENTLY')."
+            )
+
+        filter_clauses = []
+        if include_conditions:
+            filter_clauses.append(_build_filter_clause(include_conditions, "INCLUDE", scope))
+        if exclude_conditions:
+            filter_clauses.append(_build_filter_clause(exclude_conditions, "EXCLUDE", scope))
+
+        audience_kwargs: Dict[str, Any] = {
+            "display_name": display_name,
+            "description": description,
+            "membership_duration_days": membership_duration_days,
+            "filter_clauses": filter_clauses,
+        }
+
+        if exclusion_duration_mode:
+            if exclusion_duration_mode not in _EXCLUSION_MODE_MAP:
+                raise GA4AudienceError(
+                    f"exclusion_duration_mode must be one of {list(_EXCLUSION_MODE_MAP)}."
+                )
+            audience_kwargs["exclusion_duration_mode"] = _EXCLUSION_MODE_MAP[exclusion_duration_mode]
+
+        if event_trigger:
+            event_name = event_trigger.get("event_name")
+            log_condition = event_trigger.get("log_condition", "AUDIENCE_JOINED").upper()
+            if not event_name:
+                raise GA4AudienceError("event_trigger requires 'event_name'.")
+            if log_condition not in _LOG_CONDITION_MAP:
+                raise GA4AudienceError(f"log_condition must be one of {list(_LOG_CONDITION_MAP)}.")
+            audience_kwargs["event_trigger"] = AudienceEventTrigger(
+                event_name=event_name,
+                log_condition=_LOG_CONDITION_MAP[log_condition],
+            )
+
+        audience = Audience(**audience_kwargs)
+
+        parent = f"properties/{property_id}" if not str(property_id).startswith("properties/") else str(property_id)
+        request = CreateAudienceRequest(parent=parent, audience=audience)
+
+        if dry_run:
+            return audience
+
+        return self.admin_client.create_audience(request=request)
+
+
+# --------------------------------------------------------------------------
+# One-off convenience functions (no class instantiation needed)
+# --------------------------------------------------------------------------
+
+def create_audience(
+    property_id: Union[str, int],
+    display_name: str,
+    description: str,
+    membership_duration_days: int = 30,
+    include_conditions: Optional[List[Dict[str, Any]]] = None,
+    exclude_conditions: Optional[List[Dict[str, Any]]] = None,
+    scope: str = "ACROSS_ALL_SESSIONS",
+    exclusion_duration_mode: Optional[str] = None,
+    event_trigger: Optional[Dict[str, str]] = None,
+    credentials_path: Optional[str] = None,
+    credentials_info: Optional[Dict[str, Any]] = None,
+    access_token: Optional[str] = None,
+    dry_run: bool = False,
+) -> Audience:
+    """Functional one-shot version of GA4AudienceClient.create_audience.
+
+    Builds a client from the given credentials and creates the audience in
+    a single call. See GA4AudienceClient.create_audience for parameter docs.
+    """
+    client = GA4AudienceClient(
+        credentials_path=credentials_path,
+        credentials_info=credentials_info,
+        access_token=access_token,
+    )
+    return client.create_audience(
+        property_id=property_id,
+        display_name=display_name,
+        description=description,
+        membership_duration_days=membership_duration_days,
+        include_conditions=include_conditions,
+        exclude_conditions=exclude_conditions,
+        scope=scope,
+        exclusion_duration_mode=exclusion_duration_mode,
+        event_trigger=event_trigger,
+        dry_run=dry_run,
+    )