PyPoject Starter

A template for the python project. It uses poetry for dependency management and tox for testing.

Features

Some features in this template project:

Use poetry for dependency management.
Use tox、pytest、pytest-cov、coverage for testing.
Use black、isort for code formatting.
Use flake8 link for code linting.
Use mypy for static type checking.
Use pre-commit for code quality.
Use ipdb3 for debugging.
Multiple python versions support(Python 3.8.1+).
More features to be added 🚀 .

Project

Contains the following projects under src as demo:

hello is a simple hello world project.
pdf_parse is a project that parse pdf.

Prerequisite

Run project need the following environment installed:

If you want development, you need to install pre-commit V3 for git hook scripts.

Installation

following the steps below to setup the project:

# Clone the repository
git clone git@github.com:funnyzak/pyproject-starter.git && cd pyproject-starter

# Install all dependencies
poetry install --sync --all-extras --with dev,test,coverage

# install git hook scripts for development
pre-commit install

# Other useful installation dependencies commands
# Install dependencies with all extras
poetry install --all-extras
# Install dependencies with extras 'pdf' for pdf_parse project
poetry install --extras "pdf"
# Install dependencies with group 'dev'、'test' for development
poetry install --with dev,test
# Only install required dependencies for production
poetry install

# Specify python version
poetry env use python3.9

Usage

There are some useful commands for development:

# Run project => hello
poetry run hello

# Run project => pdf_parse: merge pdf
poetry run merge_pdf_demo

# Run project => pdf_parse: parse multi pdf to multi-layer pdf
poetry run multi_layer_pdf_demo

# Extract text to json from pdf
poetry run extract_text_from_pdf

# Debug "hello" project with ipdb3
poetry run ipdb3 ./src/hello/main.py

# Code test
poetry run pytest -s

# Run default coverage test
poetry run tox

# Run hello project coverage test at python 3.9 and 3.10
poetry run tox -e py{39,310}-hello

# Lint with black
poetry run black ./src --check

# Format code with black
poetry run black ./src

# Check with mypy
poetry run mypy ./src

# Check import order with isort
poetry run isort ./src --check

# Lint with flake8
poetry run flake8 ./src

Q&A

Development

Add new project

Create a new folder under src folder.
You can copy the hello project as a template.
Add folder name to packages in pyproject.toml file.
Code and test it.

Tip for project

You can create test cases for the new project in tests folder.
You can define script commands for the new project in pyproject.toml file. like poetry run hello command.
You can add new project to tox.ini file for coverage test.
You can add new project to mypy.ini file for static type checking.

Environment setup

References

some useful references:

poetry is a dependency manager for Python that allows you to declare the libraries your project depends on and it will manage (install/update) them for you.
PyPDF2 is a library for working with PDF files.
flake8 is a wrapper around these tools: PyFlakes, pycodestyle, and Ned Batchelder’s McCabe script.
isort is a Python utility / library to sort imports alphabetically, and automatically separated into sections and by type.
black is a Python code formatter.
mypy is a static type checker for Python.
pytest is a testing framework for Python.
pytest-cov is a plugin for the pytest testing tool that measures coverage of Python code.
coverage is a tool for measuring code coverage of Python programs.
ipdb is a IPython-enabled pdb.
pre-commit is a framework for managing and maintaining multi-language pre-commit hooks.
tox is a generic virtualenv management and test command line tool you can use for:
- checking your package installs correctly with different Python versions and interpreters
- running your tests in each of the environments, configuring your test tool of choice
- acting as a frontend to Continuous Integration servers, greatly reducing boilerplate and merging CI and shell-based testing.

Contribution

If you have any questions or suggestions, please feel free to open an issue or pull request.