Improve coerce_context() documentation

Author: xolox

linux_utils/__init__.py

@@ -1,7 +1,7 @@
 # linux-utils: Linux system administration tools for Python.
 #
 # Author: Peter Odding <[email protected]>
-# Last Change: July 3, 2018
+# Last Change: February 9, 2020
 # URL: https://linux-utils.readthedocs.io
 
 """Linux system administration tools for Python."""
@@ -30,13 +30,26 @@
 
 def coerce_context(value):
     """
-    Coerce a value to an execution context.
+    Coerce the given value to an execution context.
 
     :param value: The value to coerce (an execution context created
                   by :mod:`executor.contexts` or :data:`None`).
     :returns: An execution context created by :mod:`executor.contexts`.
     :raises: :exc:`~exceptions.ValueError` when `value` isn't :data:`None`
              but also isn't a valid execution context.
+
+    This function is used throughout the modules in the :mod:`linux_utils`
+    package to abstract away the details of external command execution using
+    `dependency injection`_:
+
+    - If no execution context is provided (`value` is :data:`None`)
+      :class:`executor.contexts.LocalContext` is used by default.
+
+    - Callers can provide :class:`executor.contexts.RemoteContext` in
+      which case the :mod:`linux_utils` package seamlessly adapts to
+      command execution on a remote system over :man:`ssh`.
+
+    .. _dependency injection: https://en.wikipedia.org/wiki/Dependency_injection
     """
     if value is None:
         value = LocalContext()

linux_utils/crypttab.py

@@ -1,7 +1,7 @@
 # linux-utils: Linux system administration tools for Python.
 #
 # Author: Peter Odding <[email protected]>
-# Last Change: July 3, 2018
+# Last Change: February 9, 2020
 # URL: https://linux-utils.readthedocs.io
 
 """
@@ -55,8 +55,7 @@ def parse_crypttab(filename='/etc/crypttab', context=None):
 
     :param filename: The absolute pathname of the file to parse (a string,
                      defaults to ``/etc/crypttab``).
-    :param context: An execution context created by :mod:`executor.contexts`
-                    (coerced using :func:`.coerce_context()`).
+    :param context: See :func:`.coerce_context()` for details.
     :returns: A generator of :class:`EncryptedFileSystemEntry` objects.
 
     Here's an example:

linux_utils/fstab.py

@@ -39,8 +39,7 @@ def find_mounted_filesystems(filename='/proc/mounts', context=None):
 
     :param filename: The absolute pathname of the file to parse (a string,
                      defaults to ``/proc/mounts``).
-    :param context: An execution context created by :mod:`executor.contexts`
-                    (coerced using :func:`.coerce_context()`).
+    :param context: See :func:`.coerce_context()` for details.
     :returns: A generator of :class:`FileSystemEntry` objects.
 
     This function is a trivial wrapper for :func:`parse_fstab()` that instructs
@@ -81,8 +80,7 @@ def parse_fstab(filename='/etc/fstab', context=None):
 
     :param filename: The absolute pathname of the file to parse (a string,
                      defaults to `/etc/fstab`_).
-    :param context: An execution context created by :mod:`executor.contexts`
-                    (coerced using :func:`.coerce_context()`).
+    :param context: See :func:`.coerce_context()` for details.
     :returns: A generator of :class:`FileSystemEntry` objects.
 
     Here's an example:

linux_utils/luks.py

@@ -89,8 +89,7 @@ def create_image_file(filename, size, context=None):
 
     :param filename: The pathname of the image file (a string).
     :param size: How large the image file should be (see :func:`.coerce_size()`).
-    :param context: An execution context created by :mod:`executor.contexts`
-                    (coerced using :func:`.coerce_context()`).
+    :param context: See :func:`.coerce_context()` for details.
     :raises: :exc:`~exceptions.ValueError` when `size` is invalid,
              :exc:`~executor.ExternalCommandFailed` when the command fails.
     """
@@ -108,8 +107,7 @@ def generate_key_file(filename, size=DEFAULT_KEY_SIZE, context=None):
     :param filename: The pathname of the key file (a string).
     :param size: How large the key file should be (see :func:`.coerce_size()`,
                  defaults to :data:`DEFAULT_KEY_SIZE`).
