ybox 0.9.8__py3-none-any.whl

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 (76) hide show
  1. ybox/__init__.py +2 -0
  2. ybox/cmd.py +307 -0
  3. ybox/conf/completions/ybox.fish +93 -0
  4. ybox/conf/distros/arch/add-gpg-key.sh +29 -0
  5. ybox/conf/distros/arch/distro.ini +192 -0
  6. ybox/conf/distros/arch/init-base.sh +10 -0
  7. ybox/conf/distros/arch/init-user.sh +35 -0
  8. ybox/conf/distros/arch/init.sh +82 -0
  9. ybox/conf/distros/arch/list_fmt_long.py +76 -0
  10. ybox/conf/distros/arch/pkgdeps.py +276 -0
  11. ybox/conf/distros/deb-generic/check-package.sh +77 -0
  12. ybox/conf/distros/deb-generic/distro.ini +190 -0
  13. ybox/conf/distros/deb-generic/fetch-gpg-key-id.sh +30 -0
  14. ybox/conf/distros/deb-generic/init-base.sh +11 -0
  15. ybox/conf/distros/deb-generic/init-user.sh +3 -0
  16. ybox/conf/distros/deb-generic/init.sh +136 -0
  17. ybox/conf/distros/deb-generic/list_fmt_long.py +114 -0
  18. ybox/conf/distros/deb-generic/pkgdeps.py +208 -0
  19. ybox/conf/distros/deb-oldstable/distro.ini +21 -0
  20. ybox/conf/distros/deb-stable/distro.ini +21 -0
  21. ybox/conf/distros/supported.list +5 -0
  22. ybox/conf/distros/ubuntu2204/distro.ini +21 -0
  23. ybox/conf/distros/ubuntu2404/distro.ini +21 -0
  24. ybox/conf/profiles/apps.ini +26 -0
  25. ybox/conf/profiles/basic.ini +310 -0
  26. ybox/conf/profiles/dev.ini +25 -0
  27. ybox/conf/profiles/games.ini +39 -0
  28. ybox/conf/resources/entrypoint-base.sh +170 -0
  29. ybox/conf/resources/entrypoint-common.sh +23 -0
  30. ybox/conf/resources/entrypoint-cp.sh +32 -0
  31. ybox/conf/resources/entrypoint-root.sh +20 -0
  32. ybox/conf/resources/entrypoint-user.sh +21 -0
  33. ybox/conf/resources/entrypoint.sh +249 -0
  34. ybox/conf/resources/prime-run +13 -0
  35. ybox/conf/resources/run-in-dir +60 -0
  36. ybox/conf/resources/run-user-bash-cmd +14 -0
  37. ybox/config.py +255 -0
  38. ybox/env.py +205 -0
  39. ybox/filelock.py +77 -0
  40. ybox/migrate/0.9.0-0.9.7:0.9.8.py +33 -0
  41. ybox/pkg/__init__.py +0 -0
  42. ybox/pkg/clean.py +33 -0
  43. ybox/pkg/info.py +40 -0
  44. ybox/pkg/inst.py +638 -0
  45. ybox/pkg/list.py +191 -0
  46. ybox/pkg/mark.py +68 -0
  47. ybox/pkg/repair.py +150 -0
  48. ybox/pkg/repo.py +251 -0
  49. ybox/pkg/search.py +52 -0
  50. ybox/pkg/uninst.py +92 -0
  51. ybox/pkg/update.py +56 -0
  52. ybox/print.py +121 -0
  53. ybox/run/__init__.py +0 -0
  54. ybox/run/cmd.py +54 -0
  55. ybox/run/control.py +102 -0
  56. ybox/run/create.py +1116 -0
  57. ybox/run/destroy.py +64 -0
  58. ybox/run/graphics.py +367 -0
  59. ybox/run/logs.py +57 -0
  60. ybox/run/ls.py +64 -0
  61. ybox/run/pkg.py +445 -0
  62. ybox/schema/0.9.1-added.sql +27 -0
  63. ybox/schema/0.9.6-added.sql +18 -0
  64. ybox/schema/init.sql +39 -0
  65. ybox/schema/migrate/0.9.0:0.9.1.sql +42 -0
  66. ybox/schema/migrate/0.9.1:0.9.2.sql +8 -0
  67. ybox/schema/migrate/0.9.2:0.9.3.sql +2 -0
  68. ybox/schema/migrate/0.9.5:0.9.6.sql +2 -0
  69. ybox/state.py +914 -0
  70. ybox/util.py +351 -0
  71. ybox-0.9.8.dist-info/LICENSE +19 -0
  72. ybox-0.9.8.dist-info/METADATA +533 -0
  73. ybox-0.9.8.dist-info/RECORD +76 -0
  74. ybox-0.9.8.dist-info/WHEEL +5 -0
  75. ybox-0.9.8.dist-info/entry_points.txt +8 -0
  76. ybox-0.9.8.dist-info/top_level.txt +1 -0
