Merge branch 'release/0.3.8'

LICENSE

@@ -1,15 +1,24 @@
+This is free and unencumbered software released into the public domain.
 
-             DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
-                     Version 2, December 2004
-
- Copyright (C) 2004 Sam Hocevar <[email protected]>
-
- Everyone is permitted to copy and distribute verbatim or modified
- copies of this license document, and changing it is allowed as long
- as the name is changed.
-
-             DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
-     TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
- 0. You just DO WHAT THE FUCK YOU WANT TO.
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
 
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

NEWS.rst

@@ -2,6 +2,19 @@
 News
 ====
 
+0.3.8
+=====
+
+Changed
+-------
+
+- Add alternative documentation parsing backend: ugrep
+- Small improvements to docs and error messages
+- Updated Alpine demo container base image
+- Use localtraps option everywhere we TRAP
+- Document zsh-autoenv and direnv zpy-friendly configuration
+- Increase uniformity of behavior between uv pip sync and pip-sync
+
 0.3.7
 =====
 

doc/mkdocs/mkdocs.yml

@@ -1,6 +1,6 @@
 # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
 
-site_name: 'zpy: Manage Python Environments in Zsh'
+site_name: "zpy: Manage Python Environments in Zsh"
 site_url: https://andydecleyre.github.io/zpy/
 repo_url: https://github.com/andydecleyre/zpy
 docs_dir: ../src
@@ -40,20 +40,21 @@ theme:
 nav:
   - index.md
   - Guide:
-    - start.md
-    - new_proj.md
-    - new_proj/activate.md
-    - new_proj/pipacs.md
-    - new_proj/pipac.md
-    - new_proj/pips_envin.md
-    - new_proj/upgrade.md
-    - new_proj/pyproject.md
-    - new_proj/run.md
-    - existing_projects.md
-    - pipz.md
-    - python_versions.md
+      - start.md
+      - new_proj.md
+      - new_proj/activate.md
+      - new_proj/pipacs.md
+      - new_proj/pipac.md
+      - new_proj/pips_envin.md
+      - new_proj/upgrade.md
+      - new_proj/pyproject.md
+      - new_proj/run.md
+      - existing_projects.md
+      - pipz.md
+      - python_versions.md
   - Details:
-    - help_all.md
-    - deps.md
-    - install.md
-    - completions.md
+      - help_all.md
+      - deps.md
+      - install.md
+      - completions.md
+      - direnv.md

doc/mkdocs/requirements.txt

@@ -1,29 +1,29 @@
-babel==2.15.0             # via mkdocs-material
-certifi==2024.2.2         # via requests
+babel==2.16.0             # via mkdocs-material
+certifi==2024.8.30        # via requests
 charset-normalizer==3.3.2  # via requests
 click==8.1.7              # via mkdocs
 colorama==0.4.6           # via mkdocs-material
 ghp-import==2.1.0         # via mkdocs
-idna==3.7                 # via requests
+idna==3.10                # via requests
 jinja2==3.1.4             # via mkdocs, mkdocs-material
-markdown==3.6             # via mkdocs, mkdocs-material, pymdown-extensions
+markdown==3.7             # via mkdocs, mkdocs-material, pymdown-extensions
 markupsafe==2.1.5         # via jinja2, mkdocs
 mergedeep==1.3.4          # via mkdocs, mkdocs-get-deps
-mkdocs==1.6.0             # via -r requirements.in, mkdocs-material
+mkdocs==1.6.1             # via -r requirements.in, mkdocs-material
 mkdocs-get-deps==0.2.0    # via mkdocs
-mkdocs-material==9.5.21   # via -r requirements.in
+mkdocs-material==9.5.34   # via -r requirements.in
 mkdocs-material-extensions==1.3.1  # via mkdocs-material
-packaging==24.0           # via mkdocs
-paginate==0.5.6           # via mkdocs-material
+packaging==24.1           # via mkdocs
+paginate==0.5.7           # via mkdocs-material
 pathspec==0.12.1          # via mkdocs
-platformdirs==4.2.1       # via mkdocs-get-deps
+platformdirs==4.3.3       # via mkdocs-get-deps
 pygments==2.18.0          # via mkdocs-material
-pymdown-extensions==10.8.1  # via mkdocs-material
+pymdown-extensions==10.9  # via mkdocs-material
 python-dateutil==2.9.0.post0  # via ghp-import
-pyyaml==6.0.1             # via mkdocs, mkdocs-get-deps, pymdown-extensions, pyyaml-env-tag
+pyyaml==6.0.2             # via mkdocs, mkdocs-get-deps, pymdown-extensions, pyyaml-env-tag
 pyyaml-env-tag==0.1       # via mkdocs
