# googleads/googleads-python-lib architecture

> Architecture diagram of the GitHub repository googleads/googleads-python-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googleads/googleads-python-lib
- Repository: https://github.com/googleads/googleads-python-lib

## Overview

##### Project Type and Purpose
- This is a Python client library (“googleads”) that provides a high-level wrapper around the Google Ad Manager SOAP API.
- It offers authentication management, configuration loading, SOAP service proxies (via Zeep), caching, logging, and example scripts to help users integrate Ad Manager into their own Python applications.

##### High-Level Components
a. User Application
- Your own Python scripts or applications that import `googleads.ad_manager.AdManagerClient` and call example or service methods.
b. Configuration Loader
- Reads `googleads.yaml` from the user’s home directory (or specified path) to obtain OAuth2 credentials, network codes, logging settings, etc.
c. OAuth2 Authentication Module
- The `googleads.oauth2` module (backed by `oauth2client`) issues access/refresh tokens for Ad Manager API calls.
d. AdManagerClient Facade
- The `googleads.ad_manager.AdManagerClient` class exposes methods for each SOAP service version (e.g., v202502, v202505, v202508).
- Internally it wraps Zeep SOAP clients, handling WSDL retrieval and caching.
e. SOAP Transport Layer
- Under the hood Zeep (`zeep.Client`) serializes method calls into SOAP envelopes, sends them over HTTP, and parses the XML responses.
f. Caching Subsystem
- Uses Zeep’s `SqliteCache` (or `NO_CACHE`) to avoid reloading large WSDL files on every instantiation.
g. Logging Subsystem
- Leverages Python’s `logging` framework. The `googleads.util.LOGGER_FORMAT` constant helps format SOAP request/response logs.
h. Example Scripts Directory
- Under `examples/ad_manager/…` you find per-version, per-service sample scripts demonstrating how to call each SOAP service.
i. Unit Tests
- Under `tests/…` covering modules: `ad_manager`, `common`, `errors`, `oauth2`, `util`. These validate core logic without invoking real API endpoints.

##### Relationships and Data Flows
- The User Application → invokes → AdManagerClient.LoadFromStorage()
- AdManagerClient → uses → Configuration Loader → returns → OAuth2 Credentials + settings
- OAuth2 Module → fetches/refreshes → Access Token ← stored in cache or config
- AdManagerClient → instantiates → Zeep SOAP Client (with caching plugin)
- AdManagerClient → calls → Zeep client methods → sends → SOAP envelope → to → Google Ad Manager SOAP Endpoint
- Endpoint → returns → SOAP response → parsed by Zeep → mapped back to Python objects → returned to user code
- Logging Subsystem → intercepts → outgoing/incoming SOAP envelopes → writes → logs to stdout/file based on config
- Example Scripts → showcase → how each service is called (auth flow → client instantiation → service call → output)

##### Architectural Patterns and Principles
- Facade Pattern: `AdManagerClient` hides the complexity of SOAP, WSDL loading, authentication, and caching behind a simple Pythonic interface.
- Adapter Pattern: Zeep acts as an adapter between Python code and raw SOAP service definitions.
- Configuration‐Driven Design: `googleads.yaml` externalizes credentials, API versions, logging and caching options.
- Layered Architecture:
- Presentation Layer: User scripts / examples
- API Layer: AdManagerClient façade
- Service Layer: Zeep SOAP clients + OAuth2
- Infrastructure Layer: HTTP transport, caching, logging

