Enlistment in this repository involves these steps.
| Step | Command Line | Description | ||||
|---|---|---|---|---|---|---|
| 1. Clone the repository locally | git clone https://github.com/gt-sse-center/PythonProjectBootstrapper |
https://git-scm.com/docs/git-clone | ||||
| 2. Bootstrap the repository |
|
Prepares the repository for local development by enlisting in all dependencies. The--package argument is required to run the Python Package Creation and Python Package Publising steps below. |
||||
| 3. Activate the environment |
|
Activates the terminal for development. Each new terminal window must be activated.
|
||||
| 4. [Optional] Deactivate the environment |
|
Deactivates the terminal environment. Deactivating is optional, as the terminal window itself may be closed when development activities are complete. |
Each of these activities can be invoked from an activated terminal on your local machine.
| Activity | Command Line | Description | Invoked by Continuous Integration |
|---|---|---|---|
| Code Formatting | python Build.py black [--format] |
Format source code using black based on settings in pyproject.toml. | ✅ |
| Static Code Analysis | python Build pylint |
Validate source code using pylint based on settings in pyproject.toml. | ✅ |
| Automated Testing | python Build pytest [--code-coverage] |
Run automated tests using pytest and (optionally) extract code coverage information using coverage based on settings in pyproject.toml. | ✅ |
| Semantic Version Generation | python Build.py update_version |
Generate a new Semantic Version based on git commits using AutoGitSemVer. Version information is stored here. | ✅ |
| Python Package Creation |
Requires that the repository was bootstrapped with the |
Create a python package using setuptools based on settings in pyproject.toml. | ✅ Packages are built for all supported python versions. |
| Python Package Publishing |
Requires that the repository was bootstrapped with the |
Publish a python package to PyPi. | ✅ |
| Build Binaries | python Build.py build_binaries |
Create a python binary for your current operating system using cx_Freeze based on settings in BuildBinary.py. | ✅ Binaries are built for Linux, MacOS, and Windows. |
A brief description of the most important content generated by PythonProjectBootstrapper.
Information that defines the CI/CD workflows used by GitHub actions.
Python source code making up the contents of your package. src/<project_name>/EntryPoint.py represents an executable script that can be invoked on the command line once your package is installed and src/<project_name>/Math.py contains functionality that can be used by other python modules when your package is installed.
Automated tests that exercise functionality defined within your package. There should be a file in tests/ that corresponds to every file in src/.
Script that prepares your repository for development within the local environment. This script installs python (if necessary), creates a virtual python environment, and installs the python dependencies defined in pyproject.toml. In addition, it creates the files Activate.sh / Activate.cmd and Deactivate.sh / Deactivate.cmd.
Visit PythonBootstrapper for more information about these files.
The entry point for local development activities for your repository. Run python Build.py --help for more information about this script.
Configuration settings for your python project and tools used in its development. Visit the Python Packaging User Guide for more information on this file.
Open /pyproject.toml and edit one of the following values:
| Section | Value | Description |
|---|---|---|
[project] |
dependencies |
Python package dependencies required by your package; these will be installed when your package is installed. |
[project.optional-dependencies] |
dev |
Python package dependencies required for local development (e.g. when Bootstrap is invoked). |
[project.optional-dependencies] |
package |
Additional python package dependencies required for local development when creating or publishing wheels (e.g. when Bootstrap --package is invoked). |
Information about the format of these values can be found here.
Executable scripts are python files that can be executed from the command line when your python package is installed. You may specify any number of these scripts.
Open /pyproject.toml and modify the [project.scripts] section. These values are line delimited and should be in the format:
<script_name> = <module_name>:<script_name>.app
Example:
src/MyPackage/ScriptA.pyis a python file using typer that defines a global variable namedapp.src/MyPackage/ScriptB.pyis a python file using typer that defines a global variable namedapp.
[project.scripts]
MyScript1 = MyPackage:ScriptA.app
MyScript2 = MyPackage:ScriptB.app
After these changes, running MyScript1 on the command line will invoke src/MyPackage/ScriptA.py and running MyScript2 will invoke src/MyPackage/ScriptB.py.
Note that this example used different names for the script name and the python file that it invokes. This is to show that these values can vary independently when defined in pyproject.toml. Normally, the script name should be the same as the name of the python file that implements it.
Open Build.py and search for default_min_score=. Set this to a decimal value >= 0.0 and <= 10.0.
Open Build.py and search for default_min_coverage=. Set this to a decimal value >= 0.0 and <= 100.0.
Open .github/workflows/standard.yaml and search for validation_command: under the section validate_package. Update the value to the new command line.
Open .github/workflows/standard.yaml and search for validation_command: under the section validate_binary. Update the value to the new command line.