doc: README and CLAUDE.md for the uv workflow; fix debug env var and platform claims
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
golem
@@ -10,12 +10,12 @@ Application framework for Python, features include:
|
||||
- Simple to define services and automatic dependency injection based on name (with custom invocation as an option). \*WIP
|
||||
- INI-style config and and validation (provided through ConfigObj).
|
||||
- Colored logging (provided through colorlog)
|
||||
- Works on Linux, Windows, and Mac.
|
||||
- Linux supported. Windows and macOS are goals, but untested.
|
||||
|
||||
Principles:
|
||||
- Lend to creating beautiful, easy to read and understand code in the application.
|
||||
- Minimize coupling of applications to this framework.
|
||||
- Compatible with Linux, Windows, and Mac. Try to be compatible as possible otherwise.
|
||||
- Aim for Linux, Windows and macOS. Only Linux is tested today; full multi-platform CI is a long-term goal.
|
||||
- Try to be compatible with alternate Python runtimes such as PyPy and older python environments. \*WIP
|
||||
|
||||
# Python Package Index (PyPi) - Installation Instruction
|
||||
@@ -70,7 +70,7 @@ argument.
|
||||
|
||||
# Debug - Turn on Logging
|
||||
|
||||
Set 'APPSKELLINGTON_ENABLE_LOGGING' environment variable to any value which turns
|
||||
Set the 'APPSKELLINGTON_DEBUG' environment variable to any value to turn
|
||||
on AppSkellington-level logging. For example,
|
||||
|
||||
APPSKELLINGTON_DEBUG=1 <executable>
|
||||
@@ -82,83 +82,65 @@ or
|
||||
|
||||
# Tests
|
||||
|
||||
Tests are a WIP and not fully built out yet. Recommendation is to run 'pytest' in the 'tests' directory.
|
||||
```
|
||||
uv run pytest # full suite
|
||||
uv run pytest tests/cfg/test_cfg.py::TestConfig_e2e::test_uses_spec_as_defaults
|
||||
uv run pytest -k "<keyword>"
|
||||
uv run --python 3.8 pytest # against another supported Python
|
||||
```
|
||||
|
||||
# Development
|
||||
|
||||
I recommend pyenv to install a reliable, controlled python of preferred version locally.
|
||||
Install [uv](https://docs.astral.sh/uv/). It manages Python versions and the
|
||||
virtual environment, so you don't need pyenv or a hand-made venv.
|
||||
|
||||
```
|
||||
curl https://pyenv.run | bash
|
||||
|
||||
# Add to .bashrc or similar for different shells:
|
||||
tee -a "$HOME"/.profile <<'EOF'
|
||||
|
||||
export PYENV_ROOT="$HOME/.pyenv"
|
||||
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
|
||||
eval "$(pyenv init -)"
|
||||
|
||||
EOF
|
||||
```
|
||||
* reference https://github.com/pyenv/pyenv
|
||||
* Use pyenv to install desired python version, and/or create any virtual environments you desire
|
||||
|
||||
Clone the repo:
|
||||
```commandline
|
||||
git clone https://git-repos.zavage.net/zavage-software/app_skellington.git
|
||||
cd app_skellington
|
||||
uv sync # creates .venv with the package (editable) + dev tools
|
||||
uv run pre-commit install # ruff lint + format on every commit
|
||||
```
|
||||
|
||||
Install pre-commit hooks:
|
||||
```commandline
|
||||
pre-commit install
|
||||
Lint and format (ruff, line length 88):
|
||||
```
|
||||
uv run ruff check --fix
|
||||
uv run ruff format
|
||||
```
|
||||
|
||||
Build:
|
||||
Build the sdist and wheel into `dist/`:
|
||||
```
|
||||
python -m build
|
||||
uv build
|
||||
```
|
||||
|
||||
Install:
|
||||
|
||||
```
|
||||
pip install .
|
||||
```
|
||||
|
||||
Formatting and Linters:
|
||||
```
|
||||
black app_skellington
|
||||
isort app_skellington
|
||||
flake8 app_skellington
|
||||
```
|
||||
|
||||
Publish:
|
||||
|
||||
```
|
||||
# Push latest commit, or on commit ready to publish:
|
||||
git push
|
||||
|
||||
# Create a tag with the desired version number and push:
|
||||
git tag -a v0.2.0 -m "0.2.0 provides modern pyproject.toml build with setuptools, versioning, and publishing"
|
||||
git push origin v0.2.0
|
||||
|
||||
# Build the wheel:
|
||||
python -m build
|
||||
|
||||
# Publish to pypi:
|
||||
twine check dist/*
|
||||
twine upload dist/*
|
||||
```
|
||||
* Reference https://packaging.python.org/en/latest/overview/
|
||||
|
||||
Dependencies are locked in `uv.lock`. After editing dependencies in
|
||||
`pyproject.toml`, run `uv lock` and commit the result.
|
||||
|
||||
# Version
|
||||
|
||||
setuptools_scm will infer the version based on the latest tag in your Git history.
|
||||
Ensure you are tagging your commits with meaningful version numbers like v1.0.0, v1.1.0, etc.
|
||||
setuptools_scm derives the version from the latest `vX.Y.Z` git tag. Between
|
||||
tags you get development versions like `0.3.0.dev4+g1a2b3c4`. The generated
|
||||
`app_skellington/_version.py` is git-ignored.
|
||||
|
||||
You can view the current version number with the command:
|
||||
uv build # the version appears in the dist/ file names
|
||||
|
||||
python -m setuptools_scm
|
||||
# Publish
|
||||
|
||||
Publish only from a tagged commit on `main`, after CI is green, and only after
|
||||
TestPyPI has been checked.
|
||||
|
||||
```
|
||||
git switch main && git pull --ff-only
|
||||
git tag -a v0.2.3 -m "0.2.3: <summary>"
|
||||
git push origin v0.2.3
|
||||
rm -rf dist && uv build
|
||||
ls dist # must be exactly app_skellington-0.2.3.tar.gz and app_skellington-0.2.3-py3-none-any.whl
|
||||
|
||||
uv publish --publish-url https://test.pypi.org/legacy/ dist/* # TestPyPI first
|
||||
scripts/verify_index_release.sh 0.2.3 # every supported Python
|
||||
uv publish dist/* # then PyPI
|
||||
scripts/verify_index_release.sh 0.2.3 https://pypi.org/simple/
|
||||
```
|
||||
* Reference https://packaging.python.org/en/latest/overview/
|
||||
|
||||
# License
|
||||
|
||||
|
||||
Reference in New Issue
Block a user