224 lines
4.3 KiB
Markdown
224 lines
4.3 KiB
Markdown
# 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/)
|