digital-analytics-toolkit 0.1.0__tar.gz

digital_analytics_toolkit-0.1.0/LICENSE

@@ -0,0 +1,55 @@
+Copyright (c) 2026 Isha Panchal and Kris Dsouza
+
+PROPRIETARY SOFTWARE LICENSE
+
+1. Ownership
+
+This software, including its source code, documentation, and associated
+materials, is proprietary software. All copyrights and other intellectual
+property rights in the software are retained by the copyright holders.
+
+2. Permission to Use
+
+Permission is granted to any individual or organization to install and use
+this software free of charge for personal, educational, research, or
+commercial purposes.
+
+3. Restrictions
+
+Except as expressly permitted by this license, you may not:
+
+- modify, alter, or create derivative works of the software;
+- copy or reproduce the software for redistribution;
+- redistribute, republish, sublicense, or sell the software;
+- package or incorporate the software into another publicly distributed
+  software package;
+- publish modified or unmodified copies of the software;
+- claim ownership of the software or its source code.
+
+4. Source Code
+
+The source code is proprietary and is not licensed for public access,
+modification, or redistribution. The availability of a package through
+PyPI does not grant any rights to access, modify, or redistribute the
+source code beyond the rights explicitly granted by this license.
+
+5. Contributions and Modifications
+
+Only individuals expressly authorized by the copyright holders may modify
+the original source code or contribute modifications to the project.
+
+6. No Warranty
+
+The software is provided "AS IS", without warranty of any kind, express or
+implied. The copyright holders shall not be liable for any claim, damages,
+or other liability arising from the use of the software.
+
+7. Termination
+
+Any rights granted under this license terminate automatically if you
+violate the terms of this license.
+
+8. Copyright
+
+Copyright (c) 2026 Isha Panchal and Kris Dsouza.
+All rights reserved.

