The pyscript
environment is a recipe for an opinionated, python3 virtual environment, emphasizing rapid building of small, robust, easy-to-use applications for everyday use.
Pyscript applications are intended to fill a niche that exists between small "hacked together" scripts and large, widely distributed projects. Despite being small and built quickly, a Pyscript application follows rigorous code quality practices by default. Additionally, Pyscript applications are flexible, being able to be easily run as a standalone cli or as an imported module in another python application.
Features
- easily deployed templates to get up and running quickly
- built-in code quality tooling with
black
,flake8
,isort
, andmypy
- integration with VS Code
python
extension - utilizes
git
to track changes - validate commit quality with rigorous
pre-commit
hooks - lean dependencies
Requirements
- modern Python 3 installation (
python>=3.6
) pipx
(for development dependencies)
# make the setup scripts executable
chmod u+x ./pyscript-tools.py
chmod u+x ./pyscript-init.py
# validate they can be run by reviewing their help output
./pyscript-tools.py --help
./pyscript-init.py --help
# setup development environment tooling
# (wraps pipx actions to install predefined list of tools)
./pyscript-tools.py install
# setup pyscript primary and build envs with defaults
# (depends on virtualenv, one of the tool )
./pyscript-init.py
New pyscript applications can be quickly setup using the template script.
# make the setup scripts executable
chmod u+x ./pyscript-template.py
# generate pyscript application with NAME, under /path/to/parent
./pyscript-template.py --path /path/to/parent NAME
See README under template/
directory for details on what is generated, and creating a template config file.
The pyscript environment consists of two installed virtualenvs named, primary
and build
default install location:
${HOME}/bin/pyscriptbuild
Contains only what is needed to perform a build for a custom application. This environment includes PEP-517/518 compliant tooling:
- PyPA
build
tool flit-core
default install location:
${HOME}/bin/pyscriptenv
Contains all runtime dependencies and installed executables for custom applications. Completed pyscript applications can be added by pip install
, along with standard dependencies as well.
A pyscript application by default has a number of (opinionated) design choices with the goal of getting up and running quickly.
${app_name}/
├── .vscode/
│ ├── tasks.json
│ ├── launch.json
│ └── workspace.code-workspace
├── pyscript_${app_name}/
│ ├── __init__.py
│ ├── __main__.py
│ ├── cli/
│ │ ├── __init__.py
│ │ ├── root.py
│ │ ├── utils.py
│ │ └── ...
│ ├── config/
│ │ ├── __init__.py
│ │ ├── default.py
│ │ └── ...
│ ├── logging/
│ │ ├── __init__.py
│ │ └── ...
│ └── ...
├── .pre-commit-config.yaml
├── .flake8
├── .gitignore
├── pyproject.toml
└── README.md
All pyscript applications use pyproject.toml
as the primary entrypoint for build/installation. There are many benefits to this approach, but suffice it to say, that it keeps things simple and predictable when building python applications.
The module name defaults to pyscript_${app_name}
. This is done to make custom Pyscript applications easily recognizable in a pip list, or in code. The executable entry point defaults to ${app_name}
and pyscript_${app_name}
[build-system]
requires = ["flit_core >=3,<4"]
build-backend = "flit_core.buildapi"
[tool.flit.metadata]
module = "pyscript_${app_name}"
author = "${author_name}"
home-page = "${home_page}"
requires = [
# default dependencies
"click==7.1.2",
"colorama==0.4.4",
"pytomlpp==0.3.5",
]
requires-python=">=3.6"
[tool.flit.scripts]
# makes app executable by name upon install
${app_name} = "pyscriptenv_${app_name}:cli"
pyscriptenv_${app_name} = "pyscriptenv_${app_name}:cli"
Pyscript applications also takes advantage of tooling configuration in pyproject.toml
where possible (c'mon flake8
!)
[tool.black]
line-length = 88
target-version = ['py38']
include = 'pyscriptenv_${app_name}/.*\.py$'
[tool.isort]
profile = "black"
src_paths = ["pyscriptenv_${app_name}"]
filter_files = true
skip_gitignore = false
[tool.mypy]
ignore_missing_imports = true
follow_imports = "silent"
show_column_numbers = true
show_error_context = true
show_error_code = true
pretty = true
[tool.flake8]
# no support yet for flake8 in pyproject.toml, see .flake8 file
pre-commit
configuration can be optionally added to any Pyscript application template. This can be installed as a hook to each commit, or just used as a useful bundle of code quality tools.
The pre-commit
config is purposely strict to force a habit of code quality. This can, of course, be adjusted per individual preferences.
A VS Code workspace can be optionally included in each Pyscript application. This workspace integrates nicely with the installed Pyscript environments, and development tools installed in the "Getting Started" section.
- points
python.pythonPath
to the Pyscriptprimary
environment python - code quality tooling (
black
,flake8
,isort
,mypy
) point to the pipx installed versions of these tools - task set to run
pre-commit
checks on the project or individual files - task set to bump the application version (major, minor, or patch)
- note: this requires a functioning
grep
installation
- note: this requires a functioning
- task to build using the Pyscript
build
environment, and install into the Pyscriptprimary
environment - launch configuration to debug application from within VS Code
A functional command line interface is provided by default in each new Pyscript application template. The click
library (Command Line Interface Creation Kit) is used for this.
By default, the following is enabled for every app:
- color output support with
--color/--no-color
--dry-run
flag- toml configuration file initialization
--default
flag to bypass configuration file altogetherclick.Context
population of all relevant cli, and application config- use
--show
flag to print configuration (useful for debugging, and verbose outputs)
All cli operations are segregated to the cli.py
file, allowing applications to easily add importable modules, while also keeping useful functionality available on the cli.
flit-core
defines some simplified defaults for defining project metadata
- application version is defined in the root
__init__.py
using the__version__
attribute - application description is also grabbed from the
__init__.py
docstring