ducktools-env 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. ducktools_env-0.1.0/.github/dependabot.yml +7 -0
  2. ducktools_env-0.1.0/.github/workflows/auto_test.yml +32 -0
  3. ducktools_env-0.1.0/.github/workflows/build_zipapp.yml +65 -0
  4. ducktools_env-0.1.0/.github/workflows/publish_to_pypi.yml +87 -0
  5. ducktools_env-0.1.0/.github/workflows/publish_to_testpypi.yml +55 -0
  6. ducktools_env-0.1.0/.gitignore +139 -0
  7. ducktools_env-0.1.0/LICENSE +21 -0
  8. ducktools_env-0.1.0/PKG-INFO +236 -0
  9. ducktools_env-0.1.0/README.md +209 -0
  10. ducktools_env-0.1.0/docs/bootstrap_structure.md +25 -0
  11. ducktools_env-0.1.0/examples/inline/cowsay_ex.py +26 -0
  12. ducktools_env-0.1.0/examples/inline/empty_311_env.py +23 -0
  13. ducktools_env-0.1.0/examples/inline/empty_312_env.py +23 -0
  14. ducktools_env-0.1.0/examples/inline/pep_723_example.py +14 -0
  15. ducktools_env-0.1.0/examples/inline/print_environment_variables.py +57 -0
  16. ducktools_env-0.1.0/pyproject.toml +62 -0
  17. ducktools_env-0.1.0/setup.cfg +4 -0
  18. ducktools_env-0.1.0/src/ducktools/env/__init__.py +46 -0
  19. ducktools_env-0.1.0/src/ducktools/env/__main__.py +241 -0
  20. ducktools_env-0.1.0/src/ducktools/env/_version.py +2 -0
  21. ducktools_env-0.1.0/src/ducktools/env/bootstrapping/bootstrap.py +119 -0
  22. ducktools_env-0.1.0/src/ducktools/env/bootstrapping/bundle_main.py +93 -0
  23. ducktools_env-0.1.0/src/ducktools/env/bootstrapping/zipapp_main.py +45 -0
  24. ducktools_env-0.1.0/src/ducktools/env/bundle.py +168 -0
  25. ducktools_env-0.1.0/src/ducktools/env/bundled_data.py +152 -0
  26. ducktools_env-0.1.0/src/ducktools/env/catalogue.py +536 -0
  27. ducktools_env-0.1.0/src/ducktools/env/check_outdated_python.py +39 -0
  28. ducktools_env-0.1.0/src/ducktools/env/config.py +86 -0
  29. ducktools_env-0.1.0/src/ducktools/env/environment_specs.py +224 -0
  30. ducktools_env-0.1.0/src/ducktools/env/exceptions.py +60 -0
  31. ducktools_env-0.1.0/src/ducktools/env/manager.py +263 -0
  32. ducktools_env-0.1.0/src/ducktools/env/platform_paths.py +161 -0
  33. ducktools_env-0.1.0/src/ducktools/env/scripts/__init__.py +22 -0
  34. ducktools_env-0.1.0/src/ducktools/env/scripts/create_zipapp.py +222 -0
  35. ducktools_env-0.1.0/src/ducktools/env/scripts/get_pip.py +156 -0
  36. ducktools_env-0.1.0/src/ducktools/env/scripts/get_uv.py +87 -0
  37. ducktools_env-0.1.0/src/ducktools_env.egg-info/PKG-INFO +236 -0
  38. ducktools_env-0.1.0/src/ducktools_env.egg-info/SOURCES.txt +44 -0
  39. ducktools_env-0.1.0/src/ducktools_env.egg-info/dependency_links.txt +1 -0
  40. ducktools_env-0.1.0/src/ducktools_env.egg-info/requires.txt +13 -0
  41. ducktools_env-0.1.0/src/ducktools_env.egg-info/top_level.txt +1 -0
  42. ducktools_env-0.1.0/tests/conftest.py +77 -0
  43. ducktools_env-0.1.0/tests/test_catalogue.py +158 -0
  44. ducktools_env-0.1.0/tests/test_environmentspec.py +185 -0
  45. ducktools_env-0.1.0/tests/test_fixtures_active.py +20 -0
  46. ducktools_env-0.1.0/tests/test_integration/test_build_retrieve.py +46 -0
