Note: some badges above might not work unless you use CI (Github or Gitlab) and publish your app on Pypi
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' ;)
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 addto add a new dependenciespoetry installto create a virtualenv with all needed libraries to run your apppoetry shellto enter your virtualenv and run your app or testspoetry buildto create a distributable binary package of your app
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.
$ git clone https://github.com/essembeh/python-helloworld cool-project $ cd cool-project$ mv helloworld cool_projectNote: python modules cannot contain dash, you have to replace
-with_
Edit pyproject.toml and change the following lines:
namewith your project name (which can contain dash)descriptionwith a better descriptionhomepageto point to the homepage of your projectauthorswith your nameclassifiersif you want to publish your project, it might be useful to add/remove some classifiers
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.
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"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 =======================================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.gzYou can use Poetry to publish your app to PyPI
$ poetry publishBy 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 --tagsInstall from the sources
$ pip3 install poetry $ pip3 install git+https://github.com/jdoe/cool-project $ cool-command --helpInstall from PyPI if you published it
$ pip3 install cool-project $ cool-command --help# 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'