How ink-developer/pymax works
Project Type and Purpose
• PyMax is an asynchronous Python SDK (open-source library) that wraps the internal WebSocket API of the “Max” messenger.
• It provides an event-driven interface (MaxClient) for user code to authenticate, send/edit/delete messages, manage chats/channels, and handle incoming events.
File Structure Analysis
• Top level:
• src/pymax – SDK package
• examples/ – user-facing usage scripts
• docs/ – Markdown API documentation
• assets/, mkdocs.yml – static site for docs
• Inside src/pymax:
• core.py – MaxClient implementation (initialization, lifecycle)
• interfaces.py – abstract definitions of client methods
• mixins/ – composable feature modules (auth, message, channel, socket, telemetry, etc.)
• payloads.py, models.py, types.py – domain models, request/response types
• static/ – constants and enums
• files.py, crud.py, filters.py, formatter.py/formatting.py – helper modules
• exceptions.py – error handling classes
• Configuration files (pyproject.toml, ruff.toml, .github/workflows) reflect CI, packaging, linting.
Architectural Insights from README
• Event-driven, asynchronous design using asyncio and WebSocket.
• Core entrypoint: MaxClient; users register @client.on_message(), @client.on_start handlers.
• Communication over a persistent WebSocket connection to Max’s API.
• Maintains local state: chats, channels, dialogs.
a. Main Components
1. User Application (example.py, reg.py, telegram_bridge.py, or any consumer code)
2. PyMax SDK
• MaxClient (core lifecycle + event dispatcher)
• Mixin Modules (auth, socket, message, channel, group, telemetry, user, etc.)
• Transport Layer (WebSocket client)
• Models & Payloads (domain objects)
• Utilities (filters, formatting, files, crud operations)
3. External Max Messenger API Service (WebSocket endpoint)
4. Optional Local Cache/File Storage (work_dir)
b. Relationships & Data Flow
• User App calls MaxClient.start() → Core initializes WebSocket transport.
• Core dispatches handshake/auth sequence (via auth mixin) → Max API responds.
• User registers event handlers → on incoming WebSocket messages:
• Transport Layer parses JSON → Payloads → Models → Core dispatches to handlers.
• User code invokes client.send_message() → Core → Transport Layer → WebSocket → Max API.
• SDK updates local state (chats, dialogs) and optionally writes to cache directory.
c. Architectural Patterns & Principles
• Event-driven, asynchronous I/O (asyncio + websockets)
• Mixin-based composition (separate concerns by feature)
• Layered design: transport, core orchestration, domain logic, user interface
• Domain modeling via typed payloads and models
d. Key Technologies & Libraries
• Python 3.10+, asyncio, websockets (or similar)
• Typed interfaces (from src/pymax/types.py, interfaces.py)
• CI/CD: GitHub Actions (publish workflow), ruff linter
• Documentation: MkDocs