`px_core.utility`

Utility types — serialization, geometry, errors.

Module Contents

Classes

`HttpResponseClassErrorCode`	Custom error class for dealing with HTTP responses as error_code values.
`JsonSerializerErrorCode`	Error codes for JsonSerializer serialization errors
`CallbackFuture`	A utility class to associate a future with the value passed to a callback
`Color`	Utility class to represent color values
`IErrorCodeException`	Base interface for error_code-based errors
`GLibFileErrorCategory`	Error category for GLib GFileError error codes
`HttpFetch`	A helper class to make simple HTTP requests
`HttpResponseClassErrorCategory`	Error category for HttpResponseClassErrorCode
`IAccessTokenProvider`	An interface to provide fresh access tokens on demand.
`JsonSerializer`	A serializer that allows data interchange between typed C++ structs and JSON objects using Boost's JSON support.
`JsonSerializerErrorCategory`	Error category for JsonSerializerErrorCode
`PointDouble`	General purpose point/position class
`PointInt`	General purpose point/position class
`RectangleInt`	General purpose rectangle class
`RectangleUInt`	General purpose rectangle class
`SizeInt`	General purpose size class
`SizeUInt`	General purpose size class

Functions

`escape_string`(→ escape_string.str)
`high_word32`(→ int)
`is_uuid`(→ bool)
`is_video_device`(→ bool)
`low_word32`(→ int)
`make_word32`(→ int)

Attributes

`Bands`
`BandThresholds`
`ComponentSequence`
`ProviderSequence`
`AudioInputFeedComponents`
`Point`
`Rectangle`
`Size`

px_core.utility.Bands

px_core.utility.BandThresholds

px_core.utility.ComponentSequence

px_core.utility.ProviderSequence

px_core.utility.AudioInputFeedComponents

class px_core.utility.HttpResponseClassErrorCode

Bases: enum.IntEnum

Custom error class for dealing with HTTP responses as error_code values.

Boost/Beast does not have error_code support for HTTP response status codes. Further, std error_codes require code zero (only) to indicate success and non-zero for error conditions. This error code encapsulates the response status class only, allowing allowing a single ‘successful’ class (namely 200s). The caller can check this code to determine if it needs to inspect the full response for more detail (chiefly when non-successful).

Successful: int = 0

Informational: int = 1

Redirection: int = 3

ClientError: int = 4

ServerError: int = 5

Unknown: int = 10

class px_core.utility.JsonSerializerErrorCode

Bases: enum.IntEnum

Error codes for JsonSerializer serialization errors

Successful: int = 0

InvalidType: int = 1

KeyMissing: int = 2

ReadOnlyValueMismatch: int = 3

InternalError: int = 4

class px_core.utility.CallbackFuture: A utility class to associate a future with the value passed to a callback

class px_core.utility.Color

class px_core.utility.Color(red: float, green: float, blue: float, alpha: float = 1)

Utility class to represent color values

static grey(value: float, alpha: float = 1) → Color: Create a grey value with equal red, green, blue

static black(alpha: float = 1) → Color: Standard black color

static white(alpha: float = 1) → Color: Standard white color

property red: float

property green: float

property blue: float

property alpha: float

opaque() → Color: Set alpha to opaque

to_argb32() → int: Convert to ARGB 32 bit value

static from_argb32(color: int) → Color: Create from an ARGB 32 bit value

class px_core.utility.IErrorCodeException

Base interface for error_code-based errors

This abstract interface class provides functions common to all error_code-based exceptions. This allows code to catch all error_code-based exceptions and examine the error code.

error_code() → int: Return an error_code corrsponding to the exception’s code

class px_core.utility.GLibFileErrorCategory

Error category for GLib GFileError error codes

static category() → GLibFileErrorCategory: Returns the category instance for the GLibFileErrorCategory

static message_from_error_code(code: int) → str: Helper to translate an error code into a message string

Error category

Implements the error_category interface

name() → str: Returns the error category name as a string

message(code: int) → str: Returns the message for the provided error code

class px_core.utility.HttpFetch

A helper class to make simple HTTP requests

