essembeh / python-helloworld

Simple helloworld skeleton to help starting a new python project

Note: some badges above might not work unless you use CI (Github or Gitlab) and publish your app on Pypi

Introduction

This is just a sample helloworld project which aims to provide some good (at least not so bad) praticies to start a new project.

Basically, you can clone this repository and run sed -i 's/helloworld/YOURPROJECTNAME/g' ;)

Tools

There are multiple good Python IDE, but I'm would suggest using vscodium with at least these plugins:

• Python to add python language support
• Pyright for better python programming
• isort combined with black, your code will always be perfectly formatted
• better-toml for a better TOML file support (and poetry configuration file is a toml file)

Black is a strict code formatter that automatically format source code on save using VSCodium.

In the past years, I found Gitmoji quite useful to get a more efficient Git history.

Poetry is THE PERFECT SOLUTION to avoid dealing with setup.py, setup.cfg, requirements.txt, requirements-dev.txt ... You will handle all common tasks easily:

• poetry add to add a new dependencies
• poetry install to create a virtualenv with all needed libraries to run your app
• poetry shell to enter your virtualenv and run your app or tests
• poetry build to create a distributable binary package of your app

Start your new project

One way to start a project a new Python project is to clone this repository, rename some files and folders and init a new .git repository.

Clone the project

$ git clone https://github.com/essembeh/python-helloworld cool-project
$ cd cool-project

Rename your main python module (the folder that contains the source code)

$ mv helloworld cool_project

Note: python modules cannot contain dash, you have to replace - with _

Update the project metadata

Edit pyproject.toml and change the following lines:

• name with your project name (which can contain dash)
• description with a better description
• homepage to point to the homepage of your project
• authors with your name
• classifiers if you want to publish your project, it might be useful to add/remove some classifiers

Configure the entrypoint(s)

The pyproject.toml file can also contains the entrypoints of your project, which are the new commands you want to get when you install your project.

[tool.poetry.scripts]
cool-command = 'cool_project.cli:run'

Here, I declared a cool-command that runs the function def run(): from my cli.py file in my cool_project module.

Note: If you develop a library or you don't have any entrypoint, you should remove the [tool.poetry.scripts] section.

Setup a new Git repository

You can remove the .git folder that contains the history of this helloworld project, and initialize a new one

$ rm -rf .git
$ git init .

# you  can also commit your first version
$ git add .
$ git commit -m "🚀 First release"

Run the tests

To run the tests, you need to be in the virtualenv

# init your virtualenv if it is not
$ poetry install

# enter your virtualenv
$ poetry shell

# note that your shell prompt is updated once you are in a virtualenv
(helloworld-py3.10) $ pytest
====================================== test session starts ======================================
platform linux -- Python 3.10.13, pytest-7.2.0, pluggy-1.0.0
rootdir: /home/seb/cool-project
plugins: dotenv-0.5.2, cov-4.0.0
collected 3 items

tests/test_cli.py ...                                                                     [ 66%]
tests/test_user.py .                                                                      [100%]

======================================= 3 passed in 0.07s =======================================

Build your app

You can use Poetry to build your app and get a .whl

$ poetry build
Building cool-project (0.1.0)
  - Building sdist
  - Built cool_project-0.1.0.tar.gz
  - Building wheel
  - Built cool_project-0.1.0-py3-none-any.whl

$ ls -l dist
total 20
-rw-r--r-- 1 seb users 8569 17 oct.  11:12 cool_project-0.1.0-py3-none-any.whl
-rw-r--r-- 1 seb users 7484 17 oct.  11:12 cool_project-0.1.0.tar.gz

Publish your app

You can use Poetry to publish your app to PyPI

$ poetry publish

By default, Github Actions are configured to

• build your app and run your unit tests with coverage on every push
• build the wheel package and upload it to Pypi on every tag

Note: to allow Github CI to publish on PyPI, you need to create a token and add it to your project settings, the name of the token should be PYPI_TOKEN

I personnally use this command to bump the version using poetry, create the associated git tag and push to Github:

# for a patch bump
$ poetry version patch && git commit -a -m '🔖 New release' && git tag -f $(poetry version -s) && git push --tags
# for a minor bump
$ poetry version minor && git commit -a -m '🔖 New release' && git tag -f $(poetry version -s) && git push --tags
# for a major bump
$ poetry version major && git commit -a -m '🔖 New release' && git tag -f $(poetry version -s) && git push --tags

How to install your app

Install from the sources

$ pip3 install poetry
$ pip3 install git+https://github.com/jdoe/cool-project
$ cool-command --help

Install from PyPI if you published it

$ pip3 install cool-project
$ cool-command --help

Start a new project from scratch

# create the new project folder
$ mkdir cool-project && cd cool-project

# create a README
$ cat << EOF >> README.md
Here is my cool project
EOF

# configure excluded files
$ cat << EOF >> .gitignore
# Generated files
__pycache__
*.pyc
/.pytest_cache
/.coverage*
/dist
# IDE configuration
/.vscode/*
!/.vscode/settings.json
EOF

# init the root python module
$ mkdir cool_project
$ cat << EOF >> cool_project/__init__.py
from importlib.metadata import version

__version__ = version(__name__)
EOF

# create the first commit
$ git init
$ git add .
$ git commit -m "🚀 First release"

# init the poetry pyproject.toml
$ poetry init -n

# configure poetry to create the virtualenv dir in the project folder
$ cat << EOF >> poetry.toml
[virtualenvs]
in-project = true
EOF

# create the virtualenv
$ poetry shell

# add some runtime dependencies
$ poetry add colorama

# add some development dependencies
$ poetry add --group dev black isort pylint pytest pytest-cov pytest-dotenv

# install your package
$ poetry install

# test that your app is installed in your virtualenv
$ python -c 'import cool_project; print(cool_project.__version__)'

Snippet to add an entrypoint

[tool.poetry.scripts]
mycommand = 'cool_project.cli:run'