@@ -0,0 +1,533 @@
1
+ Metadata-Version: 2.2
2
+ Name: ybox
3
+ Version: 0.9.8
4
+ Summary: Securely run Linux distribution inside a container
5
+ Author-email: Sumedh Wale <sumwale@yahoo.com>, Vishal Rao <vishalrao@gmail.com>
6
+ License: Copyright (c) 2024-2025 Sumedh Wale and contributors
7
+
8
+ Permission is hereby granted, free of charge, to any person obtaining a copy
9
+ of this software and associated documentation files (the "Software"), to deal
10
+ in the Software without restriction, including without limitation the rights
11
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12
+ copies of the Software, and to permit persons to whom the Software is
13
+ furnished to do so, subject to the following conditions:
14
+
15
+ The above copyright notice and this permission notice shall be included in all
16
+ copies or substantial portions of the Software.
17
+
18
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24
+ SOFTWARE.
25
+
26
+ Project-URL: Homepage, https://github.com/sumwale/ybox
27
+ Project-URL: Issues, https://github.com/sumwale/ybox/issues
28
+ Keywords: Linux in container,toolbox
29
+ Classifier: Development Status :: 4 - Beta
30
+ Classifier: Intended Audience :: End Users/Desktop
31
+ Classifier: License :: OSI Approved :: MIT License
32
+ Classifier: Operating System :: OS Independent
33
+ Classifier: Programming Language :: Python :: 3
34
+ Classifier: Programming Language :: Python :: 3.9
35
+ Classifier: Programming Language :: Python :: 3.10
36
+ Classifier: Programming Language :: Python :: 3.11
37
+ Classifier: Programming Language :: Python :: 3.12
38
+ Requires-Python: >=3.9
39
+ Description-Content-Type: text/markdown
40
+ License-File: LICENSE
41
+ Requires-Dist: packaging
42
+ Requires-Dist: simple-term-menu
43
+ Requires-Dist: tabulate>=0.9.0
44
+
45
+ ## Introduction
46
+
47
+ Create and manage podman/docker containers hosting different Linux
48
+ distribution images. Manage their packages and applications directly
49
+ from your host machine and easily configure the containers with
50
+ simple INI files. It allows for set up of various aspects of
51
+ the container including support for X11, Wayland, audio, video acceleration,
52
+ NVIDIA, dbus among others. It also allows controlling various parameters
53
+ of the container including directories to be shared, logging etc.
54
+
55
+ Special emphasis is given on security where users can choose to lock down
56
+ or open up the container as required with reasonable defaults out of the
57
+ box. There is no sharing of HOME or no privileged mode container.
58
+
59
+ Expected usage is for users to group similar applications in a container
60
+ and separate out containers depending on different needs like higher/lower
61
+ security, features off to minimum required for those set of applications.
62
+
63
+
64
+ ## Features
65
+
66
+ - simple creation of podman or docker containers hosting Linux distributions (Arch Linux, Ubuntu
67
+ and Debian supported currently) using `ybox-create` with interactive menus
68
+ - special emphasis on security to lock down applications as much as possible to avoid
69
+ "malicious" apps, backdoors etc., from affecting your main work space, so you can play/test
70
+ software/games/... to your heart's content in these containers
71
+ - pre-built profiles for common uses, so you can just run `ybox-create`, select profile and
72
+ be done with it; or advanced users can micro-customize a profile ini file as required
73
+ - allow for sharing root directories (like /usr, /etc) among various containers to reduce
74
+ disk and memory usage (default behaviour in the shipped profiles)
75
+ - simple specification to list configuration files that you want to share with the containers
76
+ in readonly mode (e.g. the basic.ini lists .bashrc, .vimrc etc.)
77
+ - completely isolated home directories in the containers, but you can still precisely control
78
+ which directories to mount for sharing between the host and guests
79
+ - a high level generic package manager `ybox-pkg` with simple install/uninstall/... commands
80
+ that uses the distribution package manager for the operation, creates wrapper desktop and
81
+ executable files to invoke the container's executables, allows specifying additional
82
+ optional dependencies you need with an application, and so on
83
+ - specify startup applications to run in a container if required (TBD)
84
+
85
+ If you create an Arch Linux based container (which probably hosts the largest repository of Linux
86
+ applications with its AUR), then you will have its applications to run in the host OS.
87
+ So, for example, if you want to run the latest and greatest Intellij IDEA community, all you need
88
+ to do is:
89
+
90
+ ```sh
91
+ # create an Arch Linux based container
92
+ ybox-create arch
93
+ # then select an appropriate built-in profile e.g. "dev.ini" from the menu
94
+
95
+ # then install the Arch package in the container
96
+ ybox-pkg install intellij-idea-community-edition
97
+ ```
98
+
99
+ This will automatically create a wrapper desktop file that launches from the container, so
100
+ you can simply launch it from your desktop environment's applications as usual.
101
+
102
+ In this way this acts as a complete replacement of flatpak/snap while being able to choose
103
+ from way bigger software repositories, and with applications configured the way they are
104
+ supposed to be in the original Linux distribution (which is only Arch Linux for now).
105
+ The big difference being that these are just containers where you can open a shell
106
+ (using `ybox-cmd`) and learn/play as required, or micro-configure stuff. The shell will
107
+ behave quite like a full Linux installation apart from missing system-level stuff like systemd.
108
+
109
+
110
+ ## Installation
111
+
112
+ If you have cloned the repository, then no further installation is required to run the utilities
113
+ in `src` directory which can be done directly off the repository. In the near future this will
114
+ also be published on `pypi.org`, so you will be able to install with `pip install --user ybox`.
115
+
116
+ As of now the following is required:
117
+
118
+ - clone the repo: `git clone https://github.com/sumwale/ybox.git`
119
+ - rootless podman or docker
120
+ * for podman this needs installation of `podman` and `slirp4netns`/`passt` packages,
121
+ then setup /etc/subuid and /etc/subgid as noted here:
122
+ [/etc/subuid and /etc/subgid configuration](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md#etcsubuid-and-etcsubgid-configuration)
123
+ (many distributions like ubuntu will set up subuid/subgid for current user automatically)
124
+ * for docker follow the instructions in the official [docs](https://docs.docker.com/engine/security/rootless/)
125
+ - python version 3.9 or higher -- all fairly recent Linux distributions should satisfy this
126
+ but still confirm with `python3 --version`
127
+ - install [simple-term-menu](https://pypi.org/project/simple-term-menu/),
128
+ [tabulate](https://pypi.org/project/tabulate/) and
129
+ [packaging](https://pypi.org/project/packaging/), either from your distribution
130
+ repository, if available, else: `pip install --user simple-term-menu packaging tabulate`
131
+ (obviously you will need `pip` itself to be installed which should be in your
132
+ distribution repositories e.g. ubuntu/debian have it as `python3-pip`)
133
+
134
+ In the future, installer will take care of setting all of these up.
135
+
136
+ Now you can simply go to the repository and run the `ybox-create` and other utilities from
137
+ the `src` directory of the repository checkout. For convenience, you can symlink these to
138
+ your `~/.local/bin` directory which should be in PATH in modern Linux distributions:
139
+
140
+ ```sh
141
+ ln -s <full path of checkout ybox directory>/src/ybox-* ~/.local/bin/
142
+ ```
143
+
144
+ All the `ybox-*` utilities will show detailed help with the `-h`/`--help` option.
145
+
146
+
147
+ ## Usage
148
+
149
+ The basic workflow consists of setting up one or more containers, installing/removing/...
150
+ packages in those containers and opening a shell into a container for more "direct" usage.
151
+
152
+ You can also destroy the containers, list them, see their logs, or restart them using
153
+ convenient utilities.
154
+
155
+ All the commands support podman or docker configured in rootless mode. When using docker, its
156
+ `dockerd` daemon needs to be running in background as the current user, while for podman
157
+ there is no such requirement. Additionally podman will run applications in the container using
158
+ the same user/group as the current user on the host, while docker needs to use the root user in
159
+ the container due to missing support of `--userns=keep-id` option.
160
+
161
+ Consequently podman is the recommended container manager for ybox containers. Its rootless mode
162
+ also works out of the box in most modern linux distributions, unlike docker that needs some
163
+ configuration to setup its user-mode rootless daemon.
164
+
165
+ The commands search for `/usr/bin/podman` followed by `/usr/bin/docker` for the container manager
166
+ executable. This can be overridden using the `YBOX_CONTAINER_MANAGER` environment variable
167
+ to point to the full path of the podman or docker executable.
168
+
169
+ ### Create a new ybox container
170
+
171
+ ```sh
172
+ ybox-create
173
+ ```
174
+
175
+ This will allow choosing from supported distributions, then from the available profiles.
176
+ You can start with the Arch Linux distribution and `apps.ini` profile to try it out. The container
177
+ will have a name like `ybox-<distribution>_<profile>` by default like `ybox-arch_apps` for the
178
+ `apps.ini` profile using Arch Linux distribution.
179
+
180
+ The `$HOME` directory of the container can be found in `~/.local/share/ybox/<container>/home`
181
+ e.g. `~/.local/share/ybox/ybox-arch_apps/home` for the above example.
182
+
183
+ When shared root directory is enabled (which is the default in the shipped profiles), then
184
+ it uses the common distribution path in `~/.local/share/ybox/SHARED_ROOTS/<distribution>`
185
+ by default i.e. `~/.local/share/ybox/SHARED_ROOTS/arch` for the Arch Linux guests.
186
+
187
+ For more advanced usage, you can copy from the available profiles in `src/ybox/conf/profiles`
188
+ into `~/.config/ybox/profiles`, then edit as required. The `basic.ini` profile lists
189
+ all the available options with detailed comments.
190
+
191
+ Note that when using podman, the container will use the same user/group as the current user
192
+ on the host, while if docker is being used then the container will use the root user.
193
+ This is because of missing support for `--userns=keep-id` in docker that allows mapping the
194
+ host user to the same user in the container when using podman. This means that if some application
195
+ does not run properly as root, then you cannot run it when using docker unless you explicitly
196
+ `sudo/su` to the host user in the container command. However, running as host user when running
197
+ rootless docker will map to a different user ID in the host (as specified in `/etc/subuid` on the
198
+ host) so files shared with the host, including devices like those in `/dev/dri`, will cause
199
+ permission issues that can hinder or break the application.
200
+
201
+
202
+ ### Package management: install/uninstall/list/search/...
203
+
204
+ Install a new package with `ybox-pkg` like firefox below:
205
+
206
+ ```sh
207
+ ybox-pkg install firefox
208
+ ```
209
+
210
+ If you have created multiples containers, then this will allow you to choose one among
211
+ them for the installation. After the main package installation, it will also list
212
+ the optional dependencies of the installed package (only till second level) and allow you
213
+ to choose from among them which may add additional features to the package.
214
+
215
+ The installation will also create wrapper desktop files in `~/.local/share/applications`
216
+ and executables in `~/.local/bin` with man pages linked in `~/.local/share/man` so you can execute
217
+ the newly install application binaries from your desktop environment's application menu and/or
218
+ from command-line having corresponding man pages.
219
+
220
+ Likewise, you can uninstall all the changes (including the optional packages chosen before):
221
+
222
+ ```sh
223
+ ybox-pkg uninstall firefox
224
+ ```
225
+
226
+ List the explicitly installed packages using `ybox-pkg`:
227
+
228
+ ```sh
229
+ ybox-pkg list
230
+ ```
231
+ This will show the chosen dependent packages in addition to the explicitly installed ones.
232
+
233
+ ```sh
234
+ ybox-pkg list -a
235
+ ```
236
+ This will list all the distribution packages in the container including those not installed
237
+ by `ybox-pkg` (either installed in the base image, or installed later using the distribution
238
+ package manager directly) -- combine with `-a` to also list all dependent packages.
239
+
240
+ ```sh
241
+ ybox-pkg list -o
242
+ ```
243
+ To show more details of the packages (combine with -a/-o as required):
244
+ ```sh
245
+ ybox-pkg list -o
246
+ ```
247
+
248
+ List all the files installed by the package:
249
+ ```sh
250
+ ybox-pkg list-files firefox
251
+ ```
252
+
253
+ Search the repositories for packages with names matching search terms:
254
+
255
+ ```sh
256
+ ybox-pkg search intellij
257
+ ```
258
+
259
+ Search the repositories for packages with names or descriptions matching search terms:
260
+
261
+ ```sh
262
+ ybox-pkg search intellij -a
263
+ ```
264
+
265
+ You can also restrict the search to full word matches (can be combined with `-a`):
266
+
267
+ ```sh
268
+ ybox-pkg search intellij -w
269
+ ```
270
+
271
+ Show detailed information for an installed package:
272
+ ```sh
273
+ ybox-pkg info firefox
274
+ ```
275
+
276
+ Show detailed information for any package in the available repositories:
277
+ ```sh
278
+ ybox-pkg info firefox -a
279
+ ```
280
+
281
+ Clean package cache, temporary downloads etc:
282
+ ```sh
283
+ ybox-pkg clean
284
+ ```
285
+
286
+ Mark a package as explicitly installed (also registers with `ybox-pkg` if not present):
287
+ ```sh
288
+ ybox-pkg mark firefox -e
289
+ ```
290
+
291
+ Mark a package as a dependency of another (also registers with `ybox-pkg` if not present):
292
+ ```sh
293
+ ybox-pkg mark qt5ct -D zoom # mark qt5ct as an optional dependency of zoom
294
+ ```
295
+
296
+ Repair package installation after a failure or interrupt:
297
+ ```sh
298
+ ybox-pkg repair
299
+ ```
300
+
301
+ More extensive repair of package installation including reinstallation of all packages:
302
+ ```sh
303
+ ybox-pkg repair --extensive
304
+ ```
305
+
306
+ All the `ybox-pkg` subcommands will show detailed help with `-h/--help` option e.g.
307
+ `ybox-pkg list --help`.
308
+
309
+
310
+ ### List the available containers
311
+
312
+ ```sh
313
+ ybox-ls
314
+ ```
315
+
316
+ will list the active ybox containers
317
+
318
+ ```sh
319
+ ybox-ls -a
320
+ ```
321
+
322
+ will list all ybox containers including stopped ones
323
+
324
+
325
+ ### Destroy a container
326
+
327
+ ```sh
328
+ ybox-destroy ybox-arch_apps
329
+ ```
330
+
331
+ Will destroy the `apps` container created in the example before. This does not delete the
332
+ $HOME files, nor does it delete the shared root directory (if enabled). Hence, if you create
333
+ a new container having the same shared root, then it will inherit everything installed
334
+ previously. Likewise, if you create the container with the same profile again, then it
335
+ will also have the $HOME as before if you do not explicitly delete the directories
336
+ in `~/.local/share/ybox`.
337
+
338
+
339
+ **NOTE:** an auto-complete file for fish shell has been provided in
340
+ `src/ybox/conf/completions/ybox.fish`, so you can link that to your fish config:
341
+ ```sh
342
+ ln -s <full path of checkout ybox directory>/src/ybox/conf/completions/ybox.fish ~/.config/fish/conf.d/
343
+ ```
344
+ This will allow auto complete for ybox container names, profiles among others.
345
+ Auto-complete for bash/zsh will be added in the future.
346
+
347
+
348
+ ### Running a command in a container
349
+
350
+ The `ybox-cmd` runs `/bin/bash` in the container by default:
351
+
352
+ ```sh
353
+ ybox-cmd ybox-arch_apps
354
+ ```
355
+
356
+ You can run other commands instead of bash shell, but if those commands require options
357
+ starting with a hyphen, then first end the options to `ybox-cmd` with a double hyphen:
358
+
359
+ ```sh
360
+ ybox-cmd ybox-arch_apps -- ls -l
361
+ ```
362
+
363
+ The default profiles also link the .bashrc and starship configuration files from your host
364
+ $HOME directory by default, so you should see the same bash shell configuration as in your
365
+ host. These are linked in read-only mode, so if you want to change these auto-linked
366
+ configuration files inside the container, then you will need to create a copy from the symlink
367
+ first (but then it will lose the link from the host $HOME).
368
+
369
+ A shell on a container will act like a native Linux distribution environment for most purposes.
370
+ The one prominent missing thing is systemd which is not enabled deliberately since it requires
371
+ highly elevated privileges. It is strongly recommended not to try and somehow enable systemd
372
+ in the containers lest it will bypass most of the security provided by a container environment.
373
+ Instead, you should just start any daemons the normal way as required. You will also need
374
+ to ensure that the daemons don't try and use journald for the logging, rather use the
375
+ normal /var/log based logging. Overall these containers are not meant for running system
376
+ daemons and similar low level utilities which should be the job of your host system.
377
+
378
+
379
+ ### Show the container logs
380
+
381
+ ```sh
382
+ ybox-logs ybox-arch_apps
383
+ ```
384
+
385
+ Follow the logs like `tail -f`:
386
+
387
+ ```sh
388
+ ybox-logs ybox-arch_apps -f
389
+ ```
390
+
391
+ In the shipped profiles, the container logs go to `~/.local/share/ybox/<container>/logs/`
392
+ directory instead of polluting your journald logs as the podman/docker do by default.
393
+ You can delete old log files there safely if they start taking a lot of disk space.
394
+
395
+
396
+ ### Restart a container
397
+
398
+ A container may get stopped after a reboot if systemd/... is not configured to auto-start
399
+ the podman/docker containers. Or you can explicitly stop a container using podman/docker.
400
+ You can check using `ybox-ls -a` and restart a stopped container as below:
401
+
402
+ ```sh
403
+ ybox-control start ybox-arch_apps
404
+ ```
405
+
406
+ The `ybox-control` script also allows for other actions `stop`, `restart` and `status`
407
+ for a ybox container. See the full set of options with `ybox-control -h/--help`.
408
+
409
+
410
+ ### Auto-starting containers
411
+
412
+ Containers can be auto-started as per the usual way for rootless podman/docker services.
413
+ This is triggered by systemd on user login which is exactly what we want for ybox
414
+ containers so that the container applications are available on login and are stopped on
415
+ session logout. For docker the following should suffice:
416
+
417
+ ```sh
418
+ systemctl --user enable docker
419
+ ```
420
+
421
+ See [docker docs](https://docs.docker.com/engine/security/rootless/#daemon) for details.
422
+
423
+ For podman you will need to explicitly generate systemd service file for each container and
424
+ copy to your systemd configuration directory since podman does not use a background daemon.
425
+ For the `ybox-arch_apps` container in the examples before:
426
+
427
+ ```sh
428
+ mkdir -p ~/.config/systemd/user/
429
+ podman generate systemd --name ybox-arch_apps > ~/.config/systemd/user/container-ybox-arch_apps.service
430
+ systemctl --user enable container-ybox-arch_apps.service
431
+ ```
432
+
433
+
434
+ ## Development
435
+
436
+ Virtual environment setup have been provided for consistent development, test and build
437
+ with multiple python versions. The minimum python version required is 3.9 and tests are
438
+ run against all major python versions higher than that (i.e. 3.10, 3.11, 3.12 and others
439
+ in future).
440
+
441
+ The setup uses pyenv with venv which can be used for development with IDEA/PyCharm/VSCode
442
+ or in terminal, running tests against all supported python versions using `tox` etc.
443
+ Scripts to set up a pyenv with venv environment have been provided in the `pyenv` directory
444
+ which creates a `venv` environment in `.venv` directory of the checkout.
445
+
446
+ If you do not have `pyenv` installed and configured, then you can install it using:
447
+
448
+ ```sh
449
+ pyenv/install.sh
450
+ ```
451
+
452
+ **NOTE:** this script will delete any existing `pyenv` artifacts in `$HOME/.pyenv`, so use
453
+ it only if you have never installed `pyenv` before.
454
+
455
+ The script will try to handle installation of required packages on most modern Linux
456
+ distributions (Ubuntu/Debian, Fedora, Arch Linux, OpenSUSE, homebrew), but if yours is a
457
+ different one, then check [pyenv wiki](https://github.com/pyenv/pyenv/wiki) or your
458
+ distribution docs/forums.
459
+
460
+ Next you can install the required python versions and venv environment:
461
+
462
+ ```sh
463
+ pyenv/setup-venv.sh
464
+ ```
465
+
466
+ Finally, you can activate it in bash/zsh:
467
+
468
+ ```sh
469
+ source pyenv/activate.sh
470
+ source .venv/bin/activate
471
+ ```
472
+
473
+ Or in fish shell:
474
+
475
+ ```
476
+ source pyenv/activate.fish
477
+ source .venv/bin/activate.fish
478
+ ```
479
+
480
+ **NOTE:** while the pyenv installation and venv set up needs to be done only once, the last
481
+ steps of `source` of the two files will need to be done for every shell. Hence, you can consider
482
+ placing those in your bashrc/zshrc or fish conf.d so that they get applied in every interactive
483
+ shell automatically.
484
+
485
+ You can open the checkout directory as an existing project in Intellij IDEA/PyCharm and then
486
+ add Python SDK (File -> Project Settings -> Project -> SDK -> Add Python SDK...).
487
+ Choose an existing environment in Virtualenv environment and select the
488
+ `<checkout dir>/.venv/bin/python3` for the interpreter.
489
+
490
+ For using VSCode, ensure that the python extension from Microsoft and preferably the following
491
+ additional extensions are installed: autopep8, Flake8, isort, audoDocstring and
492
+ Python Environment Manager. The open the checkout directory and you should be good to go.
493
+
494
+
495
+ ### Notes on writing tests
496
+
497
+ Tests have been categorized into two:
498
+ - in `tests/unit` directory: these have module/function/class level tests; convention is to
499
+ use a separate test module for corresponding source module e.g. `test_state.py` for
500
+ `ybox/state.py` module
501
+ - in `tests/functional` directory: these are end-to-end tests that invoke and check the
502
+ top-level `ybox-*` utilities
503
+
504
+ All the existing tests use the `pytest` framework and new ones should do the same.
505
+ After adding new tests to the appropriate test directory run `code-check.sh` and
506
+ `tests-coverage.sh` scripts which should succeed and also see coverage report from latter.
507
+
508
+ **NOTE:** use mock only if absolutely necessary (e.g. for unexpected error
509
+ conditions that are difficult to simulate in tests or will cause other trouble).
510
+ For example the state database used is sqlite, but that is an internal detail and could
511
+ potentially change so mocking sqlite3 objects in tests for `ybox.state` module is a really
512
+ bad idea and one should just test for public API of `ybox.state`. On the other hand
513
+ checking for exceptions like `KeyboardInterrupt` can use mock since simulating them
514
+ otherwise is error-prone and can cause unwanted side-effects for other tests.
515
+
516
+
517
+ ### Running the test suite
518
+
519
+ Once pyenv+venv set up is working, you can run the entire test suite and other checks
520
+ using `tox` in the checkout directory, or `tox -p` for parallel run. It will run with
521
+ all supported python versions (i.e. from 3.9 onwards). Tests are written using the `pytest`
522
+ test framework which will be installed along with other requirements by the `setup-venv.sh`
523
+ script (or you can explicitly use `requirements.txt` and install `tox` separately).
524
+
525
+ There is also a simple script `tests-coverage.sh` in the top-level directory which can be
526
+ used to run just the tests with the current python version and produce coverage report.
527
+ It accepts a single argument `-f` to run functional tests in addition to the unit tests,
528
+ else only unit tests are run with coverage. Any arguments afterwards are passed as such
529
+ to `pytest`. This will skip other stuff like `pyright`, for example, which is invoked by
530
+ `tox`. The lint and other related tools can be run explicitly using the `code-check.sh`
531
+ script in the top-level directory.
532
+
533
+ See `tox` and `pytest` documentation for more details like running individual tests.
@@ -0,0 +1,76 @@
1
+ ybox/__init__.py,sha256=8FzWRJgA6Vf9G715kHHM9hIALv9DUhgcadJtma5PKvc,96
2
+ ybox/cmd.py,sha256=49a1Oo1YgLbXlHqZ1PL1okKGtxlXya1DClM-uh1TuKI,14213
3
+ ybox/config.py,sha256=bFz6MIVCEbwOjG0m6L5JPngQqta5J9aXU4osKtD2QDE,9632
4
+ ybox/env.py,sha256=vfHuvTOpApR4fLx1vePWRrTYxzo50c-7dFcnm1-vDHo,8738
5
+ ybox/filelock.py,sha256=nWBp3jvbtrNziRzNcWm6FVVA_lhMccLwgLCVT2IDK5c,3185
6
+ ybox/print.py,sha256=hAQjTb6JmtjWh0sF4GdZHcKRph5iMKP5x23s8LE85q4,4343
7
+ ybox/state.py,sha256=ZEJr3Aib2UT1N7JFfQAWWESx5Vd0GtL3srY9T3Iq1mQ,49008
8
+ ybox/util.py,sha256=2kuUsRCzSuoTypRTeyJXZMWh-XZK_P7M_wsGa3LcIng,16454
9
+ ybox/conf/completions/ybox.fish,sha256=n62vAH60G_kGytPmdNPSvHaiu9k87Yg33maoje_pRl8,5851
10
+ ybox/conf/distros/supported.list,sha256=KAN7lbNfbRqF20KqEd0-BzF8U5uPx4n9h0W9zVh9z5o,52
11
+ ybox/conf/distros/arch/add-gpg-key.sh,sha256=kLMCT15hYadjhInYwQiiyF4u6rJl8n4gGfzEKuMKvTg,644
12
+ ybox/conf/distros/arch/distro.ini,sha256=NlCnhU4mmO9nE08BcO7hEQ83osMbHgIhLYybGG5rCNc,11026
13
+ ybox/conf/distros/arch/init-base.sh,sha256=eqdVzrMqP0hP52S_xxYZJ8n1lStlPn-eSP2e4DpHvWc,311
14
+ ybox/conf/distros/arch/init-user.sh,sha256=4PqUP6QsE50SeymCeNv70PcabrTpEvt8UO_0t4pDksw,1106
15
+ ybox/conf/distros/arch/init.sh,sha256=jGyDLo1sKDTjUWWW9XnUDejHKNR2w7dnsYfdzHg5E9Y,3560
16
+ ybox/conf/distros/arch/list_fmt_long.py,sha256=Ws9Mt9CKInxqUSn98P6-Csik2QqEjyBHp5NyUHlbcoU,2825
17
+ ybox/conf/distros/arch/pkgdeps.py,sha256=26s92G99CR-JqVBl8UANASHHHjONRSwzNDxKJyd6Pqo,13998
18
+ ybox/conf/distros/deb-generic/check-package.sh,sha256=bMiOi6Cp_UrtXm_sXOWBq4Xng2EwXYerqBuRLtGYIlo,2621
19
+ ybox/conf/distros/deb-generic/distro.ini,sha256=ZDWJG-cvx1BuI2RwynIvDwxzuzvVaYNv68PD-J57t84,11361
20
+ ybox/conf/distros/deb-generic/fetch-gpg-key-id.sh,sha256=sTsLWILZosYJcGV1u8qBdczQAFBda2Zlsp1xbpy8nzo,836
21
+ ybox/conf/distros/deb-generic/init-base.sh,sha256=rim7UckGos0phyOAiNYbIjOVG9C4gKQSB-YbZcTFIms,191
22
+ ybox/conf/distros/deb-generic/init-user.sh,sha256=RDt9sZuv6cSX1WBaRGcLMq2ZTBhVZmZVWD1t0wjvizU,20
23
+ ybox/conf/distros/deb-generic/init.sh,sha256=KW0a76BJm75VHDaLPCE4MdLThcy__NpE6Z8pLB0Q7IM,5748
24
+ ybox/conf/distros/deb-generic/list_fmt_long.py,sha256=66sOC0Uzv5nuTRaQQ_9R-GFJju4PSPXNlXv_eHmx57k,5701
25
+ ybox/conf/distros/deb-generic/pkgdeps.py,sha256=corAt8k8QMiQwL2zJMsfFhDeyFJKaY53G7v5odqnyZY,10549
26
+ ybox/conf/distros/deb-oldstable/distro.ini,sha256=lr7140ftndEvs3Liavf3hg3v0qHHWAn0RRm_HAQTw8M,1103
27
+ ybox/conf/distros/deb-stable/distro.ini,sha256=xyQ31mLOpj3Z1MK-UYuc_9NfEkb7Gy10MdDKXMgnqDo,1100
28
+ ybox/conf/distros/ubuntu2204/distro.ini,sha256=3Pw1Q30USyKMUcHp_cvlqhwyU0FPo8O2AHWkgd0cdE4,1105
29
+ ybox/conf/distros/ubuntu2404/distro.ini,sha256=ra4_EteDsHrw9UcehP4qLGTn98gAHc4JCb56CDzz1Wo,1102
30
+ ybox/conf/profiles/apps.ini,sha256=9GCZJvdB5yOfx-mXyti3M-YQjeLnugrhOp43sQQvqQ0,1001
31
+ ybox/conf/profiles/basic.ini,sha256=ObEGUmtEm6hABAv9XrDk_Uivv7ib_utcgfxA3qBYNj0,17783
32
+ ybox/conf/profiles/dev.ini,sha256=D0Sj1orfhn7UnTbRJg5FSTn8yXFQ08MdcSXTQq7qPAE,930
33
+ ybox/conf/profiles/games.ini,sha256=FiBILNFOMpjKhrIR9nPbPj9QDUeI5h9wZaNXIb6Z7dc,1792
34
+ ybox/conf/resources/entrypoint-base.sh,sha256=hcW8ZLHM-jlHx7McoKTo8HIFz_VBBPD0I3WqlX7LjHs,4890
35
+ ybox/conf/resources/entrypoint-common.sh,sha256=fMopKBLeGuVV0ukANXh_ZHGTR1yGq108CTN_M2MNPyQ,461
36
+ ybox/conf/resources/entrypoint-cp.sh,sha256=4R1UA2YLcKH_tUcyiioHSJA5B_t7GT1Z9gVFnCMi2a0,813
37
+ ybox/conf/resources/entrypoint-root.sh,sha256=wTn5Sl6Fy8T_zOYgP2IlCHOYYY3Qa07kK-NC7O03OqI,685
38
+ ybox/conf/resources/entrypoint-user.sh,sha256=ypHVX2jCvKTPd-_UzIWgY13n9C1glmDdeHYqh_Ahrbk,637
39
+ ybox/conf/resources/entrypoint.sh,sha256=iatkLEBGoZRNm9idDeIOAiN7enYVIZVedbDgq0KLbtE,8280
40
+ ybox/conf/resources/prime-run,sha256=Yu9VuT1aZ8c36s_pOCnkGYn1aL8K1BONiUUv63cw9P4,347
41
+ ybox/conf/resources/run-in-dir,sha256=Z9xHEUDpOc7h3yCowPeZ47PzzgbTq__9aCO2S9TCqdI,1784
42
+ ybox/conf/resources/run-user-bash-cmd,sha256=DgcBNcxeN6EWVLetGj9ZZtcqwWPJ4jGDPNt3WA_F3fI,337
43
+ ybox/migrate/0.9.0-0.9.7:0.9.8.py,sha256=N7O7HtoMh_l404v2bHG5Od-_4fCDFMUBZ1SeT1P9F4M,1582
44
+ ybox/pkg/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
45
+ ybox/pkg/clean.py,sha256=t8WlVZHL-6xLnU5E5-L4otAwX-qSz9NQmupVwkGAcJw,1592
46
+ ybox/pkg/info.py,sha256=izuVJNG4PjCqahzO5_tn8GAuGFX-1bf1rT0HbAO5a4c,1982
47
+ ybox/pkg/inst.py,sha256=bADv0lOX3W9rsM98QYWszmCX9fFegsCn0cwpxi2Y0Nc,35574
48
+ ybox/pkg/list.py,sha256=FTDYTkuf4PzB2PhHl4vdGnHILQeR8ZMFHyyp4p7LTXg,10404
49
+ ybox/pkg/mark.py,sha256=cdTOKpo7Vb8j8lM0oZxdvAsJpIktnskyHWd6vEt-pG0,3748
50
+ ybox/pkg/repair.py,sha256=hfJ5ETQVHSHX4F5On-8WLKJvWGFfsRaQkZ5fKyeZKSQ,7798
51
+ ybox/pkg/repo.py,sha256=25gQgGMPeHgX83iqqWXyG6V6rIZ4i_KEnIbNG-CrxTk,13677
52
+ ybox/pkg/search.py,sha256=mOJaQ2Tk-Tr3wSk4jHqCFsEtyEt00J8ULLow-cYa-0E,2903
53
+ ybox/pkg/uninst.py,sha256=ndqZ_WYr9HE5jVL1tQ_tTmSPyTFM6OJRCTLLmG-Qm4w,5338
54
+ ybox/pkg/update.py,sha256=M-1MC8oh-baTHdSPWUUSTU_AhN3eu2nTCSge3bb6GmI,3269
55
+ ybox/run/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
56
+ ybox/run/cmd.py,sha256=f4-iyS5GTHbz1e3XirVii5XvLnGxQfPjXxZGb37GhzE,2044
57
+ ybox/run/control.py,sha256=PH85xf8ex28x-ojqwTjdIMgg9KH7cJmUwZPoCTblPFI,4192
58
+ ybox/run/create.py,sha256=uy0NAKh5JudzakqBmKFYuedVkEB1cfWl02qD6gO7C6U,62097
59
+ ybox/run/destroy.py,sha256=xwp_JMPPCl6oF1mY3kXTVfk2Nn3sdMA3iIkh00zCKB4,2570
60
+ ybox/run/graphics.py,sha256=635Ry0sXIKCpM14ZPDHsQfw-xHNARbvaaAFNDpx3oo4,18991
61
+ ybox/run/logs.py,sha256=i2q0wLrsUwXYSrzfBADyiYiQ2MymSBn3N4JqPmqq03U,1989
62
+ ybox/run/ls.py,sha256=Mek493Z9GbLZ5o3FytgJSzZ9Z4olhMjz3vOUe_apMOw,2726
63
+ ybox/run/pkg.py,sha256=fYaQwXTUyd8MbZMLoXiogEO6l_i94lCovbarsCReT3I,24947
64
+ ybox/schema/0.9.1-added.sql,sha256=1rGp2DczZmmC_xwjmheeZNPSbDpFzasu6LO3tpTy3zI,1049
65
+ ybox/schema/0.9.6-added.sql,sha256=Qcho6dP5OUpPUW3IBWl_kv88agMPHzueUAKqnZPnt3U,809
66
+ ybox/schema/init.sql,sha256=fei8lPvjb-EIjm5zuA_XkEdjsIE3vtROhgRPt7QMlSs,1599
67
+ ybox/schema/migrate/0.9.0:0.9.1.sql,sha256=e9JGwrjFZXdWKGv2JQZlKcWz8DmOuUARpToSsCyiksQ,1555
68
+ ybox/schema/migrate/0.9.1:0.9.2.sql,sha256=X5J3unDS0eLeVvYKxQgx-iUBoAOk9T2suO34pWlQ-lE,362
69
+ ybox/schema/migrate/0.9.2:0.9.3.sql,sha256=Y7GeBSuEEs7Hs9hh-KYDARgeeMgwQwercvTB5P_-k6I,102
70
+ ybox/schema/migrate/0.9.5:0.9.6.sql,sha256=wqYhmputlUQzBI5zfP7O5kqIFWAbZQ05kolyHK4714A,70
71
+ ybox-0.9.8.dist-info/LICENSE,sha256=7GbFgERMXSwD1VyLA5bo_XHvJipmNEUhDW5Sy51TFeY,1077
72
+ ybox-0.9.8.dist-info/METADATA,sha256=voBq82-8y-GKD1wzYEdXPwTniZlcWDyHVAl3vj8isAg,23050
73
+ ybox-0.9.8.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
74
+ ybox-0.9.8.dist-info/entry_points.txt,sha256=xDlI_84Hl3ytYO_ERyt0rkJ4ioUF8Z1r49Hx1xL28Rk,243
75
+ ybox-0.9.8.dist-info/top_level.txt,sha256=DYX7jvndHcBaJXLJ8vDyKrq0_KWoSeXXFq8r0d5L6Nk,5
76
+ ybox-0.9.8.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (75.8.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,8 @@
1
+ [console_scripts]
2
+ ybox-cmd = ybox.run.cmd:main
3
+ ybox-control = ybox.run.control:main
4
+ ybox-create = ybox.run.create:main
5
+ ybox-destroy = ybox.run.destroy:main
6
+ ybox-logs = ybox.run.logs:main
7
+ ybox-ls = ybox.run.ls:main
8
+ ybox-pkg = ybox.run.pkg:main
@@ -0,0 +1 @@
1
+ ybox