sg-python-api 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

shotgun_api3/lib/mockgun/_query.py

@@ -15,10 +15,14 @@ from ._errors import MockgunError, ServerFaultError
 from ._events import check_meta
 from ._links import (
     RecordState,
+    connection_backed,
+    connection_record,
     deciding_record,
     derived_name,
     display_name,
     hidden,
+    implicit_link_hidden,
+    link_target,
     named_link,
 )
 from ._presets import (
@@ -44,7 +48,7 @@ _COLLATION_CHARACTERS = frozenset(ascii_letters + digits)
 _COLLATION_IGNORED = str.maketrans('', '', '_-. ')
 _EntityLink: TypeAlias = dict[str, FieldValue]
 _LINK_PATH_PARTS = 3
-_NOTE_LINK_PAIR = {'Asset', 'Shot'}
+_MEMBER_ORDER_MINIMUM = 2
 _NUMERIC_TYPES = frozenset({'date', 'date_time', 'duration', 'float', 'number', 'percent'})
 _ORDER_TYPES = _NUMERIC_TYPES | {
     'checkbox',
@@ -220,9 +224,7 @@ class _RowReader:
         self._schema = schema
         self._assume: dict[tuple[str, int], RecordState] | None = None
 
-    def _direct_field_value(
-        self, entity_type: str, row: Row, field_name: str, *, membership: bool = False
-    ) -> FieldValue:
+    def _direct_field_value(self, entity_type: str, row: Row, field_name: str) -> FieldValue:
         """Read a stored field or compute its non-retained display cache."""
         if entity_type == 'Project' and field_name == 'last_accessed_by_current_user':
             context = self._store.context
@@ -241,8 +243,8 @@ class _RowReader:
                     'actor has never accessed the Project'
                 )
             return value
-        if '__unknown' in row or (not membership and '__unordered' in row):
-            self._store.check_known(row, field_name, membership=membership)
+        if '__unknown' in row:
+            self._store.check_known(row, field_name)
         if entity_type == 'EventLogEntry' and field_name == 'meta':
             check_meta(self._store, row)
         if field_name == 'cached_display_name' and entity_type != 'EventLogEntry':
@@ -282,7 +284,7 @@ class _Projection(_RowReader):
         if len(parts) != _LINK_PATH_PARTS:
             value = self._direct_field_value(entity_type, row, path)
             visible = self._visible_value(row, path, value)
-            return True, _ordered_note_links(row, path, value, visible, self._projection_context)
+            return True, visible
         field, linked_type, rest = parts
         link_value = self._direct_field_value(entity_type, row, field)
         if self._visible_value(row, field, link_value) != link_value:
@@ -368,9 +370,11 @@ class _Projection(_RowReader):
                     continue
                 if field_type in {'entity', 'multi_entity'}:
                     if isinstance(value, list):
-                        value = [
-                            named_link(self._store, cast('_EntityLink', item)) for item in value
-                        ]
+                        value = _member_order(
+                            entity_type,
+                            name,
+                            [named_link(self._store, cast('_EntityLink', item)) for item in value],
+                        )
                     elif isinstance(value, dict):
                         value = named_link(self._store, value)
                 elif field_type == 'date_time':
@@ -608,7 +612,7 @@ class _Query(_RowReader):
     ) -> bool:
         """Reduce identity conditions before reading link visibility."""
         field_type = self._schema.field_type(entity_type, path)
-        actual = self._direct_field_value(entity_type, row, path, membership=True)
+        actual = self._direct_field_value(entity_type, row, path)
         if (
             field_type in {'entity', 'multi_entity'}
             and relation == 'is'
@@ -646,7 +650,7 @@ class _Query(_RowReader):
         if len(parts) != _LINK_PATH_PARTS:
             return self._matches_direct(entity_type, row, path, relation, values)
         field, linked_type, rest = parts
-        actual = self._direct_field_value(entity_type, row, field, membership=True)
+        actual = self._direct_field_value(entity_type, row, field)
         actual = self._hidden_filter_value(row, field, actual, relation, values)
         links = actual if isinstance(actual, list) else [actual]
         matches: list[bool] = []
@@ -956,6 +960,19 @@ class _Query(_RowReader):
             )
         return bool(row['__retired'])
 
