mattermost/python-sdk/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with the Mattermost Python Plugin SDK.

Repository Purpose

This is the Python SDK for Mattermost plugins. It provides:

• gRPC client for calling Mattermost Plugin API
• Plugin base class and hook decorators
• Type-safe wrappers for Mattermost data types

Key Commands

Setup

# Create virtual environment with dev dependencies
make venv

# Activate environment
source .venv/bin/activate

Development

# Regenerate gRPC code from proto files
make proto-gen

# Run tests
make test

# Run type checking
make lint

# Build package
make build

Testing

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_hooks_lifecycle.py -v

# Run integration tests (requires Go binaries)
pytest tests/test_integration_e2e.py -v

Architecture Overview

Directory Structure

python-sdk/
├── src/mattermost_plugin/
│   ├── __init__.py          # Public API exports
│   ├── plugin.py            # Plugin base class
│   ├── hooks.py             # @hook decorator and HookName enum
│   ├── client.py            # Sync API client
│   ├── async_client.py      # Async API client
│   ├── server.py            # gRPC server for hooks
│   ├── exceptions.py        # Exception types
│   ├── _internal/           # Internal implementation
│   │   └── wrappers.py      # Proto-to-Python type wrappers
│   ├── grpc/                # Generated gRPC code (do not edit)
│   └── servicers/           # gRPC servicer implementations
│       └── hooks_servicer.py
├── tests/                   # Test suite
└── scripts/
    └── generate_protos.py   # Proto generation script

Key Components

1. Plugin Class (plugin.py)

   • Base class all plugins inherit from
   • Provides self.api and self.logger
   • Uses __init_subclass__ for hook discovery

2. Hook System (hooks.py)

   • @hook(HookName.X) decorator
   • HookName enum with all available hooks
   • Automatic registration via metaclass

3. API Client (client.py)

   • Typed wrapper around gRPC stubs
   • Mixin classes for API domains (UsersMixin, ChannelsMixin, etc.)
   • Converts proto types to Python dataclasses

4. gRPC Server (server.py)

   • PluginHooks gRPC server
   • Handles hook dispatch from Go server
   • Health checking for go-plugin protocol

Code Generation

Proto files are in server/public/pluginapi/grpc/proto/. After modifying:

# From python-sdk/
make proto-gen

# Or from server/
make python-proto-gen

Generated files go to src/mattermost_plugin/grpc/.

Best Practices

1. Type Annotations: All public APIs must have type hints
2. Proto Wrappers: Use _internal/wrappers.py for proto conversions
3. Testing: Add tests for any new hooks or API methods
4. Backwards Compatibility: Don't break existing plugin APIs
5. Generated Code: Never manually edit files in grpc/ directory

Adding a New Hook

1. Define hook in server/public/pluginapi/grpc/proto/hooks_*.proto
2. Run make proto-gen-all from server/
3. Add to HookName enum in hooks.py
4. Add handler in servicers/hooks_servicer.py
5. Add test in tests/test_hooks_*.py

Adding a New API Method

1. Define RPC in server/public/pluginapi/grpc/proto/api*.proto
2. Run make proto-gen-all from server/
3. Add to appropriate mixin in client.py
4. Add wrapper types to _internal/wrappers.py if needed
5. Add test in tests/test_client_*.py