app_skellington/README.md

---
gitea: none
include_toc: true
---

**app_skellington**

Application framework for Python, features include:
 - Pain-free multi-level command menu: Expose public class methods as commands available to user.
 - 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)
 - Linux supported. Windows and macOS are goals, but untested.

**Tested:** Linux, CPython 3.8–3.14 (Gitea CI on every PR). Windows and macOS: goals, untested.

Principles:
 - Lend to creating beautiful, easy to read and understand code in the application.
 - Minimize coupling of applications to this framework.
 - 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

This is the project page for PyPi: The Python Package Index for community third-party libraries

https://pypi.org/project/app-skellington/

```
pip install app_skellington          # install
pip uninstall app_skellington        # uninstall
pip download app_skellington         # download .whl wheel files for redistributable install
pip install -U app_skellington       # upgrade
pip list                             # list install packages in environment
pip index version app_skellington    # enumerate available distributions in pypi for package
```

# Description

This is a library. There is nothing to run by itself. It would be helpful to have a sample application that uses
it or something, but I don't have that ready at the moment.

# Application Configuration

Site configurations are supported through ConfigObj. There is a config.spec
in the src directory which is a validation file; it contains the accepted
parameter names, types, and limits for configurable options in the
application which is built on app_skellington. The format is multi-level .ini syntax.

Reference the ConfigObj documentation for config.ini and config.spec
format. See:

 - https://configobj.readthedocs.io/en/latest/configobj.html#the-config-file-format
 - https://configobj.readthedocs.io/en/latest/configobj.html#validation

Config files (config.ini) are created if they don't exist. The
file always contains the full specification of parameters; i.e. even default
parameters are added into the config file.

Linux:

 * /home/\<user\>/.config/\<app_name\>/config.ini
 * /home/\<user\>/.cache/\<app_name\>/log/\<app_name\>.log

Windows:

 * C:\\Users\\\<user>\\\<app_name\>\\Local\\\<app_name\>\\config.ini
 * C:\\Users\\\<user>\\\<app_name\>\\Local\\\<app_name\>\\Logs\\\<app_name\>.log

Application configuration can be overridden ad-hoc through the --config <filename>
argument.

# Debug - Turn on Logging

Set the 'APPSKELLINGTON_DEBUG' environment variable to any value to turn
on AppSkellington-level logging. For example,

    APPSKELLINGTON_DEBUG=1 <executable>

or

    export APPSKELLINGTON_DEBUG=1
    <executable>

# Tests

```
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 --isolated --python 3.8 pytest           # another supported Python; --isolated keeps .venv as is
```

# Development

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.

```
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
```

Lint and format (ruff, line length 88):
```
uv run ruff check --fix
uv run ruff format
```

Build the sdist and wheel into `dist/`:
```
uv build
```

Dependencies are locked in `uv.lock`. After editing dependencies in
`pyproject.toml`, run `uv lock` and commit the result.

# Version

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.

    uv build    # the version appears in the dist/ file names

# 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

See [license](LICENSE.txt)

MIT no attribution required - https://opensource.org/license/mit-0

 * Allows commercial use.
 * Allows modifications and closed-source derivatives.
 * Fully interoperable with nearly all other open-source licenses, including GPL (when combined properly).

# See Also

 * Project page: https://zavage-software.com/portfolio/app_skellington
 * Please report bugs, improvements, or feedback!
 * Contact: mat@zavage.net

 * Packing and distribution conforms to PEP 621 https://peps.python.org/pep-0621/
 * Reference https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/