Python Starter Package
The purpose of this project is to show you how to create a standard Python
package from scratch. This project is inspired by the excellent
getmyip package
by @iamtennislover
and this tutorial on deploying
python packages by @areed1192.
For a step-by-step guide on how to deploy a package check the
PythonStarterPackage tutorial.
If you are using this starter package for the first time, I definitely
recommend following the tutorial first.
This repository can also be used as a template each time you create a new
package. Use the instructions below for installing, testing, and deploying.
Prerequisites
Requirements
- Python3 >= 3.8
- depending on the platform you can either download Python 3 from the
official website, use the package
manager of your distribution or the Windows store
- see the Virtual environment section below
- check the version with
python3 --version
- pip3 >= 20.2.1
- make sure to install the
python3-pip package in order to use the
pip install command
- check the version with
pip3 --version
- a Python virtual environment
Virtual environment
Using a virtual environment is a solution strongly suggested by
PEP 668. When you attempt to install a
package directly from PyPI using pip, you might get this error message:
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
python3-xyz, where xyz is the package you are trying to
install.
If you wish to install a non-Debian-packaged Python package,
create a virtual environment using python3 -m venv path/to/venv.
Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
sure you have python3-full installed.
If you wish to install a non-Debian packaged Python application,
it may be easiest to use pipx install xyz, which will manage a
virtual environment for you. Make sure you have pipx installed.
If you follow all the instructions below, depending on your operating system,
the process of creating a virtual environment should require just a few
minutes. See also
How venvs work.
Historically there have been lots of different tools to manage virtual
environments and dependencies (requirements), and new ones continue to pop up.
To keep things simple, it's better to stick to the two standard built-in tools:
pip and venv.
Linux
-
open a terminal and go into the project directory
-
if you are on a new Debian-based system and never created a Python virtual
environment before, you most probably need to install this package:
sudo apt install python3-venv
Other distrubutions might have this package bundled in Python, or the name
might differ
-
after you clone the repository go to the project directory
and create the virtual environment
python3 -m venv .venv
. .venv/bin/activate
-
install the package in editable mode:
-
depending on the shell, the prompt changes to something similar to
(.venv) $
-
after working on the package, to quit the Python virtual environment run:
Windows
There are two ways to work with this app in Windows. Choose either one or the
other. The Git bash way (Linux emulation layer) is the suggested method.
Native method
Important
These instructions work without emulation layers.
-
install Python 3.13 from the
Windows store
which works out of the box. Don't use the releases from the Python website.
-
open the Powershell as administrator, then set the execution policy to
Unrestricted. This needs to be done only once, not every time you create a
virtual environment. See also
https://go.microsoft.com/fwlink/?LinkID=135170
Set-ExecutionPolicy -ExecutionPolicy Unrestricted
-
close the administrator Powershell
-
open a normal Powershell
-
after you clone the repository (see also the
Git Bash instructions on how to install Git), go to the project
directory and proceed to create the virtual environment
python3 -m venv .venv
. .\.venv\Scripts\activate
-
install the package in editable mode:
-
after working on the package, to exit the Python virtual environment run:
Git Bash
You can run this app on a Linux emulation layer like the Git Bash terminal.
To install and set up Git Bash:
-
go to the official Git website and click
download (version >= 2.34.1)
-
during the setup, make sure to include OpenSSH. The recommended setting
should be fine:
Use bundled OpenSSH - This uses ssh.exe that comes with Git.
-
leave the other settings as default, click through, and install
-
download and install Python3
-
open a new PowerShell from the start menu
-
open Bash:
C:\Program Files\Git\bin\bash.exe
-
after you clone the repository, go into the project
directory and proceed to create the virtual environment
python3 -m venv .venv
. .venv/Scripts/activate
-
install the package in editable mode:
-
after working on the package, to exit the Python virtual environment run:
Important
Use the bash.exe terminal rather than git-bash.exe (which is also the one
in the start menu).
There is a known issue with git-bash.exe messing up Python os commands in
import os. See
this thread for details.
You can find the bash.exe Git folder in the bin/ directory. For example,
if git-bash.exe is in C:\Program Files\Git\git-bash.exe then you should
find bash.exe in C:\Program Files\Git\bin\bash.exe.
MacOS
-
open a terminal and go into the project directory
-
if not already installed, install Python
-
after you clone the repository go to the project directory
and create the virtual environment
python3 -m venv .venv
source .venv/bin/activate
-
install the package in editable mode:
-
after working on the package, to exit the Python virtual environment run:
Installation
There several ways to install this app in production mode, i.e. as a
standalone Python package.
Install via pip
This Python app is hosted on PyPI and can be installed with the following
command:
pip3 install PythonStarterPackage
Local Install
Alternatively, you can download or Git clone the GitHub repo and install it
locally with the following. This method is useful also if you need to test
local changes and is equivalent to a virtual environment install, if done inside one.
git clone https://github.com/ArcticTechnology/PythonStarterPackage.git
cd PythonStarterPackage
pip3 install -e .
Usage
After installation, you have a few ways to run this app.
-
run this app from the terminal with this command:
-
run this app by letting Python discover the module:
python3 -m pythonstarterpackage
-
you can also import the package resources and run them in your own project:
>>> from pythonstarterpackage import *
>>> starter = StarterPkg()
>>> starter.run()
Deployment
To deploy this package make sure you have gone through all the
PythonStarterPackage tutorial file.
Removal
-
uninstall the app:
pip3 uninstall PythonStarterPackage
If you used the local install option, you will also want to delete the
.egg-info file located in the src/ directory of the repo. This gets
created automatically with pip3 install -e ..
-
deactivate the environment once you stopped working with it:
-
remove the virtual envoronment:
Troubleshooting
This section goes over some of the common issues found and how to resolve them.
Command Not Found error When Running the App
Linux
On Linux, if you are getting a command not found error when trying to run the
app, you may need to add ~/.local/bin/ to the PATH environment variable.
This should only be needed when installing the package outside a virtual
environment.
See this thread for details.
If you use the Bash shell:
-
add the Python path into the PATH environment variable:
echo export PATH=~/.local/bin:$PATH > ~/.bash_profile
-
close the terminal
-
open a new terminal
"ImportError: No module named 'tkinter'
Your python version is probably missing tkinter which typically comes default.
See this post for details. Install it
with the following.
Linux
sudo apt-get install python3-tk
Mac
Support, contributions and resources
Our software is open source and free for public use. If you found any of these
repos useful and would like to support this project financially, feel free to
donate to our bitcoin address.