-    :param context: An execution context created by :mod:`executor.contexts`
-                    (coerced using :func:`.coerce_context()`).
+    :param context: See :func:`.coerce_context()` for details.
     :raises: :exc:`~executor.ExternalCommandFailed` when the command fails.
     """
     context = coerce_context(context)
@@ -134,8 +132,7 @@ def create_encrypted_filesystem(device_file, key_file=None, context=None):
     :param device_file: The pathname of the block special device or file (a string).
     :param key_file: The pathname of the key file used to encrypt the
                      filesystem (a string or :data:`None`).
-    :param context: An execution context created by :mod:`executor.contexts`
-                    (coerced using :func:`.coerce_context()`).
+    :param context: See :func:`.coerce_context()` for details.
     :raises: :exc:`~executor.ExternalCommandFailed` when the command fails.
 
     If no `key_file` is given the operator is prompted to choose a password.
@@ -164,8 +161,7 @@ def unlock_filesystem(device_file, target, key_file=None, options=None, context=
                     :data:`None` (in which case the default options are used).
                     Currently 'discard', 'readonly' and 'tries' are the only
                     supported options (other options are silently ignored).
-    :param context: An execution context created by :mod:`executor.contexts`
-                    (coerced using :func:`.coerce_context()`).
+    :param context: See :func:`.coerce_context()` for details.
     :raises: :exc:`~executor.ExternalCommandFailed` when the command fails.
 
     If no `key_file` is given the operator is prompted to enter a password.
@@ -205,8 +201,7 @@ def lock_filesystem(target, context=None):
     Lock a currently unlocked LUKS filesystem.
 
     :param target: The mapped device name (a string).
-    :param context: An execution context created by :mod:`executor.contexts`
-                    (coerced using :func:`.coerce_context()`).
+    :param context: See :func:`.coerce_context()` for details.
     :raises: :exc:`~executor.ExternalCommandFailed` when the command fails.
     """
     context = coerce_context(context)
@@ -220,8 +215,7 @@ def cryptdisks_start(target, context=None):
     Execute :man:`cryptdisks_start` or emulate its functionality.
 
     :param target: The mapped device name (a string).
-    :param context: An execution context created by :mod:`executor.contexts`
-                    (coerced using :func:`.coerce_context()`).
+    :param context: See :func:`.coerce_context()` for details.
     :raises: :exc:`~executor.ExternalCommandFailed` when a command fails,
              :exc:`~exceptions.ValueError` when no entry in `/etc/crypttab`_
              matches `target`.
@@ -255,8 +249,7 @@ def cryptdisks_stop(target, context=None):
     Execute :man:`cryptdisks_stop` or emulate its functionality.
 
     :param target: The mapped device name (a string).
-    :param context: An execution context created by :mod:`executor.contexts`
-                    (coerced using :func:`.coerce_context()`).
+    :param context: See :func:`.coerce_context()` for details.
     :raises: :exc:`~executor.ExternalCommandFailed` when a command fails,
              :exc:`~exceptions.ValueError` when no entry in `/etc/crypttab`_
              matches `target`.

linux_utils/tabfile.py

@@ -1,7 +1,7 @@
 # linux-utils: Linux system administration tools for Python.
 #
 # Author: Peter Odding <[email protected]>
-# Last Change: June 24, 2017
+# Last Change: February 9, 2020
 # URL: https://linux-utils.readthedocs.io
 
 """Generic parsing of Linux configuration files like ``/etc/fstab`` and ``/etc/crypttab``."""
@@ -27,8 +27,7 @@ def parse_tab_file(filename, context=None, encoding='UTF-8'):
     Parse a Linux configuration file like ``/etc/fstab`` or ``/etc/crypttab``.
 
     :param filename: The absolute pathname of the file to parse (a string).
-    :param context: An execution context created by :mod:`executor.contexts`
-                    (coerced using :func:`.coerce_context()`).
+    :param context: See :func:`.coerce_context()` for details.
     :param encoding: The name of the text encoding of the file (a string).
     :returns: A generator of :class:`TabFileEntry` objects.