comms-sdk Python SDK

A Python implementation of the CommsSDK for sending SMS and managing communications, following the same patterns as the Ruby and Kotlin reference implementations.

Version: 1.1.0

Features

• Consistent API across all supported languages
• Authenticate with username and API key
• Send SMS to one or more recipients
• Optional sender ID and message priority
• Check account balance
• Comprehensive error handling

Installation

Install the package from PyPI:

pip install comms-sdk

Or for development:

pip install .

Usage

Basic Authentication

from comms_sdk.v1 import CommsSDK, MessagePriority

# Authenticate with username and API key
sdk = CommsSDK.authenticate("your_username", "your_api_key")

Sending SMS

# Send SMS to a single number
success = sdk.send_sms("0712345678", "Message to send")

# Send SMS to multiple numbers
success = sdk.send_sms(["0712345678", "0787654321"], "Message to many")

# Send SMS with custom sender ID and priority
success = sdk.send_sms(
    "0712345678",
    "Hello!",
    sender_id="MyApp",
    priority=MessagePriority.HIGH
)

# Get full API response
response = sdk.query_send_sms(
    ["0712345678"],
    "Hello!",
    "MyApp",
    MessagePriority.HIGHEST
)

Checking Balance

# Get balance as a float
balance = sdk.get_balance()
print(f"Balance: {balance}")

# Get full balance response
response = sdk.query_balance()
print(f"Status: {response.Status}")
print(f"Balance: {response.Balance}")

Configuration

# Use sandbox environment
CommsSDK.use_sandbox()

# Use live server (default)
CommsSDK.use_live_server()

# Set custom sender ID
sdk.with_sender_id("MyCustomSender")

API Reference

CommsSDK

Static/Class Methods

• CommsSDK.authenticate(user_name: str, api_key: str) -> CommsSDK
  • Authenticate and return SDK instance.
• CommsSDK.use_sandbox()
  • Switch to sandbox environment.
• CommsSDK.use_live_server()
  • Switch to live environment.

Instance Methods

• with_sender_id(sender_id: str) -> CommsSDK
  • Set sender ID, returns self for chaining.
• send_sms(numbers: str | List[str], message: str, sender_id: Optional[str] = None, priority: MessagePriority = MessagePriority.HIGH) -> bool
  • Send SMS, returns boolean.
• query_send_sms(numbers: str | List[str], message: str, sender_id: Optional[str] = None, priority: MessagePriority = MessagePriority.HIGH) -> Optional[ApiResponse]
  • Same as send_sms, but returns the full ApiResponse.
• get_balance() -> Optional[float]
  • Get account balance as float.
• query_balance() -> Optional[ApiResponse]
  • Get full balance response as ApiResponse.
• set_authenticated()
  • Mark SDK as authenticated (internal use).

Properties

• api_key - The API key used for authentication.
• user_name - The username used for authentication.
• sender_id - Current sender ID.
• is_authenticated - Authentication status.

Models

MessagePriority

• MessagePriority.HIGHEST - Priority "0"
• MessagePriority.HIGH - Priority "1"
• MessagePriority.MEDIUM - Priority "2"
• MessagePriority.LOW - Priority "3"
• MessagePriority.LOWEST - Priority "4"

ApiResponse

• Status - Response status ("OK" or "Failed")
• Message - Response message
• Cost - Message cost (not always a whole number)
• MsgFollowUpUniqueCode - Unique tracking code
• Balance - Account balance

Error Handling

The SDK raises appropriate Python exceptions:

try:
    sdk = CommsSDK.authenticate("", "")  # Empty credentials
except ValueError as e:
    print(f"Authentication error: {e}")

try:
    sdk.send_sms([], "")  # Empty numbers and message
except ValueError as e:
    print(f"Validation error: {e}")

Thread Safety

The SDK is thread-safe for read operations. For write operations or shared state modifications, use appropriate synchronization mechanisms.

Contributing

Bug reports and pull requests are welcome on GitHub.

License

The package is available as open source under the terms of the MIT License.