Skip to content

Commit bbb8ebf

Browse files
WilliamBergaminWilliamBergamin
committed
improve based on feedback
1 parent 5933cb0 commit bbb8ebf

File tree

2 files changed

+102
-104
lines changed

2 files changed

+102
-104
lines changed

‎.claude/settings.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@
55
"Bash(./scripts/format.sh:*)",
66
"Bash(./scripts/generate_api_docs.sh:*)",
77
"Bash(./scripts/install.sh:*)",
8-
"Bash(./scripts/install_all_and_run_tests.sh:*)",
98
"Bash(./scripts/lint.sh:*)",
109
"Bash(./scripts/run_mypy.sh:*)",
1110
"Bash(./scripts/run_tests.sh:*)",

‎AGENTS.md‎

Lines changed: 102 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -37,71 +37,44 @@ These are the most important constraints in this project. Violating any of them
3737

3838
### Package Structure
3939

40-
```text
41-
slack_sdk/ # Main package (active development)
42-
├── web/ # Web API client (sync, async, legacy)
43-
│ ├── client.py # *** CANONICAL SOURCE — edit this file ***
44-
│ ├── async_client.py # AUTO-GENERATED from client.py (do not edit)
45-
│ ├── legacy_client.py # AUTO-GENERATED from client.py (do not edit)
46-
│ ├── base_client.py # Sync HTTP transport (urllib)
47-
│ ├── async_base_client.py # Async HTTP transport (aiohttp)
48-
│ ├── legacy_base_client.py
49-
│ ├── slack_response.py # Response wrapper (sync)
50-
│ ├── async_slack_response.py
51-
│ ├── chat_stream.py # Streaming chat (edit this file)
52-
│ ├── async_chat_stream.py # AUTO-GENERATED from chat_stream.py (do not edit)
53-
│ └── internal_utils.py # Shared helpers
54-
├── webhook/ # Incoming Webhooks & response_url
55-
├── socket_mode/ # Socket Mode (multiple backend implementations)
56-
│ ├── builtin/ # Built-in WebSocket (no extra deps)
57-
│ ├── aiohttp/ # aiohttp backend
58-
│ ├── websocket_client/ # websocket-client backend
59-
│ └── websockets/ # websockets backend
60-
├── oauth/ # OAuth V2 + OpenID Connect flows
61-
│ ├── installation_store/ # Token storage (file, SQLAlchemy, S3, etc.)
62-
│ ├── state_store/ # OAuth state management
63-
│ └── token_rotation/ # Token refresh logic
64-
├── models/ # Block Kit UI builders
65-
│ ├── blocks/ # Block elements
66-
│ ├── views/ # Modal views
67-
│ ├── attachments/ # Legacy attachments
68-
│ └── metadata/ # Event/entity metadata
69-
├── audit_logs/v1/ # Audit Logs API client
70-
├── scim/v1/ # SCIM API client
71-
├── signature/ # Request signature verification
72-
├── http_retry/ # HTTP retry handlers (builtin sync + async)
73-
├── rtm_v2/ # Real-time messaging (legacy)
74-
├── errors/ # Exception types
75-
└── version.py # Single source of truth for version
76-
77-
slack/ # Legacy package (maintenance mode, do not modify)
78-
```
40+
The SDK is organized into independent sub-packages:
7941