+    def _retired_hidden(self, row: Row, field: str, link: _EntityLink) -> _Decision:
+        """Hide a retired holder's links to retired targets and retired connections."""
+        target = link_target(self._store, link)
+        if target is None or (target['type'], target['id']) == (row['type'], row['id']):
+            return False
+        retired_target = self._symbolic_retired(target)
+        if not connection_backed(row, field, target):
+            return retired_target
+        record = connection_record(self._store, row, field, target)
+        if record is None:
+            return self._any(retired_target, implicit_link_hidden(row, field, target))
+        return self._any(retired_target, self._symbolic_retired(record))
+
     def _symbolic_hidden(self, row: Row, field: str, link: _EntityLink) -> _Decision:
         """Express hiding through the deciding record and the holder's scope."""
         deciding = deciding_record(self._store, row, field, link)
@@ -978,7 +995,9 @@ class _Query(_RowReader):
                 (cast('str', row['type']), cast('int', row['id'])): RecordState(retired=False)
             }
             outcome = hidden(self._store, row, field, link, assume=active)
-        return self._choose(self._symbolic_retired(row), yes=False, no=outcome)
+        return self._choose(
+            self._symbolic_retired(row), yes=self._retired_hidden(row, field, link), no=outcome
+        )
 
     def _symbolic_archive(self, row: Row, scope: ReadScope) -> _Decision:
         """Retain a project visibility bit only when its archive status matters."""
@@ -1004,7 +1023,7 @@ class _Query(_RowReader):
         relation = cast('str', condition['relation'])
         values = cast('list[FieldValue]', condition['values'])
         field_type = self._schema.field_type(kind, path)
-        actual = self._direct_field_value(kind, row, path, membership=True)
+        actual = self._direct_field_value(kind, row, path)
         if field_type not in {'entity', 'multi_entity'}:
             return self._matches_direct(kind, row, path, relation, values)
         links = actual if isinstance(actual, list) else [actual]
@@ -1037,9 +1056,7 @@ class _Query(_RowReader):
             if len(path.split('.', 2)) != _LINK_PATH_PARTS:
                 return self._symbolic_direct(row, condition)
             field = path.split('.', 1)[0]
-            actual = self._direct_field_value(
-                cast('str', row['type']), row, field, membership=True
-            )
+            actual = self._direct_field_value(cast('str', row['type']), row, field)
             links = actual if isinstance(actual, list) else [actual]
             result: _Decision = False
             for link in links:
@@ -1952,26 +1969,51 @@ def _operand_fault(field_type: str, relation: str, value: object) -> str | None:
     return None
 
 
