Skip to content

00-README.md

Latest commit

 

History

History
255 lines (190 loc) · 8.81 KB

00-README.md

File metadata and controls

255 lines (190 loc) · 8.81 KB

Documentation Index

Welcome to the Puzzel SMS Gateway Python Client (Kiota) documentation.

Getting Started

Start here if you're new to the client:

  1. Main README - Overview, installation, and quick start guide
  2. 01 - uv Setup Guide - Complete guide for setting up with uv (recommended)
  3. 02 - Getting Started Guide - Step-by-step guide for beginners
  4. 03 - Quick Reference - Cheat sheet for common operations
  5. Basic Example - Simple SMS sending example

Documentation

Setup and Installation

  • 01 - uv Setup Guide - Complete guide for setting up with uv (recommended)

    • Installation and project creation
    • Virtual environment management
    • Common commands and best practices
    • Troubleshooting

  • 02 - Getting Started Guide - Step-by-step guide for beginners

    • Send your first SMS in 5 minutes
    • Common issues and troubleshooting
    • Complete working examples

Quick References

  • 03 - Quick Reference Guide - Quick lookup for common operations
    • Common code snippets
    • Status codes
    • Model hierarchy
    • Best practices

Core Documentation

  • 04 - Usage Examples - Comprehensive code examples covering all features

    • Basic message sending
    • Message settings and configuration
    • Batch operations
    • Advanced use cases
    • Error handling
    • Production patterns

  • 05 - API Models Reference - Detailed documentation of all data models

    • Request and response models
    • Message models
    • Settings models
    • Batch models
    • Error models
    • Enums

  • 06 - Advanced Topics - Deep dive into advanced features

    • Architecture overview
    • Request adapters
    • Authentication
    • Middleware
    • Timeout and retry configuration
    • Performance optimization
    • Security best practices
    • Monitoring and observability
    • Troubleshooting

  • 07 - Testing Guide - Running and writing tests

    • Running the test suite with uv
    • Coverage reporting
    • Test structure overview
    • What is tested (client, models, request builders)
    • Shared fixtures reference
    • Writing sync, async, and parametrized tests

  • 08 - Publishing Guide - Publishing the package to PyPI with uv

    • Bumping the version
    • Building wheel and sdist with uv build
    • Publishing to TestPyPI for validation
    • Publishing to PyPI with uv publish
    • Storing credentials securely

Example Files

Practical examples you can run directly (located in docs/examples/):

Documentation Structure

Python/
├── README.md                          # Main documentation
├── docs/
│   ├── 00-README.md                   # This file - Documentation index
│   ├── 01-uv-setup.md                 # uv setup guide
│   ├── 02-getting-started.md          # Getting started guide
│   ├── 03-quick-reference.md          # Quick reference guide
│   ├── 04-examples.md                 # Comprehensive examples
│   ├── 05-models.md                   # API models reference
│   ├── 06-advanced.md                 # Advanced topics
│   ├── 07-testing.md                  # Testing guide
│   ├── 08-publishing.md               # Publishing guide
│   └── examples/                      # Example code files
│       ├── README.md                  # Examples guide
│       ├── example_basic.py           # Basic example
│       ├── example_advanced.py        # Advanced example
│       ├── example_multiple_recipients.py  # Multiple recipients
│       └── example_batch_management.py     # Batch management
└── src/                               # Generated Kiota client code
    ├── mt_http_client.py              # Main client
    ├── models/                        # Data models
    ├── gw/                            # Gateway endpoints
    ├── management/                    # Management endpoints
    └── ...

Common Tasks

Sending Messages

Batch Management

Configuration

Error Handling

Testing

Production

API Reference

Main Components

  • MtHttpClient - Main entry point for the SDK
  • GatewayRequest - Request object for sending messages
  • Message - Individual SMS message
  • Settings - Message configuration options
  • GatewayResponse - Response from send operations

Endpoints

  • client.gw.rs.send_messages - Send messages
  • client.management - Batch management operations

For detailed API reference, see 05 - API Models Reference.

Migration Guide

If you're migrating from the previous version (v2.x), see the Migration Guide in the main README.

Key differences:

  • Fully asynchronous (requires async/await)
  • Credentials in request instead of client
  • Fluent, path-based API
  • Type-safe dataclass models

Support and Resources

Quick Links

For Beginners

  1. 01 - uv Setup Guide - Set up your development environment
  2. Installation - Install the client
  3. 02 - Getting Started Guide - Send your first SMS
  4. Quick Start - Quick code example
  5. Basic Example - Runnable example
  6. 03 - Quick Reference - Common operations cheat sheet

For Developers

  1. 04 - Usage Examples
  2. 05 - API Models
  3. 06 - Advanced Topics
  4. 07 - Testing Guide
  5. 08 - Publishing Guide

For Production

  1. Security Best Practices
  2. Performance Optimization
  3. Monitoring
  4. Troubleshooting

Maintenance

Keeping Documentation Updated

When the API changes:

  1. Update 05-models.md with new or changed models
  2. Add examples to 04-examples.md
  3. Update 03-quick-reference.md snippets
  4. Add migration notes to README.md if needed

Adding New Examples

New examples should:

  1. Be placed in docs/examples/ as example_*.py
  2. Be referenced in this index under Example Files
  3. Include detailed comments
  4. Follow the existing style

Contributing

For issues, questions, or contributions, please contact Puzzel support.

License

Released under the MIT license. See LICENSE for details.

Last Updated: March 2026
Version: 3.0 (Kiota-generated)