class RequestFields

class RequestFields(tokenProvider: IAccessTokenProvider)

Request fields, which are typically common/reused across requests

Parameter values

Note: setter methods are chainable

property token_provider: IAccessTokenProvider

property user_agent: str

class RequestParams

Request parameters define the specifics of a request

Helpers

static from_url(verb: int, url: str, body: str = ...) → HttpFetch.RequestParams: Create request params from a source URL string

Parameter values

Note: setter methods are chainable

property verb: int

property host: str

property port: int

port_or_default(def_: int) → int: Get port, or a given default if not set

property target: str

property body: str

class FetchRequest(context: px_core.core.ProximieContext)

The full request structure

property px_context: px_core.core.ProximieContext

property params: HttpFetch.RequestParams

property fields: HttpFetch.RequestFields

class FetchResponse

class FetchResponse(status: int, value: str)

The response from a fetch request

Convenience helpers

status_summary() → str

Return a string with the HTTP status code and reason, e.g.

for logging/debugging

property http_status: int

property value_text: str

property value_json: object | None

class FetchResult

The fetch result is the final error code with the fetch response

status_summary() → str: Helper to return a string with any error and response summary

property error: int

property response: HttpFetch.FetchResponse

Make a request

static fetch(request: HttpFetch.FetchRequest, handler: Callable[[HttpFetch.FetchResult], None]) → None: Make a fetch request asynchronously, calling the handler when complete

static fetch(request: HttpFetch.FetchRequest) → HttpFetch.FetchResult: Make a fetch request and return a future with the result

class px_core.utility.HttpResponseClassErrorCategory

Error category for HttpResponseClassErrorCode

static category() → HttpResponseClassErrorCategory: Returns the category instance for the HttpResponseClassErrorCategory

Error category

Implements the error_category interface

name() → str: Returns the error category name as a string

message(code: int) → str: Returns the message for the provided error code

class px_core.utility.IAccessTokenProvider

An interface to provide fresh access tokens on demand.

This simple interface is used by the SDK where HTTP requests need to be made using access tokens. The mechanism of obtaining and refreshing an access token is an application implementation decision, so the caller needs to provide an IAccessTokenProvider-derived object which implements the interface. The concrete provider should arrange to have a fresh, valid token available to respond to ad hoc requests. Typically this involves obtaining an initial access token (e.g. via some authentication flow), and to note when the token expires in order to pre-emptively refresh it.

access_token() → str: Obtain a fresh, valid access token string on demand.

class px_core.utility.JsonSerializer

A serializer that allows data interchange between typed C++ structs and JSON objects using Boost’s JSON support.

Implementing serializable objects Providing the C++ value struct (or class) implement a suitable serialization function, class JsonSerializer can be used serialize from a Boost JSON value into the C++ value, or create a JSON value from a C++ value. The C++ serializable values are objects that implement a serialize function: ` void serialize(JsonSerializer& serializer); ` This function is called for serialization to and from the object. The implementation simply calls JsonSerializer.serialize (or variants) for each of it’s own members. This includes serializing members which are themselves C++ objects that implement serialize, allowing object hierarchies to be easily serialized. Serializing between C++ and JSON objects Creation of a JSON object from a serializable source object should always succeed except for exceptional (throwing) errors (e.g. memory allocation). The philosophy here is that an object should always be able to reliably create a JSON representation of itself. However, we assume that any JSON values that we are attempting to serialize into a C++ object can fail, the assumption being the source of the JSON is not within application control and so may not match the required format/structure. For this reason, there are variants for reading from JSON values (see the full JsonSerializer documentation below for details). Briefly, readObject. function variants should be used where it’s considered an error if the serialization fails, and they return an error-code or throw in case of failure. The check. function variants are used when the JSON object type is not known or guaranteed, and so it’s not an error if serialization fails.

class WhenKeyMissing

Bases: enum.IntEnum

How to handle a missing key when reading JSON into a C++ object

UseDefault: int = 0

Throw: int = 1

static string_from_json_object(object: dict) → str

Helper function to convert a JSON object into a plain string