digital_analytics_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: digital-analytics-toolkit
+Version: 0.1.0
+Summary: Toolkit for Google Analytics, Google Tag Manager, and BigQuery workflows
+Author: Isha Panchal, Kris Dsouza
+Maintainer-email: Isha Panchal <hacker.knight177@gmail.com>, Kris Dsouza <kris.dsouza64@gmail.com>
+License-Expression: LicenseRef-Proprietary
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: google-auth
+Requires-Dist: google-analytics-data
+Requires-Dist: google-analytics-admin
+Requires-Dist: google-api-python-client
+Requires-Dist: gspread
+Requires-Dist: google-cloud-bigquery
+Requires-Dist: db-dtypes
+Dynamic: license-file
+
+# 🚀 Digital Analytics Toolkit
+
+### A Python toolkit for Google Analytics 4, Google Tag Manager, and BigQuery workflows
+
+**Digital Analytics Toolkit** is a Python library designed to streamline GA4 reporting, GA4 administration, audience management, GTM container inspection, and BigQuery querying through reusable Python functions and clients.
+
+---
+
+## 📦 Installation
+
+Install the latest release from PyPI:
+
+```bash
+pip install digital-analytics-toolkit
+```
+
+For future upgrade:
+
+```bash
+pip install --upgrade digital-analytics-toolkit
+```
+
+---
+
+## 🔐 Authentication
+
+Digital Analytics Toolkit supports **Service Account Key JSON files** and **Google OAuth2 Credentials**.
+
+1. Create a Service Account in the [Google Cloud Console](https://console.cloud.google.com/).
+2. Enable necessary APIs:
+   - Google Analytics Data API
+   - Google Analytics Admin API
+   - Google Tag Manager API
+   - BigQuery API
+3. Download the JSON key file and share your GA4 property / GTM account access with the service account email.
+
+---
+
+## 🧩 Features & Module Usage
+
+The toolkit is organized into 4 primary functional areas:
+
+1. [GA4 Free-Form & Funnel Reporting](#1-ga4-reporting)
+2. [GA4 Admin & Audience Management](#2-ga4-admin--audiences)
+3. [Google Tag Manager (GTM) Operations](#3-google-tag-manager-gtm)
+4. [BigQuery Integration](#4-bigquery-integration)
+
+---
+
+### 1. GA4 Reporting
+
+#### 📊 Free-Form Reports (`free_form_report_GA4`)
+Run custom GA4 reports specifying metrics, dimensions, date ranges, and optional dimension/metric filters.
+
+```python
+from digital_analytics_toolkit import free_form_report_GA4, dimension_filter_generation
+
+# Initialize client
+report_client = free_form_report_GA4(
+    service_account_file="path/to/service_account.json",
+    property_id="123456789"
+)
+
+# Optional: Generate dimension filter
+dim_filter = dimension_filter_generation(
+    operator="CONTAINS",
+    value="Organic",
+    dimension_name="sessionDefaultChannelGroup"
+)
+
+# Generate report
+df = report_client.free_form_report(
+    start_date="30daysAgo",
+    end_date="today",
+    metrics=["activeUsers", "eventCount", "conversions"],
+    dimensions=["date", "sessionDefaultChannelGroup"],
+    dimension_filter=dim_filter
+)
+
+print(df.head())
+```
+
+#### 🏆 Multi-Step Funnel Reports (`Funnel_Reports`)
+Generate multi-step funnel analysis with support for breakdown dimensions based on funnel step definitions configured in Google Sheets.
+
+```python
+from digital_analytics_toolkit import Funnel_Reports
+
+funnel = Funnel_Reports(
+    reporting_client="path/to/service_account.json",
+    prop_id="123456789"
+)
+
+# Run funnel report using steps defined in a Google Sheet
+response = funnel.funnel_report(
+    startDate="2024-01-01",
+    endDate="2024-01-31",
+    file_n="My_Funnel_Steps_Sheet_Name",
+    breakdown="deviceCategory",
+    breakdown_limit="5"
+)
+```
+
+#### 📜 Dimension & Metric Metadata (`get_dimension_metric`)
+Fetch all available custom & standard dimensions/metrics for a GA4 property and export to CSV.
+
+```python
+from digital_analytics_toolkit import utils
+
+utils.get_dimension_metric(
+    service_account_file="path/to/service_account.json",
+    property_id="123456789",
+    file_name="ga4_dimensions_metrics"
+)
+```
+
+---
+
+### 2. GA4 Admin & Audiences
+
+#### 🏢 Accounts & Property Discovery
+Discover accounts, properties, key events (conversions), and BigQuery links.
+
+```python
+from google.oauth2 import service_account
+from digital_analytics_toolkit import (
+    get_ga4_accounts_list,
+    get_ga4_properties_list,
+    get_ga4_property_keyEvents,
+    get_ga4_property_bq_link
+)
+
+creds = service_account.Credentials.from_service_account_file(
+    "path/to/service_account.json",
+    scopes=["https://www.googleapis.com/auth/analytics.readonly"]
+)
+
+# List accounts & properties
+accounts_df = get_ga4_accounts_list(creds)
+properties_df = get_ga4_properties_list(creds, account_id="12345678")
+
+# Key events & BigQuery export status
+key_events_df = get_ga4_property_keyEvents(creds, property_id="123456789")
+bq_links_df = get_ga4_property_bq_link(creds, property_id="123456789")
+```
+
+#### 🎯 Audience Creation (`GA4AudienceClient`)
+Programmatically construct and create GA4 audiences using a simplified dictionary condition language.
+
+```python
+from digital_analytics_toolkit import GA4AudienceClient
+
+client = GA4AudienceClient(credentials_path="path/to/service_account.json")
+
+audience = client.create_audience(
+    property_id="123456789",
+    display_name="High Intent Purchasers",
+    description="Users with > 3 sessions who completed a purchase",
+    membership_duration_days=30,
+    scope="ACROSS_ALL_SESSIONS",
+    include_conditions=[
+        {"type": "event", "event_name": "purchase"},
+        {"type": "numeric", "field_name": "sessionCount", "operation": "GREATER_THAN", "value": 3}
+    ]
+)
+print(f"Created audience: {audience.name}")
+```
+
+---
+
+### 3. Google Tag Manager (GTM)
+
+Inspect accounts, containers, workspaces, tags, triggers, variables, built-in variables, and custom templates.
+
+```python
+from google.oauth2 import service_account
+from digital_analytics_toolkit import (
+    get_accounts,
+    get_containers,
+    get_workspaces,
+    get_tags,
+    get_triggers,
+    get_variables,
+    get_built_in_variables,
+    get_custom_templates
+)
+
+creds = service_account.Credentials.from_service_account_file(
+    "path/to/service_account.json",
+    scopes=["https://www.googleapis.com/auth/tagmanager.readonly"]
+)
+
+# List accounts & containers
+gtm_accounts = get_accounts(creds)
+containers_df = get_containers(creds, account_id="123456")
+
+# Inspect workspace assets
+workspace_id = get_workspaces(creds, account_id="123456", container_id="987654")
+tags = get_tags(creds, account_id="123456", container_id="987654", workspace_id=workspace_id)
+triggers = get_triggers(creds, account_id="123456", container_id="987654", workspace_id=workspace_id)
+variables = get_variables(creds, account_id="123456", container_id="987654", workspace_id=workspace_id)
+```
+
+---
+
+### 4. BigQuery Integration
+
+Run custom SQL queries or extract full tables directly into Pandas DataFrames.
+
+```python
+from digital_analytics_toolkit import bq_functions
+
+service_account_file = "path/to/service_account.json"
+project_id = "my-gcp-project"
+
+# List Datasets
+datasets = bq_functions.list_bq_datasets(credentials=None, gcp_project_id=project_id)
+
+# Execute SQL query to DataFrame
+query = """
+    SELECT event_name, COUNT(1) AS event_count
+    FROM `my-gcp-project.analytics_123456789.events_*`
+    WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE())
+    GROUP BY 1
+"""
+df = bq_functions.get_ga4_data_from_bq(
+    project_id=project_id,
+    query=query,
+    service_account_file=service_account_file
+)
+```
+
+---
+
+## 🛠 Project Structure
+
+```
+digital-analytics-toolkit/
+├── pyproject.toml
+├── README.md
+└── digital_analytics_toolkit/
+    ├── __init__.py               # Package entrypoint & exported symbols
+    ├── free_form_report_GA4.py   # GA4 Free-form reporting & dimension filter generation
+    ├── funnel_report_GA4.py      # GA4 Funnel report engine
+    ├── ga4_admin_functions.py    # GA4 Admin API helpers (Accounts, Properties, Key Events, BQ Links)
+    ├── ga4_audience.py           # GA4 Audience creation & condition parser
+    ├── gtm_functions.py          # Google Tag Manager (GTM) API helper functions
+    ├── bq_functions.py           # BigQuery query execution & dataset tools
+    └── utils.py                  # Utility functions & metadata extractors
+```
+
+---
+
+## 💬 Support & Inquiries
+
+- For questions, bug reports, or feature requests, contact: **[hacker.knight177@gmail.com](mailto:hacker.knight177@gmail.com)** or **[kris.dsouza64@gmail.com](mailto:kris.dsouza64@gmail.com)**
+
+---
+
+## 📄 License
+
+Digital Analytics Toolkit is proprietary software.
+
+It is free to install and use for personal, educational, research,
+and commercial purposes.
+
+Modification, redistribution, sublicensing, resale, and creation of
+derivative works are not permitted without explicit written
+permission from the copyright holders.
+
+See the [LICENSE](LICENSE) file for the complete terms.

digital_analytics_toolkit-0.1.0/README.md

@@ -0,0 +1,271 @@
+# 🚀 Digital Analytics Toolkit
+
+### A Python toolkit for Google Analytics 4, Google Tag Manager, and BigQuery workflows
+
+**Digital Analytics Toolkit** is a Python library designed to streamline GA4 reporting, GA4 administration, audience management, GTM container inspection, and BigQuery querying through reusable Python functions and clients.
+
+---
+
+## 📦 Installation
+
+Install the latest release from PyPI:
+
+```bash
+pip install digital-analytics-toolkit
+```
+
+For future upgrade:
+
+```bash
+pip install --upgrade digital-analytics-toolkit
+```
+
+---
+
+## 🔐 Authentication
+
+Digital Analytics Toolkit supports **Service Account Key JSON files** and **Google OAuth2 Credentials**.
+
+1. Create a Service Account in the [Google Cloud Console](https://console.cloud.google.com/).
+2. Enable necessary APIs:
+   - Google Analytics Data API
+   - Google Analytics Admin API
+   - Google Tag Manager API
+   - BigQuery API
+3. Download the JSON key file and share your GA4 property / GTM account access with the service account email.
+
+---
+
+## 🧩 Features & Module Usage
+
+The toolkit is organized into 4 primary functional areas:
+
+1. [GA4 Free-Form & Funnel Reporting](#1-ga4-reporting)
+2. [GA4 Admin & Audience Management](#2-ga4-admin--audiences)
+3. [Google Tag Manager (GTM) Operations](#3-google-tag-manager-gtm)
+4. [BigQuery Integration](#4-bigquery-integration)
+
+---
+
+### 1. GA4 Reporting
+
+#### 📊 Free-Form Reports (`free_form_report_GA4`)
+Run custom GA4 reports specifying metrics, dimensions, date ranges, and optional dimension/metric filters.
+
+```python
+from digital_analytics_toolkit import free_form_report_GA4, dimension_filter_generation
+
+# Initialize client
+report_client = free_form_report_GA4(
+    service_account_file="path/to/service_account.json",
+    property_id="123456789"
+)
+
+# Optional: Generate dimension filter
+dim_filter = dimension_filter_generation(
+    operator="CONTAINS",
+    value="Organic",
+    dimension_name="sessionDefaultChannelGroup"
+)
+
+# Generate report
+df = report_client.free_form_report(
+    start_date="30daysAgo",
+    end_date="today",
+    metrics=["activeUsers", "eventCount", "conversions"],
+    dimensions=["date", "sessionDefaultChannelGroup"],
+    dimension_filter=dim_filter
+)
+
+print(df.head())
+```
+
+#### 🏆 Multi-Step Funnel Reports (`Funnel_Reports`)
+Generate multi-step funnel analysis with support for breakdown dimensions based on funnel step definitions configured in Google Sheets.
+
+```python
+from digital_analytics_toolkit import Funnel_Reports
+
+funnel = Funnel_Reports(
+    reporting_client="path/to/service_account.json",
+    prop_id="123456789"
+)
+
+# Run funnel report using steps defined in a Google Sheet
+response = funnel.funnel_report(
+    startDate="2024-01-01",
+    endDate="2024-01-31",
+    file_n="My_Funnel_Steps_Sheet_Name",
+    breakdown="deviceCategory",
+    breakdown_limit="5"
+)
+```
+
+#### 📜 Dimension & Metric Metadata (`get_dimension_metric`)
+Fetch all available custom & standard dimensions/metrics for a GA4 property and export to CSV.
+
+```python
+from digital_analytics_toolkit import utils
+
+utils.get_dimension_metric(
+    service_account_file="path/to/service_account.json",
+    property_id="123456789",
+    file_name="ga4_dimensions_metrics"
+)
+```
+
+---
+
+### 2. GA4 Admin & Audiences
+
+#### 🏢 Accounts & Property Discovery
+Discover accounts, properties, key events (conversions), and BigQuery links.
+
+```python
+from google.oauth2 import service_account
+from digital_analytics_toolkit import (
+    get_ga4_accounts_list,
+    get_ga4_properties_list,
+    get_ga4_property_keyEvents,
+    get_ga4_property_bq_link
+)
+
+creds = service_account.Credentials.from_service_account_file(
+    "path/to/service_account.json",
+    scopes=["https://www.googleapis.com/auth/analytics.readonly"]
+)
+
+# List accounts & properties
+accounts_df = get_ga4_accounts_list(creds)
+properties_df = get_ga4_properties_list(creds, account_id="12345678")
+
+# Key events & BigQuery export status
+key_events_df = get_ga4_property_keyEvents(creds, property_id="123456789")
+bq_links_df = get_ga4_property_bq_link(creds, property_id="123456789")
+```
+
+#### 🎯 Audience Creation (`GA4AudienceClient`)
+Programmatically construct and create GA4 audiences using a simplified dictionary condition language.
+
+```python
+from digital_analytics_toolkit import GA4AudienceClient
+
+client = GA4AudienceClient(credentials_path="path/to/service_account.json")
+
+audience = client.create_audience(
+    property_id="123456789",
+    display_name="High Intent Purchasers",
+    description="Users with > 3 sessions who completed a purchase",
+    membership_duration_days=30,
+    scope="ACROSS_ALL_SESSIONS",
+    include_conditions=[
+        {"type": "event", "event_name": "purchase"},
+        {"type": "numeric", "field_name": "sessionCount", "operation": "GREATER_THAN", "value": 3}
+    ]
+)
+print(f"Created audience: {audience.name}")
+```
+
+---
+
+### 3. Google Tag Manager (GTM)
+
+Inspect accounts, containers, workspaces, tags, triggers, variables, built-in variables, and custom templates.
+
+```python
+from google.oauth2 import service_account
+from digital_analytics_toolkit import (
+    get_accounts,
+    get_containers,
+    get_workspaces,
+    get_tags,
+    get_triggers,
+    get_variables,
+    get_built_in_variables,
+    get_custom_templates
+)
+
+creds = service_account.Credentials.from_service_account_file(
+    "path/to/service_account.json",
+    scopes=["https://www.googleapis.com/auth/tagmanager.readonly"]
+)
+
+# List accounts & containers
+gtm_accounts = get_accounts(creds)
+containers_df = get_containers(creds, account_id="123456")
+
+# Inspect workspace assets
+workspace_id = get_workspaces(creds, account_id="123456", container_id="987654")
+tags = get_tags(creds, account_id="123456", container_id="987654", workspace_id=workspace_id)
+triggers = get_triggers(creds, account_id="123456", container_id="987654", workspace_id=workspace_id)
+variables = get_variables(creds, account_id="123456", container_id="987654", workspace_id=workspace_id)
+```
+
+---
+
+### 4. BigQuery Integration
+
+Run custom SQL queries or extract full tables directly into Pandas DataFrames.
+
+```python
+from digital_analytics_toolkit import bq_functions
+
+service_account_file = "path/to/service_account.json"
+project_id = "my-gcp-project"
+
+# List Datasets
+datasets = bq_functions.list_bq_datasets(credentials=None, gcp_project_id=project_id)
+
+# Execute SQL query to DataFrame
+query = """
+    SELECT event_name, COUNT(1) AS event_count
+    FROM `my-gcp-project.analytics_123456789.events_*`
+    WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE())
+    GROUP BY 1
+"""
+df = bq_functions.get_ga4_data_from_bq(
+    project_id=project_id,
+    query=query,
+    service_account_file=service_account_file
+)
+```
+
+---
+
+## 🛠 Project Structure
+
+```
+digital-analytics-toolkit/
+├── pyproject.toml
+├── README.md
+└── digital_analytics_toolkit/
+    ├── __init__.py               # Package entrypoint & exported symbols
+    ├── free_form_report_GA4.py   # GA4 Free-form reporting & dimension filter generation
+    ├── funnel_report_GA4.py      # GA4 Funnel report engine
+    ├── ga4_admin_functions.py    # GA4 Admin API helpers (Accounts, Properties, Key Events, BQ Links)
+    ├── ga4_audience.py           # GA4 Audience creation & condition parser
+    ├── gtm_functions.py          # Google Tag Manager (GTM) API helper functions
+    ├── bq_functions.py           # BigQuery query execution & dataset tools
+    └── utils.py                  # Utility functions & metadata extractors
+```
+
+---
+
+## 💬 Support & Inquiries
+
+- For questions, bug reports, or feature requests, contact: **[hacker.knight177@gmail.com](mailto:hacker.knight177@gmail.com)** or **[kris.dsouza64@gmail.com](mailto:kris.dsouza64@gmail.com)**
+
+---
+
+## 📄 License
+
+Digital Analytics Toolkit is proprietary software.
+
+It is free to install and use for personal, educational, research,
+and commercial purposes.
+
+Modification, redistribution, sublicensing, resale, and creation of
+derivative works are not permitted without explicit written
+permission from the copyright holders.
+
+See the [LICENSE](LICENSE) file for the complete terms.

digital_analytics_toolkit-0.1.0/digital_analytics_toolkit/__init__.py

@@ -0,0 +1,81 @@
+from . import (
+    bq_functions,
+    free_form_report_GA4,
+    funnel_report_GA4,
+    ga4_admin_functions,
+    ga4_audience,
+    gtm_functions,
+    utils,
+)
+from .bq_functions import (
+    get_from_bigquery,
+    get_ga4_data_from_bq,
+    list_bq_datasets,
+)
+from .free_form_report_GA4 import dimension_filter_generation, free_form_report_GA4
+from .funnel_report_GA4 import Funnel_Reports
+from .ga4_admin_functions import (
+    get_ga4_accounts_list,
+    get_ga4_properties_list,
+    get_ga4_property_bq_link,
+    get_ga4_property_keyEvents,
+)
+from .ga4_audience import (
+    GA4AudienceClient,
+    GA4AudienceError,
+    build_admin_client,
+    create_audience,
+)
+from .gtm_functions import (
+    get_accounts,
+    get_built_in_variables,
+    get_containers,
+    get_custom_templates,
+    get_tags,
+    get_triggers,
+    get_variables,
+    get_workspaces,
+    getLatestVersionHeader,
+)
+from .utils import get_dimension_metric
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Submodules
+    "bq_functions",
+    "ga4_admin_functions",
+    "ga4_audience",
+    "gtm_functions",
+    "utils",
+    # Reporting
+    "Funnel_Reports",
+    "free_form_report_GA4",
+    "dimension_filter_generation",
+    # GA4 Admin
+    "get_ga4_accounts_list",
+    "get_ga4_properties_list",
+    "get_ga4_property_keyEvents",
+    "get_ga4_property_bq_link",
+    # Audiences
+    "GA4AudienceClient",
+    "create_audience",
+    "build_admin_client",
+    "GA4AudienceError",
+    # GTM
+    "get_accounts",
+    "get_containers",
+    "get_workspaces",
+    "getLatestVersionHeader",
+    "get_tags",
+    "get_variables",
+    "get_triggers",
+    "get_built_in_variables",
+    "get_custom_templates",
+    # BigQuery
+    "list_bq_datasets",
+    "get_from_bigquery",
+    "get_ga4_data_from_bq",
+    # Utilities
+    "get_dimension_metric",
+]