On Windows, the licenses session does not work:

[Errno 13] Permission denied: 'C:\\Users\\User\\AppData\\Local\\Temp\\tmppridh_h4'

This is because of NamedTemporaryFile issues on Windows: https://stackoverflow.com/a/23212515

The default Python 3.8 on Ubuntu leaks into the environment, so an unqualified nox -s test will run 3.8 in addition to 3.9/10.

Possible fix:

• https://github.com/drhagen/parsita/blob/master/.github/workflows/python.yml#L25
• https://github.com/cda-tum/qcec/runs/7518809863?check_suite_focus=true

Will need to add a minimum pip version that supports this feature. I think it's version 10.

It was recently decided that dependencies would be described in pyproject.toml.

When pip, pip-tools, tox, etc. add support for this, should move away from requirements.txt/dev-requirements.txt.

Relates to #16

Once this is merged/released upstream, remove lxml pinned dependency:

• manuzhang/mkdocs-htmlproofer-plugin#38

Add Dockerfile with best practices for Python Docker images.

New insider features landed:

• https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
• https://squidfunk.github.io/mkdocs-material/insiders/#8000-scotch-bonnet

• squidfunk/mkdocs-material#3430

Once Python 3.9 is released, upgrade venv creation docs to specify the new --upgrade-deps option

• https://bugs.python.org/issue34556

There's no license associated with this project. How are we legally allowed to use it?

setup.py mentions MIT style.

https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html

Related to #16

Add a build tox env and depend on the build package.

• https://github.com/manuzhang/mkdocs-htmlproofer-plugin#enabled

This greatly simplifies usage with pip-sync at the small expense that tox is itself installed within tox's virtual environments.

https://mkdocstrings.github.io/handlers/overview/#migrate-to-the-experimental-python-handler

This issue tracks upstream issues that could in some way improve the experience of python-blueprint.

Poetry

• python-poetry/poetry#5729
• python-poetry/poetry#461
• python-poetry/poetry#1132 (For non-wheel-packaged applications
  • python-poetry/poetry#2458
  • #212
• python-poetry/poetry#1537
• python-poetry/poetry#6756
  • #189
• python-poetry/poetry#7303
  • #175

Nox

• wntrblm/nox#488
  • #214
• wntrblm/nox#624
  • #115
• wntrblm/nox#650

nox-poetry

• cjolowicz/nox-poetry#680
• cjolowicz/nox-poetry#663
• cjolowicz/nox-poetry#1063

Ruff

• astral-sh/ruff#8272
• astral-sh/ruff#9457
• astral-sh/ruff#3465

Ruff PyCharm Plugin

• koxudaxi/ruff-pycharm-plugin#140

https://github.com/dmerejkowsky/tbump seems superior to the bumpversion

• its more up to date than bump2?version
• it's integrated with pyproject.toml
• overall i find it easier to use

Consider evaluating from this list:

• https://github.com/wemake-services/wemake-python-styleguide/blob/master/pyproject.toml#L65

See also:

• https://github.com/DmytroLitvinov/awesome-flake8-extensions

If/when the flake8 developers decide to support pyproject.toml, should move flake8 configuration to that to consolidate configurations.

• PyCQA/flake8#234 (locked)

Current Status

This comment lists blockers the Flake8 developers have listed:

• PyCQA/flake8#234 (comment)

• "pip to change its behaviour so mere presence of the file does not change functionality"

  • pypa/pip#9175
  • pypa/pip#8102

• "neither toml nor the python implementations are even 1.0"

  • The TOML language is 1.0

• "python to consider adding a standard library toml implementation"

  • tomllib has been added to Python 3.11

This comment lists a non-technical reason a Flake8 developer has against TOML (against the creator of TOML himself):

• PyCQA/flake8#1467 (comment)

Recent tweets:

• https://twitter.com/codewithanthony/status/1556976653208780805
  • Using TOML has the risk of breaking Flake8 plugins
• https://twitter.com/codewithanthony/status/1556979272534876160?s=20&t=ZnRLnfD4K4JIXmyqQq5zxg
  • Due to the complexity of Flake8's configuration system, adding TOML support would require a full rewrite of the plugin system

There are some additional mypy checks that could be enabled: https://mypy.readthedocs.io/en/stable/command_line.html#miscellaneous-strictness-flags

Tracking: raimon49/pip-licenses#77

MkDocs and specifically Material for MkDocs offers a very nice alternative to Sphinx to consider.

For opensource project, you could add a minimal .github folder for issues and PRs .