-regex==2024.4.28          # via mkdocs-material
-requests==2.31.0          # via mkdocs-material
+regex==2024.9.11          # via mkdocs-material
+requests==2.32.3          # via mkdocs-material
 six==1.16.0               # via python-dateutil
-urllib3==2.2.1            # via requests
-watchdog==4.0.0           # via mkdocs
+urllib3==2.2.3            # via requests
+watchdog==5.0.2           # via mkdocs

doc/src/deps.md

@@ -98,5 +98,6 @@ with optional additions for more colorful output, alternative json parsers, and
     - a pcre tool -- provided by
       pcregrep/pcre-tools,
       pcre2grep/pcre2-tools,
-      [ripgrep](https://repology.org/project/ripgrep/versions),
+      [ripgrep (>=14.0.0)](https://repology.org/project/ripgrep/versions),
+      [ugrep](https://repology.org/project/ugrep/versions),
       or Zsh with pcre enabled

doc/src/direnv.md

@@ -0,0 +1,64 @@
+# Automatic Activation
+
+If you'd like your shell to automatically activate and deactivate venvs
+when you switch directories, there are a few tools to make that happen.
+
+Here's how to configure them to do so in a zpy-friendly way.
+If you notice room for improvement, or your favorite tool is missing,
+please open an issue or discussion on GitHub.
+
+=== "zsh-autoenv"
+
+    [zsh-autoenv](https://github.com/Tarrasch/zsh-autoenv)
+    runs any Zsh code you want in your current shell,
+    making it the simplest tool to configure for this job.
+
+    In any project folder, create the following two files:
+
+    `.autoenv.zsh`:
+
+    ```zsh
+    a8 ${0:h}
+    ```
+
+    `.autoenv_leave.zsh`:
+
+    ```zsh
+    if [[ $VIRTUAL_ENV ]]  envout
+    ```
+
+    The zero in `${0:h}` is the path of the `.autoenv.zsh` file,
+    and the `:h` expansion gets that path's parent.
+    This ensures the proper project folder is used,
+    even if you're activating the script by entering a deeper subdirectory.
+
+=== "direnv"
+
+    [direnv](https://github.com/direnv/direnv/)
+    runs Bash (not Zsh) and exports variables.
+    We'll create a self-contained script for each of `a8` and `venvs_path`,
+    so that we can easily call them from Bash.
+
+    Assuming `~/.local/bin` is in your `PATH`, run
+
+    ```console
+    $ zpy mkbin a8 ~/.local/bin/
+    $ zpy mkbin venvs_path ~/.local/bin/
+    ```
+
+    Now define a Bash function within the file `~/.config/direnv/direnvrc`:
+
+    ```bash
+    layout_zpy () {
+      a8
+      export VIRTUAL_ENV="$(venvs_path)/venv"
+      PATH_add "$VIRTUAL_ENV/bin"
+      export VENV_ACTIVE=1
+    }
+    ```
+
+    In any project folder, create `.envrc`:
+
+    ```bash
+    layout zpy
+    ```

doc/src/new_proj/pipacs.md

@@ -17,7 +17,7 @@ we'll use `pipacs` to:
 [venv] % pipacs beautifulsoup4
 ```
 
-![Animated demo: pipacs](https://gist.githubusercontent.com/AndydeCleyre/b422097e220806b31c4d1c80ed0ed6b5/raw/ee65dd02265b3e5e7b85996bc6dfd22175a3b78c/guide_pipacs.svg?sanitize=true)
+![Animated demo: pipacs](https://github.com/AndydeCleyre/zpy/blob/assets/guide_pipacs.gif?raw=true)
 
 Being such a popular package,
 we were able to tab-complete the name `beautifulsoup4`,

doc/src/new_proj/pyproject.md

@@ -34,7 +34,7 @@ we can populate it with entries from our `requirements.in` files:
 [venv] % pypc
 ```
 
-![Animated demo: pypc](https://gist.github.com/AndydeCleyre/c8cad3380bd475706815969b07733a55/raw/5a4b327bf699819c96c8126de4ef60546c5cccea/pypc_demo.svg?sanitize=true)
+![Animated demo: pypc](https://github.com/AndydeCleyre/zpy/blob/assets/pypc.gif?raw=true)
 
 The dependencies have been injected according to
 [PEP 621](https://www.python.org/dev/peps/pep-0621/),

doc/src/new_proj/run.md

@@ -15,7 +15,7 @@ We can ensure we've got a proper environment and run it:
 [venv] % ./do_thing.py
 ```
 
-![Animated demo: envin, run script](https://gist.github.com/AndydeCleyre/27bfa0e10a1b42191f777530a500263e/raw/0554370718428b26755902f5c6b12375cabc2d59/envin_do_thing.svg?sanitize=true)
+![Animated demo: envin, run script](https://github.com/AndydeCleyre/zpy/blob/assets/envin_do_thing.gif?raw=true)
 
 But what if we don't want to manually activate its environment?
 

doc/src/pipz.md

@@ -34,11 +34,7 @@ The paths printed on the first three lines of output may be overridden with the
 `ZPY_PIPZ_BINS`,
 respectively.
 
-![Animated demo: pipz install, list](https://gist.github.com/AndydeCleyre/5ad45d78336fc2cc4625b0dc6b450849/raw/777e77607786beb65b2d6e00fb27c507c5e7abfa/pipz_install_list.svg?sanitize=true)
-
-!!! note
-
-    The last frame is mangled in this animation, but not in real usage.
+![Animated demo: pipz install, list](https://github.com/AndydeCleyre/zpy/blob/assets/pipz_install_list.gif?raw=true)
 
 Example installing an app package from git:
 

doc/src/start.md

@@ -1,5 +1,11 @@
 # Get started
 
+!!! tip
+
+    You can flip through these docs with `n` and `p`, or `.` and `,`.
+
+## Install locally
+
 Aside from Zsh and Python, the only dependency you're likely to *need* is
 [`fzf`](https://github.com/junegunn/fzf).
 For more details and recommended package manager commands, see [Dependencies](deps.md).
@@ -17,9 +23,6 @@ For now, let's just source it in the current session:
 % . ~/.zpy/zpy.plugin.zsh
 ```
 
-The user-facing functions are all available as subcommands to `zpy`.
-Try typing `zpy`, then a space, then tab.
-
 !!! tip
 
     Everything zpy does will generally be much faster if uv is installed.
@@ -29,26 +32,52 @@ Try typing `zpy`, then a space, then tab.
     % pipz install uv
     ```
 
-!!! info
+## Try it in a container, instead
+
+Using either podman or docker, launch a temporary container based on Ubuntu, Alpine, or Fedora:
+
+=== "Ubuntu"
+
+    ```console
+    $ podman run --net=host -it --rm -e TERM=$TERM quay.io/andykluger/zpy-ubuntu:master
+    $ docker run --net=host -it --rm -e TERM=$TERM quay.io/andykluger/zpy-ubuntu:master
+    ```
+
+=== "Alpine"
+
+    ```console
+    $ podman run --net=host -it --rm -e TERM=$TERM quay.io/andykluger/zpy-alpine:master
+    $ docker run --net=host -it --rm -e TERM=$TERM quay.io/andykluger/zpy-alpine:master
+    ```
 
-    By default, each function is *also* available directly, as a "top-level" command[^1].
-    This can be prevented by explicitly specifying a list of functions to expose,
-    *before* sourcing the plugin.
-    This example will expose only the `pipz` and `zpy` functions
-    (the rest remaining available as subcommands):
+=== "Fedora"
 
     ```console
-    % zstyle ':zpy:*' exposed-funcs pipz zpy
+    $ podman run --net=host -it --rm -e TERM=$TERM quay.io/andykluger/zpy-fedora:master
+    $ docker run --net=host -it --rm -e TERM=$TERM quay.io/andykluger/zpy-fedora:master
     ```
 
+## Functions or Subcommands
+
+The user-facing functions are all available as subcommands to `zpy`.
+Try typing `zpy`, then a space, then tab.
+
+By default, each function is *also* available directly, as a "top-level" command[^1].
+This can be **prevented** by explicitly specifying a list of functions to expose,
+*before* sourcing the plugin.
+This example will expose only the `pipz` and `zpy` functions
+(the rest remaining available as subcommands):
+
+```console
+% zstyle ':zpy:*' exposed-funcs pipz zpy
+```
+
 [^1]: Well, except for `zpy mkbin` and `zpy help`.
 
+## Moving on
+
 From here, you may want to:
 
 - continue to the [next page](new_proj.md), for an idea of how these tools can help manage a project
 - jump to the [full reference](help_all.md)
 - jump to [`pipz`](pipz.md), a [pipx](https://pypa.github.io/pipx/) alternative
-
-!!! tip
-
-    You can flip through these docs with `n` and `p`, or `.` and `,`.

mk/ctnr/zcomet.sh

@@ -32,7 +32,7 @@ case $distro in
     alias ctnr_mkuser="ctnr_run useradd -m -s /bin/zsh"
   ;;
   alpine)
-    basetag=${2:-3.19}
+    basetag=${2:-3.20}
     pkgs="$pkgs git sudo"
     fat="$fat /var/cache/apk/*"
     alias ctnr_pkg="ctnr_run apk -q --no-progress"