starter-python-division-calculator 1.0.0
Python starter project
License: MIT
Requires Python: >=3.6
Keywords: python

# python-starter

[![GitHub Actions][github-actions-badge]](https://github.com/paulsabyasachi/python-starter/actions/)
[![Code style: black][black-badge]](https://github.com/psf/black)
[![Imports: isort][isort-badge]](https://pycqa.github.io/isort/)

[github-actions-badge]: https://github.com/paulsabyasachi/python-starter/workflows/python/badge.svg
[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
[isort-badge]: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336

Example Python project that demonstrates how to create a tested Python package using the latest
Python testing and linting tooling. The project contains a `div` package that provides a simple
implementation of division (`div.lib`)
and a command line interface (`div.cli`).

## Requirements

Python 3.6+.

> **Note**
>
> Because [Python 2.7 support ended January 1, 2020](https://pythonclock.org/), 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.

## Dependencies

Dependencies are defined in:

- `requirements.in`
- `requirements.txt`
- `dev-requirements.in`
- `dev-requirements.txt`

### Virtual Environments

It is best practice during development to create an
isolated [Python virtualenv wrapper](https://www.geeksforgeeks.org/using-mkvirtualenv-to-create-new-virtual-environment-python/) using the `mkvirtualenv`
command. This will keep dependant Python packages from interfering with other
Python projects on your system.

On *Nix:

```bash
$ mkvirtualenv -p python3.x venv
```

It is good practice to update core packaging tools (`pip`, `setuptools`,
and `wheel`) to the latest versions.

```bash
(venv) $ python -m pip install --upgrade pip setuptools wheel
```

### (Applications Only) Locking Dependencies

This project uses [pip-tools](https://github.com/jazzband/pip-tools) to lock project dependencies
and create reproducible virtual environments.

**Note:** *Library* projects should not lock their `requirements.txt`. Since `python-starter`
also has a CLI application, this end-user application example is used to demonstrate how to lock
application dependencies.

To update dependencies:

```bash
(venv) $ python -m pip install pip-tools
(venv) $ python -m piptools compile --upgrade requirements.in
(venv) $ python -m piptools compile --upgrade dev-requirements.in
```

After upgrading dependencies, run the unit tests as described in the [Unit Testing](#unit-testing)
section to ensure that none of the updated packages caused incompatibilities in the current
project.

### Syncing Virtual Environments

To cleanly install your dependencies into your virtual environment:

```bash
(venv) $ python -m piptools sync requirements.txt dev-requirements.txt
```

## Packaging

This 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.toml`
- `setup.py`
- `MANIFEST.in`

To package the project as both a 
[source distribution](https://docs.python.org/3/distutils/sourcedist.html) and
a [wheel](https://wheel.readthedocs.io/en/stable/):

```bash
(venv) $ python setup.py sdist bdist_wheel
```

This will generate `dist/div-1.0.0.tar.gz` and `dist/div-1.0.0-py3-none-any.whl`.

Read more about the [advantages of wheels](https://pythonwheels.com/) to understand why generating
wheel distributions are important.