fastgpt-python-sdk/docs/development.md

Development Guide

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

Development Setup

Clone the Repository

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

Install in Development Mode

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

pytest

Run Specific Test File

pytest tests/test_chat_client.py

Run with Coverage

pytest --cov=fastgpt_client --cov-report=html

Run with Verbose Output

pytest -v

Code Quality

Lint with Ruff

ruff check fastgpt_client/

Format with Ruff

ruff format fastgpt_client/

Fix Linting Issues

ruff check --fix fastgpt_client/

Building Documentation

Install Documentation Dependencies

pip install mkdocs-material mkdocstrings[python]

Build Documentation

mkdocs build

Serve Documentation Locally

mkdocs serve

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

Creating a Release

Update Version

Update fastgpt_client/__init__.py:

__version__ = "0.2.0"

Build Package

python -m build

Publish to PyPI

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

   git checkout -b feature/your-feature-name
   

2. Write tests first

   def test_new_feature():
       client = ChatClient(api_key="test-key")
       result = client.new_method()
       assert result is not None
   

3. Implement the feature

   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

   pytest
   

6. Submit a pull request

Writing Tests

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
• Chat API Docs
• PyPI Publishing Guide
• pytest Documentation
• Ruff Documentation