80-
### Code Generation (Critical Pattern)
42+
- **`slack_sdk/web/`** — Web API client (sync, async, legacy). Contains auto-generated files (see [Code Generation](#code-generation-critical-pattern))
43+
- **`slack_sdk/webhook/`** — Incoming Webhooks
44+
- **`slack_sdk/socket_mode/`** — Socket Mode with pluggable backends
45+
- **`slack_sdk/oauth/`** — OAuth flows and token storage
46+
- **`slack_sdk/models/`** — Block Kit UI builders
47+
- **`slack_sdk/audit_logs/`**, **`slack_sdk/scim/`** — Enterprise APIs
48+
- **`slack_sdk/signature/`** — Request verification
49+
- **`slack_sdk/http_retry/`** — Retry handlers
50+
- **`slack/`** — Legacy package (maintenance mode, do not modify)
8151

82-
The SDK uses code generation to maintain sync/async/legacy variants from a single source of truth. This is the most important pattern to understand:
52+
See the repository structure for the complete package layout.
8353

84-
1. **`slack_sdk/web/client.py`** is the canonical source for all Web API methods
85-
2. **`scripts/codegen.py`** transforms `client.py` into:
86-
- `async_client.py` — adds `async def`, `await`, replaces classes with async variants
87-
- `legacy_client.py` — adds `Union[Future, SlackResponse]` return types
88-
3. Similarly, `chat_stream.py` generates `async_chat_stream.py`
54+
### Code Generation (Critical Pattern)
8955

90-
**Never edit auto-generated files directly.** They contain a header:
56+
**NEVER edit these auto-generated files:**
9157

58+
- `slack_sdk/web/async_client.py`
59+
- `slack_sdk/web/legacy_client.py`
60+
- `slack_sdk/web/async_chat_stream.py`
61+
62+
Each contains a header warning:
9263
```text
9364
# DO NOT EDIT THIS FILE
9465
# 1) Modify slack_sdk/web/client.py
9566
# 2) Run `python scripts/codegen.py`
9667
# 3) Run `black slack_sdk/`
9768
```
9869

99-
After editing `client.py` or `chat_stream.py`, always run:
70+
**How it works:**
10071

101-
```sh
102-
python scripts/codegen.py --path .
103-
./scripts/format.sh
104-
```
72+
1. Edit `slack_sdk/web/client.py` (canonical source for Web API methods)
73+
2. Edit `slack_sdk/web/chat_stream.py` (canonical source for streaming chat)
74+
3. Run `python scripts/codegen.py --path .` to generate async/legacy variants
75+
4. Run `./scripts/format.sh` to format the generated code
76+
77+
The codegen script (`scripts/codegen.py`) automatically transforms sync code into async variants by adding `async def`, `await`, and replacing classes with async equivalents.
10578

10679
### Web API Method Pattern
10780

@@ -135,28 +108,27 @@ Key conventions:
135108

136109
### Error Types
137110

138-
Defined in `slack_sdk/errors/__init__.py`:
111+
All SDK exceptions are defined in `slack_sdk/errors/__init__.py` and inherit from `SlackClientError`.
139112

140-
| Exception | When raised |
141-
| --- | --- |
142-
| `SlackClientError` | Base class for all client errors |
143-
| `SlackApiError` | Invalid API response (carries the `response` object) |
144-
| `SlackRequestError` | Problem submitting the request |
145-
| `BotUserAccessError` | `xoxb` token used for a `xoxp`-only method |
146-
| `SlackTokenRotationError` | `oauth.v2.access` token rotation failure |
147-
| `SlackClientNotConnectedError` | WebSocket operation while disconnected |
148-
| `SlackObjectFormationError` | Malformed Block Kit or other SDK objects |
149-
| `SlackClientConfigurationError` | Invalid client-side configuration |
113+
Key exceptions to be aware of:
114+
115+
- **`SlackApiError`** — Raised when the API returns an error response (carries the `response` object)
116+
- **`SlackRequestError`** — Raised when the HTTP request itself fails
117+
- **`BotUserAccessError`** — Raised when using a bot token (`xoxb-*`) for a user-only method
118+
119+
See `slack_sdk/errors/__init__.py` for the complete list of exception types and their usage.
150120

151121
### HTTP Retry Handlers
152122

153-
The `slack_sdk/http_retry/` module provides built-in retry strategies:
123+
The `slack_sdk/http_retry/` module provides built-in retry strategies for connection errors, rate limiting (HTTP 429), and server errors (HTTP 500/503).
154124

155-
- **`ConnectionErrorRetryHandler`** / **`AsyncConnectionErrorRetryHandler`** — retries on connection errors
156-
- **`RateLimitErrorRetryHandler`** / **`AsyncRateLimitErrorRetryHandler`** — retries on HTTP 429 (respects `Retry-After`)
157-
- **`ServerErrorRetryHandler`** / **`AsyncServerErrorRetryHandler`** — retries on HTTP 500/503
125+
Key handlers:
158126

159-
Retry interval is configurable via `BackoffRetryIntervalCalculator` (exponential backoff) or `FixedValueRetryIntervalCalculator`.
127+
- **`ConnectionErrorRetryHandler`** / **`AsyncConnectionErrorRetryHandler`**
128+
- **`RateLimitErrorRetryHandler`** / **`AsyncRateLimitErrorRetryHandler`** (respects `Retry-After` header)
129+
- **`ServerErrorRetryHandler`** / **`AsyncServerErrorRetryHandler`**
130+
131+
Retry intervals can be configured with `BackoffRetryIntervalCalculator` (exponential backoff) or `FixedValueRetryIntervalCalculator`. See `slack_sdk/http_retry/` for implementation details.
160132

161133
### Test Patterns
162134

@@ -200,8 +172,9 @@ Test directories:
200172

201173
### Setup
202174

203-
A python virtual environment (`venv`) MUST be activated before running any commands. You can verify that the virtual environment is active by checking if the `$VIRTUAL_ENV` environment variable is set with `echo $VIRTUAL_ENV`.
204-
If tools like `black`, `flake8`, `mypy`, or `pytest` are not found, ask the user to activate the venv.
175+
**Prerequisites:** A Python virtual environment must be activated. See `.github/maintainers_guide.md` for detailed setup instructions using `pyenv` and `venv`.
176+
177+
**Quick check:** Verify venv is active with `echo $VIRTUAL_ENV` (should output a path).
205178

206179
Always use the project scripts instead of calling tools like `pytest` directly.
207180

@@ -219,51 +192,77 @@ Installs all project dependencies (testing, optional, and tools) via pip. This s
219192
./scripts/run_validation.sh
220193
```
221194

222-
This is the canonical check — CI runs this and the PR template asks contributors to run it. It installs requirements, runs codegen, formats, lints, runs tests with coverage, and runs mypy type checking on Python 3.14.
195+
This is the canonical check — CI runs this and the PR template asks contributors to run it. It installs requirements, runs codegen, formats, lints, runs tests with coverage, and runs mypy type checking on the latest supported Python version (check the `LATEST_SUPPORTED_PY` environment variable in `.github/workflows/ci-build.yml`).
223196

224197
### Individual Commands
225198

226-
| Task | Command |
227-
| --------------------------- | -------------------------------------------------------------------- |
228-
| Install dependencies | `./scripts/install.sh` |
229-
| Uninstall all packages | `./scripts/uninstall_all.sh` |
230-
| Format code | `./scripts/format.sh` |
231-
| Lint (check formatting) | `./scripts/lint.sh` |
232-
| Run all unit tests | `./scripts/run_tests.sh` |
233-
| Run a specific test | `./scripts/run_tests.sh tests/slack_sdk/web/test_web_client.py` |
234-
| Run type checking | `./scripts/run_mypy.sh` |
235-
| Generate async/legacy code | `python scripts/codegen.py --path .` |
236-
| Build PyPI package | `./scripts/build_pypi_package.sh` |
237-
| Generate API docs | `./scripts/generate_api_docs.sh` |
199+
Available scripts in the `scripts/` directory:
200+
201+
| Task | Command |
202+
| --- | --- |
203+
| Install dependencies | `./scripts/install.sh` |
204+
| Uninstall all packages | `./scripts/uninstall_all.sh` |
205+
| Format code | `./scripts/format.sh` |
206+
| Lint (check formatting) | `./scripts/lint.sh` |
207+
| Run all unit tests | `./scripts/run_tests.sh` |
208+
| Run a specific test | `./scripts/run_tests.sh tests/slack_sdk/web/test_web_client.py` |
209+
| Run type checking | `./scripts/run_mypy.sh` |
210+
| Generate async/legacy code | `python scripts/codegen.py --path .` |
211+
| Build PyPI package | `./scripts/build_pypi_package.sh` |
212+
| Generate API docs | `./scripts/generate_api_docs.sh` |
238213

239214
## Code Style & Tooling
240215

241-
- **Formatter**: `black` (line length: 125, version pinned in `requirements/tools.txt`)
242-
- **Linter**: `flake8` (line length: 125, configured in `.flake8`)
243-
- **Type checker**: `mypy` (configured in `pyproject.toml`, excludes `scim/` and `rtm/`)
244-
- **Test runner**: `pytest` with `pytest-asyncio` (asyncio_mode = "auto")
216+
All tooling configuration is defined in the following files:
217+
218+
- **Formatter**: `black` — see `[tool.black]` in `pyproject.toml`
219+
- **Linter**: `flake8` — see `.flake8`
220+
- **Type checker**: `mypy` — see `[tool.mypy]` in `pyproject.toml`
221+
- **Test runner**: `pytest` — see `[tool.pytest.ini_options]` in `pyproject.toml`
245222
- **Coverage**: `pytest-cov` reporting to Codecov
246-
- **Build system**: `setuptools` via `pyproject.toml`
223+
- **Build system**: see `[build-system]` and `[project]` in `pyproject.toml`
224+
225+
**Dependencies:**
226+
227+
- Testing: `requirements/testing.txt`
228+
- Optional runtime: `requirements/optional.txt`
229+
- Dev tools (black, flake8, mypy): `requirements/tools.txt`
247230

248231
## CI Pipeline (GitHub Actions)
249232

250233
Defined in `.github/workflows/ci-build.yml`, runs on push to `main`, all PRs, and daily schedule. Check the workflow file for the current Python version matrix.
251234

252-
## Key Files
253-
254-
| File | Purpose |
255-
| ----------------------------------- | -------------------------------------------------------- |
256-
| `slack_sdk/version.py` | Single source of truth for package version |
257-
| `slack_sdk/web/client.py` | Canonical Web API client (~200+ methods) |
258-
| `slack_sdk/web/chat_stream.py` | Canonical streaming chat client |
259-
| `scripts/codegen.py` | Code generator for async/legacy client variants |
260-
| `pyproject.toml` | Project config (build, black, pytest, mypy settings) |
261-
| `.flake8` | Flake8 linting config |
262-
| `requirements/testing.txt` | Test dependencies |
263-
| `requirements/optional.txt` | Optional runtime dependencies (aiohttp, SQLAlchemy, etc) |
264-
| `requirements/tools.txt` | Dev tools (black, flake8, mypy) |
265-
| `.github/workflows/ci-build.yml` | CI pipeline definition |
266-
| `.github/maintainers_guide.md` | Maintainer workflows and release process |
235+
## Key Files & Directories
236+
237+
**Source Code:**
238+
239+
- `slack_sdk/` — Main package (active development)
240+
- `slack_sdk/web/client.py` — **CANONICAL SOURCE** for all Web API methods
241+
- `slack_sdk/web/chat_stream.py` — Canonical streaming chat client
242+
- `slack_sdk/version.py` — Single source of truth for version
243+
- `slack/` — Legacy package (maintenance mode, DO NOT MODIFY)
244+
245+
**Configuration:**
246+
247+
- `pyproject.toml` — Project metadata, build config, tool settings (black, pytest, mypy)
248+
- `.flake8` — Flake8 linter configuration
249+
- `requirements/*.txt` — Dependency specifications
250+
251+
**Tooling:**
252+
253+
- `scripts/codegen.py` — Generates async/legacy client variants
254+
- `scripts/*.sh` — Development and CI helper scripts
255+
256+
**GitHub & CI/CD:**
257+
258+
- `.github/` — GitHub-specific configuration and documentation
259+
- `.github/workflows/` — Continuous integration pipeline definitions that run on GitHub Actions
260+
- `.github/maintainers_guide.md` — Maintainer workflows and release process
261+
262+
**Documentation:**
263+
264+
- `README.md` — Project overview, installation, and usage examples
265+
- `.github/maintainers_guide.md` — Maintainer workflows and release process
267266

268267
## Common Contribution Workflows
269268

0 commit comments

Comments
 (0)