opendp.typing module

The typing module provides utilities that bridge between Python and Rust types. OpenDP relies on precise descriptions of data types to make its security guarantees: These are more natural in Rust with its fine-grained type system, but they may feel out of place in Python. These utilities try to fill that gap.

For more context, see typing in the User Guide.

For convenience, all the functions of this module are also available from opendp.prelude. We suggest importing under the conventional name dp:

>>> import opendp.prelude as dp

class opendp.typing.Carrier(origin, args=None)

Bases: RuntimeType

Parameters:

• origin (str) –

• args (list[RuntimeType | str]) –

class opendp.typing.DomainDescriptor(origin, args=None)

Bases: RuntimeType

Parameters:

• origin (str) –

• args (list[RuntimeType | str]) –

class opendp.typing.GenericType(origin, args=None)

Bases: RuntimeType

Parameters:

• origin (str) –

• args (list[RuntimeType | str]) –

class opendp.typing.PrivacyMeasure(origin, args=None)

Bases: RuntimeType

All measure RuntimeTypes inherit from PrivacyMeasure. Provides static type checking in user-code for privacy measures and a getitem interface like stdlib typing.

Parameters:

• origin (str) –

• args (list[RuntimeType | str]) –

class opendp.typing.RuntimeType(origin, args=None)

Utility for validating, manipulating, inferring and parsing/normalizing type information.

Parameters:

• origin (str) –

• args (list[RuntimeType | str]) –

args: list[RuntimeType | str]

classmethod infer(public_example, py_object=False)

Infer the normalized type from a public example.

Parameters:

• public_example (Any) – data used to infer the type

• py_object – return “ExtrinsicObject” when type not recognized, instead of error

Returns:

Normalized type. If the type has subtypes, returns a RuntimeType, else a str.

Return type:

Union[“RuntimeType”, str]

Raises:

UnknownTypeException – if inference fails on public_example

Examples:

>>> import opendp.prelude as dp
>>> assert dp.RuntimeType.infer(23) == "i32"
>>> assert dp.RuntimeType.infer(12.) == "f64"
>>> assert dp.RuntimeType.infer(["A", "B"]) == "Vec<String>"
>>> assert dp.RuntimeType.infer((12., True, "A")) == "(f64,  bool,String)" # eq doesn't care about whitespace

>>> print(dp.RuntimeType.infer([]))
Traceback (most recent call last):
...
opendp.mod.UnknownTypeException: attempted to create a type_name with an unknown type: cannot infer atomic type when empty

origin: str

classmethod parse(type_name, generics=None)

Parse type descriptor into a normalized Rust type.

Type descriptor may be expressed as:

• Python type hints from std typing module

• plaintext Rust type strings for setting specific bit depth

• Python type class - one of {int, str, float, bool}

• tuple of type information - for example: (float, float)

Parameters:

• type_name (RuntimeType | str | Type[list[Any] | tuple[Any, Any] | float | str | bool] | tuple[RuntimeTypeDescriptor, ...] | _GenericAlias | GenericAlias) – type specifier

• generics (list[str] | None) – For internal use. List of type names to consider generic when parsing.

Type:

list[str]

Returns:

Normalized type. If the type has subtypes, returns a RuntimeType, else a str.

Return type:

Union[“RuntimeType”, str]

Raises:

UnknownTypeException – if type_name fails to parse

Examples:

>>> import opendp.prelude as dp
>>> dp.RuntimeType.parse(int)
'i32'
>>> dp.RuntimeType.parse("i32")
'i32'
>>> dp.RuntimeType.parse(L1Distance[int])
L1Distance<i32>
>>> dp.RuntimeType.parse(L1Distance["f32"])
L1Distance<f32>

classmethod parse_or_infer(type_name=None, public_example=None, generics=None)

If type_name is supplied, normalize it. Otherwise, infer the normalized type from a public example.

Parameters:

• type_name (RuntimeType | str | Type[list[Any] | tuple[Any, Any] | float | str | bool] | tuple[RuntimeTypeDescriptor, ...] | _GenericAlias | GenericAlias | None) – type specifier. See RuntimeType.parse for documentation on valid inputs

• public_example (Any | None) – data used to infer the type

• generics (list[str] | None) – For internal use. List of type names to consider generic when parsing.

Returns:

Normalized type. If the type has subtypes, returns a RuntimeType, else a str.

Return type:

Union[“RuntimeType”, str]

Type:

list[str]

Raises:

• ValueError – if type_name fails to parse

• UnknownTypeException – if inference fails on public_example or no args are supplied

substitute(**kwargs)

Parameters:

self (RuntimeType | str) –

class opendp.typing.SensitivityMetric(origin, args=None)

Bases: RuntimeType

All sensitivity RuntimeTypes inherit from SensitivityMetric. Provides static type checking in user-code for sensitivity metrics and a getitem interface like stdlib typing.

Parameters:

• origin (str) –

• args (list[RuntimeType | str]) –

class opendp.typing.UnknownType(reason)

Bases: RuntimeType

Indicator for a type that cannot be inferred. Typically the atomic type of an empty list. RuntimeTypes containing UnknownType cannot be used in FFI

args: None

origin: None

opendp.typing.get_atom(type_name)

opendp.typing.get_atom_or_infer(type_name, example)

Parameters:

type_name (RuntimeType | str) –

opendp.typing.get_carrier_type(value)

Parameters:

value (Domain) –

Return type:

RuntimeType | str

opendp.typing.get_dependencies(value)

Parameters:

value (Measurement | Transformation | Function) –

Return type:

Any

opendp.typing.get_dependencies_iterable(value)

Parameters:

value (list[Measurement | Transformation | Function]) –

Return type:

list[Any]

opendp.typing.get_distance_type(value)

Parameters:

value (Metric | Measure) –

Return type:

RuntimeType | str

opendp.typing.get_first(value)

opendp.typing.get_type(value)

opendp.typing.get_value_type(type_name)

opendp.typing.parse_or_infer(type_name, example)

Parameters:

type_name (RuntimeType | str | Type[list[Any] | tuple[Any, Any] | float | str | bool] | tuple[RuntimeTypeDescriptor, ...] | _GenericAlias | GenericAlias | None) –

Return type:

RuntimeType | str

opendp.typing.pass_through(value)

Parameters:

value (Any) –

Return type:

Any

opendp.typing.set_default_float_type(T)

Set the default float type throughout the library. This function is particularly useful when building computation chains with constructors. When you build a computation chain, any unspecified float types default to this float type.

The default float type is f64.

Params T:

must be one of [f32, f64]

Parameters:

T (Type Argument) –

Return type:

None

opendp.typing.set_default_int_type(T)

Set the default integer type throughout the library. This function is particularly useful when building computation chains with constructors. When you build a computation chain, any unspecified integer types default to this int type.

The default int type is i32.

Params T:

must be one of [u8, u16, u32, u64, usize, i8, i16, i32, i64]

Parameters:

T (Type Argument) –

Return type:

None