Parameters:: object (dict) – The source JSON object to read
Returns:: The stringified form of the JSON object as a str.

static parse_json_object_string(target: dict, json: str) → None

Helper function to parse a string into a target JSON object

Convenience function since object serialization expects JSON objects rather than general values.

Parameters:

target (dict) – The target JSON value to be set
json (str) – A JSON string value to parse

Returns:

outcome.result<void>

serialize_as_read_only(key: str, value: str) → JsonSerializer

Serialize a read-only string value

A common use case is that a payload string value is read-only: - When writing to JSON, write the value as normal - When reading from JSON, the value must equal the value in the C++ object.

Parameters:

key (str) – The key that will be used in the JSON object
value (str) – The member value to be serialized

Returns:

The JsonSerializer object, allowing chained calls

serialize_as_fixed(key: str, value: str) → JsonSerializer

Serialize a constant string value

A common use case is that a payload string value is fixed for the type. This is similar to JsonSerializer.serializeAsReadOnly except that the C++ object does not need to include the value as a data member and can just provide the value required as a constant. - When writing to JSON, write the constant value - When reading from JSON, the value must equal constant value

Parameters:

key (str) – The key that will be used in the JSON object
value (str) – The constant value to be written or expected to be read

Returns:

The JsonSerializer object, allowing chained calls

class px_core.utility.JsonSerializerErrorCategory

Error category for JsonSerializerErrorCode

static category() → JsonSerializerErrorCategory: Returns the category instance for the JsonSerializerErrorCategory

static message_from_error_code(code: JsonSerializerErrorCode) → str: Helper to translate an error code into a message string

Error category

Implements the error_category interface

name() → str: Returns the error category name as a string

message(code: int) → str: Returns the message for the provided error code

class px_core.utility.PointDouble

class px_core.utility.PointDouble(x: float, y: float)

General purpose point/position class

reset() → PointDouble: Reset the point to zero

property x: float

property y: float

property zero: bool

class px_core.utility.PointInt

class px_core.utility.PointInt(x: int, y: int)

General purpose point/position class

reset() → PointInt: Reset the point to zero

property x: int

property y: int

property zero: bool

class px_core.utility.RectangleInt

General purpose rectangle class

reset() → RectangleInt: Reset the rectangle to an “empty” state (all zero values)

property left: int

property top: int

property right: int

property bottom: int

empty() → bool: Test for “empty” (all zero values) rectangle

to_string() → str: Convert to a string representation

class px_core.utility.RectangleUInt

General purpose rectangle class

reset() → RectangleUInt: Reset the rectangle to an “empty” state (all zero values)

property left: int

property top: int

property right: int

property bottom: int

empty() → bool: Test for “empty” (all zero values) rectangle

to_string() → str: Convert to a string representation

class px_core.utility.SizeInt

class px_core.utility.SizeInt(width: int, height: int)

General purpose size class

reset() → SizeInt: Reset the size to “empty” (all zero values)

property width: int

property height: int

flip() → SizeInt: Flip/swap the width and height

empty() → bool: Test for “empty” (all zero values)

property has_positive_dimensions: bool

to_string() → str: Get string representation of the size

class px_core.utility.SizeUInt

class px_core.utility.SizeUInt(width: int, height: int)

General purpose size class

reset() → SizeUInt: Reset the size to “empty” (all zero values)

property width: int

property height: int

flip() → SizeUInt: Flip/swap the width and height

empty() → bool: Test for “empty” (all zero values)

property has_positive_dimensions: bool

to_string() → str: Get string representation of the size

px_core.utility.Point

px_core.utility.Rectangle

px_core.utility.Size

px_core.utility.escape_string(str: escape_string.str) → escape_string.str

px_core.utility.high_word32(dword: int) → int

px_core.utility.is_uuid(str: is_uuid.str) → bool

px_core.utility.is_video_device(path: str) → bool

px_core.utility.low_word32(dword: int) → int

px_core.utility.make_word32(high: int, low: int) → int

px_core.utility

Module Contents

Classes

Functions

Attributes

`px_core.utility`