How gam-team/gam works
Purpose and Runtime
GAM is a Python command-line administration client for Google Workspace domains and users. It runs locally on administrator machines, is installable as gam7, and is also packaged for Windows/Linux/macOS distribution. Its operational boundary is the local CLI versus authenticated Google APIs.
Paths: pyproject.toml, src/gam/__main__.py, src/gam.py
Entry Points and Command Dispatch
The executable/module entry point initializes GAM and routes command-line invocations into the main command implementation. The large command surface is centralized in gam.py; legacy launch/setup wrappers support installed distributions.
Paths: src/gam/__main__.py, src/gam.py, src/callgam.py
CLI Parsing and Execution Model
Commands are parsed into actions, entities, and API operations. The gamlib layer separates argument parsing, action dispatch, entity expansion, global state/configuration, output messages, and API-facing operations. This is the principal control-flow backbone: CLI arguments → parsed action/entity → selected Google API calls → formatted output/exit status.
Paths: src/gam/gamlib/glclargs.py, src/gam/gamlib/glaction.py, src/gam/gamlib/glentity.py
Google API Integration
GAM manages Workspace resources through Google APIs, with shared API construction and request orchestration in the GAM library. Bundled discovery documents extend supported services—including CBCM, Meet, Looker Studio, Contact Delegation, and Service Account Lookup—without requiring those schemas to be fetched at runtime.
Paths: src/gam/gamlib/glapi.py, src/gam/gamlib/glgapi.py, src/gam/cbcm-v1.1beta1.json
Authentication and HTTP Boundary
Authentication, token storage, HTTP transport, URL handling, and service-client abstractions are implemented in the embedded atom package. This is the security and network boundary between local credentials/configuration and Google endpoints; it includes mock transport/service implementations for non-networked behavior.
Paths: src/gam/atom/auth.py, src/gam/atom/token_store.py, src/gam/atom/http.py
Legacy Google Data APIs
Alongside modern Google API integration, GAM carries a vendored gdata implementation for older Google Data APIs and specialized services such as audit and contacts. This preserves compatibility for command areas not represented solely by newer REST clients.
Paths: src/gam/gdata/service.py, src/gam/gdata/apps/audit/service.py, src/gam/gdata/apps/contacts/service.py
Distribution, Trust, and Automation
Packaging supports Python distribution plus native installers/bundles: PyInstaller spec, Windows Inno Setup, and WiX. A bundled CA bundle supports TLS validation. GitHub Actions builds releases, publishes PyPI artifacts, refreshes CA certificates, and maintains wiki/dependencies.
Paths: src/gam.spec, src/gam.iss, .github/workflows/build.yml
Main entry points: service.py Legacy GData services · glclargs.py Argument parsing · glaction.py Action dispatch · glgapi.py Google API client
Components 19
Local CLI
Command parsing and execution on administrator machines.
- Module entry point
src/gam/__main__.py - Command implementation · Centralized GAM command surface.
src/gam.py - Legacy launcher
src/callgam.py - Argument parsing
src/gam/gamlib/glclargs.py - Action dispatch
src/gam/gamlib/glaction.py - Entity expansion
src/gam/gamlib/glentity.py
API Integration
Google Workspace API clients and compatibility layers.
- API orchestration · Builds services and executes Google API requests.
src/gam/gamlib/glapi.py - Google API client
src/gam/gamlib/glgapi.py - Bundled discovery docs · Adds supported services without runtime schema fetches.
src/gam/cbcm-v1.1beta1.json - Authentication
src/gam/atom/auth.py - Token storage
src/gam/atom/token_store.py - HTTP transport · Transports authenticated requests to Google endpoints.
src/gam/atom/http.py - Legacy GData services · Compatibility client for older Google Data API command areas.
src/gam/gdata/service.py - Audit service
src/gam/gdata/apps/audit/service.py - Contacts service
src/gam/gdata/apps/contacts/service.py
Distribution & Automation
Packaging, installers, trust material, and release workflows.
- Python package
pyproject.toml - Native bundles · PyInstaller and Windows installer packaging.
src/gam.spec - Release workflow · Builds releases, publishes artifacts, and maintains dependencies.
.github/workflows/build.yml
Other components
- Google Workspace APIs
Connections 21
- Python package → Module entry point: installs
- Module entry point → Command implementation: invokes
- Legacy launcher → Command implementation: launches
- Command implementation → Argument parsing: parses CLI
- Argument parsing → Action dispatch: selects action
- Argument parsing → Entity expansion: selects entities
- Action dispatch → API orchestration: executes operations
- Entity expansion → API orchestration: supplies targets
- API orchestration → Google API client: orchestrates
- Google API client → Bundled discovery docs: uses schemas
- Google API client → Authentication: authenticates through
- Authentication → Token storage: reads and stores tokens
- Authentication → HTTP transport: authorizes transport
- HTTP transport → Google Workspace APIs: HTTPS requests
- Action dispatch → Legacy GData services: uses legacy commands
- Legacy GData services → Audit service: provides
- Legacy GData services → Contacts service: provides
- Legacy GData services → Google Workspace APIs: legacy API requests
- Native bundles → Python package: packages
- Release workflow → Native bundles: builds
- Release workflow → Python package: publishes