cadrumo.adapters.outbound.google.drive_entries module

Shared Drive owned-entry query, lookup, and identity validation.

Every adapter that resolves an app-owned Drive entry by name runs the same policy: build a parent/name/MIME query literal, accept an entry carrying the appProperties.cadrumo_vault_app=cadrumo ownership marker, backfill that marker onto an unmarked entry a previous run created, and refuse a foreign-owned entry rather than adopt operator content.

That policy previously existed twice inside adapters.outbound.google.calc_sheets_apply (once for folders, once for spreadsheets), differing only in MIME type and in the action and error text. Two copies of one ownership decision can drift independently, and a drift here means adopting or overwriting Drive content the operator owns, so the policy lives here once and is parameterised by the parts that genuinely differ.

The module also owns two invariants the duplicated copies did not enforce:

  • Query-name escaping. A Drive v3 query embeds the name as a single-quoted literal, so an apostrophe in the configured name closes the literal early and the server parses a different (or invalid) predicate. Escaping belongs to whoever builds the query, so it cannot be applied on one call path and forgotten on another.

  • Entry identity. A Drive response is untyped JSON, so an owned entry with an absent or blank id is representable. Callers immediately index entry["id"], which surfaced as a raw KeyError from the provider instead of a typed storage failure. Validating identity before an entry is returned means no caller can index one that has none.

See also

adapters.outbound.google.api.execute_request()

Executor that maps Drive transport failures onto the typed adapters.outbound.storage.errors.OutboundStorageError hierarchy.

class DriveEntryPreconditionCondition(*values)[source]

Bases: StrEnum

Closed terminal conditions owned by the Drive entry adapter.

IDENTIFIER_VALID
LIST_RESPONSE_VALID
ENTRY_MAPPING_VALID
OWNERSHIP_METADATA_VALID
OWNERSHIP_ALIGNED
escape_drive_query_name(name)[source]

Return name escaped for use inside a single-quoted Drive query literal.

Drive v3 query literals escape a backslash and a single quote with a preceding backslash. The backslash is replaced first so an escape introduced for an apostrophe is not itself re-escaped.

Parameters:

name (str) – Raw entry name, which may contain apostrophes or backslashes.

Return type:

str

Returns:

The escaped name, safe to interpolate between single quotes.

build_owned_entry_query(*, parent_id, name, mime_type)[source]

Return the Drive query selecting a non-trashed child of parent_id.

Parameters:

  • parent_id (str) – Drive folder ID the entry must be parented by.

  • name (str) – Entry name, escaped through escape_drive_query_name().

  • mime_type (str) – Drive MIME type constraining the entry kind.

Return type:

str

Returns:

A Drive v3 q predicate string.

require_drive_entry_id(entry, *, name, parent_id)[source]

Return the entry’s non-empty Drive ID, or refuse with a typed error.

Parameters:

  • entry (File) – Drive entry mapping as returned by files().list().

  • name (str) – Entry name, for the refusal context.

  • parent_id (str) – Parent folder ID, for the refusal context.

Return type:

str

Returns:

The validated Drive object ID.

Raises:

OutboundStorageValidationError – When the entry carries no id, a non-string id, or a blank one. Without this the caller’s entry["id"] raised a raw KeyError out of the provider boundary.

find_owned_drive_entry(drive, *, parent_id, name, mime_type, list_action, backfill_action, conflict_message)[source]

Return the app-owned Drive entry of name under parent_id, if any.

Applies the one ownership policy shared by every Drive lookup: an entry already carrying the ownership marker is adopted; an entry carrying no appProperties at all is a pre-marker artefact of this app and is backfilled then adopted; an entry carrying foreign properties is refused. Every returned entry has been checked to carry a usable ID.

Parameters:

  • drive (DriveResource) – Drive v3 service resource.

  • parent_id (str) – Folder ID to search within.

  • name (str) – Entry name to match.

  • mime_type (str) – Drive MIME type constraining the entry kind.

  • list_action (str) – Action label for the list call’s error context.

  • backfill_action (str) – Action label for the marker-backfill call.

  • conflict_message (str) – Message raised when a foreign-owned entry is found.

Return type:

File | None

Returns:

The owned entry mapping, or None when no such entry exists.

Raises: