Python library to create and parse Siri Shortcuts
Project description
# WIP: python-shortcuts
[![Build Status](https://travis-ci.org/alexander-akhmetov/python-shortcuts.svg?branch=master)](https://travis-ci.org/alexander-akhmetov/python-shortcuts)
[![PyPI](https://img.shields.io/pypi/v/shortcuts.svg)](https://pypi.python.org/pypi/shortcuts)
🍏 + 🐍 = ❤️
**python-shortcuts** is a library to create [Siri Shortcuts](https://support.apple.com/en-ae/guide/shortcuts/welcome/ios) on your laptop with your favourite text editor.
It uses [toml](https://github.com/toml-lang/toml) to represent shortcuts.
The library is in a very early development state (PR welcome!), so it does not support all actions from Shortcuts app.
* [Toml tutorial](docs/tutorial.md)
* [Python tutorial](docs/python_tutorial.md)
* [How to add a new action](docs/new_action.md)
* [Supported actions](docs/actions.md)
* [Examples](examples/)
* [Changelog](CHANGELOG.md)
* [Documentation](docs/)
Supported Python version: **>=3.6**.
## Why
I wanted to convert my shortcut to a file in human-readable format. :)
From the code below this library can create a working shortcut:
```toml
[[action]]
type = "ask"
question = "What is your name?"
[[action]]
type = "set_variable"
name = "name"
[[action]]
type = "show_result"
text = "Hello, {{name}}!"
```
Or the same with Python:
```python
from shortcuts import Shortcut, actions
sc = Shortcut()
sc.actions = [
actions.AskAction(data={'question': 'What is your name?'}),
actions.SetVariableAction(data={'name': 'name'}),
actions.ShowResultAction(data={'text': 'Hello, {{name}}!'})
]
```
## How to use
### Installation
```bash
pip install shortcuts
```
### Usage
### shortcut → toml
If you need to convert existing shortcut to a toml file, at first you need to export it.
Go into Shortcuts app, open the shortcut and share it. Choose "Share as file" and use this file with this library.
Convert shortcut file to `toml`:
```bash
shortcuts what_is_your_name.shortcut what_is_your_name.toml
```
### toml → shortcut
Convert a `toml` file to a shortcut file.
After you will need to open the file with iOS Shortcuts app.
```bash
shortcuts examples/what_is_your_name.toml what_is_your_name.shortcut
```
More examples of `toml` files you can find [here](examples/).
And [read the tutorial](docs/tutorial.md)! :)
### URL → [toml|shortcut]
Also, you can download shortcut directly from iCloud.
If somebody shared shortcut link with you, just run:
```bash
shortcuts https://www.icloud.com/shortcuts/... my_shortcut.toml # or my_shortcut.shortcut
```
And it will download this shortcut and save it in `toml` or `shortcut` format.
### Docker
It's possible to use [pre-built Docker container](https://cloud.docker.com/u/akhmetov/repository/docker/akhmetov/shortcuts-cli) with python-shortcuts inside:
```shell
# convert s.toml from the current directory into s.shortcut
docker run -v $(pwd):/files akhmetov/shortcuts-cli /files/s.toml /files/s.shortcut
docker run -v $(pwd):/files akhmetov/shortcuts-cli --help
usage: shortcuts [-h] [--version] [file] [output]
Shortcuts: Siri shortcuts creator
positional arguments:
file Input file: *.(toml|shortcut|itunes url)
output Output file: *.(toml|shortcut)
optional arguments:
-h, --help show this help message and exit
--version Version information
```
## Development
### Tests
Run tests:
```bash
tox
```
### How to add a new action
See [documentation](/docs/new_action.md).
### TODO
* ☑ ~~Conditionals with auto-group_id: if-else, menu~~
* ☐ Nested fields: dict/array/etc
* ☐ Support variables in every field which support them in Shortcuts app
* ☐ Workflow types: widget, etc.
* ☐ Import questions
* ☐ Document all actions
* ☐ Support magic variables
* ☐ Support all current actions from Shortcuts app
### Similar projects
* [Shortcuts JS](https://github.com/joshfarrant/shortcuts-js)
[![Build Status](https://travis-ci.org/alexander-akhmetov/python-shortcuts.svg?branch=master)](https://travis-ci.org/alexander-akhmetov/python-shortcuts)
[![PyPI](https://img.shields.io/pypi/v/shortcuts.svg)](https://pypi.python.org/pypi/shortcuts)
🍏 + 🐍 = ❤️
**python-shortcuts** is a library to create [Siri Shortcuts](https://support.apple.com/en-ae/guide/shortcuts/welcome/ios) on your laptop with your favourite text editor.
It uses [toml](https://github.com/toml-lang/toml) to represent shortcuts.
The library is in a very early development state (PR welcome!), so it does not support all actions from Shortcuts app.
* [Toml tutorial](docs/tutorial.md)
* [Python tutorial](docs/python_tutorial.md)
* [How to add a new action](docs/new_action.md)
* [Supported actions](docs/actions.md)
* [Examples](examples/)
* [Changelog](CHANGELOG.md)
* [Documentation](docs/)
Supported Python version: **>=3.6**.
## Why
I wanted to convert my shortcut to a file in human-readable format. :)
From the code below this library can create a working shortcut:
```toml
[[action]]
type = "ask"
question = "What is your name?"
[[action]]
type = "set_variable"
name = "name"
[[action]]
type = "show_result"
text = "Hello, {{name}}!"
```
Or the same with Python:
```python
from shortcuts import Shortcut, actions
sc = Shortcut()
sc.actions = [
actions.AskAction(data={'question': 'What is your name?'}),
actions.SetVariableAction(data={'name': 'name'}),
actions.ShowResultAction(data={'text': 'Hello, {{name}}!'})
]
```
## How to use
### Installation
```bash
pip install shortcuts
```
### Usage
### shortcut → toml
If you need to convert existing shortcut to a toml file, at first you need to export it.
Go into Shortcuts app, open the shortcut and share it. Choose "Share as file" and use this file with this library.
Convert shortcut file to `toml`:
```bash
shortcuts what_is_your_name.shortcut what_is_your_name.toml
```
### toml → shortcut
Convert a `toml` file to a shortcut file.
After you will need to open the file with iOS Shortcuts app.
```bash
shortcuts examples/what_is_your_name.toml what_is_your_name.shortcut
```
More examples of `toml` files you can find [here](examples/).
And [read the tutorial](docs/tutorial.md)! :)
### URL → [toml|shortcut]
Also, you can download shortcut directly from iCloud.
If somebody shared shortcut link with you, just run:
```bash
shortcuts https://www.icloud.com/shortcuts/... my_shortcut.toml # or my_shortcut.shortcut
```
And it will download this shortcut and save it in `toml` or `shortcut` format.
### Docker
It's possible to use [pre-built Docker container](https://cloud.docker.com/u/akhmetov/repository/docker/akhmetov/shortcuts-cli) with python-shortcuts inside:
```shell
# convert s.toml from the current directory into s.shortcut
docker run -v $(pwd):/files akhmetov/shortcuts-cli /files/s.toml /files/s.shortcut
docker run -v $(pwd):/files akhmetov/shortcuts-cli --help
usage: shortcuts [-h] [--version] [file] [output]
Shortcuts: Siri shortcuts creator
positional arguments:
file Input file: *.(toml|shortcut|itunes url)
output Output file: *.(toml|shortcut)
optional arguments:
-h, --help show this help message and exit
--version Version information
```
## Development
### Tests
Run tests:
```bash
tox
```
### How to add a new action
See [documentation](/docs/new_action.md).
### TODO
* ☑ ~~Conditionals with auto-group_id: if-else, menu~~
* ☐ Nested fields: dict/array/etc
* ☐ Support variables in every field which support them in Shortcuts app
* ☐ Workflow types: widget, etc.
* ☐ Import questions
* ☐ Document all actions
* ☐ Support magic variables
* ☐ Support all current actions from Shortcuts app
### Similar projects
* [Shortcuts JS](https://github.com/joshfarrant/shortcuts-js)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
python-shortcuts-0.11.0.tar.gz
(24.8 kB
view details)
File details
Details for the file python-shortcuts-0.11.0.tar.gz
.
File metadata
- Download URL: python-shortcuts-0.11.0.tar.gz
- Upload date:
- Size: 24.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.21.0 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/3.7.2
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1d0895c64f243640414e63d311a1b7bc4258a2ebfd8c98195d9973ccb105d785 |
|
MD5 | 3332e9a9156a877b8892cebc56b455e7 |
|
BLAKE2b-256 | 9eabe117457ac9dfcb564242abdf241da80b9fa2e866abfead7e8da32fd04fef |