Exceptions
pyvergeos defines a hierarchy of exceptions for error handling.
Exception Classes
Custom exceptions for pyvergeos.
Note: Exception names are prefixed with ‘Verge’ to avoid shadowing Python builtins (ConnectionError, TimeoutError).
- exception pyvergeos.exceptions.VergeError[source]
Bases:
ExceptionBase exception for all pyvergeos errors.
- exception pyvergeos.exceptions.VergeConnectionError[source]
Bases:
VergeErrorConnection to VergeOS failed.
- exception pyvergeos.exceptions.NotConnectedError[source]
Bases:
VergeErrorOperation attempted without an active connection.
- exception pyvergeos.exceptions.VergeTimeoutError[source]
Bases:
VergeErrorRequest timed out.
- exception pyvergeos.exceptions.APIError[source]
Bases:
VergeErrorBase class for API errors.
- status_code
HTTP status code, when available.
- response_body
Complete parsed JSON error body, or raw text for non-JSON responses. Defaults to None for errors without a response body. May contain sensitive data; inspect it before logging or sharing it.
- exception pyvergeos.exceptions.AuthenticationError[source]
Bases:
APIErrorAuthentication failed (401/403).
- exception pyvergeos.exceptions.FieldNotProjectedError[source]
Bases:
VergeErrorAn accessor’s backing field was not included in the projection.
Raised instead of inventing a value when the field an accessor reads is absent from the row, which happens whenever the caller narrowed
fields(issue #117).Before this existed,
is_runningansweredFalsefor a running VM andstatusanswered"unknown"– indistinguishable from a real answer, and exactly the guard a caller puts in front of a destructive operation.Deliberately not an
AttributeError.ResourceObject.__getattr__is the dict fallback, and Python calls it whenever normal attribute lookup raisesAttributeError– so anAttributeErrorsubclass raised inside a property is swallowed and re-raised as a bare “has no attribute”, losing the diagnostic. It would also makehasattr()answerFalsefor a field that exists but was not fetched, which is the same silent lie in a new place.- field
Name of the field that was not projected.
- exception pyvergeos.exceptions.TaskError[source]
Bases:
VergeErrorTask execution failed.
Filters
OData-style filter expression builder for VergeOS API queries.
VergeOS filtering is “similar to OData” but has its own grammar. The
supported comparison operators are eq, ne, gt, ge, lt,
le, bw (begins-with), ew (ends-with), cs (contains,
case-sensitive), ct (contains, case-insensitive) and rx (POSIX ERE
regex). There is no like and no in – the platform rejects both
tokens with HTTP 422 – so the wildcard and list shorthands below are
translated to supported operators (issue #103).
and/or have no precedence and are evaluated strictly left-to-right,
so every generated or chain is parenthesized.
- pyvergeos.filters.quote_value(value)[source]
Quote a string literal for a VergeOS filter expression.
VergeOS uses backslash escaping, not SQL quote doubling. Three characters are reserved inside a literal and each is escaped with a backslash:
\(the escape character),'(terminates the literal) and{(opens a balanced construct).}is not reserved.An unescaped
{is the dangerous one: a balanced{...}is consumed silently and the query matches whatever the stripped string names, so a lookup-by-name can return - and the caller can then modify or delete - the wrong object (issue #100). An unbalanced{is merely rejected with HTTP 422.This only quotes the value; wildcard conversion belongs to the caller.
- pyvergeos.filters.wildcard_condition(field, pattern)[source]
Translate a
*/?wildcard pattern into supported operators.Public so resource managers with a
namesearch parameter share one translation instead of hand-rolling their own (issue #103, PR #104).VergeOS has no
likeoperator (HTTP 422 “Invalid argument”), so wildcard patterns are translated (issue #103):foo*->field bw 'foo'(begins-with)*foo->field ew 'foo'(ends-with)*foo*->field cs 'foo'(contains)*->field bw ''(matches every row)patterns with
?or an interior*-> anchored POSIX-ERErxwith metacharacters escaped, e.g.a*b->field rx '^a.*b$'
Matching is case-sensitive throughout, consistent with
eq. For a case-insensitive contains, use a rawfilter="field ct '...'". The anchored form guarantees therxpattern is never empty (an emptyrxpattern matches every row on the platform).
- class pyvergeos.filters.FilterOperator[source]
Bases:
EnumFilter operators.
LIKEandINare accepted for backwards compatibility but are never sent to the API: VergeOS rejects both tokens, so they are translated to supported operators (issue #103).- EQ = 'eq'
- NE = 'ne'
- LT = 'lt'
- GT = 'gt'
- LE = 'le'
- GE = 'ge'
- BW = 'bw'
- EW = 'ew'
- CS = 'cs'
- CT = 'ct'
- RX = 'rx'
- LIKE = 'like'
- IN = 'in'
- class pyvergeos.filters.Filter[source]
Bases:
objectOData-style filter expression builder.
Example
>>> f = Filter() >>> f.eq("status", "running").and_().like("name", "web*") >>> str(f) "status eq 'running' and name bw 'web'"
- like(field, pattern)[source]
Add a wildcard pattern condition.
*= any run,?= one char.VergeOS has no
likeoperator, so the pattern is translated to supported operators:foo*->bw,*foo->ew,*foo*->cs, complex patterns -> anchored POSIX-ERErx. Matching is case-sensitive, consistent witheq(issue #103).
- in_(field, values)[source]
Add a membership condition as a parenthesized
orchain.VergeOS has no
inoperator, so the list expands to(field eq v1 or field eq v2 ...). String values follow the same wildcard translation aslike()(issue #103).
- rx(field, pattern)[source]
Add a POSIX-ERE regex condition (partial match, case-sensitive).
The platform dialect is POSIX ERE: bracket classes like
[0-9]and[[:digit:]]work, but PCRE shorthands (\d) and inline flags ((?i)) silently match nothing, and an empty pattern matches every row. Escape literal metacharacters with a backslash.
- pyvergeos.filters.combine_filters(filter, filter_kwargs)[source]
Merge an explicit filter string with shorthand filter kwargs.
Both filter forms are honoured: when both are supplied the result is
(filter) and (built). Previously shorthand kwargs were silently dropped whenever an explicit filter was present (issue #96).- Parameters:
- Returns:
Combined filter string, or None when no filtering was requested.
- Raises:
ValueError – If filter kwargs were supplied but every value was None. An empty filter would silently match every row, so it is rejected instead of widening the result set (issue #96).
- Return type:
str | None
- pyvergeos.filters.build_filter(**kwargs)[source]
Build a filter string from keyword arguments.
- Supports:
Simple equality: name=”value”
Wildcards: name=”prefix*” (translated to bw/ew/cs/rx; VergeOS has no LIKE operator – see issue #103). Case-sensitive.
Lists: status=[“running”, “stopped”] (expanded to a parenthesized or-chain of equality/wildcard conditions; VergeOS has no IN operator). Raises ValueError for an empty sequence.
- Parameters:
**kwargs (Any) – Field-value pairs for filtering.
- Returns:
OData-style filter string.
- Return type:
Example
>>> build_filter(status="running", name="web*") "status eq 'running' and name bw 'web'" >>> build_filter(status=["running", "stopped"]) "(status eq 'running' or status eq 'stopped')"