Skip to main content
# 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)

Metadata

Release files for python-shortcuts 0.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-shortcuts 0.11.0
File Size Uploaded Provenance Actions
python-shortcuts-0.11.0.tar.gz 24.8 kB Without provenance Details for python-shortcuts-0.11.0.tar.gz

Release files / python-shortcuts-0.11.0.tar.gz

Download URL python-shortcuts-0.11.0.tar.gz
Size 24.8 kB
Tags Source
SHA-256 checksum
How to use checksums
1d0895c64f243640414e63d311a1b7bc4258a2ebfd8c98195d9973ccb105d785
BLAKE2b-256 checksum
How to use checksums
9eabe117457ac9dfcb564242abdf241da80b9fa2e866abfead7e8da32fd04fef
Upload date
Uploaded using Trusted Publishing?
What is 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

Security for python-shortcuts 0.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page