| Name | pyshortcuts JSON |
| Version |
1.9.5
JSON |
| download |
| home_page | None |
| Summary | Create desktop and Start Menu shortcuts for python scripts |
| upload_time | 2024-11-18 05:09:04 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | The MIT License Copyright (c) 2018-2024 Matthew Newville, The University of Chicago Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXP80RESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE qUSE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
desktop shortcuts
python utilities
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://github.com/newville/pyshortcuts/actions/workflows/test-ubuntu.yml)
[](https://github.com/newville/pyshortcuts/actions/workflows/test-windows.yml)
[](https://github.com/newville/pyshortcuts/actions/workflows/test-macos.yml)
[](https://pypi.org/project/pyshortcuts)
[](https://pypi.org/project/pyshortcuts)
Install `pyshortcuts` with
```
pip install pyshortcuts
```
Full documentation is at: [Pyshortcuts Documentation](https://newville.github.io/pyshortcuts/)
# Table of contents
1. [Pyshortcuts Overview](#about)
1. [Installation](#installation)
2. [Usage from Python](#frompytho)
3. [`pyshortcut` command-line program](#cli)
4. [Making a shortcut for single python command](#pycmd)
5. [Note for running wxPython GUIs on macOS with Anaconda Python](#wxapps_macos)
6. [`pyshortcut` graphical user interface](#wxgui)
## Pyshortcuts Overview <a name="about"></a>
Pyshortcuts helps Python developers and users create shortcuts that will run
python scripts and other applications. The shortcuts created can go onto the
users desktop or into the Start Menu (for systems with Start Menus) or both.
Pyshortcuts gives a consistent interface for building shortcuts that run on
Windows, macOS, and Linux in the way that is most natural for each OS.
On Windows, a Shortcut Link is created and placed on the users Desktop and in
the Start Menu. On macOS, a minimal but complete Application is created and
placed on the users Desktop. On Linux a ".desktop" file is created and placed
on the users Desktop (if that exists) and in $HOME/.local/share/applications
(if that exists), which will often get presented in a Start Menu for windowing
desktop themes that use a one. On all platforms, the shortcuts created on the
Deskop or Start Menu can be put either directly onto the Desktop / Start Menu
or in a sub-folder of the Desktop / Start Menu. Shortcuts can have a custom
icon (`.ico` files on Windows or Linux, or `.icns` files on macOS) specified,
defaulting to a Python icon included with pyshortcuts.
By writing only to the users Desktop or application folder that gets read by
the Start Menu, there is no need for elevated permission and no writing to
system-level files (registry entries, /Applications, /usr/bin, etc). After the
shortcut has been created, the end user has complete control to rename, move,
or delete it.
Pyshortcuts is pure python, small, readily installed, and easy to use from a
the command-line or from Python scripts. This means that Pyshortcuts can be
made part of an installation (or post-installation process) process for larger
packages.
Special attention is given to Anaconda Python on Windows. For that
environment, the shortcut created will be sure to run in an Anaconda
environment, explicitly selecting the "base" environment even if that has not
been explicitly set by the user.
## installation <a name="installation"></a>
To install `pyshortcuts`, use
```
pip install pyshortcuts
```
On Windows, pyshortcuts requires the pywin32 package and will be installed
if needed. There are no depenendencies on macOS or Linux.
In order to use the pyshortcut GUI, the wxPython package is required.
## Usage from Python <a name="frompython"></a>
Shortcuts can be created from a Python script with
```python
from pyshortcuts import make_shortcut
make_shortcut('/home/user/bin/myapp.py', name='MyApp', icon='/home/user/icons/myicon.ico')
```
The arguments to the `make_shortcut` function are:
* `script` (str) scipt or command to be run. This can include command-line arguments
* `name` (str or None) name to use for shortcut [defaults to script name]
* `description` (str or None) longer description of script [defaults to `name`]
* `icon` (str or None) path to icon file [defaults to python icon]
* `folder` (str or None) folder on Desktop to put shortcut [defaults to Desktop]
* `terminal` (bool) whether to run in a Terminal [True]
* `desktop` ((bool) whether to add shortcut to Desktop [True]
* `startmenu` (bool) whether to add shortcut to Start Menu [True]
* `executable` (str or None) name of executable to use [this Python]
Note that the Start Menu does not exist for macOSX.
The `executable` defaults to the version of Python executable used to make shortcut.
## `pyshortcut` command-line program <a name="cli"></a>
Pyshortcuts installs a `pyshortcut` command-line program for creating a shortcut.
From a shell or Command window with PATH set to include python programs and scripts,
a command to create a shortcut might look like:
```
~> pyshortcut -n MyApp -i /home/user/icons/myicon.icns /home/user/bin/myapp.py
```
To include command-line options for the script, put them in double quotes
```
~> pyshortcut -n MyApp -i /home/user/icons/myicon.icns "/home/user/bin/myapp.py -t 10"
```
The `pyshortcut` command line program has a form of
```
pyshortcut [-h] [-v] [-n NAME] [-i ICON] [-f FOLDER] [-e EXE] [-t] [-g] [-d] [-s] [-w] [scriptname]
```
where `scriptname` is the name of the script. To include arguments to that
script, enclose the script name and arguments in quotes (double quotes on
Windows).
There are several optional arguments:
* `-h`, `--help` show help message and exit
* `-v`, `--version` show program's version number and exit
* `-n NAME`, `--name=NAME` name for shortcut
* `-i ICON`, `--icon=ICON` name of icon file
* `-f FOLDER`, `--folder=Folder` subfolder on desktop to put icon
* `-e EXE`, `--executable EXE` name of executable to use (python)
* `-t`, `--terminal` run script in a Terminal Window [True]
* `-g`, `--gui` run script as a GUI, with no Terminal Window [False]
* `-d`,` --desktop` create desktop shortcut [True]
* `-s`, `--startmenu` create Start Menu shortcut [True]
* `-w`, `--wxgui` run GUI version of pyshortcut
* `-b`, `--bootstrap` create a desktop shortcut to run GUI version of pyshortcut
Note that running in the Terminal is True by default, which means that each
time the shortcut is used to launch the application, a new Terminal or Command
window will be created for it. For many command-line applications, this is
appropriate. The extra Terminal or Command window may be unwanted for some GUI
applications, and can be disabled with the `-g` or `--gui` option.
## Making a shortcut for single python command <a name="pycmd"></a>
A common request and simple use-case for `pyshortcuts` is to wrap a single
python command. An example of this might look like this:
```
import sys
from pyshortcuts import make_shortcut
pycmd = "_ -m pip install --upgrade pyshortcuts"
make_shortcut(pycmd, name='Update Pyshortcuts')
```
Note that using `_` or `{}` as the command name will indicate that the
current Python executable should be be used. An example that includes
an icon is given in the examples folder.
The above could be done from the command line with
```
~> pyshortcut -n "Update Pyshortcuts" "_ -m pip install pyshortcuts"
```
## Note for running wxPython GUIs on macOS with Anaconda Python <a name="wxapps_macos"></a>
If your application uses wxPython and you are running with Anaconda Python on
macOS, you may experience problems that your application does not start. If
you try to run your script from the command line, you may see the following
error message:
```
~> python my_wxpython_app.py
This program needs access to the screen. Please run with a
Framework build of python, and only when you are logged in
on the main display of your Mac.
```
If you do see that, it can be fixed and your script run properly by adding
```
import wx
wx.PyApp.IsDisplayAvailable = lambda _: True
```
in your script before runnig your starting the `wxPython` `mainloop` event handler.
## `pyshortcut` GUI <a name="wxgui"></a>
In addition to the `pyshortcut` command-line program, there is a small GUI
application that provides a simple form to help the user browse for script
and icons, and set options before creating a shortcut or generating an
example Python script to create the shortcut.
This requires the `wxPython` package which can be installed using `pip` or
`conda` but is not automatically installed when installing `pyshortcuts`.
This application can be launched from the command line with
```
~> pyshortcut --wxgui
```
Of course, that command might be the sort of command you might want to be able
to launch by clicking on a desktop shortcut. We have just the tool for that! Doing
```
~> pyshortcut --bootstrap
```
will create a desktop shortcut with an icon of a ladder that will launch
the pyshortcut GUI. This essentially runs
```python
#!/usr/bin/env python
import os
import sys
from pyshortcuts import make_shortcut, platform
bindir = 'Scripts' if platform.startswith('win') else 'bin'
pyshortcut = os.path.normpath(os.path.join(sys.prefix, bindir, 'pyshortcut'))
scut = make_shortcut(f"{pyshortcut:s} --wxgui", name='PyShortcut', terminal=False)
```
The ladder icon was made by Left Martinez, and downloaded from
(https://www.iconfinder.com/iconsets/free-construction-tools)
Raw data
{
"_id": null,
"home_page": null,
"name": "pyshortcuts",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "desktop shortcuts, python utilities",
"author": null,
"author_email": "Matthew Newville <matt.newville@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/55/21/8145313e9f42fa6b8970390415b93fca6b2e56655718bfd70674bd87bd77/pyshortcuts-1.9.5.tar.gz",
"platform": null,
"description": "[](https://github.com/newville/pyshortcuts/actions/workflows/test-ubuntu.yml)\n[](https://github.com/newville/pyshortcuts/actions/workflows/test-windows.yml)\n[](https://github.com/newville/pyshortcuts/actions/workflows/test-macos.yml)\n[](https://pypi.org/project/pyshortcuts)\n[](https://pypi.org/project/pyshortcuts)\n\n\nInstall `pyshortcuts` with\n\n```\npip install pyshortcuts\n```\n\n\nFull documentation is at: [Pyshortcuts Documentation](https://newville.github.io/pyshortcuts/)\n\n\n\n# Table of contents\n\n1. [Pyshortcuts Overview](#about)\n1. [Installation](#installation)\n2. [Usage from Python](#frompytho)\n3. [`pyshortcut` command-line program](#cli)\n4. [Making a shortcut for single python command](#pycmd)\n5. [Note for running wxPython GUIs on macOS with Anaconda Python](#wxapps_macos)\n6. [`pyshortcut` graphical user interface](#wxgui)\n\n## Pyshortcuts Overview <a name=\"about\"></a>\n\nPyshortcuts helps Python developers and users create shortcuts that will run\npython scripts and other applications. The shortcuts created can go onto the\nusers desktop or into the Start Menu (for systems with Start Menus) or both.\nPyshortcuts gives a consistent interface for building shortcuts that run on\nWindows, macOS, and Linux in the way that is most natural for each OS.\n\nOn Windows, a Shortcut Link is created and placed on the users Desktop and in\nthe Start Menu. On macOS, a minimal but complete Application is created and\nplaced on the users Desktop. On Linux a \".desktop\" file is created and placed\non the users Desktop (if that exists) and in $HOME/.local/share/applications\n(if that exists), which will often get presented in a Start Menu for windowing\ndesktop themes that use a one. On all platforms, the shortcuts created on the\nDeskop or Start Menu can be put either directly onto the Desktop / Start Menu\nor in a sub-folder of the Desktop / Start Menu. Shortcuts can have a custom\nicon (`.ico` files on Windows or Linux, or `.icns` files on macOS) specified,\ndefaulting to a Python icon included with pyshortcuts.\n\n\nBy writing only to the users Desktop or application folder that gets read by\nthe Start Menu, there is no need for elevated permission and no writing to\nsystem-level files (registry entries, /Applications, /usr/bin, etc). After the\nshortcut has been created, the end user has complete control to rename, move,\nor delete it.\n\nPyshortcuts is pure python, small, readily installed, and easy to use from a\nthe command-line or from Python scripts. This means that Pyshortcuts can be\nmade part of an installation (or post-installation process) process for larger\npackages.\n\nSpecial attention is given to Anaconda Python on Windows. For that\nenvironment, the shortcut created will be sure to run in an Anaconda\nenvironment, explicitly selecting the \"base\" environment even if that has not\nbeen explicitly set by the user.\n\n## installation <a name=\"installation\"></a>\n\nTo install `pyshortcuts`, use\n\n```\npip install pyshortcuts\n```\n\nOn Windows, pyshortcuts requires the pywin32 package and will be installed\nif needed. There are no depenendencies on macOS or Linux.\n\nIn order to use the pyshortcut GUI, the wxPython package is required.\n\n## Usage from Python <a name=\"frompython\"></a>\n\nShortcuts can be created from a Python script with\n\n```python\n\nfrom pyshortcuts import make_shortcut\n\nmake_shortcut('/home/user/bin/myapp.py', name='MyApp', icon='/home/user/icons/myicon.ico')\n```\n\nThe arguments to the `make_shortcut` function are:\n\n * `script` (str) scipt or command to be run. This can include command-line arguments\n * `name` (str or None) name to use for shortcut [defaults to script name]\n * `description` (str or None) longer description of script [defaults to `name`]\n * `icon` (str or None) path to icon file [defaults to python icon]\n * `folder` (str or None) folder on Desktop to put shortcut [defaults to Desktop]\n * `terminal` (bool) whether to run in a Terminal [True]\n * `desktop` ((bool) whether to add shortcut to Desktop [True]\n * `startmenu` (bool) whether to add shortcut to Start Menu [True]\n * `executable` (str or None) name of executable to use [this Python]\n\nNote that the Start Menu does not exist for macOSX.\n\nThe `executable` defaults to the version of Python executable used to make shortcut.\n\n\n## `pyshortcut` command-line program <a name=\"cli\"></a>\n\nPyshortcuts installs a `pyshortcut` command-line program for creating a shortcut.\nFrom a shell or Command window with PATH set to include python programs and scripts,\na command to create a shortcut might look like:\n\n```\n~> pyshortcut -n MyApp -i /home/user/icons/myicon.icns /home/user/bin/myapp.py\n```\n\nTo include command-line options for the script, put them in double quotes\n\n```\n~> pyshortcut -n MyApp -i /home/user/icons/myicon.icns \"/home/user/bin/myapp.py -t 10\"\n```\n\nThe `pyshortcut` command line program has a form of\n\n```\npyshortcut [-h] [-v] [-n NAME] [-i ICON] [-f FOLDER] [-e EXE] [-t] [-g] [-d] [-s] [-w] [scriptname]\n```\n\nwhere `scriptname` is the name of the script. To include arguments to that\nscript, enclose the script name and arguments in quotes (double quotes on\nWindows).\n\n\nThere are several optional arguments:\n\n\n * `-h`, `--help` show help message and exit\n * `-v`, `--version` show program's version number and exit\n * `-n NAME`, `--name=NAME` name for shortcut\n * `-i ICON`, `--icon=ICON` name of icon file\n * `-f FOLDER`, `--folder=Folder` subfolder on desktop to put icon\n * `-e EXE`, `--executable EXE` name of executable to use (python)\n\n * `-t`, `--terminal` run script in a Terminal Window [True]\n * `-g`, `--gui` run script as a GUI, with no Terminal Window [False]\n * `-d`,` --desktop` create desktop shortcut [True]\n * `-s`, `--startmenu` create Start Menu shortcut [True]\n * `-w`, `--wxgui` run GUI version of pyshortcut\n * `-b`, `--bootstrap` create a desktop shortcut to run GUI version of pyshortcut\n\nNote that running in the Terminal is True by default, which means that each\ntime the shortcut is used to launch the application, a new Terminal or Command\nwindow will be created for it. For many command-line applications, this is\nappropriate. The extra Terminal or Command window may be unwanted for some GUI\napplications, and can be disabled with the `-g` or `--gui` option.\n\n## Making a shortcut for single python command <a name=\"pycmd\"></a>\n\nA common request and simple use-case for `pyshortcuts` is to wrap a single\npython command. An example of this might look like this:\n\n```\nimport sys\nfrom pyshortcuts import make_shortcut\n\npycmd = \"_ -m pip install --upgrade pyshortcuts\"\n\nmake_shortcut(pycmd, name='Update Pyshortcuts')\n```\n\nNote that using `_` or `{}` as the command name will indicate that the\ncurrent Python executable should be be used. An example that includes\nan icon is given in the examples folder.\n\nThe above could be done from the command line with\n\n```\n~> pyshortcut -n \"Update Pyshortcuts\" \"_ -m pip install pyshortcuts\"\n```\n\n## Note for running wxPython GUIs on macOS with Anaconda Python <a name=\"wxapps_macos\"></a>\n\nIf your application uses wxPython and you are running with Anaconda Python on\nmacOS, you may experience problems that your application does not start. If\nyou try to run your script from the command line, you may see the following\nerror message:\n\n\n```\n~> python my_wxpython_app.py\nThis program needs access to the screen. Please run with a\nFramework build of python, and only when you are logged in\non the main display of your Mac.\n```\n\n\nIf you do see that, it can be fixed and your script run properly by adding\n\n```\nimport wx\nwx.PyApp.IsDisplayAvailable = lambda _: True\n```\n\nin your script before runnig your starting the `wxPython` `mainloop` event handler.\n\n\n\n## `pyshortcut` GUI <a name=\"wxgui\"></a>\n\nIn addition to the `pyshortcut` command-line program, there is a small GUI\napplication that provides a simple form to help the user browse for script\nand icons, and set options before creating a shortcut or generating an\nexample Python script to create the shortcut.\n\n\n\nThis requires the `wxPython` package which can be installed using `pip` or\n`conda` but is not automatically installed when installing `pyshortcuts`.\nThis application can be launched from the command line with\n\n```\n~> pyshortcut --wxgui\n```\n\nOf course, that command might be the sort of command you might want to be able\nto launch by clicking on a desktop shortcut. We have just the tool for that! Doing\n\n```\n~> pyshortcut --bootstrap\n```\n\nwill create a desktop shortcut with an icon of a ladder that will launch\nthe pyshortcut GUI. This essentially runs\n\n\n```python\n#!/usr/bin/env python\nimport os\nimport sys\nfrom pyshortcuts import make_shortcut, platform\n\nbindir = 'Scripts' if platform.startswith('win') else 'bin'\npyshortcut = os.path.normpath(os.path.join(sys.prefix, bindir, 'pyshortcut'))\nscut = make_shortcut(f\"{pyshortcut:s} --wxgui\", name='PyShortcut', terminal=False)\n```\n\nThe ladder icon was made by Left Martinez, and downloaded from\n(https://www.iconfinder.com/iconsets/free-construction-tools)\n",
"bugtrack_url": null,
"license": "The MIT License Copyright (c) 2018-2024 Matthew Newville, The University of Chicago Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXP80RESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE qUSE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Create desktop and Start Menu shortcuts for python scripts",
"version": "1.9.5",
"project_urls": {
"Changelog": "https://github.com/newville/pyshortcuts/issues",
"Documentation": "https://github.com/newville/pyshortcuts/README.md",
"Homepage": "https://github.com/newville/pyshortcuts/"
},
"split_keywords": [
"desktop shortcuts",
" python utilities"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "be1c9708baee7b1213398b2f1c3d04047c5f3fbf5ee7aa438b6ad209237a435c",
"md5": "7ac42ebde766030de1a3a37c01fce73a",
"sha256": "acf0829d21a290209d26600080deda69b3622839e44311fe8e39250f185d1158"
},
"downloads": -1,
"filename": "pyshortcuts-1.9.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7ac42ebde766030de1a3a37c01fce73a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 165838,
"upload_time": "2024-11-18T05:09:02",
"upload_time_iso_8601": "2024-11-18T05:09:02.431979Z",
"url": "https://files.pythonhosted.org/packages/be/1c/9708baee7b1213398b2f1c3d04047c5f3fbf5ee7aa438b6ad209237a435c/pyshortcuts-1.9.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "55218145313e9f42fa6b8970390415b93fca6b2e56655718bfd70674bd87bd77",
"md5": "f107213a24e58aebe98bf2d994012b20",
"sha256": "49dbb4c3f032ad4f6c54ba4c84bf7ef32c5538422191924281597278bbb6913c"
},
"downloads": -1,
"filename": "pyshortcuts-1.9.5.tar.gz",
"has_sig": false,
"md5_digest": "f107213a24e58aebe98bf2d994012b20",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 1004523,
"upload_time": "2024-11-18T05:09:04",
"upload_time_iso_8601": "2024-11-18T05:09:04.519001Z",
"url": "https://files.pythonhosted.org/packages/55/21/8145313e9f42fa6b8970390415b93fca6b2e56655718bfd70674bd87bd77/pyshortcuts-1.9.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-18 05:09:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "newville",
"github_project": "pyshortcuts",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyshortcuts"
}
