Apply Python best practices: custom exceptions, context managers, session pooling, and __repr__ methods

Co-authored-by: sonnyt <183387+sonnyt@users.noreply.github.com>

Author: Copilot

README.md

@@ -8,14 +8,29 @@ Official Python SDK for the BundleUp API.
 pip install bundleup-sdk
 ```
 
+## Features
+
+- **Pythonic API Design** - Context managers, property decorators, and Python best practices
+- **Custom Exception Hierarchy** - Specific exception types for different error scenarios
+- **Connection Pooling** - Efficient HTTP connection reuse with `requests.Session`
+- **Type Hints** - Full type annotation support for better IDE integration
+- **Comprehensive Testing** - 70+ unit tests with mocked HTTP requests
+
 ## Usage
 
 ### Initialize the Client
 
+The SDK supports both regular initialization and context manager usage:
+
 ```python
 from bundleup import BundleUp
 
+# Regular usage
 client = BundleUp("your-api-key")
+
+# Context manager (automatically closes connections)
+with BundleUp("your-api-key") as client:
+    connections = client.connections.list()
 ```
 
 ### Working with Connections
@@ -96,6 +111,12 @@ The Unify API provides a standardized interface across different integrations.
 ```python
 # Get unified chat channels
 channels = client.unify("connection-id").chat.channels()
+
+# With pagination parameters
+channels = client.unify("connection-id").chat.channels({
+    "limit": 50,
+    "include_raw": True
+})
 ```
 
 #### Git
@@ -121,6 +142,68 @@ releases = unify.git.releases()
 ```python
 # Get issues
 issues = client.unify("connection-id").pm.issues()
+
+# With pagination
+issues = client.unify("connection-id").pm.issues({
+    "limit": 100,
+    "after": "cursor-id"
+})
+```
+
+## Error Handling
+
+The SDK uses a hierarchy of custom exceptions:
+
+```python
+from bundleup import BundleUp
+from bundleup.exceptions import (
+    BundleUpError,          # Base exception
+    ValidationError,        # Input validation errors
+    APIError,              # General API errors
+    AuthenticationError,   # 401 errors
+    NotFoundError,        # 404 errors
+    RateLimitError        # 429 errors
+)
+
+try:
+    client = BundleUp("your-api-key")
+    connections = client.connections.list()
+except AuthenticationError:
+    print("Invalid API key")
+except NotFoundError:
+    print("Resource not found")
+except RateLimitError:
+    print("Rate limit exceeded")
+except APIError as e:
+    print(f"API error: {e.status_code} - {e}")
+except ValidationError as e:
+    print(f"Validation error: {e}")
+```
+
+## Advanced Usage
+
+### Custom Session
+
+You can provide your own `requests.Session` for advanced configuration:
+
+```python
+import requests
+from bundleup import BundleUp
+
+session = requests.Session()
+session.timeout = 30
+session.verify = True
+
+client = BundleUp("your-api-key", session=session)
+```
+
+### Query Parameters
+
+The `list()` method supports query parameters:
+
+```python
+# List with filters
+connections = client.connections.list(status="active", limit=50)
 ```
 
 ## Requirements

bundleup/__init__.py

@@ -4,44 +4,68 @@
 
 Example:
     >>> from bundleup import BundleUp
-    >>> client = BundleUp("your-api-key")
-    >>> connections = client.connections.list()
+    >>> with BundleUp("your-api-key") as client:
+    ...     connections = client.connections.list()
 """
 
+from typing import Optional
+import requests
+
 from .base import Base
 from .connection import Connection, Connections
 from .integration import Integration, Integrations
 from .webhooks import Webhook, Webhooks
 from .proxy import Proxy
 from .unify import Unify
 from .utils import validate_non_empty_string
+from .exceptions import BundleUpError, ValidationError, APIError
 
 __version__ = "0.1.0"
 
 
 class BundleUp:
-    """Main BundleUp SDK client."""
+    """Main BundleUp SDK client with context manager support."""
 
-    def __init__(self, api_key: str):
+    def __init__(self, api_key: str, session: Optional[requests.Session] = None):
         """
         Initialize the BundleUp client.
         
         Args:
             api_key: Your BundleUp API key
+            session: Optional requests session for connection pooling
             
         Raises:
-            ValueError: If api_key is not a valid non-empty string
+            ValidationError: If api_key is not a valid non-empty string
             
         Example:
             >>> client = BundleUp("your-api-key")
+            >>> # or use as context manager
+            >>> with BundleUp("your-api-key") as client:
+            ...     connections = client.connections.list()
         """
         validate_non_empty_string(api_key, "api_key")
         self._api_key = api_key
+        self._session = session or requests.Session()
+        self._owns_session = session is None
 
-        # Initialize resource instances
-        self._connections = Connections(api_key)
-        self._integrations = Integrations(api_key)
-        self._webhooks = Webhooks(api_key)
+        # Initialize resource instances with shared session
+        self._connections = Connections(api_key, self._session)
+        self._integrations = Integrations(api_key, self._session)
+        self._webhooks = Webhooks(api_key, self._session)
+    
+    def __enter__(self):
+        """Enter context manager."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit context manager and cleanup resources."""
+        self.close()
+        return False
+    
+    def close(self):
+        """Close the underlying session if owned by this client."""
+        if self._owns_session and self._session:
+            self._session.close()
 
     @property
     def connections(self) -> Connections:
@@ -93,13 +117,13 @@ def proxy(self, connection_id: str) -> Proxy:
             Proxy instance for the specified connection
             
         Raises:
-            ValueError: If connection_id is not a valid non-empty string
+            ValidationError: If connection_id is not a valid non-empty string
             
         Example:
             >>> proxy = client.proxy("connection-id")
             >>> data = proxy.get("/users")
         """
-        return Proxy(self._api_key, connection_id)
+        return Proxy(self._api_key, connection_id, self._session)
 
     def unify(self, connection_id: str) -> Unify:
         """
@@ -112,14 +136,18 @@ def unify(self, connection_id: str) -> Unify:
             Unify instance for the specified connection
             
         Raises:
-            ValueError: If connection_id is not a valid non-empty string
+            ValidationError: If connection_id is not a valid non-empty string
             
         Example:
             >>> unify = client.unify("connection-id")
             >>> channels = unify.chat.channels()
             >>> repos = unify.git.repos()
         """
-        return Unify(self._api_key, connection_id)
+        return Unify(self._api_key, connection_id, self._session)
+    
+    def __repr__(self) -> str:
+        """Return a string representation of the client."""
+        return f"BundleUp(version='{__version__}')"
 
 
 __all__ = [
@@ -133,4 +161,7 @@ def unify(self, connection_id: str) -> Unify:
     "Webhooks",
     "Proxy",
     "Unify",
+    "BundleUpError",
+    "ValidationError",
+    "APIError",
 ]