1. “User Application / Scripts” at the left/top.
4. Inside AdManagerClient, show sub-blocks or annotate that it:
- Loads WSDL via Zeep (point to Zeep client).
- Applies caching plugin.
- Applies logging plugin.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Code" 
        direction TB
        UA["User Application / Scripts"]:::user
        Examples["Examples Directory"]:::user
    end

    subgraph "googleads Package"
        direction TB
        subgraph "Common Module"
            Config["Configuration Loader"]:::core
        end
        subgraph "OAuth2 Module"
            OAuth2["OAuth2 Authentication Module"]:::core
        end
        subgraph "Ad Manager Module"
            AMC["AdManagerClient Facade"]:::core
        end
        subgraph "Utilities"
            Util["Logging & Cache Helpers"]:::infra
        end
        Error["Error Definitions Module"]:::core
        Cache["Caching Subsystem"]:::infra
        LogSub["Logging Subsystem"]:::infra
        Zeep["Zeep SOAP Client"]:::external
    end

    Remote["Google Ad Manager SOAP Endpoint"]:::remote
    Tests["Unit Tests"]:::test

    %% Data Flows
    UA -->|calls AdManagerClient| AMC
    Examples -->|demo calls| AMC
    AMC -->|loads config| Config
    Config -->|returns settings| OAuth2
    OAuth2 -->|fetches token| OAuth2
    OAuth2 -->|provides token| AMC
    AMC -->|instantiates| Zeep
    AMC -->|attaches cache plugin| Cache
    AMC -->|attaches logging plugin| LogSub
    Zeep -->|sends SOAP request| Remote
    Remote -->|returns SOAP response| Zeep
    Zeep -->|parses XML| AMC
    LogSub -->|logs envelopes| UA
    Tests -->|test modules| Config
    Tests -->|test modules| OAuth2
    Tests -->|test modules| AMC
    Tests -->|test modules| Util
    Tests -->|test modules| Error

    %% Click Events
    click Examples "https://github.com/googleads/googleads-python-lib/tree/main/examples/"
    click Config "https://github.com/googleads/googleads-python-lib/blob/main/googleads/common.py"
    click OAuth2 "https://github.com/googleads/googleads-python-lib/blob/main/googleads/oauth2.py"
    click AMC "https://github.com/googleads/googleads-python-lib/blob/main/googleads/ad_manager.py"
    click Util "https://github.com/googleads/googleads-python-lib/blob/main/googleads/util.py"
    click Error "https://github.com/googleads/googleads-python-lib/blob/main/googleads/errors.py"
    click Cache "https://github.com/googleads/googleads-python-lib/blob/main/googleads/util.py"
    click LogSub "https://github.com/googleads/googleads-python-lib/blob/main/googleads/util.py"
    click Zeep "https://github.com/googleads/googleads-python-lib/blob/main/requirements.txt"
    click Remote "https://github.com/googleads/googleads-python-lib/tree/main/#"
    click Tests "https://github.com/googleads/googleads-python-lib/tree/main/tests/"

    %% Example Scripts Clicks
    click Auth1 "https://github.com/googleads/googleads-python-lib/blob/main/examples/ad_manager/authentication/create_ad_manager_client_with_access_token.py"
    click Auth2 "https://github.com/googleads/googleads-python-lib/blob/main/examples/ad_manager/authentication/create_ad_manager_client_with_refresh_token.py"
    click Auth3 "https://github.com/googleads/googleads-python-lib/blob/main/examples/ad_manager/authentication/create_ad_manager_client_with_service_account.py"
    click Auth4 "https://github.com/googleads/googleads-python-lib/blob/main/examples/ad_manager/authentication/generate_refresh_token.py"
    click V1 "https://github.com/googleads/googleads-python-lib/tree/main/examples/ad_manager/v202502/"
    click V2 "https://github.com/googleads/googleads-python-lib/tree/main/examples/ad_manager/v202505/"
    click V3 "https://github.com/googleads/googleads-python-lib/tree/main/examples/ad_manager/v202508/"

    %% Unit Test Clicks
    click T1 "https://github.com/googleads/googleads-python-lib/blob/main/tests/ad_manager_test.py"
    click T2 "https://github.com/googleads/googleads-python-lib/blob/main/tests/common_test.py"
    click T3 "https://github.com/googleads/googleads-python-lib/blob/main/tests/errors_test.py"
    click T4 "https://github.com/googleads/googleads-python-lib/blob/main/tests/oauth2_test.py"
    click T5 "https://github.com/googleads/googleads-python-lib/blob/main/tests/util_test.py"
    click TD "https://github.com/googleads/googleads-python-lib/tree/main/tests/test_data/"

    %% Styles
    classDef user fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef core fill:#a2c7f5,stroke:#333,stroke-width:1px
    classDef external fill:#f5e08a,stroke:#333,stroke-width:1px
    classDef infra fill:#f5b78a,stroke:#333,stroke-width:1px
    classDef remote fill:#cccccc,stroke:#333,stroke-width:1px
    classDef test fill:#d3a2f5,stroke:#333,stroke-width:1px
```