@@ -0,0 +1,7 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: "github-actions"
4
+ directory: "/"
5
+ schedule:
6
+ # Check for updates to GitHub Actions every week
7
+ interval: "weekly"
@@ -0,0 +1,32 @@
1
+ name: UnitTests
2
+
3
+ on:
4
+ push:
5
+ branches: [ "main" ]
6
+ pull_request:
7
+ branches: [ "main" ]
8
+
9
+ jobs:
10
+ test-prefab:
11
+
12
+ runs-on: ${{ matrix.os }}
13
+ strategy:
14
+ fail-fast: false
15
+ matrix:
16
+ os: [ubuntu-latest, windows-latest]
17
+ python-version: ["3.13-dev", "3.12", "3.11", "3.10"]
18
+ # python-version: ["3.12", "3.11", "3.10", "3.9", "3.8"]
19
+
20
+ steps:
21
+ - uses: actions/checkout@v4
22
+ - name: Set up Python ${{ matrix.python-version }}
23
+ uses: actions/setup-python@v5
24
+ with:
25
+ python-version: ${{ matrix.python-version }}
26
+ - name: Install dependencies
27
+ run: |
28
+ python -m pip install --upgrade pip
29
+ python -m pip install -e .[testing]
30
+ - name: Test with pytest
31
+ run: |
32
+ pytest tests/
@@ -0,0 +1,65 @@
1
+ name: Build zipapp
2
+
3
+ # run on push for setup/testing
4
+ on:
5
+ release:
6
+ types: [published]
7
+
8
+ jobs:
9
+ build:
10
+ name: Build zipapp
11
+ runs-on: ubuntu-latest
12
+
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+ - name: Set up Python
16
+ uses: actions/setup-python@v5
17
+ with:
18
+ python-version: "3.10" # build with oldest supported python
19
+ - name: Install the module
20
+ run: |
21
+ python -m pip install --upgrade pip
22
+ python -m pip install .
23
+ - name: Build the zipapp
24
+ run: |
25
+ python -m ducktools.env rebuild_env --zipapp
26
+ - name: Store the built zipapp
27
+ uses: actions/upload-artifact@v4
28
+ with:
29
+ name: ducktools-zipapp
30
+ path: dist/
31
+
32
+ add-to-github-release:
33
+ name: >-
34
+ Sign the zipapp with Sigstore
35
+ and upload it to GitHub Release
36
+ needs:
37
+ - build
38
+ runs-on: ubuntu-latest
39
+
40
+ permissions:
41
+ contents: write # IMPORTANT: mandatory for making GitHub Releases
42
+ id-token: write # IMPORTANT: mandatory for sigstore
43
+
44
+ steps:
45
+ - name: Download the zipapp
46
+ uses: actions/download-artifact@v4
47
+ with:
48
+ name: ducktools-zipapp
49
+ path: dist/
50
+ - name: Sign the zipapp with Sigstore
51
+ uses: sigstore/gh-action-sigstore-python@v3.0.0
52
+ with:
53
+ release-signing-artifacts: false
54
+ inputs: >-
55
+ ./dist/*.pyz
56
+ - name: Upload artifact signature to GitHub Release
57
+ env:
58
+ GITHUB_TOKEN: ${{ github.token }}
59
+ # Upload to GitHub Release using the `gh` CLI.
60
+ # `dist/` contains the built packages, and the
61
+ # sigstore-produced signatures and certificates.
62
+ run: >-
63
+ gh release upload
64
+ '${{ github.ref_name }}' dist/**
65
+ --repo '${{ github.repository }}'
@@ -0,0 +1,87 @@
1
+ name: Publish Package to PyPi
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ jobs:
8
+ build:
9
+ name: Build distribution 📦
10
+ runs-on: ubuntu-latest
11
+
12
+ steps:
13
+ - uses: actions/checkout@v4
14
+ - name: Set up Python
15
+ uses: actions/setup-python@v5
16
+ with:
17
+ python-version: "3.10"
18
+ - name: Install pypa/build
19
+ run: >-
20
+ python3 -m
21
+ pip install
22
+ build
23
+ --user
24
+ - name: Build a binary wheel and a source tarball
25
+ run: python3 -m build
26
+ - name: Store the distribution packages
27
+ uses: actions/upload-artifact@v4
28
+ with:
29
+ name: python-package-distributions
30
+ path: dist/
31
+
32
+ publish-to-pypi:
33
+ name: >-
34
+ Publish Python 🐍 distribution 📦 to PyPI
35
+ needs:
36
+ - build
37
+ runs-on: ubuntu-latest
38
+ environment:
39
+ name: pypi
40
+ url: https://pypi.org/p/ducktools-env
41
+ permissions:
42
+ id-token: write # IMPORTANT: mandatory for trusted publishing
43
+
44
+ steps:
45
+ - name: Download all the dists
46
+ uses: actions/download-artifact@v4
47
+ with:
48
+ name: python-package-distributions
49
+ path: dist/
50
+ - name: Publish distribution 📦 to PyPI
51
+ uses: pypa/gh-action-pypi-publish@release/v1
52
+
53
+ github-release:
54
+ name: >-
55
+ Sign the Python 🐍 distribution 📦 with Sigstore
56
+ and upload them to GitHub Release
57
+ needs:
58
+ - publish-to-pypi
59
+ runs-on: ubuntu-latest
60
+
61
+ permissions:
62
+ contents: write # IMPORTANT: mandatory for making GitHub Releases
63
+ id-token: write # IMPORTANT: mandatory for sigstore
64
+
65
+ steps:
66
+ - name: Download all the dists
67
+ uses: actions/download-artifact@v4
68
+ with:
69
+ name: python-package-distributions
70
+ path: dist/
71
+ - name: Sign the dists with Sigstore
72
+ uses: sigstore/gh-action-sigstore-python@v3.0.0
73
+ with:
74
+ release-signing-artifacts: false
75
+ inputs: >-
76
+ ./dist/*.tar.gz
77
+ ./dist/*.whl
78
+ - name: Upload artifact signatures to GitHub Release
79
+ env:
80
+ GITHUB_TOKEN: ${{ github.token }}
81
+ # Upload to GitHub Release using the `gh` CLI.
82
+ # `dist/` contains the built packages, and the
83
+ # sigstore-produced signatures and certificates.
84
+ run: >-
85
+ gh release upload
86
+ '${{ github.ref_name }}' dist/**
87
+ --repo '${{ github.repository }}'
@@ -0,0 +1,55 @@
1
+ name: Test Publish Package to TestPyPi
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v[0-9]+.[0-9]+.[0-9]+*"
7
+
8
+ jobs:
9
+ build:
10
+ name: Build distribution 📦
11
+ runs-on: ubuntu-latest
12
+
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+ - name: Set up Python
16
+ uses: actions/setup-python@v5
17
+ with:
18
+ python-version: "3.10"
19
+ - name: Install pypa/build
20
+ run: >-
21
+ python3 -m
22
+ pip install
23
+ build
24
+ --user
25
+ - name: Build a binary wheel and a source tarball
26
+ run: python3 -m build
27
+ - name: Store the distribution packages
28
+ uses: actions/upload-artifact@v4
29
+ with:
30
+ name: python-package-distributions
31
+ path: dist/
32
+
33
+ publish-to-testpypi:
34
+ name: Publish Python 🐍 distribution 📦 to TestPyPI
35
+ needs:
36
+ - build
37
+ runs-on: ubuntu-latest
38
+
39
+ environment:
40
+ name: testpypi
41
+ url: https://test.pypi.org/p/ducktools-env
42
+
43
+ permissions:
44
+ id-token: write # IMPORTANT: mandatory for trusted publishing
45
+
46
+ steps:
47
+ - name: Download all the dists
48
+ uses: actions/download-artifact@v4
49
+ with:
50
+ name: python-package-distributions
51
+ path: dist/
52
+ - name: Publish distribution 📦 to TestPyPI
53
+ uses: pypa/gh-action-pypi-publish@release/v1
54
+ with:
55
+ repository-url: https://test.pypi.org/legacy/
@@ -0,0 +1,139 @@
1
+ # IntelliJ project files
2
+ .idea
3
+ *.iml
4
+ out
5
+ gen
6
+
7
+ # VSCode Files
8
+ .vscode/
9
+
10
+ ### Python template
11
+ # Byte-compiled / optimized / DLL files
12
+ __pycache__/
13
+ *.py[cod]
14
+ *$py.class
15
+
16
+ # C extensions
17
+ *.so
18
+
19
+ # Distribution / packaging
20
+ .Python
21
+ build/
22
+ develop-eggs/
23
+ dist/
24
+ downloads/
25
+ eggs/
26
+ .eggs/
27
+ parts/
28
+ sdist/
29
+ var/
30
+ wheels/
31
+ share/python-wheels/
32
+ *.egg-info/
33
+ .installed.cfg
34
+ *.egg
35
+ MANIFEST
36
+
37
+ # PyInstaller
38
+ # Usually these files are written by a python script from a template
39
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
40
+ *.manifest
41
+ *.spec
42
+
43
+ # Installer logs
44
+ pip-log.txt
45
+ pip-delete-this-directory.txt
46
+
47
+ # Unit test / coverage reports
48
+ htmlcov/
49
+ .tox/
50
+ .nox/
51
+ .coverage
52
+ .coverage.*
53
+ .cache
54
+ nosetests.xml
55
+ coverage.xml
56
+ cov.xml
57
+ *.cover
58
+ *.py,cover
59
+ .hypothesis/
60
+ .pytest_cache/
61
+ cover/
62
+
63
+ # Translations
64
+ *.mo
65
+ *.pot
66
+
67
+ # Django stuff:
68
+ *.log
69
+ local_settings.py
70
+ db.sqlite3
71
+ db.sqlite3-journal
72
+
73
+ # Flask stuff:
74
+ instance/
75
+ .webassets-cache
76
+
77
+ # Scrapy stuff:
78
+ .scrapy
79
+
80
+ # Sphinx documentation
81
+ docs/_build/
82
+
83
+ # PyBuilder
84
+ .pybuilder/
85
+ target/
86
+
87
+ # Jupyter Notebook
88
+ .ipynb_checkpoints
89
+
90
+ # IPython
91
+ profile_default/
92
+ ipython_config.py
93
+
94
+ # pyenv
95
+ # For a library or package, you might want to ignore these files since the code is
96
+ # intended to run in multiple environments; otherwise, check them in:
97
+ # .python-version
98
+
99
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow
100
+ __pypackages__/
101
+
102
+ # Celery stuff
103
+ celerybeat-schedule
104
+ celerybeat.pid
105
+
106
+ # SageMath parsed files
107
+ *.sage.py
108
+
109
+ # Different python version envs
110
+ /env*/
111
+
112
+ # Spyder project settings
113
+ .spyderproject
114
+ .spyproject
115
+
116
+ # Rope project settings
117
+ .ropeproject
118
+
119
+ # mkdocs documentation
120
+ /site
121
+
122
+ # mypy
123
+ .mypy_cache/
124
+ .dmypy.json
125
+ dmypy.json
126
+
127
+ # Pyre type checker
128
+ .pyre/
129
+
130
+ # pytype static type analyzer
131
+ .pytype/
132
+
133
+ # Cython debug symbols
134
+ cython_debug/
135
+
136
+ # Scratch folder
137
+ scratch/
138
+
139
+ _version.py
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 David C Ellis
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,236 @@
1
+ Metadata-Version: 2.1
2
+ Name: ducktools-env
3
+ Version: 0.1.0
4
+ Summary: Virtual environment management tools and application bundle builder
5
+ Author: David C Ellis
6
+ Classifier: Development Status :: 2 - Pre-Alpha
7
+ Classifier: Programming Language :: Python :: 3.10
8
+ Classifier: Programming Language :: Python :: 3.11
9
+ Classifier: Programming Language :: Python :: 3.12
10
+ Classifier: Programming Language :: Python :: 3.13
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Operating System :: Microsoft :: Windows
13
+ Classifier: Operating System :: POSIX :: Linux
14
+ Requires-Python: >=3.10
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Requires-Dist: ducktools-classbuilder>=0.7.1
18
+ Requires-Dist: ducktools-lazyimporter>=0.5.1
19
+ Requires-Dist: ducktools-scriptmetadata
20
+ Requires-Dist: ducktools-pythonfinder>=0.5.3
21
+ Requires-Dist: tomli; python_version < "3.11"
22
+ Requires-Dist: packaging>=23.2
23
+ Provides-Extra: testing
24
+ Requires-Dist: pytest; extra == "testing"
25
+ Requires-Dist: pytest-cov; extra == "testing"
26
+ Requires-Dist: coverage-conditional-plugin; extra == "testing"
27
+
28
+ # DuckTools: Env #
29
+
30
+ `ducktools-env` intends to provide a few tools to aid in running and distributing
31
+ applications and scripts written in Python that require additional dependencies.
32
+
33
+ ## What is this for? ##
34
+
35
+ *Or: uv/hatch/pipx already exist, why are you creating yet another packaging tool?*
36
+
37
+ PEP-723 introduced
38
+ [inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata)
39
+ which allows users to declare dependencies for single python files in a standardized format.
40
+
41
+ Using this format requires the use of an extra package such as 'UV' or 'hatch'
42
+ using a specific command such as `uv run my_script.py` or `hatch run my_script.py`.
43
+
44
+ `ducktools.env` provides a similar command
45
+ `python ducktools.pyz run my_script.py` or `python -m ducktools.env run my_script.py`.
46
+
47
+ The problem that `ducktools.env` seeks to solve is what if you want to share your
48
+ script or application with someone **who doesn't already have** `uv` or `hatch` or
49
+ any other script runner that recognises this format.
50
+
51
+ To aid this, `ducktools.env` provides the `bundle` command.
52
+
53
+ `python ducktools.pyz bundle my_script.py`
54
+
55
+ This will generate a [zipapp](https://docs.python.org/3/library/zipapp.html) from your script
56
+ that will automatically extract and run it in the same way as with the `run` command.
57
+
58
+ This bundle will include `ducktools-env` and the `pip` zipapp in order to bootstrap the unbundling
59
+ process. `UV` will be downloaded and installed on unbundling if it is available (on PyPI)
60
+ for the platform.
61
+
62
+ Environment data and the application itself will be stored in the following locations:
63
+
64
+ * Windows: `%LOCALAPPDATA%\ducktools\env`
65
+ * Linux/Mac/Other: `~/.ducktools/env`
66
+
67
+ ## Discovering Python Installs ##
68
+
69
+ When you run a script with ducktools-env it will look at the inline dependencies.
70
+
71
+ It will use [ducktools-pythonfinder](https://github.com/DavidCEllis/ducktools-pythonfinder) to attempt
72
+ to find the newest valid python install (not a venv) that satisfies any python requirement. See its own
73
+ page for which python installs it can find.
74
+
75
+ ## Usage ##
76
+
77
+ Either install the tool from PyPI or simply download the zipapp from github.
78
+
79
+ If using the tool from PyPI the commands are `python -m ducktools.env <command>`
80
+ with the zipapp they are `python ducktools.pyz <command>`
81
+
82
+ Run a script that uses inline script metadata:
83
+ `python ducktools.pyz run my_script.py`
84
+
85
+ Bundle the script into a zipapp:
86
+ `python ducktools.pyz bundle my_script.py`
87
+
88
+ Clear the temporary environment cache:
89
+ `python ducktools.pyz clear_cache`
90
+
91
+ Clear the full `ducktools/env` install directory:
92
+ `python ducktools.pyz clear_cache --full`
93
+
94
+ Build the env folder from the installed package
95
+ **Generally you should not need to do this from the zipapp**
96
+ `python -m ducktools.env rebuild_env`
97
+
98
+ ## Locking environments ##
99
+
100
+ When generating zipapp bundles it may be desirable to also generate a lockfile
101
+ to make sure that the versions of installed dependencies do not change between
102
+ generation and execution without having to over specify in the original
103
+ script.
104
+
105
+ This generation feature uses `uv` which will be automatically installed.
106
+ `uv` is **not** required to use the generated lockfile (but will usually be installed).
107
+
108
+ Create a lockfile without running a script
109
+ `python ducktools.pyz generate_lock my_script.py`
110
+
111
+ Run a script and output the generated lockfile (output as my_script.py.lock)
112
+ `python ducktools.pyz run --generate-lock my_script.py`
113
+
114
+ Run a script using a pre-generated lockfile
115
+ `python ducktools.pyz run --with-lock my_script.py.lock my_script.py`
116
+
117
+ Bundle a script and generate a lockfile (that will be bundled)
118
+ `python ducktools.pyz bundle --generate-lock my_script.py`
119
+
120
+ Bundle a script with a pre-generated lockfile
121
+ `python ducktools.pyz bundle --with-lock my_script.py.lock my_script.py`
122
+
123
+
124
+ ## Including data files with script bundles ##
125
+
126
+ If you wish to include data files with your script you can do so using a tool
127
+ table in the toml block.
128
+
129
+ ```python
130
+ # /// script
131
+ # requires-python = ">=3.10"
132
+ # dependencies = ["cowsay"]
133
+ #
134
+ # [tool.ducktools.env]
135
+ # bundle.data = ["path/to/folder", "path/to/file.txt"]
136
+ # ///
137
+ ```
138
+
139
+ If this is made into a bundle these files and folders will be collected into a bundle_data folder
140
+ included in the zipapp.
141
+
142
+ This data can be retrieved on demand using `get_data_folder` from `ducktools.env.bundled_data` which
143
+ will create a temporary folder containing a copy of the data files and return the path to the folder.
144
+
145
+ Note: Paths are relative to the script folder. If you include a folder, the folder itself will be
146
+ included, not just its contents. This means that if you include `./` you will get the name of the
147
+ folder the script is in (along with all of its contents).
148
+
149
+ ```python
150
+ # /// script
151
+ # requires-python = ">=3.12"
152
+ # dependencies = ["ducktools-env>=0.1.0"]
153
+ #
154
+ # [tool.ducktools.env]
155
+ # bundle.data = ["./"]
156
+ # ///
157
+ from pathlib import Path
158
+
159
+ from ducktools.env.bundled_data import get_data_folder
160
+
161
+ with get_data_folder() as fld_name:
162
+ for f in Path(fld_name).rglob("*"):
163
+ print(f)
164
+ ```
165
+
166
+ ## Goals ##
167
+
168
+ Future goals for this tool:
169
+
170
+ * Optionally bundle requirements inside the zipapp for use without a connection.
171
+ * Allow bundling of local wheel files unavailable on PyPI
172
+ * Create 'permanent' named environments for stand-alone applications and update them
173
+ * Currently there is a maximum of 2 temporary environments that expire in a day
174
+ (this is due to the pre-release nature of the project, the future defaults will be higher/longer)
175
+ * Automatically install required Python if UV is available
176
+
177
+ ## Dependencies ##
178
+
179
+ Currently `ducktools.env` relies on the following tools.
180
+
181
+ Subprocesses:
182
+ * `venv` (via subprocess on python installs)
183
+ * (Might eventually use `virtualenv` as there are python installs without `venv`)
184
+ * `pip` (as a zipapp via subprocess)
185
+ * `uv` where available as a faster installer and for locking dependencies for bundles
186
+
187
+ PyPI:
188
+ * `ducktools-classbuilder` (A lazy, faster implementation of the building blocks behind things like dataclasses)
189
+ * `ducktools-lazyimporter` (A simple class based tool to handle deferred imports)
190
+ * `ducktools-scriptmetadata` (The parser for inline script metadata blocks)
191
+ * `ducktools-pythonfinder` (A tool to discover python installs available for environment creation)
192
+ * `packaging` (for comparing dependency lists to cached environments)
193
+ * `tomli` (for Python 3.10 and earlier to support the TOML format)
194
+
195
+ ## Other tools in this space ##
196
+
197
+ ### zipapp ###
198
+
199
+ The standard library `zipapp` is at the core of how `ducktools-env` works. However it doesn't support
200
+ running with C extensions and it has no inbuilt way to control which Python it will run under.
201
+
202
+ By contrast `ducktools-env` will respect a specified python version and required extensions, these
203
+ can be bundled or downloaded on first launch via `pip`.
204
+
205
+ ### Shiv ###
206
+
207
+ `shiv` allows you to bundle zipapps with C extensions, but doesn't provide for any `online` installs
208
+ and will extract everything into one `~/.shiv` directory unless otherwise specified.
209
+ `ducktools-env` will create a separate environment for each unique set of requirements
210
+ for temporary environments by matching specification.
211
+
212
+ ### PEX ###
213
+
214
+ `pex` provides an assortment of related tools for developers alongside a `.pex` bundler.
215
+ It doesn't (to my knowledge) have support for inline script metadata and it makes `.pex` files
216
+ instead of `.pyz` files.
217
+
218
+ ### PyInstaller ###
219
+
220
+ Pyinstaller will generate an executable from your script but will also bundle all of your
221
+ dependencies in a platform specific way. It also bundles Python itself, which while
222
+ convenient if python is not installed, is unnecessary if we can treat Python as a shared
223
+ library.
224
+
225
+ ### Hatch ###
226
+
227
+ `Hatch` allows you to run scripts with inline dependencies, but requires the user on the other end
228
+ already have hatch installed. The goal of `ducktools-env` is to make it so you can quickly bundle the script
229
+ into a zipapp that will work on the other end with only Python as the requirement.
230
+
231
+ ### pipx ###
232
+
233
+ `pipx` is another tool that allows you to install packages from PyPI and run them as applications
234
+ based on their `[project.scripts]` and `[project.gui-scripts]`. This is a goal of ducktools.env,
235
+ except it would build separate zipapps for each script and the apps would share the same cached
236
+ python environment.