Fastmcp Proper

🚀 Python Best Practices Guide

This guide provides a comprehensive set of best practices for Python projects, covering project initialization, code style, testing, documentation, and more.

🚀 Quick Start

Project Initialization

Before starting to write code, run the following commands to initialize a new Python project:

python -m venv venv && source venv/bin/activate
pip install --upgrade pip setuptools wheel

This will create a virtual environment and install the necessary build tools.

✨ Features

Code Style Guide

Basic Principles

1. Follow the PEP8 standard.
2. Ensure code readability and simplicity.
3. Avoid using from module import * statements.

Example Code

# Correct example:
import os

def greet(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    name = input("Please enter your name: ")
    print(greet(name))

Project Structure

The recommended project directory structure is as follows:

project/
├── src/
│   ├── __init__.py
│   └── main.py
├── tests/
│   ├── __init__.py
│   └── test_main.py
├── setup.py
└── pyproject.toml

Testing Guide

Unit Testing

Use the unittest framework for unit testing. Create a tests directory and write test cases in it.

Example Test Code

import unittest
from src.main import greet

class TestGreet(unittest.TestCase):
    def test_greet_with_name(self):
        self.assertEqual(greet("Alice"), "Hello, Alice!")

if __name__ == "__main__":
    unittest.main()

Test Coverage

Use the coverage tool to measure test coverage:

coverage run -m unittest tests/
coverage report

Documentation Writing

Create Documentation with Sphinx

1. Install Sphinx and related tools:

pip install sphinx setuptools-sphinx

2. Create documentation in the project root directory:

cd project
sphinx-apidoc -o docs/ src/

3. Open docs/index.html to view the generated documentation.

Dependency Management

Use requirements File

Create a requirements.txt file in the project root directory and list all dependencies:

setuptools>=60.0.0
wheel>=0.37.1

Package Building and Publishing

Environment Preparation

Ensure the following tools are installed:

pip install build twine

Packaging Steps

1. Create source distribution and wheel packages:

python -m build

2. Check that the generated files are in the dist/ directory.

Publish to TestPyPI and PyPI

Upload with Twine

1. Configure PyPI credentials by editing the ~/.pypirc file:

[distutils]
index-servers = pypi testpypi

[pypi]
username = your_username
password = your_password

[testpypi]
username = your_test_username
password = your_test_password

2. Upload to TestPyPI:

twine upload --repository testpypi dist/*

3. Upload to PyPI:

twine upload dist/*

Automate Publishing with GitHub Actions

Create a GitHub Actions Workflow File

Create a .github/workflows/publish.yml file:

name: Publish to PyPI

on:
  release:
    types: [created]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v2
      
    - name: Set up virtual environment and install dependencies
      run: |
        python -m venv venv && source venv/bin/activate
        pip install --upgrade pip setuptools wheel
        
    - name: Package the project
      run: python -m build

    - name: Upload to PyPI
      uses: twinebot/twine-action@v1
      with:
        twineUserName: ${{ secrets.PYPI_USERNAME }}
        twinePassword: ${{ secrets.PYPI_PASSWORD }}

Create Repository Secrets

Set the following secrets in GitHub Actions:

• PYPI_USERNAME: PyPI username
• PYPI_PASSWORD: PyPI password

Semantic Versioning

Follow the SemVer standard, with the format MAJOR.MINOR.PATCH.

Example Version Number Meanings

• 1.0.0: Initial release
• 2.3.1: Feature improvements and bug fixes
• 2.4.0: New features added
• 3.0.0: Major updates or non-backward-compatible changes

Install Dependencies

Use the following command to install project dependencies:

pip install -r requirements.txt

Summary of Best Practices

1. Follow the PEP8 coding standard.
2. Use virtual environments to manage dependencies.
3. Keep code simple and maintainable.
4. Write sufficient test cases.
5. Use documentation tools to record the project.
6. Configure dependency management correctly.
7. Update project versions regularly.
8. Implement automated publishing through CI/CD.

For further information, please refer to the Python official documentation or join the Python developer community.