rochacbruno / python-project-template

DO NOT FORK, CLICK ON "Use this template" - A github template to start a Python Project - this uses github actions to generate your project based on the template.

Python Project Template

A low dependency and really simple to start project template for Python Projects.

See also

• Flask-Project-Template for a full feature Flask project including database, API, admin interface, etc.
• FastAPI-Project-Template The base to start an openapi project featuring: SQLModel, Typer, FastAPI, JWT Token Auth, Interactive Shell, Management Commands.

HOW TO USE THIS TEMPLATE

DO NOT FORK this is meant to be used from Use this template feature.

1. Click on Use this template
2. Give a name to your project
   (e.g. my_awesome_project recommendation is to use all lowercase and underscores separation for repo names.)
3. Wait until the first run of CI finishes
   (Github Actions will process the template and commit to your new repo)
4. If you want codecov Reports and Automatic Release to PyPI
   On the new repository settings->secrets add your PYPI_API_TOKEN and CODECOV_TOKEN (get the tokens on respective websites)
5. Read the file CONTRIBUTING.md
6. Then clone your new project and happy coding!

NOTE: WAIT until first CI run on github actions before cloning your new project.

What is included on this template?

• 🖼️ Templates for starting multiple application types:
  • Basic low dependency Python program (default) use this template
  • Flask with database, admin interface, restapi and authentication use this template. or Run make init after cloning to generate a new project based on a template.
• 📦 A basic setup.py file to provide installation, packaging and distribution for your project.
  Template uses setuptools because it's the de-facto standard for Python packages, you can run make switch-to-poetry later if you want.
• 🤖 A Makefile with the most useful commands to install, test, lint, format and release your project.
• 📃 Documentation structure using mkdocs
• 💬 Auto generation of change log using gitchangelog to keep a HISTORY.md file automatically based on your commit history on every release.
• 🐋 A simple Containerfile to build a container image for your project.
  Containerfile is a more open standard for building container images than Dockerfile, you can use buildah or docker with this file.
• 🧪 Testing structure using pytest
• ✅ Code linting using flake8
• 📊 Code coverage reports using codecov
• 🛳️ Automatic release to PyPI using twine and github actions.
• 🎯 Entry points to execute your program using python -m <project_name> or $ project_name with basic CLI argument parsing.
• 🔄 Continuous integration using Github Actions with jobs to lint, test and release your project on Linux, Mac and Windows environments.

Curious about architectural decisions on this template? read ABOUT_THIS_TEMPLATE.md
If you want to contribute to this template please open an issue or fork and send a PULL REQUEST.

❤️ Sponsor this project

---

project_name

project_description

Install it from PyPI

pip install project_name

Usage

from project_name import BaseClass
from project_name import base_function

BaseClass().base_method()
base_function()

$ python -m project_name
#or
$ project_name

Development

Read the CONTRIBUTING.md file.

python-project-template's Issues

I got errors during 'make switch-to-poetry' that I don't understand.

This was the initial output to my terminal under MINGW64 in vscode and Win10

$ make switch-to-poetry
Switching to poetry ...

This command will guide you through creating your pyproject.toml config.

You can specify a package in the following forms:

