engineervix/hello-flit

This is a python project created with the sole purpose of testing out flit

Welcome to Hello Flit 👋

A python project created with the sole purpose of testing out Flit

Contents generated with DocToc

• What's Flit?
• What does this project do?
• Project features
• Documentation
• Installation
• Usage
• Development
  • First things first
  • Getting Started
  • Tests
  • Code Formatting
• Versioning / Creating a GitHub Release and Auto Publishing to PyPI
• Publishing
• Contributing
• TODO

What's Flit?

According to the official docs:

Flit is a simple way to put Python packages and modules on PyPI. It tries to require less thought about packaging and help you avoid common mistakes. See Why use Flit? for more about how it compares to other Python packaging tools.

What does this project do?

Well, what this project does isn't very important. The main point of this project is to try out packaging with Flit. However, since you asked, this project provides a simple CLI utility to create a directory tree suitable for organizing your work using the Year / Quarter / Month / Week convention, for instance:

2017/
├── qtr_01
│   ├── 01_Jan
│   │   ├── wk01_01Jan-07Jan
│   │   ├── wk02_08Jan-14Jan
│   │   ├── wk03_15Jan-21Jan
│   │   ├── wk04_22Jan-28Jan
│   │   └── wk05_29Jan-04Feb
│   ├── 02_Feb
│   │   ├── wk05_29Jan-04Feb
│   │   ├── wk06_05Feb-11Feb
│   │   ├── wk07_12Feb-18Feb
│   │   ├── wk08_19Feb-25Feb
│   │   └── wk09_26Feb-04Mar
│   └── 03_Mar
│       ├── wk09_26Feb-04Mar
│       ├── wk10_05Mar-11Mar
│       ├── wk11_12Mar-18Mar
│       ├── wk12_19Mar-25Mar
│       └── wk13_26Mar-01Apr
├── qtr_02
│   ├── 04_Apr
│   │   ├── wk13_26Mar-01Apr
│   │   ├── wk14_02Apr-08Apr
│   │   ├── wk15_09Apr-15Apr
│   │   ├── wk16_16Apr-22Apr
│   │   ├── wk17_23Apr-29Apr
│   │   └── wk18_30Apr-06May
│   ├── 05_May
│   │   ├── wk18_30Apr-06May
│   │   ├── wk19_07May-13May
│   │   ├── etc, you get the picture!

Project features

• This is more-or-less a typical python package, with a structure similar to that created using @audreyfeldroy/cookiecutter-pypackage
• Supports Python 3.6+
• Tests written using Pytest, linting with black, flake8, isort
• Uses Invoke for task execution
• Uses tox for test automation
• The CLI is powered by Typer
• Documentation using mkdocs and mkdocs-material

Documentation

Read the docs: https://engineervix.github.io/hello-flit/

Installation

pip install -i https://test.pypi.org/simple --extra-index-url https://pypi.python.org/simple hello-flit

Usage

Usage: hello-flit [OPTIONS] [YEAR]

Arguments:
  [YEAR]  the year for which you'd like to create a directory tree  [default: <current_year>]

Options:
  -v, --version         Show the application's version and exit.
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or
                        customize the installation.
  --help                Show this message and exit.

Development

First things first

• ensure that you have Python 3.6+ on your machine, and that you are able to configure python virtual environments.
• ensure that you have git setup on your machine.

Getting Started

First, fork this repository, then fire up your command prompt and ...

1. Clone the forked repository
2. Navigate to the cloned project directory: cd hello-flit
3. activate your python virtual environment and pip install --upgrade pip
4. Install dependencies: pip install -r requirements_dev.txt
5. Setup pre-commit by running pre-commit install followed by pre-commit install --hook-type commit-msg. Optionally run pre-commit run --all-files to make sure your pre-commit setup is okay.

At this stage, hopefully everything should be working fine, and you should be able to start hacking on the project.

You can run the application via inv run [options] or

python hello_flit/cli.py [options]

Tests

Simply run pytest or inv test to run tests in your virtual environment.

Test other Python versions by running tox.

Code Formatting

• Run invoke lint to run flake8, black, isort and mypy on the code.
• If you get any errors from black and/or isort, run invoke lint --fix or invoke lint -f so that black and isort can format your files. Alternatively, just run pre-commit. You can take a look at .pre-commit-config.yaml.

Versioning / Creating a GitHub Release and Auto Publishing to PyPI

This project uses both commitizen-tools and standard-version to manage package versions and changelogs. The former is a python package, and is included in requirements-dev.txt, while the latter is a Node.js package (you'll need to install it globally: npm i -g standard-version), whose config file is .versionrc.

To bump to the next version:

inv bump

This will automagically create a tag, update the Changelog, commit the changes and push to your GitHub repo. If the CI tests are successful, a GitHub Release will be created and Flit will publish your package to the CheeseShop.

Publishing

# to TestPyPI
flit publish --repository testpypi

# to PyPI
flit publish

Contributing

Contributions, issues and feature requests are most welcome!

Feel free to check the issues page and take a look at the contributing guide before you get started. In addition, please note the following:

• if you're making code contributions, please try and write some tests to accompany your code, and ensure that the tests pass. Also, were necessary, update the docs so that they reflect your changes.
• commit your changes via cz commit. Follow the prompts. When you're done, pre-commit will be invoked to ensure that your contributions and commits follow defined conventions. See pre-commit-config.yaml for more details.
• your commit messages should follow the conventions described here. Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert. Once you are done, please create a pull request.

TODO

• Replicate this but with a Wagtail / Django package. See @engineervix/hello-flit-django-modelcluster