[project seed] python project

[sporniket]

Starting from a clean repository with a git ignore crafted for python (using github helper when creating a new repository)

[sporniket]

.gitignore

add the following lines

# START OF Special for this project
tmp.*
local.*
# END OF Special for this project

# VSCode stuff
.vscode/
# ----

[sporniket]

Project metadata

When creating a new project, only static metadata is envisionned through pyproject.toml is planned, as described by the tutorial Packaging Python Projects

pyproject.toml

Typical file.

Some properties difficult to automate :

• keywords
• classifiers
• dependencies

### [project] section: 
###     see https://peps.python.org/pep-0621/
### [build-system] section: 
###     see https://peps.python.org/pep-0517/
###     see https://peps.python.org/pep-0518/
### see https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html
[build-system]
requires = ["setuptools>=61", "setuptools-scm>=6.2"]
build-backend = "setuptools.build_meta"

[project]
name = "${PACKAGE_NAME}"
#version = "${VERSION}"
description = "${DESCRIPTION}"
readme = "README.md"
requires-python = ">=3.8"
#keywords = ["what","ever"]
license = {file = "LICENSE"}
authors = [{name="Sporniket", email="sporniket.studio@gmail.com"}]
classifiers = [
    "Programming Language :: Python :: 3.8",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)",
    "Operating System :: OS Independent",
    "Development Status :: 3 - Alpha",
    "Environment :: Console",
]
dependencies = [
    "amaranth @ git+https://github.com/amaranth-lang/amaranth@3a51b612844a23b08e744c4b3372ecb44bf9fe5d",
    "amaranth-boards @ git+https://github.com/amaranth-lang/amaranth-boards@2d0a23b75ebb769874719297dec65ff07ca9e79f",
    "amaranth-stuff-by-sporniket @ git+https://github.com/sporniket/amaranth-stuff@256bb0a1afac22b8311e5c660b8213f9dd444c94",
    'importlib-metadata; python_version>"3.8"',
]
dynamic = ["version"]

[project.urls]
homepage = "https://${FORGE_URL}/${FORGE_USER}/${FORGE_PROJECT}"
#TODO documentation = "https://readthedocs.org"
repository = "https://${FORGE_URL}/${FORGE_USER}/${FORGE_PROJECT}"
bug-tracker = "https://${FORGE_URL}/${FORGE_USER}/${FORGE_PROJECT}/${FORGE_ISSUES}"

[sporniket]

README-packaging.md, a reminder and a checklist

How to build and publish a python package

See https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives

Pre-checking

python3 -m pip install --upgrade pip build pytest twine black coverage

Build and install locally

This is what is done by the retest shell script.

python3 -m black 
python3 -m build
python3 -m pip install --force-reinstall dist/xxx.whl

Run test suites with coverage tracking and reporting :

python3 -m coverage run --source=electronic_symbol_generator_for_cad --branch -m pytest
python3 -m coverage report -m
python3 -m coverage html 

Publish on pypi

Check list

• [ ] Code complete and passing tests
• [ ] setup.cfg has the right version
• [ ] Readme up to date (MUST include release notes for the release to publish)
• [ ] Tagged with git using matching version ('v' + version)

Display the token so that a copy/paste is prepared. Then use the login __token__, and paste the token as the password.

python3 -m twine upload --repository pypi dist/*

[sporniket]

Usefull scripts

reformat

Call the black python source formatter/pretty-printer.

#!/bin/bash
# force coding style
python3 -m black .

retest

Launch the test suites.

This sample shows how to perform restrict the coverage computation on a set of modules of the project. This is mandatory to prevent showing coverage on test code.

#!/bin/bash
# clean
rm dist/*
rm -Rf .pytest_cache
# force coding style
python3 -m black .
# rebuild, install and test
python3 -m build && python3 -m pip install --force-reinstall dist/*.whl && \
python3 -m coverage run --source=moto_lib,moto_tar,moto_nl,moto_bas2lst,moto_lst2bas,moto_prettier --branch -m pytest -v && \
python3 -m coverage report -m && \
python3 -m coverage html