Source code for pyvergeos.resources.base

"""Base resource manager providing CRUD operations."""

from __future__ import annotations

import builtins
import re
from collections.abc import Callable, Iterator, Mapping, Sequence
from typing import TYPE_CHECKING, Any, Generic, TypeVar, overload

from pyvergeos.exceptions import FieldNotProjectedError, NotFoundError
from pyvergeos.filters import combine_filters, quote_value

if TYPE_CHECKING:
    from pyvergeos.client import VergeClient

T = TypeVar("T", bound="ResourceObject")
PT = TypeVar("PT")
SelfT = TypeVar("SelfT", bound="ResourceObject")


[docs] def serialize_list(value: str | builtins.list[str] | None, sep: str = ",") -> str | None: """Serialize a user-supplied multi-value parameter for the API. Accepts either the API's native delimiter-joined string or a sequence of values. A bare string passes through unchanged: joining it would iterate character by character (``",".join("$key,name")`` -> ``'$,k,e,y,,,n,a,m,e'``), which the API accepts and silently honours, corrupting the request (issue #101). An empty sequence serializes to ``""``, which callers use to clear a multi-value field, so it is deliberately not treated as "unset". Args: value: A string already in wire format, a sequence of values, or None. sep: Delimiter the API expects (``","`` or ``"\\n"``). Returns: The wire-format string, or None if ``value`` is None. Raises: TypeError: If ``value`` is a mapping, an unordered collection, or contains a non-string. Each of these would otherwise be serialized into a plausible-looking but wrong request rather than failing. """ if value is None: return None if isinstance(value, str): return value if isinstance(value, Mapping): raise TypeError( f"expected a string or a sequence of strings, not {type(value).__name__}; " "iterating a mapping yields its keys, which would be sent as the value" ) if isinstance(value, (set, frozenset)): # Order is part of the value for several of these parameters - the # first entry of dnslist is the primary DNS server - and a set has # no defined order, so the wire value would vary run to run. raise TypeError( f"expected an ordered sequence, not {type(value).__name__}; " "pass a list so the order sent to the API is defined" ) items = list(value) for item in items: if not isinstance(item, str): raise TypeError(f"values must be strings, got {type(item).__name__}: {item!r}") return sep.join(items)
[docs] def normalize_fields(fields: str | builtins.list[str] | None) -> str | None: """Serialize a ``fields`` projection parameter. Accepts a sequence of field names or the API's comma-separated string. Empty values - including strings that contain no field names, such as ``","`` or ``" "`` - mean "no projection requested" (issue #101). Passing those through would ask the API for a projection with no columns, which answers with a single ``{"$count": N}`` row instead of the requested resources: the silent-empty result #101 was filed for. Field names are cleaned exactly as :func:`split_fields` cleans them, so the string and sequence forms stay interchangeable. """ names = split_fields(fields) if not names: return None return ",".join(names)
[docs] def split_fields(fields: str | builtins.list[str] | None) -> builtins.list[str]: """Split a ``fields`` projection into individual field names. The list counterpart of :func:`normalize_fields`, for the callers that must *augment* the projection (adding ``settings``, ``client_secret`` and similar) before serializing it. Those callers cannot use ``normalize_fields()``, and ``list("$key,name")`` would split a caller-supplied string into single characters - the same silent corruption as ``",".join()`` (issue #101). Args: fields: A comma-separated string, a sequence of names, or None. Returns: A list of field names; empty when no projection was requested. Raises: TypeError: If ``fields`` is a mapping, or if any element is not a string. Iterating a mapping yields its keys, and coercing elements with ``str()`` would turn ``[1, 2]`` into the projection ``"1,2"`` - a plausible-looking but wrong request. Both must fail loudly rather than silently corrupt the query. """ if not fields: return [] if isinstance(fields, str): return [name.strip() for name in fields.split(",") if name.strip()] if isinstance(fields, Mapping): raise TypeError( f"fields must be a string or a sequence of field names, not {type(fields).__name__}" ) names = [] for name in fields: if not isinstance(name, str): raise TypeError(f"field names must be strings, got {type(name).__name__}: {name!r}") stripped = name.strip() # Empty entries are dropped here exactly as they are for the string # form, so ["$key", ""] and "$key," produce the same projection. if stripped: names.append(stripped) return names
PROJECTION_ALL = "all" _ALIAS_RE = re.compile(r"\s+as\s+(\S+)\s*$")
[docs] def projection_alias(field: str) -> str: """Return the name a projection entry lands under in the response row. ``"machine#status#running as running"`` lands under ``"running"``; a plain column lands under itself. """ match = _ALIAS_RE.search(field) return match.group(1) if match else field.strip()
[docs] def is_computed_projection(field: str) -> bool: """Is this projection entry something the server computes, not a column? ``fields=all`` returns columns. A traversal (``machine#status#running``), an aggregate (``count(members)``) or a sub-selection (``stats[reads,writes]``) is derived, so it is never part of ``all`` and has to be asked for by name -- ``all`` answers a sub-selected column with the bare foreign key instead, which is why ``storage_tier.read_ops`` raised ``AttributeError`` under ``all``. Detected structurally rather than from a list of known names, so a new kind of computed entry is covered the day it is written. """ stripped = field.strip() return ( "#" in stripped # traversal: machine#status#running or "(" in stripped # aggregate: count(members) or "[" in stripped # sub-selection: stats[reads,writes,rops] or projection_alias(stripped) != stripped # anything explicitly aliased )
[docs] def expand_projection( fields: str | builtins.list[str] | None, defaults: builtins.list[str] | None, ) -> str | builtins.list[str] | None: """Make ``all`` an actual superset of a manager's default projection. ``all`` is resolved server-side to the resource's *own columns*. Anything a manager has the server compute rather than select is therefore absent from it -- aliased traversals (``machine#status#running as running``) and aggregates (``count(members) as member_count``) alike -- so a request for ``all`` silently comes back without ``running``, ``status`` and friends, and on ``nodes`` without even ``$key``. A caller who asked for *more* data got a *wrong* answer (issue #117). When ``all`` appears in the projection, the manager's computed entries and ``$key`` are appended to it, which the API accepts and which measurably restores the missing values. Entries the caller already named are left alone, so an explicit override still wins. Independently of ``all``, a caller who names one of the manager's alias names gets the manager's entry for it. ``fields=["$key","name","running"]`` would otherwise select the ``vms`` table's own ``running`` column, which is null on every row, and the accessor would answer ``False`` for a running VM - the same defect reached without ``all``. Narrowing itself is still honoured: the projection stays exactly as wide as asked for. Args: fields: The caller's projection. defaults: The manager's default projection, or None. Returns: The projection to send, expanded only when ``all`` was requested. """ if not fields: return fields names = split_fields(fields) computed_by_alias = { projection_alias(field): field for field in defaults or () if is_computed_projection(field) } # A caller who names an alias means the manager's field of that name, not # whatever bare column happens to share it. Asking vms for "running" # returns a real column that is null on every row, and vnets drops the # name entirely - either way the accessor answered False for a running # resource, which is issue #117 reached through a narrowed projection # rather than through 'all'. Send what the manager means by the name. resolved: builtins.list[str] = [] translated = False for name in names: entry = computed_by_alias.get(name) if entry is not None and entry != name: resolved.append(entry) translated = True else: resolved.append(name) names = resolved if PROJECTION_ALL not in names: return names if translated else fields seen = {projection_alias(name) for name in names} extra: builtins.list[str] = [] # $key is the resource's identity and ResourceObject.key depends on it, # yet several endpoints leave it out of 'all' - nodes and storage_tiers # among them, where .key then raised "Resource has no $key" for a plainly # persisted row. Ask for it unconditionally: endpoints that already carry # it tolerate the duplicate, and settings, which is keyed on 'key', simply # answers with both. if "$key" not in seen: seen.add("$key") extra.append("$key") for field in defaults or (): # 'all' already covers plain own-columns, so re-listing them only # bloats the URL. It covers nothing the server has to compute, and # it drops $key on at least the nodes endpoint. if not is_computed_projection(field): continue alias = projection_alias(field) if alias in seen: continue seen.add(alias) extra.append(field) return names + extra if extra else fields
[docs] def ensure_projection_field( fields: str | builtins.list[str] | None, field: str, *, defaults: builtins.list[str] | None = None, ) -> str | builtins.list[str]: """Return a projection that includes ``field``. ``fields=None`` selects ``defaults``. When ``field`` is already present, as a column or an alias, the original value is returned unchanged so a default projection is not rebuilt. Otherwise ``field`` is appended. A narrowed ``get(key, fields=...)`` then still returns the column a scope check has to read. """ selected = defaults if fields is None else fields names = split_fields(selected) if selected is not None and any(projection_alias(name) == field for name in names): return selected return [*names, field]
[docs] def scope_values_equal(actual: Any, expected: Any) -> bool: """Return whether a row's parent column equals the manager's parent value. ``bool`` is an ``int`` subclass and is never a key. An int matches a numeric string. Other strings match only exactly, so ``tenants/5`` is not an int and a volume's hex key is not coerced. """ if isinstance(actual, bool) or isinstance(expected, bool): return False if isinstance(actual, int) and isinstance(expected, int): return actual == expected if isinstance(actual, str) and isinstance(expected, str): return actual == expected if isinstance(actual, str) and isinstance(expected, int): try: return int(actual) == expected except ValueError: return False if isinstance(actual, int) and isinstance(expected, str): try: return actual == int(expected) except ValueError: return False return False
[docs] def machine_key_matches(machine: Any, machine_key: int) -> bool: """Return whether a row's ``machine`` value is ``machine_key``. ``bool`` is an ``int`` subclass and is never a machine key. A numeric string is accepted. """ return scope_values_equal(machine, machine_key)
#: Sentinel for "nothing supplied here", distinct from a legitimate ``None``. _NO_VALUE: Any = object()
[docs] def display_map(mapping: Mapping[Any, Any], default: Any = _NO_VALUE) -> Callable[[Any], Any]: """Build a ``transform`` that renders a raw value through ``mapping``. Args: mapping: Raw value -> display value. default: Returned for an unmapped value. Omit to pass the raw value through unchanged, which is what the hand-written accessors did. Returns: A callable suitable for ``Projected(transform=...)``. """ def _render(value: Any) -> Any: if default is _NO_VALUE: return mapping.get(value, value) return mapping.get(value, default) return _render
[docs] def split_reference(value: Any) -> tuple[str | None, str | int | None]: """Split a VergeOS reference into ``(table, key)``. Several columns hold a *polymorphic* reference -- a ``"table/key"`` string such as ``"vms/39"`` naming both the table and the row, which is how ``tasks.create(owner=..., table=...)`` composes them. Others hold a plain key. A key is not always numeric either: recipes are keyed by name, so ``owner`` can be ``"vm_recipes/yottabyte-services-nas-winbind"``. Coercing any of those with ``int()`` raises ValueError, which is issue #126. This reports what is actually there instead: >>> split_reference("vms/39") ('vms', 39) >>> split_reference("vm_recipes/winbind-v1") ('vm_recipes', 'winbind-v1') >>> split_reference("deprecated") (None, 'deprecated') >>> split_reference("") (None, None) Args: value: The raw column value. Returns: ``(table, key)``. ``table`` is None when the value carries no table part; ``key`` is an int when it looks like one, and None when there is no value at all. """ if value is None: return (None, None) if isinstance(value, bool): return (None, int(value)) if isinstance(value, int): return (None, value) text = str(value).strip() if not text: return (None, None) table: str | None = None if "/" in text: table, _, text = text.partition("/") table = table or None if not text: return (table, None) try: return (table, int(text)) except ValueError: return (table, text)
[docs] def reference_key(value: Any) -> str | int | None: """The key part of a reference: 39 from ``"vms/39"``. See split_reference.""" return split_reference(value)[1]
[docs] def reference_table(value: Any) -> str | None: """The table part of a reference: ``"vms"`` from ``"vms/39"``, else None.""" return split_reference(value)[0]
[docs] def epoch_utc(value: Any) -> Any: """Render a Unix timestamp as a timezone-aware UTC datetime. A ``transform`` for the several accessors that turn an epoch column into a ``datetime``. Pair it with ``falsy=None, null=None`` so that a missing or zero timestamp stays None rather than becoming 1970. """ from datetime import datetime, timezone return datetime.fromtimestamp(int(value), tz=timezone.utc)
[docs] class Projected(Generic[PT]): """Declare an accessor and the projection entry behind it, together. Issue #117 was not that accessors guessed. It was that the fact *"``is_running`` comes from ``machine#status#running``"* was written down twice -- once in the manager's field list, once in the accessor's ``self.get("running", False)`` -- with nothing tying the two. Each fix was another sweep for copies of a hand-written pattern: ``all`` not carrying the traversal, a caller naming the alias and getting a bare column, an accessor with a two-argument read, then one with a one-argument read. Stating it once removes the class of defect rather than its instances:: class Network(ResourceObject): is_running = Projected("machine#status#running as running", bool, default=False) The manager then derives its projection from the declarations instead of restating them, so the two cannot drift, and adding an accessor adds its field to every query that reads it. The read is performed in a fixed order, which is what lets the various hand-written bodies this replaces be reproduced exactly: 1. ``require_projected(alias, default)``, or ``require_projected_any`` when several aliases are given. 2. If ``fallback`` is set and the value is falsy, re-read it from that plain field -- the ``x or self.get("y", 0)`` idiom. 3. If ``falsy`` is set and the value is falsy, substitute it -- the ``x or 0`` idiom. 4. If the value is None and ``null`` was given, return ``null``. 5. Apply ``coerce``, then ``transform``. Note that ``coerce`` is applied to a null value unless ``null`` is given. That is deliberate: it is what the accessors being replaced did, and changing it here would alter behaviour silently rather than visibly. Args: entry: The projection entry -- ``"machine#status#running as running"`` -- or a plain column name. A sequence of entries reads whichever was projected, for fields spelled differently by different endpoints. coerce: Applied to the value, typically ``str``, ``int`` or ``bool``. default: Returned when the field was requested but the server omitted it, as a traversal through a null polymorphic reference is. null: Returned uncoerced when the value is None. Omit to pass None to ``coerce``, which is what the accessors replaced here did. falsy: Substituted for any falsy value, reproducing ``x or 0``. fallback: Plain field read via ``get()`` when the value is falsy, for rows that carry the same fact under an embedded name. fallback_default: Default for that fallback read. transform: Applied last, for display maps and unit conversions. doc: Docstring for the generated attribute. """
[docs] def __init__( self, entry: str | Sequence[str], coerce: Callable[[Any], Any] | None = None, *, default: Any = None, null: Any = _NO_VALUE, falsy: Any = _NO_VALUE, fallback: str | None = None, fallback_default: Any = None, transform: Callable[[Any], Any] | None = None, doc: str | None = None, ) -> None: entries = [entry] if isinstance(entry, str) else list(entry) if not entries: raise ValueError("Projected requires at least one projection entry") self.entries: builtins.list[str] = entries self.aliases: builtins.list[str] = [projection_alias(e) for e in entries] self.coerce = coerce self.default = default self.null = null self.falsy = falsy self.fallback = fallback self.fallback_default = fallback_default self.transform = transform self.name = self.aliases[0] self.__doc__ = doc
def __set_name__(self, owner: type, name: str) -> None: self.name = name @overload def __get__(self, obj: None, objtype: type | None = None) -> Projected[PT]: ... @overload def __get__(self, obj: Any, objtype: type | None = None) -> PT: ... def __get__(self, obj: Any, objtype: type | None = None) -> Any: if obj is None: return self if len(self.aliases) == 1: value = obj.require_projected(self.aliases[0], self.default) else: value = obj.require_projected_any(*self.aliases, default=self.default) if self.fallback is not None and not value: value = obj.get(self.fallback, self.fallback_default) if self.falsy is not _NO_VALUE and not value: value = self.falsy if value is None and self.null is not _NO_VALUE: return self.null if self.coerce is not None: value = self.coerce(value) if self.transform is not None: value = self.transform(value) return value
[docs] def __set__(self, obj: Any, value: Any) -> None: """Write through to the backing mapping. Defined so this is a *data* descriptor and therefore always wins over the instance dictionary, matching the ``property`` it replaces. The value lands in the mapping, which is where ``ResourceObject``'s own ``__setattr__`` would have put it. """ obj[self.name] = value
[docs] class ResourceObject(dict[str, Any]): """Dict subclass with attribute access and resource methods. Provides a dict-like object that also supports attribute access and common resource operations like refresh, save, and delete. Attribute assignment, item assignment, ``update()`` and ``setdefault()`` all mark the field as modified; ``save()`` sends every modified field along with any keyword arguments. """
[docs] def __init__(self, data: dict[str, Any], manager: ResourceManager[Any]) -> None: super().__init__(data) self._manager = manager self._dirty: set[str] = set() # What the request that produced this row asked the server for. # None when unknown, in which case require_projected() stays strict. # Type-checked rather than taken on trust, so a hand-built or mocked # manager degrades to "unknown" instead of to a truthy non-set. requested = getattr(manager, "_requested_aliases", None) self._requested: frozenset[str] | None = ( requested if isinstance(requested, frozenset) else None )
def __setitem__(self, key: str, value: Any) -> None: self.__dict__.setdefault("_dirty", set()).add(key) super().__setitem__(key, value)
[docs] def update(self, *args: Any, **kwargs: Any) -> None: """Merge values in, marking each one modified (issue #110). ``dict.update()`` writes straight to the backing mapping, so before this override a batch update marked nothing dirty and the following ``save()`` sent an empty ``PUT`` and reported success while persisting nothing. ``refresh()`` deliberately calls ``dict.update(self, ...)`` to load server state without dirtying it, which bypasses this override. """ for key, value in dict(*args, **kwargs).items(): self[key] = value
[docs] def setdefault(self, key: str, default: Any = None) -> Any: """Insert ``default`` if absent, marking it modified (issue #110).""" if key not in self: self[key] = default return self[key]
def __getattr__(self, name: str) -> Any: try: return self[name] except KeyError: raise AttributeError(f"'{type(self).__name__}' has no attribute '{name}'") from None def __setattr__(self, name: str, value: Any) -> None: if name.startswith("_"): super().__setattr__(name, value) else: self[name] = value
[docs] @classmethod def projected_entries(cls) -> builtins.list[str]: """Projection entries declared by this model's ``Projected`` fields. Lets a manager build its default projection from the declarations rather than restating them, so an accessor and the field list that feeds it cannot disagree (issue #125). Base classes first, in declaration order, de-duplicated. """ seen: dict[str, None] = {} for klass in reversed(cls.__mro__): for value in vars(klass).values(): if isinstance(value, Projected): for entry in value.entries: seen.setdefault(entry, None) return list(seen)
[docs] def require_projected(self, name: str, default: Any = None) -> Any: """Return field ``name``, refusing to guess when it was not projected. Accessors built on this cannot conflate "the field says false" with "the field was never fetched". The test is what the request asked for, not merely whether the key came back. Most computed fields do come back null when there is nothing to report, but a traversal through a polymorphic reference is omitted outright when that reference is null, so absence alone would raise on a correctly projected row. Args: name: Field to read. default: Returned when the field was requested but the server omitted it, which a null polymorphic reference causes. This is the same value the ``self.get(name, default)`` call this replaced would have produced, so behaviour is unchanged for every case except the one being fixed. Returns: The stored value, which may be None. Raises: FieldNotProjectedError: If the field was never requested. """ try: return self[name] except KeyError: pass # Absence is not on its own proof that the field was not requested. # A traversal through a *polymorphic* reference - ``creator#$display`` # on tasks, where ``creator`` holds a ``table/key`` string - is # omitted entirely when that reference is null, rather than coming # back null. Measured on a live system: 8 such fields across 6 # managers. So the row is only "not projected" if the request did not # ask for it; if it did, ``default`` is the answer, exactly as the # ``self.get(name, default)`` this replaced would have given. if self._requested is not None and name in self._requested: return default raise FieldNotProjectedError(name, type(self).__name__) from None
[docs] def require_projected_any(self, *names: str, default: Any = None) -> Any: """Read the first of ``names`` that was projected. For accessors whose field is spelled differently depending on which projection produced the row -- ``volume_name`` or ``volume_display``, ``status`` or ``rstatus``. Requiring the first name alone would raise for a row that legitimately carries the second. Preserves the ``a or b`` chain these replaced: the first *truthy* present value wins, falling back to the first present value, so a genuine ``0`` or ``""`` is still reported. Args: *names: Candidate field names, in preference order. default: Returned when a name was requested but the server omitted it. Returns: The stored value, which may be None. Raises: FieldNotProjectedError: If none of ``names`` was requested. """ present = [name for name in names if name in self] for name in present: value = self[name] if value: return value if present: return self[present[0]] if self._requested is not None and any(name in self._requested for name in names): return default raise FieldNotProjectedError(names[0], type(self).__name__)
@property def key(self) -> int: """Resource primary key ($key). Raises: ValueError: If resource has no $key (not yet persisted). """ k = self.get("$key") if k is None: raise ValueError("Resource has no $key - may not be persisted") return int(k)
[docs] def refresh(self: SelfT) -> SelfT: """Refresh this object in place with fresh data from the API. The object this is called on is updated, so wait loops like ``while not vm.running: vm.refresh()`` observe new state. Unsaved local modifications are discarded. Returns ``self``, so ``vm = vm.refresh()`` also remains correct. Returns: This object, updated with the latest data. """ if self.key is None: raise ValueError("Cannot refresh resource without $key") result = self._manager.get(self.key) # Replace the backing mapping without marking fields dirty # (dict methods bypass the tracking __setitem__). dict.clear(self) dict.update(self, result) # Adopt the refetch's projection too. The rows are now whatever # get() asked for, so keeping the old record would have this object # disagree with an identical freshly-fetched one: a task refreshed # from a narrow projection carried the full default row yet still # raised for creator_display, which the server omits (issue #117). self._requested = getattr(result, "_requested", None) self.__dict__.setdefault("_dirty", set()).clear() return self
[docs] def save(self, **kwargs: Any) -> ResourceObject: """Save changes to resource. Sends fields modified via attribute/item assignment since the object was loaded (or last saved), merged with ``kwargs``. Keyword arguments take precedence over locally modified fields. Args: **kwargs: Additional fields to update. Returns: Updated resource object. Example: >>> vm.cpu_cores = 4 >>> vm.ram = 2048 >>> vm = vm.save() # PUT {"cpu_cores": 4, "ram": 2048} """ result = self._save(**kwargs) return result # type: ignore[no-any-return]
def _save(self, **kwargs: Any) -> Any: """Persist locally modified fields plus ``kwargs``. Subclasses that override ``save()`` must delegate here. Modified fields are first run through the manager's ``_prepare_write_fields()`` alias translation, then when the manager has a typed ``update()`` they are sent as a raw PUT and only ``kwargs`` go through ``update()``. Tracking is reset only after the request succeeds. """ if self.key is None: raise ValueError("Cannot save resource without $key") manager = self._manager dirty = self.__dict__.get("_dirty", set()) changes = {k: self[k] for k in dirty if k in self and not k.startswith("$")} if changes: # Apply the manager's write-alias translation so attribute # assignment and typed update() behave identically (issue #97). changes = manager._prepare_write_fields(changes) if not changes and not kwargs: # Nothing to write. An empty PUT is still a write - subject to # permissions, audit logging and any update side effects - for a # request the caller did not ask for (issue #111). Return current # state, which is what the write path would have returned. dirty.clear() return manager.get(self.key) if changes and type(manager).update is not ResourceManager.update: ResourceManager.update(manager, self.key, **changes) result = manager.update(self.key, **kwargs) if kwargs else manager.get(self.key) else: result = manager.update(self.key, **{**changes, **kwargs}) dirty.clear() return result
[docs] def delete(self) -> None: """Delete this resource.""" self._manager.delete(self.key)
def __repr__(self) -> str: key = self.get("$key", "?") name = self.get("name", "") return f"<{type(self).__name__} key={key} name={name!r}>"
[docs] class ResourceManager(Generic[T]): """Base class for resource managers. Provides standard CRUD operations and filtering for API resources. Subclasses should set `_endpoint` and optionally override `_to_model`. """ _endpoint: str = "" #: The manager's default projection, when it has one. Declared here so #: that list()/get() can make a caller's ``all`` a true superset of it #: (issue #117). Subclasses that keep their defaults in a module constant #: should point this at that constant. _default_fields: builtins.list[str] | None = None #: Alias names sent to the server by the most recent ``_projection()`` #: call. Captured by each ``ResourceObject`` at construction, which #: happens during the same request, so it is never read stale. _requested_aliases: frozenset[str] | None = None
[docs] def __init__(self, client: VergeClient) -> None: self._client = client
def _projection( self, fields: str | builtins.list[str] | None, *, defaults: builtins.list[str] | None = None, ) -> str | None: """Serialize a caller-supplied ``fields`` argument for the wire. The single place a projection becomes a request parameter, so that ``all`` is expanded into a true superset of this manager's default projection (issue #117) no matter which method built the request. Managers that assemble ``params`` themselves must use this rather than calling ``normalize_fields()`` directly; a tripwire enforces it. ``defaults`` is the projection that bare names and ``all`` expand against. Omit it to use this manager's ``_default_fields``. A query for a different endpoint must pass that endpoint's own columns (often ``Model.projected_entries()``). Expanding ``capacity`` against ``ClusterTier`` rewrites it to ``status#capacity``, and on ``cluster_tier_status`` ``status`` is a string, so the alias comes back as ``'online'`` (issue #149). Pass ``[]`` when the names are already the columns to send and must not be rewritten. Args: fields: The caller's projection. defaults: Projection to expand against. None uses this manager's defaults. Returns: The wire-format ``fields`` value, or None. """ basis = self._default_fields if defaults is None else defaults resolved = expand_projection(fields, basis) # Record the names this request asks the server for, so that objects # built from the response can tell "you never asked for this" from # "you asked, and the server had nothing to say" (issue #117). self._requested_aliases = ( frozenset(projection_alias(name) for name in split_fields(resolved)) if resolved else None ) return normalize_fields(resolved)
[docs] def list( self, filter: str | None = None, fields: str | builtins.list[str] | None = None, limit: int | None = None, offset: int | None = None, **filter_kwargs: Any, ) -> builtins.list[T]: """List resources with optional filtering. Args: filter: OData filter string. fields: Fields to return - a list of names or the API's comma-separated string. limit: Maximum number of results. offset: Skip this many results. **filter_kwargs: Shorthand filter arguments. Merged with ``filter`` when both are supplied. Returns: List of resource objects. Raises: ValueError: If filter kwargs are supplied but every value is None, which would silently match every row (issue #96). """ params: dict[str, Any] = {} # Merge explicit filter with shorthand kwargs (issue #96: kwargs were # silently dropped whenever a filter string was already present). combined_filter = combine_filters(filter, filter_kwargs) if combined_filter: params["filter"] = combined_filter # Field selection. 'all' is expanded to include the manager's # computed entries, which the API would otherwise omit (issue #117). if fields: params["fields"] = self._projection(fields) # Pagination if limit is not None: params["limit"] = limit if offset is not None: params["offset"] = offset response = self._client._request("GET", self._endpoint, params=params) if response is None: return [] if not isinstance(response, list): return [self._to_model(response)] return [self._to_model(item) for item in response]
[docs] def get( self, key: int | None = None, *, name: str | None = None, fields: str | builtins.list[str] | None = None, ) -> T: """Get a single resource by key or name. When looking up by ``name`` this returns the **first** match (``limit=1``). VergeOS does not enforce unique names on every table, so if two resources share a name only one is returned and the other is not reported -- the duplicate is invisible to this call, not an error. When names may not be unique, look up by ``key``, or use ``list(filter="name eq ...")`` and decide how to handle more than one row yourself. Args: key: Resource $key (ID). name: Resource name (searched if ``key`` is not provided). Returns the first match if the name is not unique; see above. fields: Fields to return - a list of names or the API's comma-separated string. Returns: Resource object (the first match when searching by ``name``). Raises: NotFoundError: If resource not found. ValueError: If neither key nor name provided. """ if key is not None: # Direct fetch by key. A scoped manager asks for its parent # column, then refuses another parent's row (#168, #188, #191). selected = self._key_get_fields(fields) params: dict[str, Any] = {} if selected: params["fields"] = self._projection(selected) response = self._client._request("GET", f"{self._endpoint}/{key}", params=params) if response is None: raise NotFoundError(f"{self._endpoint}/{key} not found") if not isinstance(response, dict): raise NotFoundError(f"{self._endpoint}/{key} returned invalid response") self._assert_row_in_scope(key, response) return self._to_model(response) if name is not None: # Search by name results = self.list(filter=f"name eq {quote_value(name)}", fields=fields, limit=1) if not results: raise NotFoundError(f"{self._endpoint} with name '{name}' not found") return results[0] raise ValueError("Either key or name must be provided")
def _to_model_unprojected(self, data: dict[str, Any]) -> T: """Build a model from a response that carried no projection. Write responses are not query results. ``POST`` answers with a receipt -- ``$key``, ``$row``, ``dbpath``, ``location``, ``response`` -- and ``PUT`` answers with ``{}``. Nothing in either was requested by a projection, so the object must not inherit the alias set left behind by whatever this manager fetched last: otherwise ``networks.list()`` followed by ``networks.update(...)`` would make the updated object answer ``is_running`` as ``False`` from a row that never contained it, which is issue #117 arriving by a side door. Clearing the record first makes such an object report the field as unfetched, the same answer it gives with no prior call, so the result does not depend on unrelated history. """ self._requested_aliases = None return self._to_model(data)
[docs] def create(self, **kwargs: Any) -> T: """Create a new resource. Args: **kwargs: Resource attributes. Returns: Created resource object. """ response = self._client._request("POST", self._endpoint, json_data=kwargs) if response is None: raise ValueError("No response from create operation") if not isinstance(response, dict): raise ValueError("Create operation returned invalid response") return self._to_model_unprojected(response)
def _scope_bindings(self) -> builtins.list[tuple[str, Any]]: """Parent columns this instance is bound to, as ``(column, value)``. Empty means the instance is not parent-scoped and may address any key. A scoped manager -- one a parent hands out, such as ``network.rules`` or ``tenant.network_blocks`` -- lists the column that points at that parent and the value it must equal. :meth:`get`, :meth:`update` and :meth:`delete` then refuse a row whose column does not match, before any write (#188). """ return [] def _scope_resource(self) -> str: """Noun used in scope errors, for example ``Rule``.""" return "Resource" def _key_get_fields( self, fields: str | builtins.list[str] | None, ) -> str | builtins.list[str] | None: """Projection for a by-key ``get``. Unscoped ``fields=None`` stays unprojected. A scoped manager with ``fields=None`` projects its default fields plus each scope column. On VergeOS 26.1.8 an unprojected read returns a short default set that often omits the parent column, and the scope check would then refuse the caller's own row (#191). """ if fields is None and self._scope_bindings(): fields = list(self._default_fields) if self._default_fields else ["$key"] return self._with_scope_fields(fields) def _with_scope_fields( self, fields: str | builtins.list[str] | None, ) -> str | builtins.list[str] | None: """Add each scope column to a narrowed projection. ``fields=None`` is left alone here. :meth:`get` does not pass None for a scoped manager; it supplies the default fields first (#191). A caller who named fields must still receive the column the scope check reads. """ bindings = self._scope_bindings() if not bindings or fields is None: return fields selected: str | builtins.list[str] | None = fields for column, _expected in bindings: selected = ensure_projection_field(selected, column, defaults=self._default_fields) return selected def _row_in_scope(self, row: dict[str, Any]) -> bool: """Return whether ``row`` belongs to this manager's parent. The default compares each :meth:`_scope_bindings` column to its value. Override when membership is not a single column on the row (a DNS zone's network is the network of its view). """ bindings = self._scope_bindings() if not bindings: return True return all(scope_values_equal(row.get(column), expected) for column, expected in bindings) def _scope_error(self, key: int | str, row: dict[str, Any]) -> str: """Error text when ``row`` is outside this manager's parent.""" for column, expected in self._scope_bindings(): if not scope_values_equal(row.get(column), expected): resource = self._scope_resource() return f"{resource} {key} does not belong to {column} {expected}" return f"{self._scope_resource()} {key} does not belong to this parent" def _assert_row_in_scope(self, key: int | str, row: dict[str, Any]) -> None: """Raise ``NotFoundError`` when ``row`` is outside this parent.""" if self._row_in_scope(row): return raise NotFoundError(self._scope_error(key, row)) def _scope_request(self, key: int | str) -> Any: """GET that reads this manager's parent columns for ``key``. The default is ``GET {endpoint}/{key}``. Override when a resource is read through the collection (``tenant_layer2_vnets`` returns a key only as a filtered list). """ columns = ["$key", *[column for column, _expected in self._scope_bindings()]] params = {"fields": self._projection(columns, defaults=[])} return self._client._request("GET", f"{self._endpoint}/{key}", params=params) def _ensure_in_scope(self, key: int | str) -> None: """Fetch the parent column and refuse a mismatch before a write. Called at the start of :meth:`update`, :meth:`delete` and :meth:`action`. Managers that reimplement those methods call this themselves. An instance with no :meth:`_scope_bindings` allows every key. A scoped instance fetches the parent column and raises ``NotFoundError`` when it does not match, so the write is not sent. ``ResourceObject.save`` reaches the base :meth:`update`, which calls this before the PUT. The projection recorded for this lookup is restored afterwards. A following ``_to_model`` must not treat the scope read as the fields the caller asked for. """ if not self._scope_bindings(): return previous = self._requested_aliases try: response = self._scope_request(key) finally: self._requested_aliases = previous if isinstance(response, builtins.list): response = response[0] if len(response) == 1 else None if response is None or not isinstance(response, dict): raise NotFoundError(f"{self._scope_resource()} {key} not found") self._assert_row_in_scope(key, response)
[docs] def update(self, key: int, **kwargs: Any) -> T: """Update an existing resource. Args: key: Resource $key (ID). **kwargs: Attributes to update. Returns: Updated resource object. """ self._ensure_in_scope(key) response = self._client._request("PUT", f"{self._endpoint}/{key}", json_data=kwargs) if response is None: # Fetch updated resource return self.get(key) if not isinstance(response, dict): return self.get(key) return self._to_model_unprojected(response)
[docs] def delete(self, key: int) -> None: """Delete a resource. Args: key: Resource $key (ID). """ self._ensure_in_scope(key) self._client._request("DELETE", f"{self._endpoint}/{key}")
[docs] def action(self, key: int, action_name: str, **kwargs: Any) -> dict[str, Any] | None: """Execute an action on a resource. Args: key: Resource $key (ID). action_name: Name of the action (e.g., "poweron", "snapshot"). **kwargs: Action parameters. Returns: Action response (often includes task information). """ self._ensure_in_scope(key) endpoint = f"{self._endpoint}/{key}?action={action_name}" response = self._client._request("PUT", endpoint, json_data=kwargs) if isinstance(response, dict): return response return None
def _to_model(self, data: dict[str, Any]) -> T: """Convert API response to model object. Override in subclasses to return specific model types. """ return ResourceObject(data, self) # type: ignore[return-value] def _prepare_write_fields(self, fields: dict[str, Any]) -> dict[str, Any]: """Translate SDK-level field aliases to API field names for writes. ``ResourceObject._save()`` sends locally modified fields as a raw PUT, bypassing a manager's typed ``update()``. Managers whose ``update()`` translates aliases (e.g. ``tier`` -> ``preferred_tier``) must apply the same translation here so attribute assignment plus ``save()`` and ``update()`` behave identically (issue #97). The default is a passthrough. Implementations must not mutate the input mapping. Args: fields: Field-value pairs as provided by the caller. Returns: Field-value pairs ready to send to the API. """ return fields
[docs] def iter_all(self, page_size: int = 100, **kwargs: Any) -> Iterator[T]: """Iterate through all resources, handling pagination automatically. Args: page_size: Number of items per page. **kwargs: Additional filter arguments. Yields: Resource objects. """ offset = 0 while True: batch = self.list(limit=page_size, offset=offset, **kwargs) if not batch: break yield from batch if len(batch) < page_size: break # Last page offset += page_size
[docs] def __iter__(self) -> Iterator[T]: """Iterate over all resources (uses iter_all with default page size).""" return self.iter_all()
def __repr__(self) -> str: return f"{type(self).__name__}(endpoint={self._endpoint!r})"