How googleads/googleads-python-lib works
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.