How sondreal/py24so works
And Define the Main Components
• Client Interface: Represent the two primary client interfaces – one for synchronous operations (Client24SO) and one for asynchronous operations (AsyncClient24SO). These clients are the entry points for library users.
• Core Functionality: This is implemented in the py24so/core folder. Break this down into essential subcomponents:
• Authentication and Connection Setup (py24so/core/auth.py)
• Batch processing logic (py24so/core/batch.py)
• Client initialization and high-level orchestration (py24so/core/client.py)
• Error handling using custom exceptions (py24so/core/exceptions.py)
• Rate limiting functionality (py24so/core/rate_limiter.py)
• API Endpoints: In the py24so/endpoints directory, the endpoints are organized by domain (customers, invoices, product_categories, products). Each endpoint acts as a dedicated communication module for a particular API section.
• Data Models: Found in py24so/models, these classes represent configuration settings (ClientOptions) and the different API entities (Customer, Invoice, Product, ProductCategory). They form the Data Transfer Objects (DTOs) and help in type checking and documentation.
• Utility and Supporting Scripts: Additional utility scripts support development tasks like testing, formatting, and CI/CD configurations (as seen in the scripts, tests, and GitHub Actions folders).
Relationships and Interactions
• The Client (sync/async) internally orchestrates requests by:
• Authenticating via the authentication module.
• Routing calls to the corresponding API endpoint handlers based on the operation (e.g., listing customers, creating invoices).
• Handling batch operations and utilizing the rate limiter to control API request flows.
• Converting incoming/outgoing data using the models.
• The endpoints act as adapters between the client and the remote 24SevenOffice API. They abstract HTTP calls and error management.
• The models provide structure for data used and returned, and they are configurable with options specified through ClientOptions.
• The core modules define lower-level, reusable functionality (e.g., rate limiting, error catching) that is shared across multiple endpoint invocations.
Architectural Patterns
• Separation of Concerns: Distinct modules for core operations, endpoints, and data models keep responsibilities loosely coupled.
• Client Abstraction: Both synchronous and asynchronous interactions are well abstracted, allowing for flexible integration.
• Cross-Cutting Concerns: Rate limiting, caching, and error handling are implemented as infrastructure-level services that overlay the API interactions.