Skip to content

docs: enhance CLAUDE.md with development commands and architecture details #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
franccesco merged 1 commit into from
Dec 10, 2025
Merged

docs: enhance CLAUDE.md with development commands and architecture details #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 39 additions & 4 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,34 @@

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

```bash
# Install dependencies
uv sync --all-extras

# Run all tests with coverage
uv run pytest

# Run a single test file
uv run pytest tests/test_users.py

# Run a specific test
uv run pytest tests/test_users.py::test_user_details -v

# Format code
uv run ruff format .

# Lint and auto-fix
uv run ruff check . --fix

# Type checking (strict mode)
uv run pyright

# Build documentation
uv run mkdocs serve
```

## Architecture Overview

### SDK Structure
Expand All @@ -22,10 +50,17 @@ The Bloomy Python SDK is organized as a client-based architecture where all API

3. **Operations Pattern**:
- Each API resource has its own operations class (e.g., `UserOperations`, `MeetingOperations`)
- All operation classes inherit from `BaseOperations` which provides lazy-loaded user ID
- Sync operations in `src/bloomy/operations/` inherit from `BaseOperations`
- Async operations in `src/bloomy/operations/async_/` inherit from `AsyncBaseOperations`
- Both inherit from `AbstractOperations` which provides shared logic
- Operations are accessed via client attributes: `client.user`, `client.meeting`, etc.

4. **API Endpoints**:
4. **Models (`src/bloomy/models.py`)**:
- Pydantic models for type-safe API responses
- All models inherit from `BloomyBaseModel` with common config
- Field aliases map PascalCase API responses to snake_case Python attributes

5. **API Endpoints**:
- Base URL: `https://app.bloomgrowth.com/api/v1`
- Authentication: Bearer token in Authorization header
- All responses are JSON
Expand All @@ -41,9 +76,9 @@ The Bloomy Python SDK is organized as a client-based architecture where all API
- `APIError` includes status code
- HTTP errors are raised via `response.raise_for_status()`

4. **Type Annotations**: Uses Python 3.12+ union syntax (`|`) and TypedDict for structured return types.
4. **Type Annotations**: Uses Python 3.12+ union syntax (`|`) and Pydantic models for structured return types.

5. **Testing**: Mock-based testing with `unittest.mock`. Fixtures defined in `conftest.py` provide sample data and mock HTTP client.
5. **Testing**: Mock-based testing with `unittest.mock`. Fixtures in `tests/conftest.py` provide sample data and mock HTTP client. Use `pytest-asyncio` for async tests.

### API Operations Reference

Expand Down