-def _ordered_note_links(
-    row: Row, field: str, stored: FieldValue, visible: FieldValue, context: RequestContext | None
-) -> FieldValue:
-    """Return Asset before Shot for script reads of a script-authored Note's two links."""
-    creator = row.get('created_by')
-    if (
-        row['type'] == 'Note'
-        and context is not None
-        and context.session_kind == 'script'
-        and isinstance(creator, dict)
-        and creator.get('type') == 'ApiUser'
-        and field == 'note_links'
-        and isinstance(stored, list)
-        and len(stored) == len(_NOTE_LINK_PAIR)
-        and {cast('str', cast('_EntityLink', member)['type']) for member in stored}
-        == _NOTE_LINK_PAIR
-        and isinstance(visible, list)
-    ):
-        return sorted(visible, key=lambda member: cast('str', cast('_EntityLink', member)['type']))
-    return visible
+def _settled_member_keys(keys: Collection[str]) -> bool:
+    """Return whether observed comparisons order distinct lowered member names.
+
+    Names compare by character code (2026-11-10), with non-ASCII characters
+    after ASCII ones; two differing non-ASCII characters were observed only in
+    lowercase.
+    """
+    for left, right in combinations(keys, 2):
+        for first, second in zip(left, right, strict=False):
+            if first != second:
+                if not (first.isascii() or second.isascii()) and (
+                    first != first.lower() or second != second.lower()
+                ):
+                    return False
+                break
+    return True
+
+
+def _member_order(entity_type: str, field: str, links: list[_EntityLink]) -> list[_EntityLink]:
+    """Order members as the site reads them: by lowercased name, then by ID.
+
+    Members without a modeled display name keep the stored order when the named
+    members already appear in their observed order within it.
+    """
+    if len(links) < _MEMBER_ORDER_MINIMUM:
+        return links
+    keyed: list[tuple[str, int, int]] = []
+    for index, link in enumerate(links):
+        name = link.get('name')
+        if isinstance(name, str):
+            keyed.append((name.translate(_ASCII_LOWER), cast('int', link['id']), index))
+    if not _settled_member_keys({key for key, _, _ in keyed}):
+        raise MockgunError(
+            f'mockgun cannot order {entity_type}.{field} members: their names compare by '
+            'unobserved rules'
+        )
+    order = [index for _, _, index in sorted(keyed)]
+    if len(keyed) == len(links):
+        return [links[index] for index in order]
+    if order != sorted(order):
+        raise MockgunError(
+            f'mockgun cannot order {entity_type}.{field} members: the order depends on '
+            'members without a modeled display name; declare their display fields'
+        )
+    return links
 
 
 def _validate_operands(

shotgun_api3/lib/mockgun/_retirement.py

@@ -5,10 +5,27 @@ from dataclasses import dataclass
 from datetime import datetime
 from typing import cast
 
-from ._links import RetirementEdge, hidden, retirement_edge
+from ._links import (
+    RetirementEdge,
+    hidden,
+    implicit_connection_fields,
+    link_target,
+    retirement_edge,
+)
 from ._sessions import RequestContext
 from ._store import FieldValue, Row, Store
 
+# A cascaded child revived while its parent stays retired hides its link to the
+# parent and is untouched by the parent's later revival (a Shot's Version
+# earlier; the rest on 2026-11-10). Each child type maps to its parent field and
+# the parent types observed.
+_SETTLED_ALONE = {
+    'Note': ('note_links', frozenset({'Asset', 'Sequence', 'Shot', 'Version'})),
+    'Shot': ('project', frozenset({'Project'})),
+    'Task': ('entity', frozenset({'Asset', 'Sequence', 'Shot'})),
+    'Version': ('entity', frozenset({'Asset', 'Sequence', 'Shot'})),
+}
+
 
 @dataclass(frozen=True)
 class RetirementEffects:
@@ -86,21 +103,54 @@ def _holder_groups(
     return list(groups.values())
 
 
+def _mark_hidden_links(store: Store, rows: list[Row]) -> None:
+    """Record the NoteLink and NoteTask members already hidden when these rows retired."""
+    operation = {_identity(row) for row in rows}
+    for row in rows:
+        members: list[FieldValue] = []
+        for field in implicit_connection_fields(cast('str', row['type'])):
+            value = row.get(field)
+            for link in cast(
+                'list[dict[str, FieldValue]]', value if isinstance(value, list) else []
+            ):
+                target = link_target(store, link)
+                if (
+                    target is not None
+                    and target['__retired']
+                    and _identity(target) not in operation
+                ):
+                    members.append([field, target['type'], target['id']])
+        if members:
+            store.remember(row)
+            row['__retired_hidden'] = members
+
+
+def _names(value: FieldValue, target: Row) -> bool:
+    """Return whether a single or multi-entity value names the target."""
+    identity: FieldValue = {'type': target['type'], 'id': target['id']}
+    return value == identity or (isinstance(value, list) and identity in value)
+
+
+def _settled_alone(root: Row, source: Row) -> bool:
+    """Identify the observed standalone revivals of cascaded children."""
+    entry = _SETTLED_ALONE.get(cast('str', root['type']))
+    if entry is None or source['type'] not in entry[1]:
+        return False
+    if root['type'] == 'Note' and root.get('tasks'):
+        return False
+    return _names(root.get(entry[0]), source)
+
+
 def _revived_alone(store: Store, roots: tuple[Row, Row | None], children: list[Row]) -> None:
-    """Taint the unobserved standalone revival while preserving the Version exception."""
+    """Taint unobserved standalone revivals, keeping the observed ones settled."""
     root, source = roots
     if source is None or not source['__retired']:
         return
-    if (
-        root['type'] == 'Version'
-        and source['type'] == 'Shot'
-        and root.get('entity') == {'type': 'Shot', 'id': source['id']}
-    ):
-        return
     reason = f'unsettled revival while {source["type"]} {source["id"]} remains retired'
-    for holder, field in store.linking(*_identity(source)):
-        if holder is root:
-            store.taint(root, reason, source, link=(field, source), active=True)
+    if not _settled_alone(root, source):
+        for holder, field in store.linking(*_identity(source)):
+            if holder is root:
+                store.taint(root, reason, source, link=(field, source), active=True)
     for row in children:
         store.taint(row, reason, source)
 
@@ -146,23 +196,25 @@ def _holder_effect(
                 _touch(store, holder, context)
                 return 'touch'
         return 'hide'
-    if effect == 'keep' and not store.tainted(target):
-        return 'keep'
     for field, _ in edges:
         store.taint(holder, reason, root, link=(field, target))
     return 'taint'
 
 
 def _restore_children(store: Store, parent: Row, context: RequestContext) -> list[Row]:
-    """Revive only still-retired children owned by this cascade marker."""
+    """Revive the children this cascade retired that still link the parent."""
     children: list[Row] = []
     for kind in store.schema.fields:
         for row in store.rows(kind, retired=True):
             if row.get('__cascaded_by') == [parent['type'], parent['id']]:
                 store.check_writable(row)
-                store.revive(*_identity(row))
                 store.remember(row)
                 row.pop('__cascaded_by', None)
+                # 2026-11-10: a child relinked or cleared while retired stays retired.
+                if not any(_names(row.get(field), parent) for field in store.schema.fields[kind]):
+                    continue
+                store.revive(*_identity(row))
+                row.pop('__retired_hidden', None)
                 _touch(store, row, context)
                 children.append(row)
     return children
@@ -175,11 +227,59 @@ def _restore_touches(store: Store, parent: Row, context: RequestContext) -> list
     for link in cast('list[list[FieldValue]]', parent.pop('__retirement_touched', [])):
         holder = store.require(cast('str', link[0]), cast('int', link[1]))
         store.check_writable(holder)
+        # 2026-11-10: a holder retired meanwhile keeps its audit fields.
+        if holder['__retired']:
+            continue
         _touch(store, holder, context)
         holders.append(holder)
     return holders
 
 
+def _revive_marked_notes(store: Store, parent: Row, context: RequestContext) -> list[Row]:
+    """Revive the observed Notes retired after this parent, or taint other shapes.
+
+    A Note linking one Shot and one Asset, retired while the Shot was retired,
+    revives with the Shot; a one-link Note, or one retired after its Task,
+    stays retired (2026-11-10).
+    """
+    revived: list[Row] = []
+    if not store.schema.declares('Note', 'note_links'):
+        return revived
+    for note in store.rows('Note', retired=True):
+        markers = cast('list[list[FieldValue]]', note.get('__retired_hidden', []))
+        fields = {
+            cast('str', marker[0])
+            for marker in markers
+            if marker[1:] == [parent['type'], parent['id']]
+        }
+        if not fields:
+            continue
+        links = cast('list[dict[str, FieldValue]]', note.get('note_links', []))
+        # 2026-11-10: a one-link Note, or one retired after its Task, stays retired.
+        if fields == {'tasks'} or (
+            fields == {'note_links'} and len(links) == 1 and not note.get('tasks')
+        ):
+            continue
+        store.check_writable(note)
+        if (
+            fields == {'note_links'}
+            and parent['type'] == 'Shot'
+            and not note.get('tasks')
+            and sorted(cast('str', link['type']) for link in links) == ['Asset', 'Shot']
+        ):
+            store.revive(*_identity(note))
+            store.remember(note)
+            note.pop('__retired_hidden', None)
+            _touch(store, note, context)
+            revived.append(note)
+        else:
+            reason = (
+                f'unsettled revival of {parent["type"]} {parent["id"]} for a Note retired after it'
+            )
+            store.taint(note, reason, None)
+    return revived
+
+
 def _revive(store: Store, root: Row, context: RequestContext) -> RetirementEffects:
     """Restore marked children and touches, then resolve source-owned taints."""
     store.remember(root)
@@ -191,6 +291,7 @@ def _revive(store: Store, root: Row, context: RequestContext) -> RetirementEffec
     )
     retired_at = cast('datetime | None', root.get('__retired_at'))
     store.revive(*_identity(root), context=context)
+    root.pop('__retired_hidden', None)
     cascaded: list[Row] = []
     touched: list[Row] = []
     queue = [root]
@@ -207,6 +308,7 @@ def _revive(store: Store, root: Row, context: RequestContext) -> RetirementEffec
         cascaded.extend(children)
         queue.extend(children)
         touched.extend(_restore_touches(store, parent, context))
+    cascaded.extend(_revive_marked_notes(store, root, context))
     cleared = _clear_source(store, root)
     _revived_alone(store, (root, source), cascaded)
     return RetirementEffects(
@@ -253,6 +355,7 @@ def _scan(store: Store, root: Row, context: RequestContext) -> RetirementEffects
                     queue.append(holder)
     store.remember(root)
     root['__retirement_touched'] = [[row['type'], row['id']] for row in touched]
+    _mark_hidden_links(store, [root, *cascaded])
     return RetirementEffects(
         changed=True,
         root=root,
@@ -270,14 +373,16 @@ def kept_members(
     entity_id: int,
     fields: Mapping[str, object],
 ) -> dict[str, list[dict[str, FieldValue]]]:
-    """Keep hidden Asset.shots members when an edit names visible members only.
+    """Keep hidden Asset.shots members through an edit of the visible members.
+
+    The edit cannot name a hidden member: the site refuses links to retired
+    records before this runs.
 
     Args:
         store: Site records used to inspect existing shot links.
         entity_type: Entity type being updated.
         entity_id: Existing entity identifier.
-        fields: Incoming field values. Naming any hidden shot explicitly
-            disables automatic preservation.
+        fields: Incoming field values.
 
     Returns:
         A `shots` entry containing preserved stored link dictionaries, or an
@@ -287,23 +392,13 @@ def kept_members(
         ServerFaultError: If the Asset record cannot be resolved.
         MockgunError: If an existing shot link's visibility is unsettled.
     """
-    if entity_type != 'Asset' or 'shots' not in fields:
+    if entity_type != 'Asset' or not isinstance(fields.get('shots'), list):
         return {}
     row = store.require(entity_type, entity_id)
     if row['__retired']:
         return {}
     members = cast('list[dict[str, FieldValue]]', row.get('shots', []))
     kept = [link for link in members if hidden(store, row, 'shots', link)]
-    incoming = fields['shots']
-    if not isinstance(incoming, list):
-        return {}
-    identities = {
-        (cast('dict[str, object]', item).get('type'), cast('dict[str, object]', item).get('id'))
-        for item in cast('list[object]', incoming)
-        if isinstance(item, dict)
-    }
-    if any((link['type'], link['id']) in identities for link in kept):
-        return {}
     return {'shots': kept} if kept else {}