• A single name (requests)
• A name and a constraint (requests@^2.23.0)
• A git url (git+https://github.com/python-poetry/poetry.git)
• A git url with a revision (git+https://github.com/python-poetry/poetry.git#develop)
• A file path (../my-package/my-package.whl)
• A directory (../my-package/)
• A url (https://example.com/packages/my-package-0.1.0.tar.gz)

Creating virtualenv a-flask-test in C:\Users\Conrad\bookish-enigma.venv

ValueError

too many values to unpack (expected 2)

at ~.poetry\lib\poetry\console\commands\init.py:456 in parse_requirements
452│ pair = pair.strip()
453│
454│ require = OrderedDict()
455│ if " " in pair:
→ 456│ name, version = pair.split(" ", 2)
457│ extras_m = re.search(r"[([\w\d,-]+)]$", name)
458│ if extras_m:
459│ extras = [e.strip() for e in extras_m.group(1).split(",")]
460│ name, _ = name.split("[")

ValueError

too many values to unpack (expected 2)

at ~.poetry\lib\poetry\console\commands\init.py:456 in parse_requirements
452│ pair = pair.strip()
453│
454│ require = OrderedDict()
455│ if " " in pair:
→ 456│ name, version = pair.split(" ", 2)
457│ extras_m = re.search(r"[([\w\d,-]+)]$", name)
458│ if extras_m:
459│ extras = [e.strip() for e in extras_m.group(1).split(",")]
460│ name, _ = name.split("[")

ValueError

too many values to unpack (expected 2)

at ~.poetry\lib\poetry\console\commands\init.py:456 in parse_requirements
452│ pair = pair.strip()
453│
454│ require = OrderedDict()
455│ if " " in pair:
→ 456│ name, version = pair.split(" ", 2)
457│ extras_m = re.search(r"[([\w\d,-]+)]$", name)
458│ if extras_m:
459│ extras = [e.strip() for e in extras_m.group(1).split(",")]
460│ name, _ = name.split("[")

ValueError

too many values to unpack (expected 2)

at ~.poetry\lib\poetry\console\commands\init.py:456 in parse_requirements
452│ pair = pair.strip()
453│
454│ require = OrderedDict()
455│ if " " in pair:
→ 456│ name, version = pair.split(" ", 2)
457│ extras_m = re.search(r"[([\w\d,-]+)]$", name)
458│ if extras_m:
459│ extras = [e.strip() for e in extras_m.group(1).split(",")]
460│ name, _ = name.split("[")

ValueError

too many values to unpack (expected 2)

at ~.poetry\lib\poetry\console\commands\init.py:456 in parse_requirements
452│ pair = pair.strip()
453│
454│ require = OrderedDict()
455│ if " " in pair:
→ 456│ name, version = pair.split(" ", 2)
457│ extras_m = re.search(r"[([\w\d,-]+)]$", name)
458│ if extras_m:
459│ extras = [e.strip() for e in extras_m.group(1).split(",")]
460│ name, _ = name.split("[")

ValueError

too many values to unpack (expected 2)

at ~.poetry\lib\poetry\console\commands\init.py:456 in parse_requirements
452│ pair = pair.strip()
453│
454│ require = OrderedDict()
455│ if " " in pair:
→ 456│ name, version = pair.split(" ", 2)
457│ extras_m = re.search(r"[([\w\d,-]+)]$", name)
458│ if extras_m:
459│ extras = [e.strip() for e in extras_m.group(1).split(",")]
460│ name, _ = name.split("[")
Using version ^6.2.5 for pytest

From here it all seemed to proceed normally and declared

You have switched to https://python-poetry.org/ package manager.
Please run 'poetry shell' or 'poetry run bookish_enigma'

I wanted to share this because I don't know if those errors were to be expected and ignored.
Thanks for your time.

CI Workflow run error

Hi,
Foremost, thanks for sharing these templates.
I'm a beginner to Python and hope this will help me build my first project, despite not being able to understand half of the content of the readme.md.

While creating my project clone, I received a “CI Workflow run” error message. Looking into it on GitHub, the detail of the error was:

…
2022-08-06T15:58:16.0724267Z ##[group]Run actions/setup-python@v2
2022-08-06T15:58:16.0724613Z with:
2022-08-06T15:58:16.0724799Z python-version: 3.9
2022-08-06T15:58:16.0725262Z token: ***
2022-08-06T15:58:16.0725445Z ##[endgroup]
2022-08-06T15:58:16.7770614Z Successfully setup CPython (3.9.13)
2022-08-06T15:58:16.8091702Z ##[group]Run pip install --user --upgrade pip
2022-08-06T15:58:16.8092164Z �[36;1mpip install --user --upgrade pip�[0m
2022-08-06T15:58:16.8276808Z shell: C:\Program Files\PowerShell\7\pwsh.EXE -command ". '{0}'"
2022-08-06T15:58:16.8277109Z env:
2022-08-06T15:58:16.8277410Z pythonLocation: C:\hostedtoolcache\windows\Python\3.9.13\x64
2022-08-06T15:58:16.8277674Z ##[endgroup]
2022-08-06T15:58:35.0156418Z Requirement already satisfied: pip in c:\hostedtoolcache\windows\python\3.9.13\x64\lib\site-packages (22.2.1)
2022-08-06T15:58:35.5641334Z Collecting pip
2022-08-06T15:58:35.5958308Z Downloading pip-22.2.2-py3-none-any.whl (2.0 MB)
2022-08-06T15:58:35.6762744Z ---------------------------------------- 2.0/2.0 MB 25.8 MB/s eta 0:00:00
2022-08-06T15:58:35.6929232Z ERROR: To modify pip, please run the following command:
2022-08-06T15:58:35.6930066Z C:\hostedtoolcache\windows\Python\3.9.13\x64\python.exe -m pip install --user --upgrade pip
…
(see enclosed print screen as well)

I'm using Anaconda Python, so I usually install packages through "Conda install" not pip (if possible).
I tried to run the command suggested in the error message "C:\hostedtoolcache\windows\Python\3.9.13\x64\python.exe -m pip install --user --upgrade pip" but the directory mentioned hostedtoolcache was no more available.

So, please help:

Am I doing something wrong?
What are the "consequences" of this error?
How can I solve the issue?
error

Many thanks for your help.

Stefano

ImportError: attempted relative import with no known parent package when running python project_name/__main__.py

Repro steps

git clone the repository and then

python -m venv venv
. venv/Scripts/activate
pip install ../python-project-template/

The project_name command works well.

$ project_name
This will do something

However, when running directly __main__.py I get the following:

$ python ../python-project-template/project_name/__main__.py
Traceback (most recent call last):
  File "C:\tmp\python-project-template\project_name\__main__.py", line 3, in <module>
    from .cli import main  # pragma: no cover
ImportError: attempted relative import with no known parent package
(venv)

Minor investigation

I noticed that if the corresponding line is changed to (removing the .)

from cli import main  # pragma: no cover

The python command goes through:

$ python ../python-project-template/project_name/__main__.py
This will do something

However, in this case, the installed project_name stops working.

$ project_name
Traceback (most recent call last):
  File "C:\Python39\lib\runpy.py", line 197, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Python39\lib\runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "C:\tmp\venvs\venv\Scripts\project_name.exe\__main__.py", line 4, in <module>
  File "c:\tmp\venvs\venv\lib\site-packages\project_name\__main__.py", line 3, in <module>
    from cli import main  # pragma: no cover
ModuleNotFoundError: No module named 'cli'
(venv)

All above observations hold irrespective of whether pip install ../python-project-template/ is run with the editable (-e) flag or not.

**Desktop **

• Python 3.9.0
• Microsoft Windows 11 Business, 10.0.22621 N/A Build 22621

typo

python-project-template/CONTRIBUTING.md

Line 100 in 3b55b1c

For this to work you need to setup a secret called `PIPY_API_TOKEN` on the project settings>secrets,

PIPY_API_TOKEN -> PYPI_API_TOKEN ?

wrong version pushed to pypi

python-project-template/Makefile

Lines 82 to 87 in 3b55b1c

	@git tag $${TAG}
	@echo "$${TAG}" > project_name/VERSION
	@$(ENV_PREFIX)gitchangelog > HISTORY.md
	@git add project_name/VERSION HISTORY.md
	@git commit -m "release: version $${TAG} 🚀"
	@git push -u origin HEAD --tags

maybe the line

    @git tag $${TAG}

should be moved to behind the line

    @git commit -m "release: version $${TAG} 🚀"

?

Thanks for your effort. A very useful template.

Cookiecutter Support

https://cookiecutter.readthedocs.io/

Writing new VERSION on MacOSX

Describe the bug
When I do
make relase
On my MacOSX. It cannot write properly VERSION file.
This is due to the read command which is not working as expected in zsh.

To Reproduce
Steps to reproduce the behavior:
Run make release on a zsh shell.

Expected behavior

@echo "WARNING: This operation will create s version tag and push to github"
@read -p "Version? (provide the next x.y.z semver) : " TAG
@echo "$${TAG}" > project_name/VERSION

The TAG variable will always be voiid and thus the VERSION file will be emplty. No release actions will be triggered in github.

Desktop (please complete the following information):

• OS: [macOS 12.0.1]
• Zsh [zsh 5.8 (x86_64-apple-darwin21.0)]

Additional context
For the moment I change by hand the version number in VERSION file.
And I changed Makefile with:
VERSION=$(shell cat checkatlas/VERSION)

@echo "Reading version $(VERSION) from: checkatlas/VERSION"
@$(ENV_PREFIX)gitchangelog > HISTORY.md
@git add checkatlas/VERSION HISTORY.md
@git commit -m "release: version $(VERSION) 🚀"

Add basic ArgParse example

The file https://github.com/rochacbruno/python-project-template/blob/main/project_name/__main__.py is missing a simple implementation of a CLI using ArgParse from stdlib.

Rename-project won't run by default

Describe the bug
Action Rename-project won't run without elevating workflow permissions

To Reproduce
Click the link in readme ( https://github.com/rochacbruno/python-project-template/generate )
Name the project
Go into actions and error should be there

Expected behavior
AFAIK this can not be worked around. Probably update readme so newbs like me don't spend 30 minutes hunting git docs for a solution. I have like 1 hour of work experience in GitHub so can't advise how it should be solved.

Error Log
remote: Permission to jdobruchowski/Oracle-REST-SQL-util-.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/jdobruchowski/Oracle-REST-SQL-util-/': The requested URL returned error: 403
Error: Invalid status code: 128
at ChildProcess. (/home/runner/work/_actions/stefanzweifel/git-auto-commit-action/v4/index.js:17:19)
at ChildProcess.emit (events.js:314:20)
at maybeClose (internal/child_process.js:1022:16)
at Process.ChildProcess._handle.onexit (internal/child_process.js:287:5) {
code: 128
}
Error: Invalid status code: 128
at ChildProcess. (/home/runner/work/_actions/stefanzweifel/git-auto-commit-action/v4/index.js:17:19)
at ChildProcess.emit (events.js:314:20)
at maybeClose (internal/child_process.js:1022:16)
at Process.ChildProcess._handle.onexit (internal/child_process.js:287:5)

Add issue and PR templates on .github dir

ADD ISSUE_TEMPLATE and PR_TEMPLATE

Github actions PYPI_API_TOKEN not working for me

Describe the bug
Hello
Thanks for your awesome template! Everything from your template is working fine,. I have only two problems: one with writing VERSION number on MACOSX (see other issue) and one with github workflows for the release.
Maybe I do it wrong. GitHub actions crashes at the end of the release.yaml.

Uploading checkatlas-0.0.8-py3-none-any.whl
25l
  0%━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━0.0/36.5 kB • --:-- • ?
  0%━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━0.0/36.5 kB • --:-- • ?
100%━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━36.5/36.5 kB • 00:00 • 32.1 MB/s
100%━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━36.5/36.5 kB • 00:00 • 32.1 MB/s
25hINFO     Response from https://upload.pypi.org/legacy/:
         403 Invalid or non-existent authentication information. See            
        [ https://pypi.org/help/#inv](https://pypi.org/help/#invalid-auth)alid-auth for more information.      
INFO     <html>                                                                 
          <head>                                                                
           <title>403 Invalid or non-existent authentication information. See   
        [ https://pypi.org/help/#inv](https://pypi.org/help/#invalid-auth)alid-auth for more information.</titl
          </head>                                                               
          <body>                                                                
           <h1>403 Invalid or non-existent authentication information. See      
        [ https://pypi.org/help/#inv](https://pypi.org/help/#invalid-auth)alid-auth for more information.</h1> 
           Access was denied to this resource.<br/><br/>                        
         Invalid or non-existent authentication information. See                
        [ https://pypi.org/help/#inv](https://pypi.org/help/#invalid-auth)alid-auth for more information.      
          </body>                                                               
         </html>                                                                
ERROR    HTTPError: 403 Forbidden from https://upload.pypi.org/legacy/
         Invalid or non-existent authentication information. See                
        [ https://pypi.org/help/#inv](https://pypi.org/help/#invalid-auth)alid-auth for more information.

This is with no doubt an error because it cannot connect to PyPi. If I run it manually with my PyPi account, everything works fine.

python setup.py sdist bdist_wheel
twine upload --verbose dist/*

I created a github secrets from PyPi and add it in GitHub.
I did not touch the end of release.yaml

- name: Build and publish
      env:
        TWINE_USERNAME: __token__
        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
      run: |
        python setup.py sdist bdist_wheel
        twine upload --verbose dist/*

Am I supposed to modify the token variable ?
Thanks !

How HISTORY.md is automated?

Is HISTORY.md is a feature of git?

I cannot see any code that makes HISTORY.md

[bug] Fix generation when project name has dashes and upper case

Example of generated repo

https://github.com/rochacbruno/This-Is_Great

This-Is_Great is replaced as This_Is_Great and it doesn't match repo URL.

Read a new variable on rename_project.sh script and job, use this as repo_slug on specific places as readme badges and URLS.

Github action for Rename the project from template runs on forks as well

This github action should not run on forks of this repository. It should only run when the template is used.

Add netlify docs hosting files

Add files to setup netlify docs hosting (example in rochacbruno/dynaconf)

HISTORY.md newest position is called (unreleased)

When making a new release, HISTORY.md newest position is called (unreleased) instead of the newest version.

I've created a simple workaround by modifying release under Makefile.

Instead of calling:

@$(ENV_PREFIX)gitchangelog  > HISTORY.md

You could perhaps do something like:

@$(ENV_PREFIX)gitchangelog | sed "s/(unreleased)/$${TAG} ($$(date +%Y-%m-%d))/g" > HISTORY.md

Furthermore, you could get rid of all the release commits from changelog:

@$(ENV_PREFIX)gitchangelog | sed "s/(unreleased)/$${TAG} ($$(date +%Y-%m-%d))/g" | grep -v "Release: version" > HISTORY.md

This way HISTORY.md contains relevant commits only.

move to pyproject.toml

Lets move to pyproject.toml in the most tool agnostic way using pip-tools and no poetry for a while.

add pre-commit config that ensures black/linting

as pre-commit ties the linting/type checking up nicely,
it would be a most fabulous addition to the listing/tooling