ducktools-env 0.1.0a1__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 (41) hide show
  1. ducktools_env-0.1.0a1/.github/dependabot.yml +7 -0
  2. ducktools_env-0.1.0a1/.github/workflow_templates/auto_test.yml +32 -0
  3. ducktools_env-0.1.0a1/.github/workflows/publish_to_pypi.yml +87 -0
  4. ducktools_env-0.1.0a1/.github/workflows/publish_to_testpypi.yml +55 -0
  5. ducktools_env-0.1.0a1/.gitignore +142 -0
  6. ducktools_env-0.1.0a1/LICENSE +21 -0
  7. ducktools_env-0.1.0a1/PKG-INFO +150 -0
  8. ducktools_env-0.1.0a1/README.md +119 -0
  9. ducktools_env-0.1.0a1/docs/bootstrap_structure.md +25 -0
  10. ducktools_env-0.1.0a1/examples/inline/cowsay_ex.py +26 -0
  11. ducktools_env-0.1.0a1/examples/inline/empty_311_env.py +23 -0
  12. ducktools_env-0.1.0a1/examples/inline/empty_312_env.py +23 -0
  13. ducktools_env-0.1.0a1/plan.md +69 -0
  14. ducktools_env-0.1.0a1/pyproject.toml +66 -0
  15. ducktools_env-0.1.0a1/setup.cfg +4 -0
  16. ducktools_env-0.1.0a1/src/ducktools/env/__init__.py +43 -0
  17. ducktools_env-0.1.0a1/src/ducktools/env/__main__.py +114 -0
  18. ducktools_env-0.1.0a1/src/ducktools/env/_version.py +2 -0
  19. ducktools_env-0.1.0a1/src/ducktools/env/bundle/__init__.py +127 -0
  20. ducktools_env-0.1.0a1/src/ducktools/env/bundle/bundle_main.py +72 -0
  21. ducktools_env-0.1.0a1/src/ducktools/env/catalogue.py +438 -0
  22. ducktools_env-0.1.0a1/src/ducktools/env/config.py +80 -0
  23. ducktools_env-0.1.0a1/src/ducktools/env/environment_specs.py +190 -0
  24. ducktools_env-0.1.0a1/src/ducktools/env/exceptions.py +56 -0
  25. ducktools_env-0.1.0a1/src/ducktools/env/manager.py +76 -0
  26. ducktools_env-0.1.0a1/src/ducktools/env/platform_paths.py +169 -0
  27. ducktools_env-0.1.0a1/src/ducktools/env/run/__init__.py +38 -0
  28. ducktools_env-0.1.0a1/src/ducktools/env/scripts/bootstrap.py +102 -0
  29. ducktools_env-0.1.0a1/src/ducktools/env/scripts/clear_cache.py +29 -0
  30. ducktools_env-0.1.0a1/src/ducktools/env/scripts/create_zipapp.py +218 -0
  31. ducktools_env-0.1.0a1/src/ducktools/env/scripts/get_pip.py +155 -0
  32. ducktools_env-0.1.0a1/src/ducktools/env/scripts/zipapp_main.py +28 -0
  33. ducktools_env-0.1.0a1/src/ducktools_env.egg-info/PKG-INFO +150 -0
  34. ducktools_env-0.1.0a1/src/ducktools_env.egg-info/SOURCES.txt +39 -0
  35. ducktools_env-0.1.0a1/src/ducktools_env.egg-info/dependency_links.txt +1 -0
  36. ducktools_env-0.1.0a1/src/ducktools_env.egg-info/requires.txt +15 -0
  37. ducktools_env-0.1.0a1/src/ducktools_env.egg-info/top_level.txt +1 -0
  38. ducktools_env-0.1.0a1/tests/conftest.py +77 -0
  39. ducktools_env-0.1.0a1/tests/test_environmentspec.py +55 -0
  40. ducktools_env-0.1.0a1/tests/test_fixtures_active.py +20 -0
  41. ducktools_env-0.1.0a1/tests/test_integration/test_build_retrieve.py +37 -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.12", "3.8"]
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,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.8"
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.8"
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,142 @@
1
+ # IntelliJ project files
2
+ .idea
3
+ *.iml
4
+ out
5
+ gen
6
+
7
+ ### Python template
8
+ # Byte-compiled / optimized / DLL files
9
+ __pycache__/
10
+ *.py[cod]
11
+ *$py.class
12
+
13
+ # C extensions
14
+ *.so
15
+
16
+ # Distribution / packaging
17
+ .Python
18
+ build/
19
+ develop-eggs/
20
+ dist/
21
+ downloads/
22
+ eggs/
23
+ .eggs/
24
+ parts/
25
+ sdist/
26
+ var/
27
+ wheels/
28
+ share/python-wheels/
29
+ *.egg-info/
30
+ .installed.cfg
31
+ *.egg
32
+ MANIFEST
33
+
34
+ # PyInstaller
35
+ # Usually these files are written by a python script from a template
36
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
37
+ *.manifest
38
+ *.spec
39
+
40
+ # Installer logs
41
+ pip-log.txt
42
+ pip-delete-this-directory.txt
43
+
44
+ # Unit test / coverage reports
45
+ htmlcov/
46
+ .tox/
47
+ .nox/
48
+ .coverage
49
+ .coverage.*
50
+ .cache
51
+ nosetests.xml
52
+ coverage.xml
53
+ *.cover
54
+ *.py,cover
55
+ .hypothesis/
56
+ .pytest_cache/
57
+ cover/
58
+
59
+ # Translations
60
+ *.mo
61
+ *.pot
62
+
63
+ # Django stuff:
64
+ *.log
65
+ local_settings.py
66
+ db.sqlite3
67
+ db.sqlite3-journal
68
+
69
+ # Flask stuff:
70
+ instance/
71
+ .webassets-cache
72
+
73
+ # Scrapy stuff:
74
+ .scrapy
75
+
76
+ # Sphinx documentation
77
+ docs/_build/
78
+
79
+ # PyBuilder
80
+ .pybuilder/
81
+ target/
82
+
83
+ # Jupyter Notebook
84
+ .ipynb_checkpoints
85
+
86
+ # IPython
87
+ profile_default/
88
+ ipython_config.py
89
+
90
+ # pyenv
91
+ # For a library or package, you might want to ignore these files since the code is
92
+ # intended to run in multiple environments; otherwise, check them in:
93
+ # .python-version
94
+
95
+ # pipenv
96
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
97
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
98
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
99
+ # install all needed dependencies.
100
+ #Pipfile.lock
101
+
102
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow
103
+ __pypackages__/
104
+
105
+ # Celery stuff
106
+ celerybeat-schedule
107
+ celerybeat.pid
108
+
109
+ # SageMath parsed files
110
+ *.sage.py
111
+
112
+ # Different python version envs
113
+ /env*/
114
+
115
+ # Spyder project settings
116
+ .spyderproject
117
+ .spyproject
118
+
119
+ # Rope project settings
120
+ .ropeproject
121
+
122
+ # mkdocs documentation
123
+ /site
124
+
125
+ # mypy
126
+ .mypy_cache/
127
+ .dmypy.json
128
+ dmypy.json
129
+
130
+ # Pyre type checker
131
+ .pyre/
132
+
133
+ # pytype static type analyzer
134
+ .pytype/
135
+
136
+ # Cython debug symbols
137
+ cython_debug/
138
+
139
+ # Scratch folder
140
+ scratch/
141
+
142
+ _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,150 @@
1
+ Metadata-Version: 2.1
2
+ Name: ducktools-env
3
+ Version: 0.1.0a1
4
+ Summary: Virtual environment management tools and application bundle builder
5
+ Author: David C Ellis
6
+ Classifier: Development Status :: 1 - Planning
7
+ Classifier: Programming Language :: Python :: 3.8
8
+ Classifier: Programming Language :: Python :: 3.9
9
+ Classifier: Programming Language :: Python :: 3.10
10
+ Classifier: Programming Language :: Python :: 3.11
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Operating System :: Microsoft :: Windows
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Requires-Python: >=3.8
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: ducktools-classbuilder>=0.7.0
20
+ Requires-Dist: ducktools-lazyimporter>=0.5.1
21
+ Requires-Dist: ducktools-scriptmetadata
22
+ Requires-Dist: ducktools-pythonfinder>=0.3.0
23
+ Requires-Dist: tomli; python_version <= "3.10"
24
+ Requires-Dist: packaging>=23.2
25
+ Requires-Dist: importlib-resources>=6.0
26
+ Requires-Dist: zipp>=3.16
27
+ Provides-Extra: testing
28
+ Requires-Dist: pytest; extra == "testing"
29
+ Requires-Dist: pytest-cov; extra == "testing"
30
+ Requires-Dist: coverage-conditional-plugin; extra == "testing"
31
+
32
+ # DuckTools: Env #
33
+
34
+ `ducktools-env` intends to provide a few tools to aid in running and distributing
35
+ applications and scripts written in Python that require additional dependencies.
36
+
37
+ ## Currently implemented ##
38
+
39
+ This pre-release version provides a way to run scripts based on
40
+ [inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata)
41
+ and a second tool to bundle such scripts into python's
42
+ [zipapp](https://docs.python.org/3/library/zipapp.html)
43
+ format in a way that can be run without needing to have `ducktools-env` already installed.
44
+
45
+ This works by creating temporary environments in the following folders:
46
+
47
+ * Windows: `%LOCALAPPDATA%\ducktools\environments`
48
+ * Linux: `~/.ducktools/environments`
49
+ * Mac: Unsure, currently not supported - possibly in `~/Library/Caches/ducktools/environments`?
50
+
51
+ ## What it does ##
52
+
53
+ When you run a script with ducktools-env it will look at the inline dependencies.
54
+
55
+ It will use [ducktools-pythonfinder](https://github.com/DavidCEllis/ducktools-pythonfinder) to attempt
56
+ to find the newest valid python install (not a venv) that satisfies any python requirement.
57
+
58
+ Having done that it will create a temporary venv with any dependencies listed and execute the script in the
59
+ venv.
60
+
61
+ ## Usage ##
62
+
63
+ Either install the tool from PyPI or simply download the zipapp from github.
64
+
65
+ Run a script that uses inline script metadata:
66
+ `python ducktools.pyz run my_script.py`
67
+
68
+ Bundle the script into a zipapp:
69
+ `python ducktools.pyz bundle my_script.py`
70
+
71
+ Clear the temporary environment cache:
72
+ `python ducktools.pyz clear_cache`
73
+
74
+ Re-install the cached ducktools-env
75
+ `python ducktools.pyz rebuild_env`
76
+
77
+ ## Goals ##
78
+
79
+ Future goals for this tool:
80
+
81
+ * Bundle requirements inside the zipapp for use without a connection.
82
+ * Bundle applications that are wheels with a `__main__.py` function.
83
+ * Create 'permanent' named environments for stand-alone applications and update them
84
+ * Currently there is a maximum of 2 temporary environments that expire in a day
85
+ (this is due to the pre-release nature of the project, the future defaults will be higher/longer)
86
+
87
+ ## Dependencies ##
88
+
89
+ Currently `ducktools.env` relies on the following tools.
90
+
91
+ Subprocesses:
92
+ * `venv` (via subprocess on python installs)
93
+ * (Might eventually use `virtualenv` as there are python installs without `venv`)
94
+ * `pip` (as a zipapp via subprocess)
95
+
96
+ PyPI:
97
+ * `ducktools-classbuilder` (A lazy, faster implementation of the building blocks behind things like dataclasses)
98
+ * `ducktools-lazyimporter` (A simple class based tool to handle deferred imports)
99
+ * `ducktools-scriptmetadata` (The parser for inline script metadata blocks)
100
+ * `ducktools-pythonfinder` (A tool to discover python installs available for environment creation)
101
+ * `packaging` (for comparing dependency lists to cached environments)
102
+ * `tomli` (for Python 3.10 and earlier to support the TOML format)
103
+ * `importlib-resources` (to handle finding file paths correctly when building bundles)
104
+ * `zipp` (To handle path-like objects in zips in older python correctly)
105
+
106
+ ## Other tools in this space ##
107
+
108
+ ### zipapp ###
109
+
110
+ The standard library `zipapp` is at the core of how `ducktools-env` works. However it doesn't support
111
+ running with C extensions and it has no inbuilt way to control which Python it will run under.
112
+
113
+ By contrast `ducktools-env` will respect a specified python version and required extensions, these
114
+ can be bundled or downloaded on first launch via `pip`.
115
+
116
+ ### Shiv ###
117
+
118
+ `shiv` allows you to bundle zipapps with C extensions, but doesn't provide for any `online` installs
119
+ and will extract everything into one `~/.shiv` directory unless otherwise specified.
120
+ `ducktools-env` will create a separate environment for each unique set of requirements
121
+ for temporary environments by matching specification.
122
+
123
+ ### PEX ###
124
+
125
+ `pex` provides an assortment of related tools for developers alongside a `.pex` bundler.
126
+ It doesn't (to my knowledge) have support for inline script metadata and it makes `.pex` files
127
+ instead of `.pyz` files.
128
+
129
+ ### Hatch ###
130
+
131
+ `Hatch` allows you to run scripts with inline dependencies, but requires the user on the other end
132
+ already have hatch installed. The goal of `ducktools-env` is to make it so you can quickly bundle the script
133
+ into a zipapp that will work on the other end with only Python as the requirement.
134
+
135
+ ### pipx ###
136
+
137
+ `pipx` is another tool that allows you to install packages from PyPI and run them as applications
138
+ based on their `[project.scripts]` and `[project.gui-scripts]`. This is *somewhat* a goal of
139
+ ducktools.env, except it would build separate zipapps for each script and the apps would share
140
+ the same cached python environment.
141
+
142
+ ## Why not use UV for dependency management? ##
143
+
144
+ UV is new and fast, but in order to make the install portable **without** always requiring
145
+ an internet connection it would be necessary to bundle the binaries for UV for every
146
+ platform, meaning 16 copies at over 200MB. Even then there may be platforms where someone
147
+ has built Python but not uv.
148
+
149
+ By relying on pure python dependencies only, `ducktools-env` should work anywhere that Python
150
+ works and does not require any additional compilation.
@@ -0,0 +1,119 @@
1
+ # DuckTools: Env #
2
+
3
+ `ducktools-env` intends to provide a few tools to aid in running and distributing
4
+ applications and scripts written in Python that require additional dependencies.
5
+
6
+ ## Currently implemented ##
7
+
8
+ This pre-release version provides a way to run scripts based on
9
+ [inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata)
10
+ and a second tool to bundle such scripts into python's
11
+ [zipapp](https://docs.python.org/3/library/zipapp.html)
12
+ format in a way that can be run without needing to have `ducktools-env` already installed.
13
+
14
+ This works by creating temporary environments in the following folders:
15
+
16
+ * Windows: `%LOCALAPPDATA%\ducktools\environments`
17
+ * Linux: `~/.ducktools/environments`
18
+ * Mac: Unsure, currently not supported - possibly in `~/Library/Caches/ducktools/environments`?
19
+
20
+ ## What it does ##
21
+
22
+ When you run a script with ducktools-env it will look at the inline dependencies.
23
+
24
+ It will use [ducktools-pythonfinder](https://github.com/DavidCEllis/ducktools-pythonfinder) to attempt
25
+ to find the newest valid python install (not a venv) that satisfies any python requirement.
26
+
27
+ Having done that it will create a temporary venv with any dependencies listed and execute the script in the
28
+ venv.
29
+
30
+ ## Usage ##
31
+
32
+ Either install the tool from PyPI or simply download the zipapp from github.
33
+
34
+ Run a script that uses inline script metadata:
35
+ `python ducktools.pyz run my_script.py`
36
+
37
+ Bundle the script into a zipapp:
38
+ `python ducktools.pyz bundle my_script.py`
39
+
40
+ Clear the temporary environment cache:
41
+ `python ducktools.pyz clear_cache`
42
+
43
+ Re-install the cached ducktools-env
44
+ `python ducktools.pyz rebuild_env`
45
+
46
+ ## Goals ##
47
+
48
+ Future goals for this tool:
49
+
50
+ * Bundle requirements inside the zipapp for use without a connection.
51
+ * Bundle applications that are wheels with a `__main__.py` function.
52
+ * Create 'permanent' named environments for stand-alone applications and update them
53
+ * Currently there is a maximum of 2 temporary environments that expire in a day
54
+ (this is due to the pre-release nature of the project, the future defaults will be higher/longer)
55
+
56
+ ## Dependencies ##
57
+
58
+ Currently `ducktools.env` relies on the following tools.
59
+
60
+ Subprocesses:
61
+ * `venv` (via subprocess on python installs)
62
+ * (Might eventually use `virtualenv` as there are python installs without `venv`)
63
+ * `pip` (as a zipapp via subprocess)
64
+
65
+ PyPI:
66
+ * `ducktools-classbuilder` (A lazy, faster implementation of the building blocks behind things like dataclasses)
67
+ * `ducktools-lazyimporter` (A simple class based tool to handle deferred imports)
68
+ * `ducktools-scriptmetadata` (The parser for inline script metadata blocks)
69
+ * `ducktools-pythonfinder` (A tool to discover python installs available for environment creation)
70
+ * `packaging` (for comparing dependency lists to cached environments)
71
+ * `tomli` (for Python 3.10 and earlier to support the TOML format)
72
+ * `importlib-resources` (to handle finding file paths correctly when building bundles)
73
+ * `zipp` (To handle path-like objects in zips in older python correctly)
74
+
75
+ ## Other tools in this space ##
76
+
77
+ ### zipapp ###
78
+
79
+ The standard library `zipapp` is at the core of how `ducktools-env` works. However it doesn't support
80
+ running with C extensions and it has no inbuilt way to control which Python it will run under.
81
+
82
+ By contrast `ducktools-env` will respect a specified python version and required extensions, these
83
+ can be bundled or downloaded on first launch via `pip`.
84
+
85
+ ### Shiv ###
86
+
87
+ `shiv` allows you to bundle zipapps with C extensions, but doesn't provide for any `online` installs
88
+ and will extract everything into one `~/.shiv` directory unless otherwise specified.
89
+ `ducktools-env` will create a separate environment for each unique set of requirements
90
+ for temporary environments by matching specification.
91
+
92
+ ### PEX ###
93
+
94
+ `pex` provides an assortment of related tools for developers alongside a `.pex` bundler.
95
+ It doesn't (to my knowledge) have support for inline script metadata and it makes `.pex` files
96
+ instead of `.pyz` files.
97
+
98
+ ### Hatch ###
99
+
100
+ `Hatch` allows you to run scripts with inline dependencies, but requires the user on the other end
101
+ already have hatch installed. The goal of `ducktools-env` is to make it so you can quickly bundle the script
102
+ into a zipapp that will work on the other end with only Python as the requirement.
103
+
104
+ ### pipx ###
105
+
106
+ `pipx` is another tool that allows you to install packages from PyPI and run them as applications
107
+ based on their `[project.scripts]` and `[project.gui-scripts]`. This is *somewhat* a goal of
108
+ ducktools.env, except it would build separate zipapps for each script and the apps would share
109
+ the same cached python environment.
110
+
111
+ ## Why not use UV for dependency management? ##
112
+
113
+ UV is new and fast, but in order to make the install portable **without** always requiring
114
+ an internet connection it would be necessary to bundle the binaries for UV for every
115
+ platform, meaning 16 copies at over 200MB. Even then there may be platforms where someone
116
+ has built Python but not uv.
117
+
118
+ By relying on pure python dependencies only, `ducktools-env` should work anywhere that Python
119
+ works and does not require any additional compilation.
@@ -0,0 +1,25 @@
1
+ # Bootstrap project structures #
2
+
3
+ ## Online Bootstrap ##
4
+
5
+ ```
6
+ __main__.py
7
+ ducktools/env/... <- Full ducktools env folder - could be reduced in future
8
+
9
+ instructions.json <- Build instructions/environment settings
10
+ app.py <- Generated application script that will be called
11
+ ```
12
+
13
+
14
+
15
+ ## Offline Bootstrap ##
16
+
17
+ ```
18
+ __main__.py
19
+ ducktools/env/... <-- Full ducktools env folder
20
+
21
+ wheels/... <-- all dependencies from pip freeze as wheels
22
+
23
+ instructions.json <-- includes instruction not to update from online
24
+ app.py
25
+ ```
@@ -0,0 +1,26 @@
1
+ # DuckTools-EnvMan
2
+ # Copyright (C) 2024 David C Ellis
3
+ #
4
+ # This program is free software: you can redistribute it and/or modify
5
+ # it under the terms of the GNU Lesser General Public License as published by
6
+ # the Free Software Foundation, either version 3 of the License, or
7
+ # (at your option) any later version.
8
+ #
9
+ # This program is distributed in the hope that it will be useful,
10
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
11
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
+ # GNU Lesser General Public License for more details.
13
+ #
14
+ # You should have received a copy of the GNU Lesser General Public License
15
+ # along with this program. If not, see <https://www.gnu.org/licenses/>.
16
+
17
+ # /// script
18
+ # requires-python = ">=3.8.0"
19
+ # dependencies = ["cowsay"]
20
+ # ///
21
+
22
+ import sys
23
+ from cowsay.__main__ import cli
24
+
25
+ if __name__ == "__main__":
26
+ cli()
@@ -0,0 +1,23 @@
1
+ # DuckTools-EnvMan
2
+ # Copyright (C) 2024 David C Ellis
3
+ #
4
+ # This program is free software: you can redistribute it and/or modify
5
+ # it under the terms of the GNU Lesser General Public License as published by
6
+ # the Free Software Foundation, either version 3 of the License, or
7
+ # (at your option) any later version.
8
+ #
9
+ # This program is distributed in the hope that it will be useful,
10
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
11
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
+ # GNU Lesser General Public License for more details.
13
+ #
14
+ # You should have received a copy of the GNU Lesser General Public License
15
+ # along with this program. If not, see <https://www.gnu.org/licenses/>.
16
+
17
+ # /// script
18
+ # requires-python = "~=3.11.0"
19
+ # ///
20
+
21
+ import sys
22
+
23
+ print(f"running in {sys.version_info}")