shortcutkit 3.0.0__tar.gz → 3.1.0__tar.gz

{shortcutkit-3.0.0/src/shortcutkit.egg-info → shortcutkit-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shortcutkit
-Version: 3.0.0
+Version: 3.1.0
 Summary: Build, validate, and sign Apple Shortcuts files from Python. All 449 built-in actions and 1,265 Apple app actions, extracted from the Shortcuts engine.
 Author: frontboat
 License-Expression: MIT
@@ -118,7 +118,12 @@ s.action(actions.SHOWRESULT, Text=text(property_(found, "body")))
 
 A dictionary parameter takes a plain dict: strings, `text()` and references are text items, and
 numbers, booleans, lists and nested dicts keep their type, as the editor's item type menu sets it.
-`coerce()` reads a value as one content type, as the variable "Type" menu does.
+`coerce()` reads a value as one content type, as the variable "Type" menu does, and `property_()` on the
+result takes that class's properties, the menu's "Get" list (`CONTENT_ITEM_PROPERTIES`):
+`property_(coerce(file, "WFGenericFileContentItem"), "File Size")`, checked at run time. An output the catalogue types, by
+class or by the object class it wraps (`CONTENT_ITEM_TYPES`), is checked the same way without a coercion:
+`property_(asked_number, "Name")`. Where a choice decides the output, the literal you pass narrows it:
+`s.action(actions.ASK, WFInputType="Number")` outputs a Number, so only Name is accepted.
 
 ```python
 from shortcutkit import coerce
@@ -162,11 +167,12 @@ s.action(actions.SHOWRESULT, Text=ref(note))
 | `shortcut_input()`, `clipboard()`, `current_date()`, `ask()`, `device_details()`, `current_app()` | Special variables. |
 | `where(*rows)`, `where_any(*rows)` | Conditions for a Find action's `WFContentItemFilter`. |
 | `property_(source, name)` | One property of an action's output or a variable. |
-| `coerce(source, class)` | A value read as one content type (`CONTENT_ITEM_CLASSES`). |
+| `coerce(source, class)` | A value read as one content type, the editor's "Type" menu (`CONTENT_ITEM_CLASSES`). |
 | `dictionary(items)` | A dictionary parameter's items; `action()` encodes a plain dict itself. |
 | `app_intent(app, intent, output=None)` | Another app's action, for `s.action()`. |
 | `FILTERS`, `ENTITY_PROPERTIES`, `FILTER_OPERATORS`, `CALENDAR_UNITS`, `CONTENT_ITEM_CLASSES` | What each Find action can filter on, each entity type's properties, and the content types a coercion can name. |
-| `actions`, `ACTIONS`, `get_action(id)` | Action identifiers and their catalog entries. |
+| `actions`, `ACTIONS`, `get_action(id)` | Action identifiers and their catalog entries: parameters and kinds, output and input types, keywords, description, flags, and the rules under which the editor shows each parameter. |
+| `accepted_by(type)`, `produced_by(type)` | Which actions take a content type as input or as an entity parameter, and which output it. |
 | `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. |
 

{shortcutkit-3.0.0 → shortcutkit-3.1.0}/README.md

@@ -97,7 +97,12 @@ s.action(actions.SHOWRESULT, Text=text(property_(found, "body")))
 
 A dictionary parameter takes a plain dict: strings, `text()` and references are text items, and
 numbers, booleans, lists and nested dicts keep their type, as the editor's item type menu sets it.
-`coerce()` reads a value as one content type, as the variable "Type" menu does.
+`coerce()` reads a value as one content type, as the variable "Type" menu does, and `property_()` on the
+result takes that class's properties, the menu's "Get" list (`CONTENT_ITEM_PROPERTIES`):
+`property_(coerce(file, "WFGenericFileContentItem"), "File Size")`, checked at run time. An output the catalogue types, by
+class or by the object class it wraps (`CONTENT_ITEM_TYPES`), is checked the same way without a coercion:
+`property_(asked_number, "Name")`. Where a choice decides the output, the literal you pass narrows it:
+`s.action(actions.ASK, WFInputType="Number")` outputs a Number, so only Name is accepted.
 
 ```python
 from shortcutkit import coerce
@@ -141,11 +146,12 @@ s.action(actions.SHOWRESULT, Text=ref(note))
 | `shortcut_input()`, `clipboard()`, `current_date()`, `ask()`, `device_details()`, `current_app()` | Special variables. |
 | `where(*rows)`, `where_any(*rows)` | Conditions for a Find action's `WFContentItemFilter`. |
 | `property_(source, name)` | One property of an action's output or a variable. |
-| `coerce(source, class)` | A value read as one content type (`CONTENT_ITEM_CLASSES`). |
+| `coerce(source, class)` | A value read as one content type, the editor's "Type" menu (`CONTENT_ITEM_CLASSES`). |
 | `dictionary(items)` | A dictionary parameter's items; `action()` encodes a plain dict itself. |
 | `app_intent(app, intent, output=None)` | Another app's action, for `s.action()`. |
 | `FILTERS`, `ENTITY_PROPERTIES`, `FILTER_OPERATORS`, `CALENDAR_UNITS`, `CONTENT_ITEM_CLASSES` | What each Find action can filter on, each entity type's properties, and the content types a coercion can name. |
-| `actions`, `ACTIONS`, `get_action(id)` | Action identifiers and their catalog entries. |
+| `actions`, `ACTIONS`, `get_action(id)` | Action identifiers and their catalog entries: parameters and kinds, output and input types, keywords, description, flags, and the rules under which the editor shows each parameter. |
+| `accepted_by(type)`, `produced_by(type)` | Which actions take a content type as input or as an entity parameter, and which output it. |
 | `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. |
 

{shortcutkit-3.0.0 → shortcutkit-3.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shortcutkit"
-version = "3.0.0"
+version = "3.1.0"
 description = "Build, validate, and sign Apple Shortcuts files from Python. All 449 built-in actions and 1,265 Apple app actions, extracted from the Shortcuts engine."
 requires-python = ">=3.9"
 readme = "README.md"

{shortcutkit-3.0.0 → shortcutkit-3.1.0}/src/shortcutkit/__init__.py

@@ -26,8 +26,8 @@ Value helpers return the exact structures WorkflowKit's state classes serialize:
   ask("Prompt")      WFTextTokenAttachment  -> ask each time
   text("a ", ref(x)) WFTextTokenString      -> text with embedded references
   subject(att)       {"Type": "Variable", "Variable": att}  (the If condition's subject; pickers take the bare attachment)
-  property_(x, "body")  a reference to one property of x (a WFPropertyVariableAggrandizement)
   coerce(x, "WFStringContentItem")  x read as one content type (a WFCoercionVariableAggrandizement; CONTENT_ITEM_CLASSES)
+  property_(x, "body")  one property of x (a WFPropertyVariableAggrandizement; ENTITY_PROPERTIES, CONTENT_ITEM_PROPERTIES)
   dictionary({...})  WFDictionaryFieldValue  -> a dictionary parameter's items, typed as the editor types them
   app_intent(app, "CreateNoteIntent")  another app's action, for action(): its identifier and descriptor
   where(row, ...)    Find conditions, encoded by action() for the Find action's entity
@@ -189,19 +189,38 @@ def subject(attachment):
 
 
 def property_(source, name):
-    """One property of an action's output or of any reference, as the editor's property picker writes
-    it (a WFPropertyVariableAggrandizement): property_(found, "body"), property_(repeat_item(), "date").
-    Given an action whose output is one of Apple's entity types, the name must be one of its
-    properties (ENTITY_PROPERTIES)."""
-    if not _is_reference(source):
-        entities = [t for t in source.get("_outputTypes", []) if t in ENTITY_PROPERTIES]
-        known = {p for e in entities for p in ENTITY_PROPERTIES[e]}
-        if entities and name not in known:
-            raise ValueError(f"{' / '.join(entities)} has no property {name}; it has {', '.join(sorted(known))}")
-        source = ref(source)
+    """One property of an action's output or of any reference, as the editor's property picker (the "Get" list
+    under a variable's "Type") writes it (a WFPropertyVariableAggrandizement): property_(found, "body"),
+    property_(repeat_item(), "date"), property_(coerce(file, "WFGenericFileContentItem"), "File Size").
+    When the output's type is known, one of Apple's entity types (ENTITY_PROPERTIES) or a content item class
+    (CONTENT_ITEM_PROPERTIES: named directly, or as the object class the definition names, NSDecimalNumber being a
+    Number, through CONTENT_ITEM_TYPES; also what a coerce()d reference has), the name must be one of its properties."""
+    if _is_reference(source):
+        cls = _coerced_class(source)
+        types = [cls] if cls else []
+    else:
+        declared = (source["_outputClasses"] + [t for t in source.get("_outputTypes", []) if t in ENTITY_PROPERTIES]) if source.get("_outputClasses") else source.get("_outputTypes", [])
+        types = list(dict.fromkeys(t if t in ENTITY_PROPERTIES else _item_class_of(t) for t in declared))
+        types = [t for t in types if t]
+    known = {p for t in types for p in (ENTITY_PROPERTIES.get(t) or CONTENT_ITEM_PROPERTIES.get(t) or [])}
+    if types and name not in known:
+        raise ValueError(f"{' / '.join(types)} has no property {name}; it has {', '.join(sorted(known))}")
     return _aggrandize(source, {"Type": "WFPropertyVariableAggrandizement", "PropertyName": name})
 
 
+def _item_class_of(type_name):
+    """An output type name as a content item class: itself when it is one, else the class that owns it (CONTENT_ITEM_TYPES)."""
+    return type_name if type_name in CONTENT_ITEM_PROPERTIES else CONTENT_ITEM_TYPES.get(type_name)
+
+
+def _coerced_class(attachment):
+    """The content item class a reference was last coerced to, when it is one the engine lists; else None."""
+    ags = attachment["Value"].get("Aggrandizements")
+    last = ags[-1] if isinstance(ags, list) and ags else None
+    cls = last.get("CoercionItemClass") if isinstance(last, dict) and last.get("Type") == "WFCoercionVariableAggrandizement" else None
+    return cls if cls in CONTENT_ITEM_PROPERTIES else None
+
+
 def _aggrandize(source, aggrandizement):
     """`source` with one more aggrandizement; an action stands for its output."""
     if not _is_reference(source):
@@ -489,6 +508,15 @@ class Shortcut:
         output = (definition or {}).get("Output", {})
         entry["_outputName"] = (output.get("OutputName") if isinstance(output, dict) else None) or catalog.get("output") or (intent or {}).get("output")
         entry["_outputTypes"] = list(catalog.get("outputTypes") or (output.get("Types") if isinstance(output, dict) else []) or [])
+        # The engine's answer to what comes out: for a choice that decides it (OUTPUT_CLASSES_BY), the literal given selects
+        # its classes and a reference means any of them; otherwise the classes for the default parameters.
+        by = OUTPUT_CLASSES_BY.get(identifier) if isinstance(identifier, str) else None
+        deciding = next((k for k in by if k in params), None) if by else None
+        if deciding:
+            v = params[deciding]
+            entry["_outputClasses"] = list(by[deciding][v]) if isinstance(v, str) and v in by[deciding] else sorted({c for cs in by[deciding].values() for c in cs})
+        elif catalog.get("outputClasses"):
+            entry["_outputClasses"] = list(catalog["outputClasses"])
         if isinstance(entry["_outputName"], dict):
             entry["_outputName"] = entry["_outputName"].get("format")
         self.actions.append(entry)
@@ -604,7 +632,11 @@ def get_action(identifier, definitions=DEFINITIONS):
     if entry is None:
         return None
     out = {"identifier": identifier, "name": entry["name"], "params": list(entry["params"]),
-           "kinds": dict(PARAM_KINDS.get(identifier, {})), "output": entry.get("output"), "outputTypes": list(entry.get("outputTypes", []))}
+           "kinds": dict(PARAM_KINDS.get(identifier, {})), "output": entry.get("output"), "outputTypes": list(entry.get("outputTypes", [])),
+           "inputTypes": list(entry.get("inputTypes", [])), "keywords": list(entry.get("keywords", []))}
+    for k in ("outputClasses", "inputKey", "inputRequired", "description", "descriptionNote", "descriptionResult", "discontinued", "unavailable", "requiresUnlock", "disabledOn", "requires"):
+        if entry.get(k):
+            out[k] = copy.deepcopy(entry[k])
     if entry.get("descriptor"):
         out["descriptor"] = entry["descriptor"]
     defs = _load_definitions(definitions) if definitions else {}
@@ -613,6 +645,20 @@ def get_action(identifier, definitions=DEFINITIONS):
     return out
 
 
+def accepted_by(type_name):
+    """Where a value of one content type can go: every built-in whose input takes it (with the key the input
+    lands in) and every App Intents parameter typed as that entity, as (identifier, key) pairs. Declared types
+    only; Shortcuts converts between many types at run time, so this is what the editor would list."""
+    out = [(i, e.get("inputKey") or "WFInput") for i, e in ACTIONS.items() if type_name in e.get("inputTypes", [])]
+    out += [(i, k) for i, keys in PARAM_ENTITY_TYPES.items() for k, t in keys.items() if t == type_name]
+    return out
+
+
+def produced_by(type_name):
+    """Every action whose output is declared as this content type (ACTIONS[id]["outputTypes"])."""
+    return [i for i, e in ACTIONS.items() if type_name in e.get("outputTypes", []) or type_name in e.get("outputClasses", [])]
+
+
 def demo(out):
     out = pathlib.Path(out)
     s = Shortcut(out.stem, color="Teal")
@@ -631,13 +677,13 @@ def demo(out):
 
 
 from . import actions  # noqa: E402  (generated identifier constants and ACTIONS metadata)
-from .actions import ACTIONS, PARAM_KINDS, PARAM_CHOICES, PARAM_VARIABLE_TYPES  # noqa: E402
-from .entities import FILTERS, FILTER_OPERATORS, CALENDAR_UNITS, BYTE_COUNT_UNITS, BOUNDED_FILTERS, ENTITY_PROPERTIES, CONTENT_ITEM_CLASSES  # noqa: E402  (generated Find filters, entity properties and content item classes)
+from .actions import ACTIONS, PARAM_KINDS, PARAM_CHOICES, PARAM_VARIABLE_TYPES, PARAM_ENTITY_TYPES, OUTPUT_CLASSES_BY  # noqa: E402
+from .entities import FILTERS, FILTER_OPERATORS, CALENDAR_UNITS, BYTE_COUNT_UNITS, BOUNDED_FILTERS, ENTITY_PROPERTIES, CONTENT_ITEM_CLASSES, CONTENT_ITEM_PROPERTIES, CONTENT_ITEM_TYPES  # noqa: E402  (generated Find filters, entity properties, content item classes, their properties and owned types)
 
 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", "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",
-           "property_", "coerce", "dictionary", "app_intent", "where", "where_any", "FILTERS", "FILTER_OPERATORS", "CALENDAR_UNITS", "BYTE_COUNT_UNITS", "BOUNDED_FILTERS", "ENTITY_PROPERTIES", "CONTENT_ITEM_CLASSES",
+__all__ = ["actions", "ACTIONS", "PARAM_KINDS", "PARAM_CHOICES", "PARAM_VARIABLE_TYPES", "PROVENANCE", "get_action", "accepted_by", "produced_by", "PARAM_ENTITY_TYPES", "OUTPUT_CLASSES_BY", "repeat_item", "repeat_index", "subject", "Shortcut", "ref", "variable", "shortcut_input", "clipboard", "current_date", "ask", "device_details", "current_app", "picker", "text",
+           "property_", "coerce", "dictionary", "app_intent", "where", "where_any", "FILTERS", "FILTER_OPERATORS", "CALENDAR_UNITS", "BYTE_COUNT_UNITS", "BOUNDED_FILTERS", "ENTITY_PROPERTIES", "CONTENT_ITEM_CLASSES", "CONTENT_ITEM_PROPERTIES", "CONTENT_ITEM_TYPES",
            "ICON_COLORS", "CONDITION", "DEFAULT_GLYPH", "LEGACY_KEYS", "demo"]
-__version__ = "3.0.0"
+__version__ = "3.1.0"