How hubspot/hubspot-api-python works
Project Type and Purpose
• This is a Python SDK (client library) for interacting with the HubSpot REST APIs (v3).
• It is *not* a full-stack web app but a standalone library that provides a convenient interface (models, API classes, configuration, helpers) to send HTTP requests to HubSpot’s servers.
High-Level Architecture
• External Systems:
• HubSpot REST API endpoints (the cloud service)
• Underlying HTTP client (urllib3 via swagger-generated API client)
• Core Library Layers:
1. Client Layer
– HubSpot class (hubspot/client.py)
– Factory methods (HubSpot.create, configuring access_token, hapikey support deprecated)
2. Configuration & Transport
– configuration.py modules in each subpackage
– api_client.py (shared HTTP client, retry middleware support)
– Request builder (utils/requests/http_request_builder.py)
– HTTP auth (utils/requests/http_auth.py)
3. API Packages
– One package per API group (e.g., crm/contacts, cms/blogs, marketing/emails, oauth, webhooks)
– Each has:
• api/*.py: entry points for operations (basic_api.py, batch_api.py, etc.)
• models/*.py: data classes for requests/responses
• exceptions.py: APIException classes
• rest.py: low-level REST call wrappers
4. Discovery Module
– discovery/: dynamically fetch metadata/endpoints from HubSpot (used for code generation or advanced use)
5. Utilities
– OAuth URL builder (utils/oauth.py)
– Signature validator (utils/signature.py)
– Generic object helpers (utils/objects.py)
• Test Suite
– tests/: integration tests (against real HubSpot if credentials provided) and spec tests (mocked).
Components and Interactions
a. User Application
– Imports and configures HubSpot client
– Invokes high-level methods (e.g., client.crm.contacts.basic_api.create(...))
b. HubSpot SDK (your library)
– Client Layer routes calls to the correct API package
– Configuration & Transport builds HTTP requests, applies auth (OAuth token or hapikey), retry policies
– API Packages serialize method parameters into request bodies/URL params, call low-level rest.py
– Models parse JSON responses into Python objects with to_dict support
– Exceptions thrown on non-2xx responses
– Discovery can dynamically introspect or generate calls for unwrapped endpoints
– Utilities provide helper functions around OAuth/URL signing
c. HTTP Client
– urllib3 (via generated swagger client) sends HTTP(S) requests to HubSpot’s servers
– Receives HTTP responses
d. HubSpot REST API
– The external service fulfilling API calls
Architectural Patterns and Principles
• Layered Architecture: clear separation between client interface, transport, API definitions, and models
• Code Generation: each API package follows a consistent pattern (api / models / rest) generated from OpenAPI definitions
• Dependency Injection: retry, auth, and base URL configurable via configuration.py
• Single Responsibility: each module has a focused role (e.g., basic_api only handles “basic” operations)
Capturing Essential Elements
• Be detailed: show each logical layer and its modules.
• Don’t over-partition: group similar API packages together (e.g., all hubspot.crm.* under one zone).
– Core SDK code
– Utility helpers
– External systems (HubSpot API, HTTP client)
– Tests