https://github.com/engineervix/hello-flit
This is a python project created with the sole purpose of testing out flit
https://github.com/engineervix/hello-flit
Last synced: 12 months ago
JSON representation
This is a python project created with the sole purpose of testing out flit
- Host: GitHub
- URL: https://github.com/engineervix/hello-flit
- Owner: engineervix
- License: mit
- Created: 2022-06-14T12:44:19.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-12T00:06:52.000Z (about 1 year ago)
- Last Synced: 2025-03-12T01:19:41.357Z (about 1 year ago)
- Language: Python
- Size: 494 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
Welcome to Hello Flit 👋
> A python project created with the sole purpose of testing out [Flit](https://flit.pypa.io/en/latest/index.html)
**Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [What's Flit?](#whats-flit)
- [What does this project do?](#what-does-this-project-do)
- [Project features](#project-features)
- [Documentation](#documentation)
- [Installation](#installation)
- [Usage](#usage)
- [Development](#development)
- [First things first](#first-things-first)
- [Getting Started](#getting-started)
- [Tests](#tests)
- [Code Formatting](#code-formatting)
- [Versioning / Creating a GitHub Release and Auto Publishing to PyPI](#versioning--creating-a-github-release-and-auto-publishing-to-pypi)
- [Publishing](#publishing)
- [Contributing](#contributing)
- [TODO](#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?](https://flit.readthedocs.io/en/latest/rationale.html) 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:
```txt
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](https://github.com/audreyfeldroy/cookiecutter-pypackage)
- Supports Python 3.6+
- Tests written using [Pytest](https://docs.pytest.org/), linting with [black](https://github.com/psf/black), [flake8](https://flake8.pycqa.org/en/latest/), [isort](https://github.com/PyCQA/isort)
- Uses [Invoke](https://www.pyinvoke.org/) for task execution
- Uses [tox](https://tox.wiki/en/latest/) for test automation
- The CLI is powered by [Typer](https://typer.tiangolo.com)
- Documentation using [mkdocs](https://mkdocs.org/) and [mkdocs-material](https://squidfunk.github.io/mkdocs-material)
## Documentation
Read the docs:
## Installation
```bash
pip install -i https://test.pypi.org/simple --extra-index-url https://pypi.python.org/simple hello-flit
```
## Usage
```txt
Usage: hello-flit [OPTIONS] [YEAR]
Arguments:
[YEAR] the year for which you'd like to create a directory tree [default: ]
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+](https://www.python.org/) on your machine, and that you are able to configure python [**virtual environment**](https://realpython.com/python-virtual-environments-a-primer/)s.
- ensure that you have [git](https://git-scm.com/) setup on your machine.
### Getting Started
First, [fork](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo) 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](https://pre-commit.com/) 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
```sh
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`](https://flake8.pycqa.org/en/latest/), [`black`](https://black.readthedocs.io/en/stable/), [`isort`](https://pycqa.github.io/isort/) and [`mypy`](https://mypy.readthedocs.io/en/stable/) 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](https://github.com/engineervix/hello-flit/blob/main/.pre-commit-config.yaml).
## Versioning / Creating a GitHub Release and Auto Publishing to PyPI
This project uses both [commitizen-tools](https://github.com/commitizen-tools/commitizen) and [standard-version](https://github.com/conventional-changelog/standard-version) to manage package versions and changelogs. The former is a python package, and is included in [`requirements-dev.txt`](./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`](./.versionrc).
To bump to the next version:
```bash
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](https://wiki.python.org/moin/CheeseShop).
## Publishing
```bash
# 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](https://github.com/engineervix/hello-flit/issues) and take a look at the [contributing guide](https://github.com/engineervix/hello-flit/blob/main/CONTRIBUTING.md) 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](https://www.conventionalcommits.org/en/v1.0.0/). 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](https://github.com/engineervix/hello-flit/pulls).
## TODO
- [x] Replicate this but with a Wagtail / Django package. See [@engineervix/hello-flit-django-modelcluster](https://github.com/engineervix/hello-flit-django-modelcluster)