Consolidate ExportVaultConfigDataFunction documentation (75ea784) - derivepassphrase.git

Consolidate ExportVaultConfigDataFunction documentation

Marco Ricci commited on 2025-01-19 14:27:33
Zeige 3 geänderte Dateien mit 71 Einfügungen und 109 Löschungen.

Instead of duplicating the argument and exception descriptions in each
function adhering to the protocol, document the protocol, and have the
implementing function reference the protocol.  (In the current
documentation layout, this is all on the same page anyway.)

src/derivepassphrase/exporter/__init__.py 7c21028..0e224eb
src/derivepassphrase/exporter/storeroom.py 5bf4188..a4fe499
src/derivepassphrase/exporter/vault_native.py a5c7bed..1296702

src/derivepassphrase/exporter/__init__.py

Zeige Datei @ 75ea784

@@ -106,13 +106,66 @@ def get_vault_path() -> str | bytes | os.PathLike:
 
 
 class ExportVaultConfigDataFunction(Protocol):  # pragma: no cover
+    """Typing protocol for vault config data export handlers."""
+
     def __call__(
         self,
         path: str | bytes | os.PathLike | None = None,
         key: str | Buffer | None = None,
         *,
         format: str,  # noqa: A002
-    ) -> Any: ...  # noqa: ANN401
+    ) -> Any:  # noqa: ANN401
+        """Export the full vault-native configuration stored in `path`.
+
+        Args:
+            path:
+                The path to the vault configuration file or directory.
+                If not given, then query [`get_vault_path`][] for the
+                correct value.
+            key:
+                Encryption key/password for the configuration file or
+                directory, usually the username, or passed via the
+                `VAULT_KEY` environment variable.  If not given, then
+                query [`get_vault_key`][] for the value.
+            format:
+                The format to attempt parsing as.  Must be `v0.2`,
+                `v0.3` or `storeroom`.
+
+        Returns:
+            The vault configuration, as recorded in the configuration
+            file.
+
+            This may or may not be a valid configuration according to
+            `vault` or `derivepassphrase`.
+
+        Raises:
+            IsADirectoryError:
+                The requested format requires a configuration file, but
+                `path` points to a directory instead.
+            NotADirectoryError:
+                The requested format requires a configuration directory,
+                but `path` points to something else instead.
+            OSError:
+                There was an OS error while accessing the configuration
+                file/directory.
+            RuntimeError:
+                Something went wrong during data collection, e.g. we
+                encountered unsupported or corrupted data in the
+                configuration file/directory.
+            json.JSONDecodeError:
+                An internal JSON data structure failed to parse from
+                disk.  The configuration file/directory is probably
+                corrupted.
+            exporter.NotAVaultConfigError:
+                The file/directory contents are not in the claimed
+                configuration format.
+            ValueError:
+                The requested format is invalid.
+            ModuleNotFoundError:
+                The requested format requires support code, which failed
+                to load because of missing Python libraries.
+
+        """
 
 
 _export_vault_config_data_registry: dict[
@@ -170,53 +223,10 @@ def export_vault_config_data(
 ) -> Any:  # noqa: ANN401
     """Export the full vault-native configuration stored in `path`.
 
-    Args:
-        path:
-            The path to the vault configuration file or directory.  If
-            not given, then query [`get_vault_path`][] for the correct
-            value.
-        key:
-            Encryption key/password for the configuration file or
-            directory, usually the username, or passed via the
-            `VAULT_KEY` environment variable.  If not given, then query
-            [`exporter.get_vault_key`][] for the value.
-        format:
-            The format to attempt parsing as.  Must be `v0.2`, `v0.3` or
-            `storeroom`.
-
-    Returns:
-        The vault configuration, as recorded in the configuration file.
-
-        This may or may not be a valid configuration according to
-        `vault` or `derivepassphrase`.
-
-    Raises:
-        IsADirectoryError:
-            The requested format requires a configuration file, but
-            `path` points to a directory instead.
-        NotADirectoryError:
-            The requested format requires a configuration directory, but
-            `path` points to something else instead.
-        OSError:
-            There was an OS error while accessing the configuration
-            file/directory.
-        RuntimeError:
-            Something went wrong during data collection, e.g. we
-            encountered unsupported or corrupted data in the
-            configuration file/directory.
-        json.JSONDecodeError:
-            An internal JSON data structure failed to parse from disk.
-            The configuration file/directory is probably corrupted.
-        exporter.NotAVaultConfigError:
-            The file/directory contents are not in the claimed
-            configuration format.
-        ValueError:
-            The requested format is invalid.
-        ModuleNotFoundError:
-            The requested format requires support code, which failed to
-            load because of missing Python libraries.
+    See [`ExportVaultConfigDataFunction`][] for an explanation of the
+    call signature, and the exceptions to expect.
 
-    """
+    """  # noqa: DOC201,DOC501
     find_vault_config_data_handlers()
     handler = _export_vault_config_data_registry.get(format)
     if handler is None:

src/derivepassphrase/exporter/storeroom.py

Zeige Datei @ 75ea784

@@ -586,7 +586,7 @@ def _store(config: dict[str, Any], path: str, json_contents: bytes) -> None:
 
 
 @exporter.register_export_vault_config_data_handler('storeroom')
-def export_storeroom_data(  # noqa: C901,PLR0912,PLR0914,PLR0915
+def export_storeroom_data(  # noqa: C901,D417,PLR0912,PLR0914,PLR0915
     path: str | bytes | os.PathLike | None = None,
     key: str | Buffer | None = None,
     *,
@@ -594,40 +594,14 @@ def export_storeroom_data(  # noqa: C901,PLR0912,PLR0914,PLR0915
 ) -> dict[str, Any]:
     """Export the full configuration stored in the storeroom.
 
-    Args:
-        path:
-            The path to the vault configuration directory.  If not
-            given, then query [`exporter.get_vault_path`][] for the
-            correct value.
-        key:
-            Encryption key/password for the (master keys file in the)
-            configuration directory, usually the username, or passed via
-            the `VAULT_KEY` environment variable.  If not given, then
-            query [`exporter.get_vault_key`][] for the value.
-        format:
-            The format to attempt parsing as.  If specified, must be
-            `storeroom`.
-
-    Returns:
-        The vault configuration, as recorded in the configuration
-        directory.
-
-        This may or may not be a valid configuration according to
-        `vault` or `derivepassphrase`.
+    See [`exporter.ExportVaultConfigDataFunction`][] for an explanation
+    of the call signature, and the exceptions to expect.
 
-    Raises:
-        RuntimeError:
-            Something went wrong during data collection, e.g. we
-            encountered unsupported or corrupted data in the storeroom.
-        json.JSONDecodeError:
-            An internal JSON data structure failed to parse from disk.
-            The storeroom is probably corrupted.
-        exporter.NotAVaultConfigError:
-            The directory does contain not a storeroom.
-        ValueError:
-            The requested format is invalid.
+    Other Args:
+        format:
+            The only supported format is `storeroom`.
 
-    """
+    """  # noqa: DOC201,DOC501
     # Trigger import errors if necessary.
     importlib.import_module('cryptography')
     if path is None:

src/derivepassphrase/exporter/vault_native.py

Zeige Datei @ 75ea784

@@ -433,7 +433,7 @@ class VaultNativeV02ConfigParser(VaultNativeConfigParser):
 
 
 @exporter.register_export_vault_config_data_handler('v0.2', 'v0.3')
-def export_vault_native_data(
+def export_vault_native_data(  # noqa: D417
     path: str | bytes | os.PathLike | None = None,
     key: str | Buffer | None = None,
     *,
@@ -441,36 +441,14 @@ def export_vault_native_data(
 ) -> Any:  # noqa: ANN401
     """Export the full configuration stored in vault native format.
 
-    Args:
-        path:
-            The path to the vault configuration file.  If not given,
-            then query [`exporter.get_vault_path`][] for the correct
-            value.
-        key:
-            Encryption key/password for the configuration file, usually
-            the username, or passed via the `VAULT_KEY` environment
-            variable.  If not given, then query
-            [`exporter.get_vault_key`][] for the value.
-        format:
-            The format to attempt parsing as.  Must be `v0.2` or `v0.3`.
-
-    Returns:
-        The vault configuration, as recorded in the configuration file.
-
-        This may or may not be a valid configuration according to
-        `vault` or `derivepassphrase`.
+    See [`exporter.ExportVaultConfigDataFunction`][] for an explanation
+    of the call signature, and the exceptions to expect.
 
-    Raises:
-        json.JSONDecodeError:
-            An internal JSON data structure failed to parse from disk.
-            The encrypted configuration is probably corrupted.
-        exporter.NotAVaultConfigError:
-            The (encrypted) contents are not in the claimed
-            configuration format.
-        ValueError:
-            The requested format is invalid.
+    Other Args:
+        format:
+            The only supported formats are `v0.2` and `v0.3`.
 
-    """
+    """  # noqa: DOC201,DOC501
     # Trigger import errors if necessary.
     importlib.import_module('cryptography')
     if path is None:


...	...	@@ -106,13 +106,66 @@ def get_vault_path() -> str \| bytes \| os.PathLike:
106	106
107	107
108	108	class ExportVaultConfigDataFunction(Protocol): # pragma: no cover
	109	+ """Typing protocol for vault config data export handlers."""
	110	+
109	111	def __call__(
110	112	self,
111	113	path: str \| bytes \| os.PathLike \| None = None,
112	114	key: str \| Buffer \| None = None,
113	115	*,
114	116	format: str, # noqa: A002
115		- ) -> Any: ... # noqa: ANN401
	117	+ ) -> Any: # noqa: ANN401
	118	+ """Export the full vault-native configuration stored in `path`.
	119	+
	120	+ Args:
	121	+ path:
	122	+ The path to the vault configuration file or directory.
	123	+ If not given, then query [`get_vault_path`][] for the
	124	+ correct value.
	125	+ key:
	126	+ Encryption key/password for the configuration file or
	127	+ directory, usually the username, or passed via the
	128	+ `VAULT_KEY` environment variable. If not given, then
	129	+ query [`get_vault_key`][] for the value.
	130	+ format:
	131	+ The format to attempt parsing as. Must be `v0.2`,
	132	+ `v0.3` or `storeroom`.
	133	+
	134	+ Returns:
	135	+ The vault configuration, as recorded in the configuration
	136	+ file.
	137	+
	138	+ This may or may not be a valid configuration according to
	139	+ `vault` or `derivepassphrase`.
	140	+
	141	+ Raises:
	142	+ IsADirectoryError:
	143	+ The requested format requires a configuration file, but
	144	+ `path` points to a directory instead.
	145	+ NotADirectoryError:
	146	+ The requested format requires a configuration directory,
	147	+ but `path` points to something else instead.
	148	+ OSError:
	149	+ There was an OS error while accessing the configuration
	150	+ file/directory.
	151	+ RuntimeError:
	152	+ Something went wrong during data collection, e.g. we
	153	+ encountered unsupported or corrupted data in the
	154	+ configuration file/directory.
	155	+ json.JSONDecodeError:
	156	+ An internal JSON data structure failed to parse from
	157	+ disk. The configuration file/directory is probably
	158	+ corrupted.
	159	+ exporter.NotAVaultConfigError:
	160	+ The file/directory contents are not in the claimed
	161	+ configuration format.
	162	+ ValueError:
	163	+ The requested format is invalid.
	164	+ ModuleNotFoundError:
	165	+ The requested format requires support code, which failed
	166	+ to load because of missing Python libraries.
	167	+
	168	+ """
116	169
117	170
118	171	_export_vault_config_data_registry: dict[
...	...	@@ -170,53 +223,10 @@ def export_vault_config_data(
170	223	) -> Any: # noqa: ANN401
171	224	"""Export the full vault-native configuration stored in `path`.
172	225
173		- Args:
174		- path:
175		- The path to the vault configuration file or directory. If
176		- not given, then query [`get_vault_path`][] for the correct
177		- value.
178		- key:
179		- Encryption key/password for the configuration file or
180		- directory, usually the username, or passed via the
181		- `VAULT_KEY` environment variable. If not given, then query
182		- [`exporter.get_vault_key`][] for the value.
183		- format:
184		- The format to attempt parsing as. Must be `v0.2`, `v0.3` or
185		- `storeroom`.
186		-
187		- Returns:
188		- The vault configuration, as recorded in the configuration file.
189		-
190		- This may or may not be a valid configuration according to
191		- `vault` or `derivepassphrase`.
192		-
193		- Raises:
194		- IsADirectoryError:
195		- The requested format requires a configuration file, but
196		- `path` points to a directory instead.
197		- NotADirectoryError:
198		- The requested format requires a configuration directory, but
199		- `path` points to something else instead.
200		- OSError:
201		- There was an OS error while accessing the configuration
202		- file/directory.
203		- RuntimeError:
204		- Something went wrong during data collection, e.g. we
205		- encountered unsupported or corrupted data in the
206		- configuration file/directory.
207		- json.JSONDecodeError:
208		- An internal JSON data structure failed to parse from disk.
209		- The configuration file/directory is probably corrupted.
210		- exporter.NotAVaultConfigError:
211		- The file/directory contents are not in the claimed
212		- configuration format.
213		- ValueError:
214		- The requested format is invalid.
215		- ModuleNotFoundError:
216		- The requested format requires support code, which failed to
217		- load because of missing Python libraries.
	226	+ See [`ExportVaultConfigDataFunction`][] for an explanation of the
	227	+ call signature, and the exceptions to expect.
218	228
219		- """
	229	+ """ # noqa: DOC201,DOC501
220	230	find_vault_config_data_handlers()
221	231	handler = _export_vault_config_data_registry.get(format)
222	232	if handler is None:

...	...	@@ -586,7 +586,7 @@ def _store(config: dict[str, Any], path: str, json_contents: bytes) -> None:
586	586
587	587
588	588	@exporter.register_export_vault_config_data_handler('storeroom')
589		-def export_storeroom_data( # noqa: C901,PLR0912,PLR0914,PLR0915
	589	+def export_storeroom_data( # noqa: C901,D417,PLR0912,PLR0914,PLR0915
590	590	path: str \| bytes \| os.PathLike \| None = None,
591	591	key: str \| Buffer \| None = None,
592	592	*,
...	...	@@ -594,40 +594,14 @@ def export_storeroom_data( # noqa: C901,PLR0912,PLR0914,PLR0915
594	594	) -> dict[str, Any]:
595	595	"""Export the full configuration stored in the storeroom.
596	596
597		- Args:
598		- path:
599		- The path to the vault configuration directory. If not
600		- given, then query [`exporter.get_vault_path`][] for the
601		- correct value.
602		- key:
603		- Encryption key/password for the (master keys file in the)
604		- configuration directory, usually the username, or passed via
605		- the `VAULT_KEY` environment variable. If not given, then
606		- query [`exporter.get_vault_key`][] for the value.
607		- format:
608		- The format to attempt parsing as. If specified, must be
609		- `storeroom`.
610		-
611		- Returns:
612		- The vault configuration, as recorded in the configuration
613		- directory.
614		-
615		- This may or may not be a valid configuration according to
616		- `vault` or `derivepassphrase`.
	597	+ See [`exporter.ExportVaultConfigDataFunction`][] for an explanation
	598	+ of the call signature, and the exceptions to expect.
617	599
618		- Raises:
619		- RuntimeError:
620		- Something went wrong during data collection, e.g. we
621		- encountered unsupported or corrupted data in the storeroom.
622		- json.JSONDecodeError:
623		- An internal JSON data structure failed to parse from disk.
624		- The storeroom is probably corrupted.
625		- exporter.NotAVaultConfigError:
626		- The directory does contain not a storeroom.
627		- ValueError:
628		- The requested format is invalid.
	600	+ Other Args:
	601	+ format:
	602	+ The only supported format is `storeroom`.
629	603
630		- """
	604	+ """ # noqa: DOC201,DOC501
631	605	# Trigger import errors if necessary.
632	606	importlib.import_module('cryptography')
633	607	if path is None:

...	...	@@ -433,7 +433,7 @@ class VaultNativeV02ConfigParser(VaultNativeConfigParser):
433	433
434	434
435	435	@exporter.register_export_vault_config_data_handler('v0.2', 'v0.3')
436		-def export_vault_native_data(
	436	+def export_vault_native_data( # noqa: D417
437	437	path: str \| bytes \| os.PathLike \| None = None,
438	438	key: str \| Buffer \| None = None,
439	439	*,
...	...	@@ -441,36 +441,14 @@ def export_vault_native_data(
441	441	) -> Any: # noqa: ANN401
442	442	"""Export the full configuration stored in vault native format.
443	443
444		- Args:
445		- path:
446		- The path to the vault configuration file. If not given,
447		- then query [`exporter.get_vault_path`][] for the correct
448		- value.
449		- key:
450		- Encryption key/password for the configuration file, usually
451		- the username, or passed via the `VAULT_KEY` environment
452		- variable. If not given, then query
453		- [`exporter.get_vault_key`][] for the value.
454		- format:
455		- The format to attempt parsing as. Must be `v0.2` or `v0.3`.
456		-
457		- Returns:
458		- The vault configuration, as recorded in the configuration file.
459		-
460		- This may or may not be a valid configuration according to
461		- `vault` or `derivepassphrase`.
	444	+ See [`exporter.ExportVaultConfigDataFunction`][] for an explanation
	445	+ of the call signature, and the exceptions to expect.
462	446
463		- Raises:
464		- json.JSONDecodeError:
465		- An internal JSON data structure failed to parse from disk.
466		- The encrypted configuration is probably corrupted.
467		- exporter.NotAVaultConfigError:
468		- The (encrypted) contents are not in the claimed
469		- configuration format.
470		- ValueError:
471		- The requested format is invalid.
	447	+ Other Args:
	448	+ format:
	449	+ The only supported formats are `v0.2` and `v0.3`.
472	450
473		- """
	451	+ """ # noqa: DOC201,DOC501
474	452	# Trigger import errors if necessary.
475	453	importlib.import_module('cryptography')
476	454	if path is None:
477	455