# Development Guide

This guide covers contributing to and developing the FastGPT Python SDK.

## Development Setup

### Clone the Repository

```bash
git clone https://github.com/yourusername/fastgpt-python-sdk.git
cd fastgpt-python-sdk
```

### Install in Development Mode

```bash
pip install -e ".[dev]"
```

This installs:
- The SDK in editable mode
- Development dependencies (pytest, ruff, etc.)

## Project Structure

```
fastgpt-python-sdk/
├── fastgpt_client/
│   ├── __init__.py              # Public API exports
│   ├── client.py                # Sync clients (ChatClient, AppClient)
│   ├── async_client.py          # Async clients
│   ├── base_client.py           # Base functionality (retry, validation)
│   └── exceptions.py            # Custom exceptions
├── tests/
│   ├── test_chat_client.py      # ChatClient tests
│   ├── test_app_client.py       # AppClient tests
│   └── test_async_client.py     # Async client tests
├── examples/
│   ├── basic_usage.py           # Basic usage examples
│   └── async_usage.py           # Async usage examples
├── docs/                        # MkDocs documentation
├── setup.py                     # Package setup
├── pyproject.toml               # Project configuration
└── mkdocs.yml                   # Documentation config
```

## Running Tests

### Run All Tests

```bash
pytest
```

### Run Specific Test File

```bash
pytest tests/test_chat_client.py
```

### Run with Coverage

```bash
pytest --cov=fastgpt_client --cov-report=html
```

### Run with Verbose Output

```bash
pytest -v
```

## Code Quality

### Lint with Ruff

```bash
ruff check fastgpt_client/
```

### Format with Ruff

```bash
ruff format fastgpt_client/
```

### Fix Linting Issues

```bash
ruff check --fix fastgpt_client/
```

## Building Documentation

### Install Documentation Dependencies

```bash
pip install mkdocs-material mkdocstrings[python]
```

### Build Documentation

```bash
mkdocs build
```

### Serve Documentation Locally

```bash
mkdocs serve
```

Then open http://127.0.0.1:8000 in your browser.

## Creating a Release

### Update Version

Update `fastgpt_client/__init__.py`:

```python
__version__ = "0.2.0"
```

### Build Package

```bash
python -m build
```

### Publish to PyPI

```bash
twine upload dist/*
```

## Contribution Guidelines

### Code Style

- Use **Google-style docstrings**
- Follow **PEP 8** formatting (handled by Ruff)
- Keep functions focused and single-purpose
- Add type hints for all public methods

### Adding Features

1. **Create a feature branch**
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Write tests first**
   ```python
   def test_new_feature():
       client = ChatClient(api_key="test-key")
       result = client.new_method()
       assert result is not None
   ```

3. **Implement the feature**
   ```python
   def new_method(self):
       """Do something new.

       Returns:
           The result.
       """
       # Implementation
       pass
   ```

4. **Add documentation**
   - Update docstrings
   - Add usage examples
   - Update API reference

5. **Run tests**
   ```bash
   pytest
   ```

6. **Submit a pull request**

### Writing Tests

```python
import pytest
from fastgpt_client import ChatClient
from httpx import Response

def test_create_chat_completion():
    """Test chat completion creation."""
    client = ChatClient(api_key="test-key")

    response = client.create_chat_completion(
        messages=[{"role": "user", "content": "Hello"}],
        stream=False
    )

    assert response.status_code == 200
```

## Useful Commands

| Command | Description |
|---------|-------------|
| `pytest` | Run all tests |
| `pytest -v` | Verbose test output |
| `pytest --cov` | Run with coverage |
| `ruff check` | Lint code |
| `ruff format` | Format code |
| `mkdocs serve` | Serve docs locally |
| `mkdocs build` | Build docs |
| `python -m build` | Build package |

## Resources

- [FastGPT Documentation](https://doc.fastgpt.io/)
- [Chat API Docs](https://doc.fastgpt.io/docs/introduction/development/openapi/chat)
- [PyPI Publishing Guide](https://packaging.python.org/tutorials/packaging-projects/)
- [pytest Documentation](https://docs.pytest.org/)
- [Ruff Documentation](https://docs.astral.sh/ruff/)