Skip to content

Latest commit

 

History

History
193 lines (136 loc) · 7.17 KB

README.md

File metadata and controls

193 lines (136 loc) · 7.17 KB
Raw

PyPoject Starter

Build Status license Documentation Status GitHub repo size codecov

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

  1. Create a new folder under src folder.
  2. You can copy the hello project as a template.
  3. Add folder name to packages in pyproject.toml file.
  4. 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

install poetry

See poetry installation.

install python3

See python installation.

install pre-commit

See pre-commit installation.

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.

License

MIT License © 2022 funnyzak