How facebook/facebook-python-business-sdk works
Project type and purpose
• This is an open-source Python SDK (facebook_business) that wraps Facebook’s Graph and Marketing APIs.
• Its goal is to present a CRUD-style, object-oriented interface to Facebook Business endpoints, hiding HTTP details and batching logic.
File structure
• Top-level package: facebook_business/
• api.py, session.py, bootstrap.py, specs.py, exceptions.py, utils/
• adobjects/: hundreds of autogenerated classes (one per FB object) plus helpers
• docs_runner/: tooling to build reference docs
• test suite (facebook_business/test/ and integration tests)
• Supporting files:
• examples/: dozens of sample scripts showing real-world usage
• config.json.example, setup.py, requirements.txt, CI workflows (GitHub Actions)
• Key patterns:
• SDK Codegen → generates adobjects/ classes from a central specification
• CRUD abstraction (AbstractObject, AbstractCrudObject)
• Batch processing (FacebookAdsApiBatch)
• Pluggable sessions for multiple access tokens
Extract insights from README
• Describes initialization (FacebookAdsApi.init / FacebookSession) and token management
• Emphasizes CRUD methods (api_get, api_update, create_xxx, etc.)
• Explains batch calls, debugging (curl output), code-generation origin
• Lists example usage and test invocation
a. Main components
1. Developer Application
– Imports facebook_business package
– Calls into SDK classes
2. Facebook Business SDK
– Session Layer (session.py, FacebookSession)
– API Layer (api.py, FacebookAdsApi, FacebookAdsApiBatch)
– Model Layer (adobjects/):
· Abstract classes (AbstractObject, AbstractCrudObject)
· Generated object classes (AdAccount, Campaign, Page, etc.)
– Utilities (utils/, specs.py)
– Documentation tooling (docs_runner/)
– Configuration (config.json.example)
3. External Service
– Facebook Graph API endpoints over HTTPS
b. Relationships & interactions
• Developer code → instantiate FacebookSession / call FacebookAdsApi.init
• API Layer uses Session Layer to dispatch HTTP requests (supporting single/multiple tokens, proxies)
• Requests: JSON payloads built from Model Layer fields & specs
• Responses: JSON parsed back into Model Layer instances
• Batch calls aggregate multiple CRUD operations into one HTTP payload
• Errors raised through facebook_business.exceptions
c. Architectural patterns & principles
• Wrapper/Adapter: maps Python methods to REST endpoints
• Code-generation: ensures high parity with API spec
• Dependency injection: pluggable sessions allow multi-tenant token management
• Separation of concerns:
• Session concerns (auth, retries, proxies)
• API orchestration (batching, debug logging)
• Data modeling (CRUD classes)
d. Key technologies & frameworks
• Python packaging (setup.py, PyPI)
• HTTP client (under the hood via requests or urllib)
• JSON serialization / deserialization
• GitHub Actions for CI
• tox for multi-version testing