Skip to content

yggdrasil.enums.mode

mode

Save mode enum — write-time disposition for any sink.

Covers the standard Spark / Delta / write-API set (OVERWRITE / APPEND / IGNORE / UPSERT / TRUNCATE / ERROR_IF_EXISTS) plus an AUTO sentinel that lets the implementation pick.

Parsing accepts three input shapes:

  1. A :class:Mode — returned as-is (idempotent).
  2. A human-readable alias — "overwrite", "replace", "append", "add", … (full list below).
  3. A POSIX/stdlib open() mode string — "rb", "wb", "ab", "xb", plus "+" / "t" / "b" variants. Parsed structurally rather than enumerated, so "rb+" and "r+b" and "+rb" all resolve correctly.

Mapping for OS modes:

  • r / rb / rt (no +) → :data:AUTO (read-only — there's no write to dispose of).
  • r+ / rb+ / rt+ → :data:AUTO (in-place edit — neither truncate nor append nor exclusive).
  • w / wb / wt / w+ / … → :data:OVERWRITE (POSIX O_TRUNC).
  • a / ab / at / a+ / … → :data:APPEND (POSIX O_APPEND).
  • x / xb / xt / x+ / … → :data:ERROR_IF_EXISTS (POSIX O_EXCL).

Note: there's no OS-mode counterpart to :data:UPSERT or :data:TRUNCATE (Spark-style "wipe and keep structure") — those are SQL/dataset-level concepts and have no open(2) analog.

Mode

Bases: IntEnum

is_read_only property 

is_read_only: bool

True for read-only modes — i.e. no write disposition.

allows_write property 

allows_write: bool

True when the mode admits any write disposition.

readable property 

readable: bool

True when the mode admits reads.

Every :class:Mode canonically resolves to a + POSIX form (rb, rb+, wb+, ab+, xb+) — all of those admit reads. Only the strict :data:READ_ONLY rb and :data:IGNORE (which is no-op) deny writes; nothing here denies reads.

writable property 

writable: bool

True when the mode admits writes — alias of :attr:allows_write.

appendable property 

appendable: bool

True when writes append at EOF rather than at the cursor.

Only :data:APPEND carries POSIX O_APPEND semantics; every other write mode positions writes at the explicit cursor.

os_mode property 

os_mode: str

Stdlib :func:open mode string for this :class:Mode.

  • :attr:READ_ONLY → "rb"
  • :attr:OVERWRITE / :attr:TRUNCATE → "wb+"
  • :attr:APPEND → "ab+"
  • :attr:ERROR_IF_EXISTS → "xb+"
  • everything else (AUTO, IGNORE, UPSERT, MERGE) → "rb+" (in-place edit; the disposition is enforced higher up).

from_ classmethod 

from_(value: Optional[ModeLike], default: Optional[Mode] = None) -> Mode

Normalize value into a :class:Mode.

Accepts:

  • :class:Mode (returned as-is, idempotent).
  • Aliases like "overwrite", "OVERWRITE", "error-if-exists", "replace", "add" — see :data:STR_MAPPING.
  • POSIX-style mode strings — "rb", "wb", "ab+", "x", "r+b" — parsed structurally; any combination of one primary character (r/w/a/x) plus optional b/t/+ flags is accepted.
  • None → returns default if supplied, else :data:Mode.AUTO.

Falls back to :class:ValueError for unrecognized strings. Numeric / non-string non-Mode inputs raise :class:TypeError — the input grammar is "string or enum," not "anything stringifiable."