diff --git a/dev/test.sh b/dev/test.sh index 8f8d9dedf6d..b8eeed14bc4 100755 --- a/dev/test.sh +++ b/dev/test.sh @@ -26,6 +26,10 @@ echo "- docformatter: start" python -m docformatter -c -r src/py/flwr e2e -e src/py/flwr/proto echo "- docformatter: done" +echo "- docsig: start" +docsig src/py/flwr +echo "- docsig: done" + echo "- ruff: start" python -m ruff check src/py/flwr echo "- ruff: done" diff --git a/pyproject.toml b/pyproject.toml index 11da893bec7..aa356835d98 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -134,6 +134,7 @@ pre-commit = "==3.5.0" sphinx-substitution-extensions = "2022.02.16" sphinxext-opengraph = "==0.9.1" docstrfmt = { git = "https://github.com/charlesbvll/docstrfmt.git", branch = "patch-1" } +docsig = "==0.64.0" [tool.docstrfmt] extend_exclude = [ @@ -224,3 +225,7 @@ convention = "numpy" [tool.ruff.per-file-ignores] "src/py/flwr/server/strategy/*.py" = ["E501"] + +[tool.docsig] +ignore-no-params = true +exclude = 'src/py/flwr/proto/.*|src/py/flwr/.*_test\.py|src/py/flwr/cli/new/templates/.*\.tpl' diff --git a/src/py/flwr/cli/config_utils.py b/src/py/flwr/cli/config_utils.py index 79e4973ccf9..73ce779c3b5 100644 --- a/src/py/flwr/cli/config_utils.py +++ b/src/py/flwr/cli/config_utils.py @@ -90,6 +90,16 @@ def load_and_validate( ) -> tuple[Optional[dict[str, Any]], list[str], list[str]]: """Load and validate pyproject.toml as dict. + Parameters + ---------- + path : Optional[Path] (default: None) + The path of the Flower App config file to load. By default it + will try to use `pyproject.toml` inside the current directory. + check_module: bool (default: True) + Whether the validity of the Python module should be checked. + This requires the project to be installed in the currently + running environment. True by default. + Returns ------- Tuple[Optional[config], List[str], List[str]] diff --git a/src/py/flwr/client/app.py b/src/py/flwr/client/app.py index 90c50aba7fa..54ed33aa66b 100644 --- a/src/py/flwr/client/app.py +++ b/src/py/flwr/client/app.py @@ -132,6 +132,11 @@ class `flwr.client.Client` (default: None) - 'grpc-bidi': gRPC, bidirectional streaming - 'grpc-rere': gRPC, request-response (experimental) - 'rest': HTTP (experimental) + authentication_keys : Optional[Tuple[PrivateKey, PublicKey]] (default: None) + Tuple containing the elliptic curve private key and public key for + authentication from the cryptography library. + Source: https://cryptography.io/en/latest/hazmat/primitives/asymmetric/ec/ + Used to establish an authenticated connection with the server. max_retries: Optional[int] (default: None) The maximum number of times the client will try to connect to the server before giving up in case of a connection error. If set to None, @@ -249,6 +254,11 @@ class `flwr.client.Client` (default: None) - 'grpc-bidi': gRPC, bidirectional streaming - 'grpc-rere': gRPC, request-response (experimental) - 'rest': HTTP (experimental) + authentication_keys : Optional[Tuple[PrivateKey, PublicKey]] (default: None) + Tuple containing the elliptic curve private key and public key for + authentication from the cryptography library. + Source: https://cryptography.io/en/latest/hazmat/primitives/asymmetric/ec/ + Used to establish an authenticated connection with the server. max_retries: Optional[int] (default: None) The maximum number of times the client will try to connect to the server before giving up in case of a connection error. If set to None, diff --git a/src/py/flwr/client/grpc_rere_client/connection.py b/src/py/flwr/client/grpc_rere_client/connection.py index b4fa2837360..06701376fac 100644 --- a/src/py/flwr/client/grpc_rere_client/connection.py +++ b/src/py/flwr/client/grpc_rere_client/connection.py @@ -120,6 +120,9 @@ def grpc_request_response( # pylint: disable=R0913, R0914, R0915 authentication from the cryptography library. Source: https://cryptography.io/en/latest/hazmat/primitives/asymmetric/ec/ Used to establish an authenticated connection with the server. + adapter_cls: Optional[Union[type[FleetStub], type[GrpcAdapter]]] (default: None) + A GrpcStub Class that can be used to send messages. By default the FleetStub + will be used. Returns ------- diff --git a/src/py/flwr/common/message.py b/src/py/flwr/common/message.py index ce4fdb3dd82..4e792e8e02a 100644 --- a/src/py/flwr/common/message.py +++ b/src/py/flwr/common/message.py @@ -290,6 +290,11 @@ def create_error_reply(self, error: Error, ttl: float | None = None) -> Message: follows the equation: ttl = msg.meta.ttl - (reply.meta.created_at - msg.meta.created_at) + + Returns + ------- + message : Message + A Message containing only the relevant error and metadata. """ # If no TTL passed, use default for message creation (will update after # message creation) diff --git a/src/py/flwr/common/recordset_compat.py b/src/py/flwr/common/recordset_compat.py index 35024fcd67d..4641b8f29c9 100644 --- a/src/py/flwr/common/recordset_compat.py +++ b/src/py/flwr/common/recordset_compat.py @@ -59,6 +59,11 @@ def parametersrecord_to_parameters( keep_input : bool A boolean indicating whether entries in the record should be deleted from the input dictionary immediately after adding them to the record. + + Returns + ------- + parameters : Parameters + The parameters in the legacy format Parameters. """ parameters = Parameters(tensors=[], tensor_type="") @@ -94,6 +99,11 @@ def parameters_to_parametersrecord( A boolean indicating whether parameters should be deleted from the input Parameters object (i.e. a list of serialized NumPy arrays) immediately after adding them to the record. + + Returns + ------- + ParametersRecord + The ParametersRecord containing the provided parameters. """ tensor_type = parameters.tensor_type diff --git a/src/py/flwr/common/retry_invoker.py b/src/py/flwr/common/retry_invoker.py index 303d5596f23..9785b0fbd9b 100644 --- a/src/py/flwr/common/retry_invoker.py +++ b/src/py/flwr/common/retry_invoker.py @@ -38,6 +38,11 @@ def exponential( Factor by which the delay is multiplied after each retry. max_delay: Optional[float] (default: None) The maximum delay duration between two consecutive retries. + + Returns + ------- + Generator[float, None, None] + A generator for the delay between 2 retries. """ delay = base_delay if max_delay is None else min(base_delay, max_delay) while True: @@ -56,6 +61,11 @@ def constant( ---------- interval: Union[float, Iterable[float]] (default: 1) A constant value to yield or an iterable of such values. + + Returns + ------- + Generator[float, None, None] + A generator for the delay between 2 retries. """ if not isinstance(interval, Iterable): interval = itertools.repeat(interval) @@ -73,6 +83,11 @@ def full_jitter(max_value: float) -> float: ---------- max_value : float The upper limit for the randomized value. + + Returns + ------- + float + A random float that is less than max_value. """ return random.uniform(0, max_value) diff --git a/src/py/flwr/server/client_manager.py b/src/py/flwr/server/client_manager.py index 175bd4a786e..9949e29f8f7 100644 --- a/src/py/flwr/server/client_manager.py +++ b/src/py/flwr/server/client_manager.py @@ -47,6 +47,7 @@ def register(self, client: ClientProxy) -> bool: Parameters ---------- client : flwr.server.client_proxy.ClientProxy + The ClientProxy of the Client to register. Returns ------- @@ -64,6 +65,7 @@ def unregister(self, client: ClientProxy) -> None: Parameters ---------- client : flwr.server.client_proxy.ClientProxy + The ClientProxy of the Client to unregister. """ @abstractmethod diff --git a/src/py/flwr/server/superlink/fleet/grpc_bidi/grpc_server.py b/src/py/flwr/server/superlink/fleet/grpc_bidi/grpc_server.py index b161492000f..70283c0e129 100644 --- a/src/py/flwr/server/superlink/fleet/grpc_bidi/grpc_server.py +++ b/src/py/flwr/server/superlink/fleet/grpc_bidi/grpc_server.py @@ -174,7 +174,7 @@ def generic_create_grpc_server( # pylint: disable=too-many-arguments Parameters ---------- - servicer_and_add_fn : Tuple + servicer_and_add_fn : tuple A tuple holding a servicer implementation and a matching add_Servicer_to_server function. server_address : str @@ -214,6 +214,8 @@ def generic_create_grpc_server( # pylint: disable=too-many-arguments * CA certificate. * server certificate. * server private key. + interceptors : Optional[Sequence[grpc.ServerInterceptor]] (default: None) + A list of gRPC interceptors. Returns ------- diff --git a/src/py/flwr/server/superlink/state/sqlite_state.py b/src/py/flwr/server/superlink/state/sqlite_state.py index 73c121b01b4..182b55d6f77 100644 --- a/src/py/flwr/server/superlink/state/sqlite_state.py +++ b/src/py/flwr/server/superlink/state/sqlite_state.py @@ -151,6 +151,11 @@ def initialize(self, log_queries: bool = False) -> list[tuple[str]]: ---------- log_queries : bool Log each query which is executed. + + Returns + ------- + list[tuple[str]] + The list of all tables in the DB. """ self.conn = sqlite3.connect(self.database_path) self.conn.execute("PRAGMA foreign_keys = ON;") diff --git a/src/py/flwr/server/superlink/state/utils.py b/src/py/flwr/server/superlink/state/utils.py index 00ba02d2e43..db44719c6a8 100644 --- a/src/py/flwr/server/superlink/state/utils.py +++ b/src/py/flwr/server/superlink/state/utils.py @@ -100,11 +100,6 @@ def convert_uint64_values_in_dict_to_sint64( A dictionary where the values are integers to be converted. keys : list[str] A list of keys in the dictionary whose values need to be converted. - - Returns - ------- - None - This function does not return a value. It modifies `data_dict` in place. """ for key in keys: if key in data_dict: @@ -122,11 +117,6 @@ def convert_sint64_values_in_dict_to_uint64( A dictionary where the values are integers to be converted. keys : list[str] A list of keys in the dictionary whose values need to be converted. - - Returns - ------- - None - This function does not return a value. It modifies `data_dict` in place. """ for key in keys: if key in data_dict: