From 3cc88b563388489b8a3f1b37f91144e08fa68712 Mon Sep 17 00:00:00 2001
From: Jeff Moe <moe@spacecruft.org>
Date: Wed, 4 Oct 2023 15:28:06 -0600
Subject: [PATCH] Docs with new hatch

---
 README.md                        | 453 ++++++++++++++++++++++++++++++-
 config/hatch/config.toml         |  44 +++
 src/tasteful_python/__about__.py |   2 +-
 3 files changed, 486 insertions(+), 13 deletions(-)
 create mode 100644 config/hatch/config.toml

diff --git a/README.md b/README.md
index fbc2c32..04a5368 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,450 @@
-# tasteful-python
+# Tasteful Python
+Python suited to my taste.
 
-[![PyPI - Version](https://img.shields.io/pypi/v/tasteful-python.svg)](https://pypi.org/project/tasteful-python)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/tasteful-python.svg)](https://pypi.org/project/tasteful-python)
+Configuration files, code snippets, etc.
 
------
 
-**Table of Contents**
+# Install
+Install thusly.
 
-- [Installation](#installation)
-- [License](#license)
+Using Debian Bookworm (stable/12) as a base.
 
-## Installation
+## Dependencies
+Dependencies that may be needed:
 
-```console
-pip install tasteful-python
+```
+sudo apt install git python3-pip python3-virtualenv
 ```
 
-## License
+## Python
+Get code and set up Python, suit to taste, such as:
 
-`tasteful-python` is distributed under the terms of the [AGPL-3.0-or-later](https://spdx.org/licenses/AGPL-3.0-or-later.html) license.
+```
+git clone https://spacecruft.org/deepcrayon/tasteful-python
+cd tasteful-python
+virtualenv -p python3 env
+source env/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+
+# Cache
+* Use ccache for caching builds.
+* Use apt for caching Debian packages.
+* Use PyPI cache for Python pacakges.
+
+
+## ccache Server
+Set up Redis for ccache server.
+
+```
+apt install redis-server
+```
+
+## ccache Client
+Set up thusly.
+
+```
+apt install ccache
+```
+
+Add to end of `~/.bashrc` and source it or logout/login:
+
+```
+PATH=/usr/lib/ccache:$PATH
+```
+
+ccache client config file, change IP to Redis server.
+
+```
+mkdir -p ~/.config/ccache
+~/.config/ccache/ccache.conf
+cat > ~/.config/ccache/ccache.conf <<EOF
+remote_storage = redis://192.168.1.101
+remote_only = true
+reshare = true
+EOF
+```
+
+## devpi PyPI Cache Server
+Set up a devpi PyPI (pip) caching server thusly:
+
+```
+sudo apt install python3-pip python3-virtualenv --no-install-recommends
+mkdir -p ~/devel/devpi
+cd ~/devel/devpi
+virtualenv env
+source env/bin/activate
+pip install -U setuptools wheel pip
+pip install devpi-server devpi-web
+
+sudo mkdir -p /srv/devpi
+sudo chown jebba:jebba /srv/devpi
+
+devpi-init \
+    --serverdir /srv/devpi
+
+devpi-gen-config \
+    --host=0.0.0.0 \
+    --port 4040 \
+    --serverdir /srv/devpi \
+    --absolute-urls
+
+# Don't use nginx (?)
+#sudo apt install nginx
+#sudo cp ~jebba/devel/devpi/gen-config/nginx-devpi.conf /etc/nginx/sites-available/
+#cd /etc/nginx/sites-enabled
+#sudo ln -s ../sites-available/nginx-devpi.conf .
+
+# meh supervisor, I guess
+sudo apt install supervisor
+sudo cp ~jebba/devel/devpi/gen-config/supervisor-devpi.conf /etc/supervisor/conf.d/
+
+crontab -e
+@reboot /usr/local/sbin/supervisord -c /home/jebba/etc/supervisor-devpi.conf
+
+supervisord -c gen-config/supervisord.conf
+sudo reboot
+
+cd ~/devel/devpi
+source env/bin/activate
+devpi use http://192.168.1.100:4040
+devpi login root --password ''
+devpi user -m root password=FOO
+devpi user -l
+devpi logoff
+devpi user -c jebba password=BAR email=foo@bar
+devpi login jebba --password=BAR
+devpi index -c dev bases=root/pypi
+devpi use jebba/dev
+devpi install pytest
+```
+
+Open up firewall port `4040/tcp`.
+
+
+## devpi PyPI Cache Client
+Set up the PyPI clients thusly substituting in the proper server IP:
+
+```
+mkdir -p ~/.config/pip
+cat > ~/.config/pip/pip.conf <<EOF
+[global]
+trusted-host = 192.168.1.100
+index-url = http://192.168.1.100:4040/root/pypi/+simple/
+
+[search]
+index = http://192.168.1.100:4040/root/pypi/
+EOF
+```
+
+
+# pyenv
+If different, typically older, versions of Python are needed,
+pyenv works well for this.
+
+Set it up on a system thusly:
+
+```
+mkdir -p ~/devel/pyenv
+sudo apt install build-essential libssl-dev zlib1g-dev \
+    libbz2-dev libreadline-dev libsqlite3-dev curl liblzma-dev \
+    libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev \
+    python3-virtualenv python3-pip
+
+curl https://pyenv.run | bash
+```
+
+If you want it to work every time the user logs in, add this to
+`~/.bashrc`.
+
+```
+# pyenv
+export PYENV_ROOT="$HOME/.pyenv"
+command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
+eval "$(pyenv init -)"
+eval "$(pyenv virtualenv-init -)"
+```
+
+If you only want pyenv sometimes, copy the above lines to a file
+(e.g. ~/bin/deepcrayon-pyenv), the source the lines instead of running the
+file, ala `source ~/bin/deepcrayon-pyenv`.
+
+To see versions of Python that can be installed:
+
+```
+pyenv install --list | sort -V
+```
+
+Perhaps install a bunch of versions, such as:
+
+```
+pyenv install 3.12.0
+pyenv install 3.11.6
+pyenv install 3.10
+pyenv install 3.9
+pyenv install 3.8
+pyenv install 3.7
+pyenv install 3.6
+pyenv install 3.5
+pyenv install 3.13-dev
+```
+
+Use pyenv to set a particular version in a virtualenv:
+
+```
+mkdir -p foodir
+cd foodir/
+pyenv local 3.12.0
+virtualenv -p 3.12.0 env
+source env/bin/activate
+python --version
+pip install --upgrade pip setuptools wheel
+pip install fooapp
+```
+
+
+# Development
+Development setup.
+
+## Dependencies
+### OS Dependencies
+Install dependencies via apt:
+
+```
+sudo apt install --no-install-recommends pipx
+```
+
+
+### Python Dependencies via pip
+Install the Python requirements:
+
+```
+pip install -r requirements-dev.txt
+```
+
+Then run black on the Python files for nice formatting.
+Use `--preview` to get the next release style changes.
+Such as:
+
+```
+black --preview tasteful-python*
+```
+
+### Python Dependenices via pipx:
+Use pipx to install hatch dependencies so the hatch
+dependency versions don't conflict with the project's
+dependencies. Perhaps this should be done for all the
+development dependencies like black, flake8 (?).
+
+Don't run this as root or in a virtual environment,
+just as regular user:
+
+
+```
+deactivate # if needed
+pipx install hatch
+pipx ensurepath
+# perhaps logout / login or new terminal
+eval "$(register-python-argcomplete pipx)"
+# perhaps
+_HATCH_COMPLETE=bash_source hatch > ~/.hatch-complete.bash
+. ~/.hatch-complete.bash
+echo ". ~/.hatch-complete.bash" >> ~/.bashrc
+```
+
+
+## Linter
+Probably:
+
+### Flake8
+
+* https://github.com/PyCQA/flake8
+
+### Bugbear
+
+* https://github.com/PyCQA/flake8-bugbear
+
+
+## Build
+### Hatch
+Build with hatch. Appears to be latest/greatest in Python ecosystem.
+
+Hatch can also create new projects, set up directory structures, etc.
+Best approach may be to create good hatch setup, then copy over
+other example files as default file template for new projects.
+
+For sample hatch config, see `config/hatch/config.toml`.
+The TOML file format is documented here:
+
+* https://toml.io/en/v1.0.0
+
+#### Hatch Create
+Create new project.
+Adding `--cli` imports `click` command line processing.
+
+```
+hatch new foo
+hatch new --cli bar
+```
+
+For a pre-existing project, it can be set up for hatch thusly:
+
+```
+cd foo/
+hatch new --init
+hatch new --init --cli
+```
+
+Using `--init` on a pre-existing project won't create the
+directory structure, it just changes `pyproject.toml`.
+
+#### Hatch Shell
+After new hatch creation, enter the shell:
+
+```
+cd foo/
+hatch shell
+```
+
+#### Hatch Version
+Various hatch versioning commands:
+
+```
+# print version 0.0.1
+hatch version
+# increment major version 1.0.0
+hatch version major
+# increment minor version 1.1.0
+hatch version minor
+# increment patch version 1.1.1
+hatch version patch
+# increment rc version 1.1.1rc0
+hatch version rc
+```
+
+#### Hatch Configuration
+
+Default config file:
+```
+hatch config find
+```
+
+File gets put in `~/.config/hatch/config.toml`.
+
+
+#### Hatch Add Dependency
+
+```
+hatch run pip list
+${EDITOR} pyproject.toml
+```
+Add dependency to `dependencies` section.
+
+Then to Sync dependencies, re-run:
+```
+hatch run pip list
+```
+
+See also:
+```
+hatch dep show table
+hatch dep show requirements
+```
+
+#### Hatch Testing
+
+```
+hatch run test
+hatch run cov
+```
+
+#### Hatch Build
+Build such as:
+
+```
+hatch build
+hatch build --clean
+```
+
+
+#### Hatch Publish
+Upload to PyPI:
+
+```
+hatch publish
+```
+
+#### Hatch Misc
+
+```
+hatch run which python3
+hatch env
+hatch config
+hatch project metadata
+hatch status
+```
+
+
+# Nope
+## No Ruff
+Not using `ruff` because:
+
+* The newer `ruff` linter from PyPI fails to run on ppc64le
+  (page size memory error with Debian's kernel).
+* To rebuild `ruff` a `rustc` compiler needs to be installed.
+* To rebuild `ruff` the compiler version in Debian stable is too
+  old, so it fails to build from source.
+
+## No Conda, No Anaconda
+While the Conda and Anaconda software is free software,
+usage isn't free for companies, who must pay for access
+to the servers. So the code is libre, but actually using
+it the way it is commonly used, can't be done under libre
+terms. Using `pip` is fine, and anaconda isn't ever needed.
+
+
+# Status
+Alpha, under development.
+
+
+# TODO
+Such as:
+
+* Find best-of-class ways to set up Python projects and code.
+* Starting code templates, headers for projects.
+* Proper directory layout, versioning, etc.
+* QT, argparse, daemon, web app, JACK, etc. templates.
+* Documentation system, perhaps Sphinx or something else SOTA.
+* Build system, probably hatch.
+* Push to PyPI test server.
+* Also re-build on ppc64le.
+* Linter, such as flake8 and bugbear. 
+* mypyc.
+
+
+# Upstream
+## Python
+Python Software Foundation
+
+* https://python.org
+
+* https://pypi.org
+
+
+# Disclaimer
+I am not a programmer, I'm learning Python.
+
+
+# Copyright
+Unofficial project, not related to the
+Python Software Foundation.
+
+Upstream sources under their respective copyrights.
+
+
+# License
+Source Code: AGPLv3+.
+
+*Copyright &copy; 2023, Jeff Moe.*
diff --git a/config/hatch/config.toml b/config/hatch/config.toml
new file mode 100644
index 0000000..b0c8ef5
--- /dev/null
+++ b/config/hatch/config.toml
@@ -0,0 +1,44 @@
+mode = "local"
+project = ""
+shell = ""
+
+[dirs]
+project = []
+python = "isolated"
+data = "/home/jebba/.local/share/hatch"
+cache = "/home/jebba/.cache/hatch"
+
+[dirs.env]
+
+[projects]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+    "Operating System :: POSIX :: Linux",
+]
+
+[publish.index]
+repo = "main"
+
+[template]
+name = "Jeff Moe"
+email = "moe@spacecruft.org"
+
+[template.licenses]
+headers = true
+default = [
+    "AGPL-3.0-or-later",
+]
+
+[template.plugins.default]
+tests = true
+ci = false
+src-layout = true
+
+[terminal.styles]
+info = "bold"
+success = "bold cyan"
+error = "bold red"
+warning = "bold yellow"
+waiting = "bold magenta"
+debug = "bold"
+spinner = "simpleDotsScrolling"
diff --git a/src/tasteful_python/__about__.py b/src/tasteful_python/__about__.py
index ef73dbd..7df4b9f 100644
--- a/src/tasteful_python/__about__.py
+++ b/src/tasteful_python/__about__.py
@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2023-present Jeff Moe <moe@spacecruft.org>
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
-__version__ = "0.0.1"
+__version__ = "0.0.5"