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: Exception

Base exception for all pyvergeos errors.

exception pyvergeos.exceptions.VergeConnectionError[source]

Bases: VergeError

Connection to VergeOS failed.

exception pyvergeos.exceptions.NotConnectedError[source]

Bases: VergeError

Operation attempted without an active connection.

exception pyvergeos.exceptions.VergeTimeoutError[source]

Bases: VergeError

Request timed out.

exception pyvergeos.exceptions.APIError[source]

Bases: VergeError

Base 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.

__init__(message, status_code=None, *, response_body=None)[source]
Parameters:
  • message (str)

  • status_code (int | None)

  • response_body (Any)

Return type:

None

exception pyvergeos.exceptions.AuthenticationError[source]

Bases: APIError

Authentication failed (401/403).

exception pyvergeos.exceptions.NotFoundError[source]

Bases: APIError

Resource not found (404).

exception pyvergeos.exceptions.ConflictError[source]

Bases: APIError

Resource conflict (409).

exception pyvergeos.exceptions.ValidationError[source]

Bases: APIError

Validation error (422).

exception pyvergeos.exceptions.FieldNotProjectedError[source]

Bases: VergeError

An 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_running answered False for a running VM and status answered "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 raises AttributeError – so an AttributeError subclass raised inside a property is swallowed and re-raised as a bare “has no attribute”, losing the diagnostic. It would also make hasattr() answer False for 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.

__init__(field, owner='resource')[source]
Parameters:
Return type:

None

exception pyvergeos.exceptions.TaskError[source]

Bases: VergeError

Task execution failed.

__init__(message, task_id=None)[source]
Parameters:
  • message (str)

  • task_id (int | None)

Return type:

None

exception pyvergeos.exceptions.TaskTimeoutError[source]

Bases: TaskError

Task wait timed out.

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.

Parameters:

value (str)

Return type:

str

pyvergeos.filters.wildcard_condition(field, pattern)[source]

Translate a */? wildcard pattern into supported operators.

Public so resource managers with a name search parameter share one translation instead of hand-rolling their own (issue #103, PR #104).

VergeOS has no like operator (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-ERE rx with 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 raw filter="field ct '...'". The anchored form guarantees the rx pattern is never empty (an empty rx pattern matches every row on the platform).

Parameters:
Return type:

str

class pyvergeos.filters.FilterOperator[source]

Bases: Enum

Filter operators.

LIKE and IN are 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: object

OData-style filter expression builder.

Example

>>> f = Filter()
>>> f.eq("status", "running").and_().like("name", "web*")
>>> str(f)
"status eq 'running' and name bw 'web'"
__init__()[source]
Return type:

None

eq(field, value)[source]

Add equals condition.

Parameters:
Return type:

Filter

ne(field, value)[source]

Add not equals condition.

Parameters:
Return type:

Filter

lt(field, value)[source]

Add less than condition.

Parameters:
Return type:

Filter

gt(field, value)[source]

Add greater than condition.

Parameters:
Return type:

Filter

le(field, value)[source]

Add less than or equal condition.

Parameters:
Return type:

Filter

ge(field, value)[source]

Add greater than or equal condition.

Parameters:
Return type:

Filter

like(field, pattern)[source]

Add a wildcard pattern condition. * = any run, ? = one char.

VergeOS has no like operator, so the pattern is translated to supported operators: foo* -> bw, *foo -> ew, *foo* -> cs, complex patterns -> anchored POSIX-ERE rx. Matching is case-sensitive, consistent with eq (issue #103).

Parameters:
Return type:

Filter

in_(field, values)[source]

Add a membership condition as a parenthesized or chain.

VergeOS has no in operator, so the list expands to (field eq v1 or field eq v2 ...). String values follow the same wildcard translation as like() (issue #103).

Raises:

ValueError – If values is an empty sequence.

Parameters:
Return type:

Filter

bw(field, value)[source]

Add begins-with condition (case-sensitive).

Parameters:
Return type:

Filter

ew(field, value)[source]

Add ends-with condition (case-sensitive).

Parameters:
Return type:

Filter

cs(field, value)[source]

Add contains condition (case-sensitive).

Parameters:
Return type:

Filter

ct(field, value)[source]

Add contains condition (case-insensitive).

Parameters:
Return type:

Filter

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.

Parameters:
Return type:

Filter

and_()[source]

Add explicit AND connector (usually not needed, AND is implicit).

Return type:

Filter

or_()[source]

Add OR connector (must be explicit, unlike AND).

Return type:

Filter

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:
  • filter (str | None) – OData filter string, or None.

  • filter_kwargs (dict[str, Any]) – Shorthand field-value filter arguments.

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:

str

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')"