.github/
├── ISSUE_TEMPLATE.md
└── PULL_REQUEST_TEMPLATE.md

Anyway, your python-blueprint is awesome. Good job ! ;)

From pytest --help:

pytest-warnings:
  -W PYTHONWARNINGS, --pythonwarnings=PYTHONWARNINGS
                        set which warnings to report, see -W option of python itself.

Passing -Werror to pytest directly is recommended from the help, and works better for pytest-xdist.

https://docs.pytest.org/en/latest/reference/reference.html#confval-filterwarnings

isort is an application to sort imports. This could replace flake8-import-order and PyCharm's "Optimize Imports" feature with something that could be run from tox.

If black is also used, would need to ensure they work together nicely.

Upstream tracking issues

• python/mypy#5205
• python/mypy#5208

Hi!

This is a great project idea!

I noticed that you didn't include a py.typed in your project. It's very useful as it tells that your project is typed

More information here:

https://www.python.org/dev/peps/pep-0561/

https://github.com/ambv/black

The only reservation is that it prescribes " " rather than ' ' string quotes.

darglint can lint Google Style docstrings and could be a useful addition.

One concern is the maintainer is no longer using Python: https://github.com/terrencepreilly/darglint#project-status

Finally, ideally the configuration would be in pyproject.toml but this isn't supported yet:

• terrencepreilly/darglint#130
• terrencepreilly/darglint#173

Poetry recently went 1.0, and looks pretty good. It's inspired by really solid package managers like Cargo.

There are some tox related issues that looked a bit concerning.

Should continue to monitor it, and if it continues to gain market share and maturity, consider switching from recommending pip-tools to poetry.

Related to #7

Consider including https://github.com/asottile/pyupgrade as a way to lint against old code forms.

Poetry 1.2 has been released:

• python-poetry/poetry#5586
• https://python-poetry.org/blog/announcing-poetry-1.2.0/

New features of particular significance

• Dependency groups
• --sync
• --with / --only

Related:

• cjolowicz/nox-poetry#663

As of Nov 2, 2020 Travis CI will no longer be free for FOSS projects.

Will need to migrate to GitHub Actions or Circle CI.

• https://typer.tiangolo.com/tutorial/commands/help/#deprecate-a-command

Should also be able to replace direct usage of colorama for Rich instead.

The idea would be to show how to share the version between the packaging system (setuptools, Sphinx project, etc) and the actual application.

The blueprint uses pytest with a tests folder that is a true Python package (it contains a __init__.py file). This is known to interact badly with having packages defined at the top level—in this case, fact. This is especially problematic when using tox, which the blueprint also uses. tox installs the distribution in a virtual environment so that the distribution itself can be tested. However, pytest adds to sys.path all directories containing test packages. Because tests is a package, the project root is added to sys.path and the fact package in the project root shadows the fact package installed in the tox environment. Then that means that the fact package being tested is actually the source package and not the fact package installed. pytest and tox may report a success even if there are problems with the packaging of the distribution.

There are a few possible solutions to ensuring that the project root does not end up included in sys.path:

• Remove the __init__.py file from tests, which prevents pytest from adding the project root to sys.path and run pytest directly as a tox command, not via python -m pytest to prevent python from adding the project root to sys.path.
• Remove the __init__.py file from tests and change the working directory of the test command to tests.
• Move the source package to a src folder. This is the recommended solution by pytest when using tox.

A possible replacement for tox is nox: https://nox.thea.codes/en/stable/

Related to #16, consider nox-poetry: https://github.com/cjolowicz/nox-poetry

As small side effect of this is that flake8 configuration would need to move back into flake8.ini or setup.cfg until #29 is complete.

• https://github.blog/2016-08-22-publish-your-project-documentation-with-github-pages/
• https://guides.github.com/features/pages/

This line in the testenv might do the trick:

    {envpython} -c "import shutil; shutil.rmtree('_build', ignore_errors=True)"

Could replace Sphinx API doc usages with https://github.com/mkdocstrings/mkdocstrings

Evaluate https://editorconfig.org/

This would be a safer default (also the same as that used by Tox):

• https://nox.thea.codes/en/stable/usage.html?highlight=external#disallowing-external-programs

furo is a clean, elegant dark theme for Sphinx worth showing in the blueprint.

This allows us to avoid excluding .nox

• PyCQA/flake8#1443

Blocked by:

• csachs/pyproject-flake8#13
• wemake-services/flake8-broken-line#264