{"id":13343251,"url":"https://github.com/joshiemoore/slitherbox","last_synced_at":"2025-04-08T01:33:31.340Z","repository":{"id":138142374,"uuid":"525724771","full_name":"joshiemoore/slitherbox","owner":"joshiemoore","description":"Drop-in pure-Python replacement for common shell utilities","archived":false,"fork":false,"pushed_at":"2022-08-17T11:29:33.000Z","size":44,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-24T15:38:55.262Z","etag":null,"topics":["free-software","linux","python","shell","snakeware","xonsh"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshiemoore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-17T09:35:28.000Z","updated_at":"2024-09-07T00:25:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"111d2ae2-bf68-4621-8504-0ee41c39f798","html_url":"https://github.com/joshiemoore/slitherbox","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshiemoore%2Fslitherbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshiemoore%2Fslitherbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshiemoore%2Fslitherbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshiemoore%2Fslitherbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshiemoore","download_url":"https://codeload.github.com/joshiemoore/slitherbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223299255,"owners_count":17122373,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["free-software","linux","python","shell","snakeware","xonsh"],"created_at":"2024-07-29T19:30:42.984Z","updated_at":"2024-11-06T07:25:26.598Z","avatar_url":"https://github.com/joshiemoore.png","language":"Python","readme":"# slitherbox\nslitherbox is a drop-in Python replacement for common shell utilities, as an incremental addition to the\n[Snakeware Project](https://github.com/joshiemoore/snakeware). The goal is to implement a useful \nset of utilities with no runtime dependencies beyond a standard Python 3 installation, in furtherance\nof the pursuit of Python-based computing environments.\n\nIn addition to a re-implementation of common shell utilities, slitherbox is also a platform for easily implementing\nyour own custom shell commands in Python. See the `Utilities` section for more information.\n\nslitherbox is primarily intended for use with [xonsh](https://xon.sh/), though the installed commands\nwill work with any shell.\n\nslitherbox is free software licensed under the terms of GPLv3 or later.\n\n## Installation\nInstallation and uninstallation of slitherbox is simple, and will not overwrite any existing utilities on your system.\nslitherbox uses the same trick as BusyBox, in that symbolic links representing different commands are made to\nthe main slitherbox script. The main script is aware of what name it was run with and executes the corresponding utility.\n\nYou only need Python 3 and pip (or git) to install slitherbox.\n\n### Installation from PyPI\n1. Run `python3 -m pip install slitherbox`.\n\n2. Open a Python interpreter and run the following:\n   ```\n   \u003e\u003e\u003e from slitherbox.slitherbox import sb_main\n   \u003e\u003e\u003e sb_main('sb_install')\n   ```\n\n   This will create symlinks in the installation directory.\n\n3. Add the installation directory to the *beginning* of your `$PATH` so your shell finds slitherbox\n   commands before it finds your native system commands. For example, you could do this by adding\n   `$PATH = ['/path/to/slitherbox'] + $PATH` to your `.xonshrc` if you use xonsh.\n\n   The installation directory is displayed at the end of the `sb_install` command you ran in step 2.\n\n   **NOTE:** You may need to also run `chmod +x slitherbox.py` inside the install directory to make\n   the main script executable, or the commands won't work properly in your shell. \n\n4. Verify the installation was successful by running `$ which echo` and observing that the resulting\n   path is inside the installation directory.\n\n5. You can now run all slitherbox utilities from your shell. If you run a command that is not\n   implemented in slitherbox, but does exist elsewhere in your path, then the existing native\n   utility will still be run.\n\n### Installation from git\n1. Clone this repository, and cd into it.\n\n2. Run `$ python3 slitherbox.py sb_install` to create the symlinks in the installation directory.\n\n3. Follow steps 3-5 from the `Installation from PyPI` section above.\n\nThe slitherbox symlinks can be removed by running `$ sb_uninstall`, restoring use of your native utilities.\nTo re-enable slitherbox, do step 2 again.\n\nYou can view a list of available commands by running `$ sb_list`.\n\nslitherbox commands can also be run without installing the symlinks by running the slitherbox script\ndirectly: `$ ./slitherbox.py \u003ccommand\u003e [args...]`.\n\n### Security Note\nOf course, it would be trivial for a user on your system to modify slitherbox utility scripts to\ncause the commands to act maliciously against other users that run them. If this is a concern for you,\nit is recommended to permission the slitherbox installation directory such that users have read and\nexecute access, but no write access.\n\n## Utilities\n\nAll slitherbox commands are implemented in the `src/slitherbox/` directory. See these files for examples of how\nslitherbox commands work.\n\nIn the future, we may add more directories to host non-core contrib/miscellaneous/fun commands to keep\nthem separate from the core utilities and allow them to be optionally installed.\n\n### Creating new commands\nAdding commands to slitherbox is very simple, even for Python beginners. Many core utilities are just\nwrappers for one line calls to the Python standard library.\n\nTo create a new command, first create a Python file in the `src/utilities/` directory corresponding to your\ncommand's name. For example, if you want to run your command as `$ mycoolcmd`, name the file `mycoolcmd.py`.\n\nThe basic structure of a slitherbox utility is as follows:\n\n```\ndef main(*args):\n    # DO STUFF\n    return 0\n```\n\nReplace `# DO STUFF` with the functionality that you want your command to implement.\n`args` is the list of arguments that were passed to your command from the shell.\n\nYour main function must be named `main`. Your main function must return an integer status\ncode, where 0 is success and non-zero is failure. If an integer status code is not returned\nfrom your main function, an exception will be raised.\n\nOnce you have created your command, run `$ sb_install` to install a symlink for it. You will then be able to run\nyour command from your shell. You don't need to re-create the symlink every time you make changes,\nany subsequent changes you make will automatically work the next time your command is run.\n\n## Contributing/TODOs\nIf you would like to contribute to slitherbox, be sure to uninstall the symlinks before you do a git commit,\nor otherwise avoid adding the symlinks to your commits.\n\nslitherbox is early in development, so there is still much to do. Below is a list of some todos/plans.\n\n* Implement more commands, to at least approximate a useful replacement for the GNU Core Utilities.\n* Add more features to existing commands, including various flags and options which would be expected\n  to exist in established implementations of that command.\n* Add more comprehensive exception handling to command implementations. Incorrect inputs or other\n  issues will often cause the Python library functions to throw exceptions, and we should display\n  graceful error messages instead of showing the actual exception to the user running the command.\n* ... \n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshiemoore%2Fslitherbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshiemoore%2Fslitherbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshiemoore%2Fslitherbox/lists"}