From 323418f0ffd01ef7e4a4018be20b4d2ce129b6b5 Mon Sep 17 00:00:00 2001 From: Mikkel Wienberg Madsen Date: Wed, 18 Sep 2024 10:54:10 +0200 Subject: [PATCH] Update python stub --- pycare/caring.pyi | 247 +++++++++++++++++++++++++--------------------- 1 file changed, 133 insertions(+), 114 deletions(-) diff --git a/pycare/caring.pyi b/pycare/caring.pyi index 0cbaea7..535d97e 100644 --- a/pycare/caring.pyi +++ b/pycare/caring.pyi @@ -1,79 +1,97 @@ -# TODO: Add documentation - -""" - Id of a party -""" class Id: - ... + """ + Id of a party + """ -""" - An opened value. - Use the Engine to evaluate it -""" class Opened: - ... + """ + An opened value. -""" - A computed result, needs to be recast into a value. + Use the Engine to evaluate it + """ - The size needs to be manually tracked, - in the case of a scalar the size will be 1, - and for any vectors given it will be the corresponding size -""" class Computed: - """ - Cast as a float - """ - def as_float(self) -> list[float]: ... + """ + A computed result, needs to be recast into a value. + The size needs to be manually tracked, + in the case of a scalar the size will be 1, + + and for any vectors given it will be the corresponding size """ - Cast as an integer - """ - def as_int(self) -> list[int]: ... + def as_float(self) -> list[float]: + """ + Cast as a float + """ + + + + def as_int(self) -> list[int]: + """ + Cast as an integer + """ -""" - An expression of an MPC routine - Note: - This allows mixing between different vector sizes and scalars, - it will however be a runtime error to add, subcract or multiply - different sized vectors. -""" -class Expr: - """ Share a given value or vector - Returns: - An expression for the given share +class Expr: + """ + An expression of an MPC routine + + Note: + This allows mixing between different vector sizes and scalars, + it will however be a runtime error to add, subcract or multiply + different sized vectors. """ + @staticmethod - def share(num: float | int | list[float] | list[int]) -> Expr: ... + def share(num: int | float | list[int] | list[float]) -> Expr: + """ Share a given value or vector + + Warning: + - Integer-mode only supports unsigned (non-negative) integers. + Negative integers will be converted to floats + - Floats will be converted to fixed point, and as such + multiplication is currently unsupported. + + Returns: + An expression for the given share + """ - """ Receive a share from another party - Returns: - An expression for the given share - """ @staticmethod - def recv(id: Id) -> Expr: ... + def recv(id: Id) -> Expr: + """ + Receive a share from another party + + Returns: + An expression for the given share + """ - """ Secret-share (symmetrically, all-parties at-once) a given value or vector - Returns: - A list of expressions, ordered by Ids - """ @staticmethod - def symmetric_share(num: float | int | list[float] | list[int], id: Id, size: int) -> list[Expr]: ... + def symmetric_share(num: int | float | list[int] | list[float], id: Id, size: int) -> list[Expr]: + """ Secret-share (symmetrically, all-parties at-once) a given value or vector - """ Open the given value + Warning: + - Integer-mode only supports unsigned (non-negative) integers. + Negative integers will be converted to floats + - Floats will be converted to fixed point, and as such + multiplication is currently unsupported. - An opened value needs to be processed in the engine to compute it's result - """ - def open(self) -> Opened: ... + Returns: + A list of expressions, ordered by Ids + """ + + def open(self) -> Opened: + """ Open the given value + + An opened value needs to be processed in the engine to compute it's result + """ def __add__(self, other: Expr) -> Expr: ... def __sub__(self, other: Expr) -> Expr: ... @@ -86,7 +104,7 @@ class Engine: """ Create a new Engine Args: - scheme: shamir-32|shamir-25519|spdz-32|spdz-25519|feldman-25519 + scheme: 'shamir-32' or 'shamir-25519' or 'spdz-32' or 'spdz-25519' or 'feldman-25519' address: address to listen on peers: peer addresses (party members) to connect to multithreaded: use a multithreaded runtime @@ -103,31 +121,32 @@ class Engine: preprocessed_path: str | None = None, ) -> None: ... - """ - Execute the opened value to evaluate it. - This runs the nesscary protocols to output it. + def execute(self, script: Opened) -> Computed: + """ + Execute the opened value to evaluate it. + This runs the nesscary protocols to output it. - Errors: This might error if the underlying computation fails + Errors: This might error if the underlying computation fails - Returns: - The result of the computation + Returns: + The result of the computation - """ - def execute(self, script: Opened) -> Computed: ... + """ - """ - Returns: - Your id in the network - """ - def id(self) -> Id: ... - """ - List the party members in the network + def id(self) -> Id: + """ + Returns: + Your id in the network + """ - Returns: - a list of party id's for each member - """ - def peers(self) -> list[Id]: ... + def peers(self) -> list[Id]: + """ + List the party members in the network + + Returns: + a list of party id's for each member + """ """ @@ -147,58 +166,58 @@ def preproc(num_shares: int, num_triplets: int, *paths_to_pre: str, scheme: str # class OldEngine: - """ - Performs a summation with the connected parties. - Returns the sum of all the numbers. - :param a: number to summate with - """ - def sum(self, a: float) -> float: ... + def sum(self, a: float) -> float: + """ + Performs a summation with the connected parties. + Returns the sum of all the numbers. + :param a: number to summate with + """ - """ - Performs a summation of a vector with the connected parties. - Returns the sum of all the vector (element-wise) of all the numbers. - :param a: vector to summate with. + def sum_many(self, a: list[float]) -> list[float]: + """ + Performs a summation of a vector with the connected parties. + Returns the sum of all the vector (element-wise) of all the numbers. + :param a: vector to summate with. - Note: that all parties must supply the same length! - """ - def sum_many(self, a: list[float]) -> list[float]: ... + Note: that all parties must supply the same length! + """ - """ - Takedown the MPC Engine, releasing the resources and dropping connections. - """ - def takedown(self) -> None: ... + def takedown(self) -> None: + """ + Takedown the MPC Engine, releasing the resources and dropping connections. + """ -""" - Setup a MPC Engine for adding numbers together using SPDZ - The engine will connect to the given addresses and listen - on the first socket address. - :path_to_pre: path to precomputed triples - :param my_addr: the address to listen on - :param others: the addresses to connect to -""" -def spdz(path_to_pre: str, my_addr: str, *others: str) -> Engine: ... +def spdz(path_to_pre: str, my_addr: str, *others: str) -> Engine: + """ + Setup a MPC Engine for adding numbers together using SPDZ + The engine will connect to the given addresses and listen + on the first socket address. + :path_to_pre: path to precomputed triples + :param my_addr: the address to listen on + :param others: the addresses to connect to + """ -""" - Setup a MPC Engine for adding numbers together using Shamir Secret Sharing. - The engine will connect to the given addresses and listen - on the first socket address. - :threshold: threshold to use - :param my_addr: the address to listen on - :param horsepower: the addresses to connect to -""" -def shamir(threshold: int, my_addr: str, *others: str) -> Engine: ... +def shamir(threshold: int, my_addr: str, *others: str) -> Engine: + """ + Setup a MPC Engine for adding numbers together using Shamir Secret Sharing. + The engine will connect to the given addresses and listen + on the first socket address. + :threshold: threshold to use + :param my_addr: the address to listen on + :param horsepower: the addresses to connect to + """ -""" - Setup a MPC Engine for adding numbers together using Feldman Verifiable Secret Sharing. - The engine will connect to the given addresses and listen - on the first socket address. - :threshold: threshold to use - :param my_addr: the address to listen on - :param horsepower: the addresses to connect to -""" -def feldman(threshold: int, my_addr: str, *others: str) -> Engine: ... +def feldman(threshold: int, my_addr: str, *others: str) -> Engine: + """ + Setup a MPC Engine for adding numbers together using Feldman Verifiable Secret Sharing. + The engine will connect to the given addresses and listen + on the first socket address. + :threshold: threshold to use + :param my_addr: the address to listen on + :param horsepower: the addresses to connect to + """