MCP Python Server

This is a Python project template that integrates code inspection and formatting tools such as ruff and black, uses pre-commit to manage hooks, includes the pytest testing framework and coverage plugin, and implements automated testing through Github Actions. It supports the devcontainer development environment and traditional virtual environments.

Developer tools Version control #Python Template #Code Inspection #Automated Testing #Development Tools .Python

rating : 2 points

downloads : 22

update time : 2025-04-28

What is this Python Project Template?

This is a starter template for Python projects that comes pre-configured with essential development tools like code formatters, linters, and testing frameworks. It helps developers quickly start new projects with best practices already in place.

How to use this template?

You can either use the built-in devcontainer for a containerized development environment or set up manually with virtualenv. The template includes pre-commit hooks for code quality checks and GitHub Actions for continuous integration.

When should I use this template?

Ideal for starting new Python projects of any size, especially when you want to ensure code quality from the beginning. Great for both individual developers and teams.

Key Features

Code Quality ToolsIncludes ruff (combining flake8, isort, pyupgrade) for linting and black for automatic code formatting

Testing FrameworkComes with pytest and pytest-cov for testing with coverage reporting

CI/CD IntegrationGitHub Actions workflow pre-configured to run checks on every pull request and merge

DevContainer SupportReady-to-use development container configuration for VS Code and GitHub Codespaces

Pros and Cons

Advantages

Saves setup time with pre-configured tools

Enforces consistent code style across team members

Containerized development environment reduces 'works on my machine' issues

Built-in CI/CD pipeline ensures code quality

Limitations

Initial learning curve for developers unfamiliar with the tools

Might include unnecessary tools for very simple projects

Default Python version (3.11) may need adjustment for some projects

Getting Started

Option 1: Use DevContainer

Open in VS Code with Dev Containers extension or GitHub Codespaces for automatic setup

Option 2: Manual Setup

Create virtual environment and install dependencies

Install Pre-commit Hooks

Set up git hooks to run quality checks before each commit

Start Developing

Replace the sample main.py and tests with your own code

Example Workflows

Adding New Feature1. Create feature branch 2. Write code 3. Add tests 4. Pre-commit checks will run automatically 5. Push to GitHub where CI runs full checks

Fixing Style IssuesWhen pre-commit finds style violations, it will either auto-fix them or show you what needs manual fixing

Frequently Asked Questions

How do I change the Python version?

Can I add more pre-commit hooks?

What if I don't want to use all these tools?

Additional Resources

Blog Post: How I Setup Python Projects

Detailed explanation of the template's design decisions

DevContainer Images

List of available Python devcontainer images

Pre-commit Hooks

Additional hooks you can add to the configuration

🚀 Python Project Template

This is a template repository suitable for any Python project, equipped with the following development tools:

ruff: Identifies many errors and style issues (like flake8, isort, pyupgrade).
black: Automatically formats code.

These checks are executed as pre - commit hooks using the pre-commit library.

The project includes pytest for testing and the pytest-cov plugin to measure coverage.

All checks and tests run on Github Actions for each pull request and merge to the main branch.

This repository is set up for Python 3.11. To change the version:

Change the image parameter in .devcontainer/devcontainer.json (see https://github.com/devcontainers/images/tree/main/src/python for a list of pre - built Docker images).
Change the configuration options in .precommit-config.yaml.
Change the version number in .github/workflows/python.yaml.

🚀 Quick Start

Using devcontainer

This repository contains a devcontainer (a Dockerized Python environment). If opened in Codespaces, it automatically initializes the devcontainer.

For local use, you can install the Dev Containers extension in VS Code to open it.

Without using devcontainer

If you can't or don't want to use the devcontainer, you should first create a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Then install the development tools and pre - commit hooks:

python3 -m pip install --user -r requirements-dev.txt
pre-commit install

Adding Code and Tests

This repository starts with a very simple main.py and a test file tests/main_test.py for it. You need to replace it with your own code and may need to add more files to increase code complexity.

When you're ready to run tests, execute:

python3 -m pytest

📚 Documentation

File Breakdown

Here is a brief description of some files/folders:

.devcontainer: Files and folders for setting up the devcontainer.
- devcontainer.json: A file for configuring the devcontainer, including VS Code settings.
.github: Files and folders specific to Github.
- workflows: The folder where Github Actions configuration files are located.
  - python.yaml: A file for configuring Github actions to run tools and tests.
tests: The Python test folder.
- main_test.py: A pytest - style test file for main.py.
.gitignore: A list of file patterns that Git should not track.
.pre-commit-config.yaml: A file listing all pre - commit hooks and their parameters.
main.py: The main (currently the only) Python file of the project.
pyproject.toml: A file for configuring most Python development tools.
README.md: You're reading it!
requirements-dev.txt: A file listing the PyPi packages required for development.
requirements.txt: A file listing the PyPi packages required for production.