{"id":17193948,"url":"https://github.com/alastairtree/python-cli-devenv-and-ci-sample","last_synced_at":"2025-07-27T14:32:48.188Z","repository":{"id":78267443,"uuid":"592703900","full_name":"alastairtree/python-cli-devenv-and-ci-sample","owner":"alastairtree","description":"Demo an opinionated setup for a python command line app with tests and CI","archived":false,"fork":false,"pushed_at":"2023-08-31T10:38:28.000Z","size":33,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T03:12:02.730Z","etag":null,"topics":["cicd","cli","python","testing"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alastairtree.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-24T10:53:37.000Z","updated_at":"2023-09-29T22:37:05.000Z","dependencies_parsed_at":"2024-12-02T22:40:08.764Z","dependency_job_id":null,"html_url":"https://github.com/alastairtree/python-cli-devenv-and-ci-sample","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alastairtree/python-cli-devenv-and-ci-sample","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alastairtree%2Fpython-cli-devenv-and-ci-sample","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alastairtree%2Fpython-cli-devenv-and-ci-sample/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alastairtree%2Fpython-cli-devenv-and-ci-sample/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alastairtree%2Fpython-cli-devenv-and-ci-sample/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alastairtree","download_url":"https://codeload.github.com/alastairtree/python-cli-devenv-and-ci-sample/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alastairtree%2Fpython-cli-devenv-and-ci-sample/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267370642,"owners_count":24076461,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cicd","cli","python","testing"],"created_at":"2024-10-15T01:45:25.994Z","updated_at":"2025-07-27T14:32:48.181Z","avatar_url":"https://github.com/alastairtree.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sample python command line app with developer environment and continuous integration\n\nThis repository demonstrates an opinionated setup for a python command line app. It shows how to\n\n- configure the VS Code IDE for easy  python3 based development, including testing and linting\n- a docker based development environment\n- package management and python version tooling\n- continuous integration using GitHub including unit tests and code coverage\n- packaging and building the python CLI app ready for distribution\n\n## Developer Quick start\n\n- install vs code and docker (tested on windows with WSL2 and docker desktop)\n- clone the repository\n- open the repo in vscode and switch to the dev container (CTRL-P -\u003e Reopen in dev container)\n- open a terminal and run `poetry install` to restore dependencies\n- run the code within poetry in a virtual environment: `poetry run demo hello bob`\n- or run the code with python3 in a virtual environment: `poetry shell` and `poetry install` to setup env and then `python3 src/main.py hello alice` or even just `demo hello charlie` works because the command is actually installed in the virtual env.\n- One click to run the tests and generate coverage: `./build.sh`\n- One click to package the app into the /dist folder: `./pack.sh`\n- One click to run the tests and package the app across multiple versions of python 3.9, 3.10, 3.11 etc: `./build-all.sh`\n\n## How to install and use the tool\n\nSee `install.sh`.\n\n- Download the tar from the GitHub Actions build artifacts (could also use the wheel (.whl) if you prefer)\n- Install pipx (not required but this ensures the tool is installed in it's own environment and dependencies cannot make a mess of your system)\n- [Install it with pipx](https://pypa.github.io/pipx/docs/#pipx-install) `pipx install --python some-version path-to-tar` (or with pip if you must).\n- Run `demo hello world` on the command line to check it installed ok\n\n## IDE, Docker, Python\n\nThe app uses VS code with docker the devcontainers feature to setup a python environment with all tools preinstalled. All you need is vscode and docker to be able develop.\n\n## Python command line app using typer\n\nThis repo publishes to the `/dist` folder a python wheel (.whl) and tar containing a CLI executable called `demo` that can be installed and run. This app uses the library typer to produce a user friendly interactive cli\n\n## Tools - poetry, pyenv, isort, flake8, black\n\nAll these tools are preinstalled in the dev container:\n\n- **Python3** - multiple versions installed and available, managed using pyenv\n- **Poetry** - tool to manage python dependencies, tools and package\n- **isort, black and flake8** - configured to lint and tidy up your python code automatically. Executed using ./build.sh and CTRL+SHIFT+B (build in vscode)\n\n## Testing - pytest, code coverage\n\nThe project shows how to create unit test.\n\nEither use the test runner in vscode (with debugging)\n\nOr on the cli using pytest:\n\n```\n$ pytest\n\n# or a subset of tests\n$ pytest tests/test_main.py\n$ pytest -k hello\n```\n\nThe tests can be run:\n\n- from inside vscode using the Testing window\n- from the CLI against the current and multiple python versions (See quick start)\n- In GitHub actions on every check-in\n\nTest reports appear automatically in the github actions report\n\nCode coverage data is generated on build into the folder `htmlcov`\n\n\n## Continuous Integration with GitHub Actions\n\nThe `.github/workflows/ci.yml` define a workflow to run on build and test the CLI against multiple versions of python. Build artifacts are generated and a copy of the cli app is available for download for every build\n\n## Want to know more?\n\nCheck out the [Tour](Tour.md)\n\n## Troubleshooting\n\nMake sure you have opened the folder in VS Code with Dev Containers.\n\nReinstall everything by re-running instal script (done for you in dev container init is using vscode)\n\n```\n./dev-env-first-time.sh\n```\n\nCheck the tools are on the path and work:\n\n```\n$ poetry --version\nPoetry (version 1.3.2)\n\n# also you can update it\n$ poetry self update\n```\n\nStart a shell (this creates a virtual env for you automatically) with the tools we need available. vscode may do this automagically when you spawn a terminal.\n\n```\n$ poetry shell\n```\n\nRestore dependencies\n\n```\n$ poetry install\n```\n\nand now you can run tools on the cli such as\n\n```\npytest\nflake8\nblack src\n```\n\nYou may need to tell vscode to use your python venv: CTRL+P `Python: select Interpreter` and select the python in the `.venv/bin/python3` folder\n\n\nTry changing from zsh to bash shell.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falastairtree%2Fpython-cli-devenv-and-ci-sample","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falastairtree%2Fpython-cli-devenv-and-ci-sample","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falastairtree%2Fpython-cli-devenv-and-ci-sample/lists"}