diff --git a/README.md b/README.md index 26736f5..25d50dc 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ +### [20260204 Python Repo Practices](articles/20260204_python_repo_practices/20260204_python_repo_practices.md) + +> _Rules of thumb for python repos_ + ### [20260123 ANSI to UTF8 Part 1: Intro](articles/20260123_ansi_to_utf8_part_1_intro/20260123_ansi_to_utf8_part_1_intro.md) > _My journey converting ANSI art files for my linux terminal_ diff --git a/articles/20260204_python_repo_practices/20260204_python_repo_practices.md b/articles/20260204_python_repo_practices/20260204_python_repo_practices.md new file mode 100644 index 0000000..e1d1970 --- /dev/null +++ b/articles/20260204_python_repo_practices/20260204_python_repo_practices.md @@ -0,0 +1,68 @@ +# 20260204 Python Repo Practices + +- [Setting up a new Python repo](#setting-up-a-new-python-repo) +- [Examples](#examples) + - [Basic structure](#basic-structure) + +--- + +## Setting up a new Python repo + + +0. Create the repository via the Github web UI + - This allows you to add a README.md, and a .gitignore for Python (super handy!) + - Add a license if desired (BSD-3-Clause is a good default) + - Clone the repo to your local machine + +1. Install uv on your local machine + - Follow the instructions at https://docs.astral.sh/uv/#installation + +2. Create a `pyproject.toml` file + - Define some basic dependencies in it + +3. Run `uv sync` to create the `uv.lock` file + +4. Create your dirs + +- `ops/` - for Dockerfiles, CI/CD configs, etc. +- `test/` - for your unit tests +- `/` - for your main package code + - _make sure it's underscored, not hyphenated_ + - and matches the name in `pyproject.toml` + +5. Add a Dockerfile in `ops/` if desired + - Copy one of the templates from this repo: https://github.com/astral-sh/uv-docker-example + +5. Add a `Makefile` for common tasks + - e.g., `make build`, `make test`, `make lint`, etc. + +6. Make sure there is an `__init__.py` file in + - the `test/` directory + - This ensures that the tests can be discovered and run properly + - the main package directory + - This ensures that the package is recognized as a module + +7. Commit and push your changes to GitHub + +## Examples + +### Basic structure + +An example from one of my projects: + +``` +. +├── LICENSE +├── Makefile +├── README.md +├── abn_lookup_service +│   └── lookup.py +├── ops +│   ├── Dockerfile +├── pyproject.toml +├── test +│   ├── __init__.py +│   └── test_lookup.py +└── uv.lock +``` +