shortcutkit 0.7.2__tar.gz → 1.0.0__tar.gz

shortcutkit-1.0.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: shortcutkit
+Version: 1.0.0
+Summary: Build, validate, and sign Apple Shortcuts files from Python. All 434 built-in actions and 1,449 Apple app actions, extracted from the Shortcuts engine.
+Author: frontboat
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/frontboat/shortcutkit
+Project-URL: Documentation, https://github.com/frontboat/shortcutkit/blob/main/docs/shortcut-file-format.md
+Project-URL: Repository, https://github.com/frontboat/shortcutkit.git
+Project-URL: Changelog, https://github.com/frontboat/shortcutkit/blob/main/CHANGELOG.md
+Keywords: apple,apple-shortcuts,shortcuts,shortcuts-app,workflowkit,workflow,automation,macos,macos-automation,ios,plist
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# shortcutkit
+
+Build, validate, and sign Apple Shortcuts (`.shortcut`) files from Python.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/frontboat/shortcutkit/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/frontboat/shortcutkit/ci.yml?branch=main)](https://github.com/frontboat/shortcutkit/actions)
+
+A shortcut that asks your name and says hello:
+
+```python
+from shortcutkit import Shortcut, actions, ref, text
+
+s = Shortcut("Greeting")
+name = s.action(actions.ASK, WFAskActionPrompt="What's your name?")
+s.action(actions.SHOWRESULT, Text=text("Hello, ", ref(name), "!"))
+
+s.write()  # Greeting.shortcut
+Shortcut.sign("Greeting.shortcut", "Greeting-signed.shortcut")
+```
+
+Open `Greeting-signed.shortcut` and Shortcuts adds it to your library. Shortcuts only imports
+signed files, and signing needs a Mac with an iCloud login; everything else runs on any OS.
+
+## Why
+
+The action catalog is extracted from the Shortcuts app's own frameworks, not written by hand,
+and one command refreshes it after a macOS update. Earlier libraries kept hand-written lists and
+are archived ([python-shortcuts](https://github.com/alexander-akhmetov/python-shortcuts),
+[shortcuts-js](https://github.com/joshfarrant/shortcuts-js));
+[Cherri](https://github.com/electrikmilk/cherri) is a separate language with its own compiler.
+
+- All 434 built-in actions as constants, so a typo is an `AttributeError`.
+- 1,449 actions from Apple's apps: Reminders, Notes, Messages, Settings, and 73 more.
+- Third-party app actions, given their descriptor.
+- If, Repeat, Repeat with Each, and Choose from Menu blocks.
+- A wrong key or value raises `ValueError` before anything is written.
+- Pure Python, no dependencies.
+
+A [TypeScript package](https://www.npmjs.com/package/shortcutkit) with the same name and data
+adds compile-time checks.
+
+## Install
+
+```bash
+pip install shortcutkit   # Python 3.9+
+```
+
+## Usage
+
+These examples build on the one at the top.
+
+### Share sheet
+
+```python
+from shortcutkit import shortcut_input
+
+s = Shortcut("Page Links", types=["ActionExtension"], input_classes=["WFSafariWebPageContentItem"])
+links = s.action(actions.RUNJAVASCRIPTONWEBPAGE, WFInput=shortcut_input(), WFJavaScript="completion(document.links.length)")
+s.action(actions.SHOWRESULT, Text=text("Links: ", ref(links)))
+```
+
+### Control flow
+
+```python
+gid = s.if_(ref(name), "has_any_value")
+s.action(actions.SHOWRESULT, Text=text("Hello, ", ref(name)))
+s.otherwise(gid)
+s.action(actions.SHOWRESULT, Text=text("Hello, stranger"))
+s.end_if(gid)
+```
+
+### Apple's apps
+
+```python
+r = s.action(actions.REMINDERS_CREATE_REMINDER, title=text("Buy milk"), priorityLevel="high")
+s.action(actions.NOTES_CREATE_NOTE, name="Shopping", content=text("Added ", ref(r)))
+```
+
+### Other apps
+
+Pass the identifier and descriptor yourself; the parameters are not checked.
+
+```python
+s.action(
+    "com.example.app.CreateNoteIntent",
+    AppIntentDescriptor={
+        "BundleIdentifier": "com.example.app", "Name": "Example", "TeamIdentifier": "ABCDE12345",
+        "AppIntentIdentifier": "CreateNoteIntent", "ActionRequiresAppInstallation": True,
+    },
+    title=text("Hello"),
+    body=ref(name),
+)
+```
+
+## API
+
+| Export | What it does |
+|---|---|
+| `Shortcut(name, color=, glyph=, types=, input_classes=)` | A shortcut. |
+| `s.action(id, **params)` | Appends an action and returns it. |
+| `s.if_(subject, condition, value=None)`, `s.otherwise(gid)`, `s.end_if(gid)` | An If block. |
+| `s.repeat_each(items)`, `s.end_repeat_each(gid)` | A Repeat with Each block. |
+| `s.repeat_count(n)`, `s.end_repeat_count(gid)` | A Repeat block. |
+| `s.choose_from_menu(prompt, items)`, `s.menu_item(gid, title)`, `s.end_menu(gid)` | A Choose from Menu block. |
+| `s.write(path=None)` | Writes the unsigned file and returns its path. |
+| `Shortcut.sign(src, dst, mode="anyone")` | Signs a file with `shortcuts sign`. |
+| `s.to_plist()` | The shortcut as a plist dictionary. |
+| `ref(action)` | An action's output. |
+| `text(*parts)` | A string with references in it. |
+| `variable(name)`, `repeat_item()`, `repeat_index()` | Named and repeat variables. |
+| `shortcut_input()`, `clipboard()`, `current_date()`, `ask()`, `device_details()`, `current_app()` | Special variables. |
+| `actions`, `ACTIONS`, `get_action(id)` | Action identifiers and their catalog entries. |
+| `PARAM_KINDS`, `PARAM_CHOICES`, `PARAM_VARIABLE_TYPES` | What each parameter accepts. |
+| `CONDITION`, `ICON_COLORS`, `PROVENANCE` | If conditions, icon colors, and the build the data came from. |
+
+## Documentation
+
+- [Shortcut file format](https://github.com/frontboat/shortcutkit/blob/main/docs/shortcut-file-format.md)
+- [Built-in actions](https://github.com/frontboat/shortcutkit/blob/main/docs/builtin-actions-reference.md)
+- [Apple app actions](https://github.com/frontboat/shortcutkit/blob/main/docs/apple-app-intents-reference.md)
+- [Parameter encodings](https://github.com/frontboat/shortcutkit/blob/main/docs/parameter-encodings.md)
+- [How the data was extracted](https://github.com/frontboat/shortcutkit/blob/main/docs/extraction.md),
+  and what is still approximate
+
+## Contributing
+
+Issues and pull requests are welcome. See
+[`CONTRIBUTING.md`](https://github.com/frontboat/shortcutkit/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/frontboat/shortcutkit/blob/main/LICENSE).

shortcutkit-1.0.0/README.md

@@ -0,0 +1,132 @@
+# shortcutkit
+
+Build, validate, and sign Apple Shortcuts (`.shortcut`) files from Python.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/frontboat/shortcutkit/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/frontboat/shortcutkit/ci.yml?branch=main)](https://github.com/frontboat/shortcutkit/actions)
+
+A shortcut that asks your name and says hello:
+
+```python
+from shortcutkit import Shortcut, actions, ref, text
+
+s = Shortcut("Greeting")
+name = s.action(actions.ASK, WFAskActionPrompt="What's your name?")
+s.action(actions.SHOWRESULT, Text=text("Hello, ", ref(name), "!"))
+
+s.write()  # Greeting.shortcut
+Shortcut.sign("Greeting.shortcut", "Greeting-signed.shortcut")
+```
+
+Open `Greeting-signed.shortcut` and Shortcuts adds it to your library. Shortcuts only imports
+signed files, and signing needs a Mac with an iCloud login; everything else runs on any OS.
+
+## Why
+
+The action catalog is extracted from the Shortcuts app's own frameworks, not written by hand,
+and one command refreshes it after a macOS update. Earlier libraries kept hand-written lists and
+are archived ([python-shortcuts](https://github.com/alexander-akhmetov/python-shortcuts),
+[shortcuts-js](https://github.com/joshfarrant/shortcuts-js));
+[Cherri](https://github.com/electrikmilk/cherri) is a separate language with its own compiler.
+
+- All 434 built-in actions as constants, so a typo is an `AttributeError`.
+- 1,449 actions from Apple's apps: Reminders, Notes, Messages, Settings, and 73 more.
+- Third-party app actions, given their descriptor.
+- If, Repeat, Repeat with Each, and Choose from Menu blocks.
+- A wrong key or value raises `ValueError` before anything is written.
+- Pure Python, no dependencies.
+
+A [TypeScript package](https://www.npmjs.com/package/shortcutkit) with the same name and data
+adds compile-time checks.
+
+## Install
+
+```bash
+pip install shortcutkit   # Python 3.9+
+```
+
+## Usage
+
+These examples build on the one at the top.
+
+### Share sheet
+
+```python
+from shortcutkit import shortcut_input
+
+s = Shortcut("Page Links", types=["ActionExtension"], input_classes=["WFSafariWebPageContentItem"])
+links = s.action(actions.RUNJAVASCRIPTONWEBPAGE, WFInput=shortcut_input(), WFJavaScript="completion(document.links.length)")
+s.action(actions.SHOWRESULT, Text=text("Links: ", ref(links)))
+```
+
+### Control flow
+
+```python
+gid = s.if_(ref(name), "has_any_value")
+s.action(actions.SHOWRESULT, Text=text("Hello, ", ref(name)))
+s.otherwise(gid)
+s.action(actions.SHOWRESULT, Text=text("Hello, stranger"))
+s.end_if(gid)
+```
+
+### Apple's apps
+
+```python
+r = s.action(actions.REMINDERS_CREATE_REMINDER, title=text("Buy milk"), priorityLevel="high")
+s.action(actions.NOTES_CREATE_NOTE, name="Shopping", content=text("Added ", ref(r)))
+```
+
+### Other apps
+
+Pass the identifier and descriptor yourself; the parameters are not checked.
+
+```python
+s.action(
+    "com.example.app.CreateNoteIntent",
+    AppIntentDescriptor={
+        "BundleIdentifier": "com.example.app", "Name": "Example", "TeamIdentifier": "ABCDE12345",
+        "AppIntentIdentifier": "CreateNoteIntent", "ActionRequiresAppInstallation": True,
+    },
+    title=text("Hello"),
+    body=ref(name),
+)
+```
+
+## API
+
+| Export | What it does |
+|---|---|
+| `Shortcut(name, color=, glyph=, types=, input_classes=)` | A shortcut. |
+| `s.action(id, **params)` | Appends an action and returns it. |
+| `s.if_(subject, condition, value=None)`, `s.otherwise(gid)`, `s.end_if(gid)` | An If block. |
+| `s.repeat_each(items)`, `s.end_repeat_each(gid)` | A Repeat with Each block. |
+| `s.repeat_count(n)`, `s.end_repeat_count(gid)` | A Repeat block. |
+| `s.choose_from_menu(prompt, items)`, `s.menu_item(gid, title)`, `s.end_menu(gid)` | A Choose from Menu block. |
+| `s.write(path=None)` | Writes the unsigned file and returns its path. |
+| `Shortcut.sign(src, dst, mode="anyone")` | Signs a file with `shortcuts sign`. |
+| `s.to_plist()` | The shortcut as a plist dictionary. |
+| `ref(action)` | An action's output. |
+| `text(*parts)` | A string with references in it. |
+| `variable(name)`, `repeat_item()`, `repeat_index()` | Named and repeat variables. |
+| `shortcut_input()`, `clipboard()`, `current_date()`, `ask()`, `device_details()`, `current_app()` | Special variables. |
+| `actions`, `ACTIONS`, `get_action(id)` | Action identifiers and their catalog entries. |
+| `PARAM_KINDS`, `PARAM_CHOICES`, `PARAM_VARIABLE_TYPES` | What each parameter accepts. |
+| `CONDITION`, `ICON_COLORS`, `PROVENANCE` | If conditions, icon colors, and the build the data came from. |
+
+## Documentation
+
+- [Shortcut file format](https://github.com/frontboat/shortcutkit/blob/main/docs/shortcut-file-format.md)
+- [Built-in actions](https://github.com/frontboat/shortcutkit/blob/main/docs/builtin-actions-reference.md)
+- [Apple app actions](https://github.com/frontboat/shortcutkit/blob/main/docs/apple-app-intents-reference.md)
+- [Parameter encodings](https://github.com/frontboat/shortcutkit/blob/main/docs/parameter-encodings.md)
+- [How the data was extracted](https://github.com/frontboat/shortcutkit/blob/main/docs/extraction.md),
+  and what is still approximate
+
+## Contributing
+
+Issues and pull requests are welcome. See
+[`CONTRIBUTING.md`](https://github.com/frontboat/shortcutkit/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/frontboat/shortcutkit/blob/main/LICENSE).

{shortcutkit-0.7.2 → shortcutkit-1.0.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shortcutkit"
-version = "0.7.2"
-description = "Build, validate and sign Apple Shortcuts (.shortcut) files."
+version = "1.0.0"
+description = "Build, validate, and sign Apple Shortcuts files from Python. All 434 built-in actions and 1,449 Apple app actions, extracted from the Shortcuts engine."
 requires-python = ">=3.9"
 readme = "README.md"
 license = "MIT"

{shortcutkit-0.7.2 → shortcutkit-1.0.0}/src/shortcutkit/__init__.py

@@ -25,9 +25,11 @@ Value helpers return the exact structures WorkflowKit's state classes serialize:
   current_date()     WFTextTokenAttachment  -> current date
   ask("Prompt")      WFTextTokenAttachment  -> ask each time
   text("a ", ref(x)) WFTextTokenString      -> text with embedded references
-  picker(att)        {"Type": "Variable", "Variable": att}  (variable-picker parameters)
+  subject(att)       {"Type": "Variable", "Variable": att}  (the If condition's subject; pickers take the bare attachment)
 Plain str / int / float / bool / list are written as-is.
 """
+import copy
+import functools
 import json
 import pathlib
 import plistlib
@@ -38,6 +40,13 @@ import uuid
 HERE = pathlib.Path(__file__).resolve().parent
 DEFINITIONS = HERE / "data" / "builtin-actions.json"
 
+
+@functools.lru_cache(maxsize=None)
+def _load_definitions(path):
+    """The definitions file, parsed once per path; {} when it is absent."""
+    path = pathlib.Path(path)
+    return json.loads(path.read_text()) if path.exists() else {}
+
 # WFWorkflowIcon.backgroundColorValue for palette colors 0-14, as the unsigned 32-bit
 # value the plist stores. Names follow Shortcuts' picker order.
 ICON_COLORS = {
@@ -95,7 +104,9 @@ def _check_kind(kind, value):
     if kind in ("string", "text", "plainString") and not isinstance(value, str):
         return f"expected a string{'' if kind == 'plainString' else ' or a reference'}, got {type(value).__name__}"
     if kind == "picker":
-        return "expected picker(<attachment>) or an attachment"
+        return "expected a reference (ref(), variable(), shortcut_input(), ...)"
+    if kind == "subject" and not (isinstance(value, dict) and value.get("Type") == "Variable" and "Variable" in value):
+        return "expected a reference or subject(<reference>)"
     return None
 
 
@@ -104,31 +115,59 @@ def _attachment(value):
 
 
 def ref(action, output_name=None):
-    """Reference another action's output. `action` is the dict returned by Shortcut.action()."""
+    """Another action's output. `action` is what Shortcut.action() returned."""
     return _attachment({"Type": "ActionOutput", "OutputUUID": action["WFWorkflowActionParameters"]["UUID"],
                         "OutputName": output_name or action.get("_outputName", "Output")})
 
 
 def variable(name):
+    """A named variable, as set by Set Variable or Add to Variable."""
     return _attachment({"Type": "Variable", "VariableName": name})
 
 
 def shortcut_input():
+    """The shortcut's input, from the share sheet, Quick Actions, or Run Shortcut."""
     return _attachment({"Type": "ExtensionInput"})
 
 
 def clipboard():
+    """The clipboard's contents."""
     return _attachment({"Type": "Clipboard"})
 
 
 def current_date():
+    """The date and time the shortcut runs."""
     return _attachment({"Type": "CurrentDate"})
 
 
 def ask(prompt=None):
+    """A value the user is asked for each time the shortcut runs."""
     return _attachment({"Type": "Ask", **({"Prompt": prompt} if prompt else {})})
 
 
+def device_details():
+    """Device Details (name, model, OS version, ...); the app usually adds a property aggrandizement."""
+    return _attachment({"Type": "DeviceDetails"})
+
+
+def current_app():
+    """The app the shortcut was run from."""
+    return _attachment({"Type": "CurrentApp"})
+
+
+def _reference_types(value):
+    """The variable types (Ask, ActionOutput, Variable, ...) referenced anywhere in a value."""
+    if not isinstance(value, dict):
+        return []
+    if value.get("WFSerializationType") == "WFTextTokenAttachment":
+        return [str(value.get("Value", {}).get("Type"))]
+    if value.get("WFSerializationType") == "WFTextTokenString":
+        return [str(a.get("Type")) for a in value.get("Value", {}).get("attachmentsByRange", {}).values()]
+    if value.get("Type") == "Variable" and isinstance(value.get("Variable"), dict):
+        return _reference_types(value["Variable"])
+    return []
+
+
 def repeat_item():
     """The current item inside a Repeat with Each block."""
     return _attachment({"Type": "Variable", "VariableName": "Repeat Item"})
@@ -139,13 +178,19 @@ def repeat_index():
     return _attachment({"Type": "Variable", "VariableName": "Repeat Index"})
 
 
+def subject(attachment):
+    """The If-subject form of a reference. if_() and action() apply it for you."""
+    return {"Type": "Variable", "Variable": attachment}
+
+
 def picker(attachment):
+    """Deprecated, misnamed: this is the If-subject form. Pass a bare reference to picker parameters."""
     """Wrap an attachment for WFVariablePickerParameter keys (e.g. WFInput on Repeat with Each)."""
     return {"Type": "Variable", "Variable": attachment}
 
 
 def text(*parts):
-    """A WFTextTokenString: strings and attachments interleaved. Each attachment becomes U+FFFC."""
+    """Text with references in it: text("Hello, ", ref(name), "!")."""
     string = ""
     attachments = {}
     for part in parts:
@@ -159,20 +204,27 @@ def text(*parts):
 
 
 class Shortcut:
+    """A shortcut. Add actions, then write() and sign(); Shortcuts names the import after the file,
+    which defaults to <name>.shortcut."""
+
     def __init__(self, name, color="Blue", glyph=DEFAULT_GLYPH, input_classes=None, types=None, definitions=DEFINITIONS):
-        """types: surfaces the shortcut appears in (WFWorkflowTypes): "ActionExtension" is the share
-        sheet, "QuickActions" the Finder and Services menus, also "MenuBar", "NCWidget", "WatchKit",
-        "Sleep", "ReceivesOnScreenContent". input_classes: content item classes accepted as input."""
+        """color: a palette name ("Teal") or a raw value. glyph: a codepoint from Shortcuts' icon font.
+        types: where the shortcut appears: "ActionExtension" (share sheet), "QuickActions" (Finder and
+        Services menus), "MenuBar", "NCWidget", "WatchKit", "Sleep", "ReceivesOnScreenContent".
+        input_classes: content item classes it accepts as input."""
         self.name = name
         self.color = ICON_COLORS[color] if isinstance(color, str) else color
         self.glyph = glyph
         self.input_classes = input_classes or []
         self.types = list(types or [])
         self.actions = []
-        self.defs = json.load(open(definitions)) if pathlib.Path(definitions).exists() else {}
+        self.defs = _load_definitions(definitions)
 
-    def action(self, identifier, **params):
-        """Append an action. Unknown identifiers or parameter keys raise ValueError."""
+    def action(self, identifier, /, **params):
+        """Append an action and return it; ref() it to use its output. Catalog identifiers are
+        checked: unknown keys, wrong value kinds, and unreadable references raise ValueError. Other
+        identifiers pass through unchecked. `identifier` is positional-only, so a parameter can
+        have that name."""
         definition = self.defs.get(identifier)
         catalog = ACTIONS.get(identifier) or {}
         descriptor = catalog.get("descriptor")
@@ -192,13 +244,20 @@ class Shortcut:
             if unknown and known - {"UUID", "GroupingIdentifier", "WFControlFlowMode", "CustomOutputName"}:
                 raise ValueError(f"{identifier}: unknown parameter(s) {sorted(unknown)}; known: {sorted(known)}")
         kinds = PARAM_KINDS.get(identifier, {})
+        restricted = PARAM_VARIABLE_TYPES.get(identifier, {})
         for key, value in params.items():
             problem = _check_kind(kinds.get(key, "any"), value)
             if problem:
                 raise ValueError(f"{identifier}.{key}: {problem}")
+            # Keys the engine reads no reference for (or only Ask): the same rule as the TypeScript types, at run time.
+            if key in restricted:
+                bad = [t for t in _reference_types(value) if t not in restricted[key]]
+                if bad:
+                    raise ValueError(f"{identifier}.{key}: the engine does not read a {'/'.join(bad)} reference here (it reads {', '.join(restricted[key]) if restricted[key] else 'only a plain value'})")
         # Text parameters never hold a bare attachment: the engine writes a lone variable as a
         # token string with one placeholder. Wrap it so ref() works for text keys too.
-        params = {k: (text(v) if kinds.get(k) == "text" and isinstance(v, dict) and v.get("WFSerializationType") == "WFTextTokenAttachment" else v)
+        params = {k: (text(v) if kinds.get(k) == "text" and _is_reference(v) and v.get("WFSerializationType") == "WFTextTokenAttachment"
+                      else subject(v) if kinds.get(k) == "subject" and _is_reference(v) and v.get("WFSerializationType") == "WFTextTokenAttachment" else v)
                   for k, v in params.items()}
         # App Intents actions carry a descriptor naming the app that provides them.
         head = {"UUID": str(uuid.uuid4()).upper()}
@@ -216,9 +275,15 @@ class Shortcut:
 
     # Control flow: each block is a group sharing a GroupingIdentifier, with
     # WFControlFlowMode 0 = start, 1 = middle (Otherwise / menu item), 2 = end.
+    @staticmethod
+    def _subject(value):
+        return value if isinstance(value, dict) and value.get("Type") == "Variable" and "Variable" in value else subject(value)
+
     def if_(self, subject, condition, value=None):
+        """Open an If block on `subject`. `condition` is a CONDITION name or code; `value` is what it
+        compares with, if anything. Returns the id for otherwise() and end_if()."""
         gid = str(uuid.uuid4()).upper()
-        params = {"GroupingIdentifier": gid, "WFControlFlowMode": 0, "WFInput": picker(subject),
+        params = {"GroupingIdentifier": gid, "WFControlFlowMode": 0, "WFInput": self._subject(subject),
                   "WFCondition": CONDITION[condition] if isinstance(condition, str) else condition}
         if isinstance(value, (int, float)) and not isinstance(value, bool):
             params["WFNumberValue"] = value
@@ -228,49 +293,55 @@ class Shortcut:
         return gid
 
     def otherwise(self, gid):
+        """Start the Otherwise branch of If block `gid`."""
         self.action("is.workflow.actions.conditional", GroupingIdentifier=gid, WFControlFlowMode=1)
 
     def end_if(self, gid):
+        """Close If block `gid`."""
         self.action("is.workflow.actions.conditional", GroupingIdentifier=gid, WFControlFlowMode=2)
 
     def repeat_each(self, items):
-        """Open a Repeat with Each block; returns the grouping identifier to pass to end_repeat_each()."""
+        """Open a Repeat with Each block over `items`; returns the id for end_repeat_each(). Inside,
+        use repeat_item() and repeat_index()."""
         gid = str(uuid.uuid4()).upper()
-        self.action("is.workflow.actions.repeat.each", GroupingIdentifier=gid, WFControlFlowMode=0, WFInput=picker(items))
+        self.action("is.workflow.actions.repeat.each", GroupingIdentifier=gid, WFControlFlowMode=0, WFInput=items)
         return gid
 
     def end_repeat_each(self, gid):
-        """Close a Repeat with Each block. The returned action is the block's output: ref() it for "Repeat Results"."""
+        """Close a Repeat with Each block and return it; ref() it for the Repeat Results."""
         a = self.action("is.workflow.actions.repeat.each", GroupingIdentifier=gid, WFControlFlowMode=2)
         a["_outputName"] = "Repeat Results"
         return a
 
     def repeat_count(self, count):
-        """Open a Repeat block that runs `count` times; returns the grouping identifier for end_repeat_count()."""
+        """Open a Repeat block that runs `count` times; returns the id for end_repeat_count()."""
         gid = str(uuid.uuid4()).upper()
         self.action("is.workflow.actions.repeat.count", GroupingIdentifier=gid, WFControlFlowMode=0, WFRepeatCount=count)
         return gid
 
     def end_repeat_count(self, gid):
-        """Close a Repeat block. The returned action is the block's output: ref() it for "Repeat Results"."""
+        """Close a Repeat block and return it; ref() it for the Repeat Results."""
         a = self.action("is.workflow.actions.repeat.count", GroupingIdentifier=gid, WFControlFlowMode=2)
         a["_outputName"] = "Repeat Results"
         return a
 
     def choose_from_menu(self, prompt, items):
-        """Open a Choose from Menu block. Follow with one menu_item() per title, in order, each with
-        the actions of that branch, then end_menu(). Returns the grouping identifier."""
+        """Open a Choose from Menu block; returns the id for menu_item() and end_menu(). Follow with
+        one menu_item() per title, in order, each followed by that branch's actions."""
         gid = str(uuid.uuid4()).upper()
         self.action("is.workflow.actions.choosefrommenu", GroupingIdentifier=gid, WFControlFlowMode=0, WFMenuPrompt=prompt, WFMenuItems=list(items))
         return gid
 
     def menu_item(self, gid, title):
+        """Start the branch for `title` in menu `gid`."""
         self.action("is.workflow.actions.choosefrommenu", GroupingIdentifier=gid, WFControlFlowMode=1, WFMenuItemTitle=title)
 
     def end_menu(self, gid):
+        """Close menu `gid`."""
         self.action("is.workflow.actions.choosefrommenu", GroupingIdentifier=gid, WFControlFlowMode=2)
 
     def to_plist(self):
+        """The shortcut as a plist dictionary."""
         actions = []
         for a in self.actions:
             actions.append({k: v for k, v in a.items() if not k.startswith("_")})
@@ -291,8 +362,7 @@ class Shortcut:
         }
 
     def write(self, path=None):
-        """Write the unsigned plist. Shortcuts names an imported shortcut after its file, so the
-        default file name is the shortcut's name."""
+        """Write the unsigned file, <name>.shortcut by default, and return its path."""
         path = pathlib.Path(path) if path else pathlib.Path(f"{self.name}.shortcut")
         with open(path, "wb") as f:
             plistlib.dump(self.to_plist(), f, fmt=plistlib.FMT_BINARY)
@@ -300,13 +370,15 @@ class Shortcut:
 
     @staticmethod
     def sign(src, dst, mode="anyone"):
+        """Sign `src` into `dst`, which Shortcuts will import, and return `dst`. Needs a Mac with an
+        iCloud login."""
         subprocess.run(["shortcuts", "sign", "--mode", mode, "--input", str(src), "--output", str(dst)], check=True)
         return dst
 
 
 def get_action(identifier, definitions=DEFINITIONS):
-    """What the catalogue knows about any identifier, built-in or App Intent, in one shape:
-    name, params, kinds, output, descriptor (App Intents) and definition (built-ins)."""
+    """What the catalog knows about any identifier, built-in or App Intent: name, params, kinds,
+    output, descriptor (App Intents), and definition (built-ins)."""
     entry = ACTIONS.get(identifier)
     if entry is None:
         return None
@@ -314,9 +386,9 @@ def get_action(identifier, definitions=DEFINITIONS):
            "kinds": dict(PARAM_KINDS.get(identifier, {})), "output": entry.get("output"), "outputTypes": list(entry.get("outputTypes", []))}
     if entry.get("descriptor"):
         out["descriptor"] = entry["descriptor"]
-    defs = json.load(open(definitions)) if definitions and pathlib.Path(definitions).exists() else {}
+    defs = _load_definitions(definitions) if definitions else {}
     if identifier in defs:
-        out["definition"] = defs[identifier]
+        out["definition"] = copy.deepcopy(defs[identifier])
     return out
 
 
@@ -338,11 +410,11 @@ def demo(out):
 
 
 from . import actions  # noqa: E402  (generated identifier constants and ACTIONS metadata)
-from .actions import ACTIONS, PARAM_KINDS, PARAM_CHOICES  # noqa: E402
+from .actions import ACTIONS, PARAM_KINDS, PARAM_CHOICES, PARAM_VARIABLE_TYPES  # noqa: E402
 
 PROVENANCE = json.load(open(HERE / "data" / "provenance.json")) if (HERE / "data" / "provenance.json").exists() else {}
 """Which macOS and Shortcuts build the bundled data was extracted from."""
 
-__all__ = ["actions", "ACTIONS", "PARAM_KINDS", "PARAM_CHOICES", "PROVENANCE", "get_action", "repeat_item", "repeat_index", "Shortcut", "ref", "variable", "shortcut_input", "clipboard", "current_date", "ask", "picker", "text",
+__all__ = ["actions", "ACTIONS", "PARAM_KINDS", "PARAM_CHOICES", "PARAM_VARIABLE_TYPES", "PROVENANCE", "get_action", "repeat_item", "repeat_index", "subject", "Shortcut", "ref", "variable", "shortcut_input", "clipboard", "current_date", "ask", "device_details", "current_app", "picker", "text",
            "ICON_COLORS", "CONDITION", "DEFAULT_GLYPH", "LEGACY_KEYS", "demo"]
-__version__ = "0.7.2"
+__version__ = "1.0.0"