Package: python-starter-package
python-starterExample Python project that demonstrates how to create a tested Python package using the latest
Python testing and linting tooling. The project contains adivpackage that provides a simple
implementation of division (div.lib)
and a command line interface (div.cli).RequirementsPython 3.6+.NoteBecausePython 2.7 support ended January 1, 2020, new projects
should consider supporting Python 3 only, which is simpler than trying to support both. As a
result, support for Python 2.7 in this example project has been dropped.Running CLI applicationexport PYTHONPATH="${PYTHONPATH}:<path_to_directory>/python-starter/src"python cli.py -a 5 -b 2DependenciesDependencies are defined in:requirements.txtdev-requirements.txtVirtual EnvironmentsIt is best practice during development to create an
isolatedPython virtualenv wrapperusing themkvirtualenvcommand. This will keep dependant Python packages from interfering with other
Python projects on your system.On *Nix:$mkvirtualenv-ppython3.xvenvIt is good practice to update core packaging tools (pip,setuptools,
andwheel) to the latest versions.(venv)$python-mpipinstall--upgradepipsetuptoolswheelInstalling DependenciesTo update dependencies:(venv)$pipinstall-rrequirements.txt(venv)$pipinstall-rdev-requirements.txtAfter upgrading dependencies, run the unit tests as described in theUnit Testingsection to ensure that none of the updated packages caused incompatibilities in the current
project.PackagingThis project is designed as a Python package, meaning that it can be bundled up and redistributed
as a single compressed file.Packaging is configured by:pyproject.tomlsetup.pyMANIFEST.inTo package the project as both asource distributionand
awheel:(venv)$pythonsetup.pysdistbdist_wheelThis will generatedist/div-1.0.0.tar.gzanddist/div-1.0.0-py3-none-any.whl.Read more about theadvantages of wheelsto understand why generating
wheel distributions are important.Upload Distributions to PyPISource and wheel redistributable packages can
beuploaded to PyPIor installed
directly from the filesystem usingpip.To upload to PyPI:(venv)$python-mpipinstalltwine(venv)$twineuploaddist/*TestingAutomated testing is performed usingtox. tox
will automatically create virtual environments based ontox.inifor unit testing, PEP8 style
guide checking, and documentation generation.# Run all environments.#   To only run a single environment, specify it like: -e lint# command above.(venv)$toxUnit TestingUnit testing is performed withpytest. pytest has become the defacto Python
unit testing framework. Some key advantages over the built
inunittestmodule are:Significantly less boilerplate needed for tests.PEP8 compliant names (e.g.pytest.raises()instead ofself.assertRaises()).Vibrant ecosystem of plugins.pytest will automatically discover and run tests by recursively searching for folders and.pyfiles prefixed withtestfor any functions prefixed bytest.Thetestsfolder is created as a Python package (i.e. there is an__init__.pyfile within it)
because this helpspytestuniquely namespace the test files. Without this, two test files cannot
be named the same, even if they are in different sub-directories.Code coverage is provided by thepytest-covplugin.When running a unit test tox environment (e.g.tox -e py36), an HTML report is generated in
thehtmlcovfolder showing each source file and which lines were executed during unit testing.
Openhtmlcov/index.htmlin a web browser to view the report. Code coverage reports help identify
areas of the project that are currently not tested.Code coverage is configured inpyproject.toml.To pass arguments topytestthroughtox:(venv)$tox-epy36---kinvalid_divideCode Style CheckingPEP8is the universally accepted style guide for
Python code. PEP8 code compliance is verified usingflake8. flake8 is
configured in the[flake8]section oftox.ini. Extra flake8 plugins are also included:pep8-naming: Ensure functions, classes, and variables are named with correct casing.Automated Code FormattingCode is automatically formatted usingblack. Imports are
automatically sorted and grouped usingisort.These tools are configured by:pyproject.tomlTo automatically format code, run:(venv)$tox-efmtTo verify code has been formatted, such as in a CI job:(venv)$tox-efmt-checkGenerated API DocumentationGenerate a New Sphinx ProjectTo generate the Sphinx project shown in this project:(venv)$mkdir-pdocs/api(venv)$cddocs/api(venv)$sphinx-quickstart--no-makefile--no-batchfile--extensionssphinx.ext.napoleon# When prompted, select all defaults.Modifyconf.pyappropriately:# Add the project's Python package to the path so that autodoc can find it.importosimportsyssys.path.insert(0,os.path.abspath("../../src"))You might also need to addapidoc/modules.rstinindex.rstfile (See line number 13). This has already been done for this project but might be helpful if you start a project of your own.API Documentation for thedivPython project modules is automatically
generated using aSphinxtox environment. Sphinx is a documentation
generation tool that is the defacto tool for Python API documentation. Sphinx uses
theRSTmarkup language.This project uses
thenapoleonplugin for
Sphinx, which renders Google-style docstrings. Google-style docstrings provide a good mix of
easy-to-read docstrings in code as well as nicely-rendered output."""Divides first input with the second input.Args:a: Numeratorb: DenominatorRaises:InvalidDivideError: If denominator is 0Returns:Computed division."""The Sphinx project is configured indocs/api/conf.py.This project uses thefuroSphinx theme for its elegant, simple to
use, dark theme.Build the docs using thedocs-apitox environment (e.g.toxortox -e docs-api). Once built,
opendocs/api/_build/index.htmlin a web browser.To configure Sphinx to automatically rebuild when it detects changes, runtox -e docs-api-serveand openhttp://127.0.0.1:8000in a browser.