Add missing doc stubs, use f-strings, add CLI examples

doc/ref/modules/all/salt.modules.win_appx.rst

@@ -0,0 +1,5 @@
+salt.modules.win_appx
+=====================
+
+.. automodule:: salt.modules.win_appx
+    :members:

doc/ref/states/all/salt.states.win_appx.rst

@@ -0,0 +1,5 @@
+salt.states.win_appx
+====================
+
+.. automodule:: salt.states.win_appx
+    :members:

salt/modules/win_appx.py

@@ -236,7 +236,7 @@ def remove(query=None, include_store=False, frameworks=False, deprovision_only=F
 
     .. code-block:: bash
 
-        salt
+        salt "*" appx.remove *candy*
     """
     packages = list_(
         query=query,
@@ -309,6 +309,12 @@ def list_deprovisioned(query=None):
 
     Returns:
         list: A list of packages matching the query criteria
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt "*" appx.list_deprovisioned *zune*
     """
     ret = salt.utils.win_reg.list_keys(hive="HKLM", key=f"{DEPROVISIONED_KEY}")
     if query is None:
@@ -341,6 +347,12 @@ def install(package):
 
     Returns:
         bool: ``True`` if successful, otherwise ``False``
+
+    CLI Example:
+
+    .. code-block:: bash
+
+        salt "*" appx.install "C:\\Temp\\Microsoft.ZuneMusic.msixbundle"
     """
     # I don't see a way to make the app installed for existing users on
     # the system. The best we can do is provision the package for new

salt/modules/win_dism.py

@@ -52,14 +52,14 @@ def _get_components(type_regex, plural_type, install_value, image=None):
     cmd = [
         bin_dism,
         "/English",
-        "/Image:{}".format(image) if image else "/Online",
-        "/Get-{}".format(plural_type),
+        f"/Image:{image}" if image else "/Online",
+        f"/Get-{plural_type}",
     ]
     out = __salt__["cmd.run"](cmd)
     if install_value:
-        pattern = r"{} : (.*)\r\n.*State : {}\r\n".format(type_regex, install_value)
+        pattern = rf"{type_regex} : (.*)\r\n.*State : {install_value}\r\n"
     else:
-        pattern = r"{} : (.*)\r\n.*".format(type_regex, install_value)
+        pattern = rf"{type_regex} : (.*)\r\n.*"
     capabilities = re.findall(pattern, out, re.MULTILINE)
     capabilities.sort()
     return capabilities
@@ -98,19 +98,19 @@ def add_capability(
     if salt.utils.versions.version_cmp(__grains__["osversion"], "10") == -1:
         raise NotImplementedError(
             "`install_capability` is not available on this version of Windows: "
-            "{}".format(__grains__["osversion"])
+            f'{__grains__["osversion"]}'
         )
 
     cmd = [
         bin_dism,
         "/Quiet",
-        "/Image:{}".format(image) if image else "/Online",
+        f"/Image:{image}" if image else "/Online",
         "/Add-Capability",
-        "/CapabilityName:{}".format(capability),
+        f"/CapabilityName:{capability}",
     ]
 
     if source:
-        cmd.append("/Source:{}".format(source))
+        cmd.append(f"/Source:{source}")
     if limit_access:
         cmd.append("/LimitAccess")
     if not restart:
@@ -146,15 +146,15 @@ def remove_capability(capability, image=None, restart=False):
     if salt.utils.versions.version_cmp(__grains__["osversion"], "10") == -1:
         raise NotImplementedError(
             "`uninstall_capability` is not available on this version of "
-            "Windows: {}".format(__grains__["osversion"])
+            f'Windows: {__grains__["osversion"]}'
         )
 
     cmd = [
         bin_dism,
         "/Quiet",
-        "/Image:{}".format(image) if image else "/Online",
+        f"/Image:{image}" if image else "/Online",
         "/Remove-Capability",
-        "/CapabilityName:{}".format(capability),
+        f"/CapabilityName:{capability}",
     ]
 
     if not restart:
@@ -188,13 +188,13 @@ def get_capabilities(image=None):
     if salt.utils.versions.version_cmp(__grains__["osversion"], "10") == -1:
         raise NotImplementedError(
             "`installed_capabilities` is not available on this version of "
-            "Windows: {}".format(__grains__["osversion"])
+            f'Windows: {__grains__["osversion"]}'
         )
 
     cmd = [
         bin_dism,
         "/English",
-        "/Image:{}".format(image) if image else "/Online",
+        f"/Image:{image}" if image else "/Online",
         "/Get-Capabilities",
     ]
     out = __salt__["cmd.run"](cmd)
@@ -231,7 +231,7 @@ def installed_capabilities(image=None):
     if salt.utils.versions.version_cmp(__grains__["osversion"], "10") == -1:
         raise NotImplementedError(
             "`installed_capabilities` is not available on this version of "
-            "Windows: {}".format(__grains__["osversion"])
+            f'Windows: {__grains__["osversion"]}'
         )
     return _get_components("Capability Identity", "Capabilities", "Installed")
 
@@ -261,7 +261,7 @@ def available_capabilities(image=None):
     if salt.utils.versions.version_cmp(__grains__["osversion"], "10") == -1:
         raise NotImplementedError(
             "`installed_capabilities` is not available on this version of "
-            "Windows: {}".format(__grains__["osversion"])
+            f'Windows: {__grains__["osversion"]}'
         )
     return _get_components("Capability Identity", "Capabilities", "Not Present")
 
@@ -306,14 +306,14 @@ def add_feature(
     cmd = [
         bin_dism,
         "/Quiet",
-        "/Image:{}".format(image) if image else "/Online",
+        f"/Image:{image}" if image else "/Online",
         "/Enable-Feature",
-        "/FeatureName:{}".format(feature),
+        f"/FeatureName:{feature}",
     ]
     if package:
-        cmd.append("/PackageName:{}".format(package))
+        cmd.append(f"/PackageName:{package}")
     if source:
-        cmd.append("/Source:{}".format(source))
+        cmd.append(f"/Source:{source}")
     if limit_access:
         cmd.append("/LimitAccess")
     if enable_parent:
@@ -349,9 +349,9 @@ def remove_feature(feature, remove_payload=False, image=None, restart=False):
     cmd = [
         bin_dism,
         "/Quiet",
-        "/Image:{}".format(image) if image else "/Online",
+        f"/Image:{image}" if image else "/Online",
         "/Disable-Feature",
-        "/FeatureName:{}".format(feature),
+        f"/FeatureName:{feature}",
     ]
 
     if remove_payload:
@@ -397,15 +397,15 @@ def get_features(package=None, image=None):
     cmd = [
         bin_dism,
         "/English",
-        "/Image:{}".format(image) if image else "/Online",
+        f"/Image:{image}" if image else "/Online",
         "/Get-Features",
     ]
 
     if package:
         if "~" in package:
-            cmd.append("/PackageName:{}".format(package))
+            cmd.append(f"/PackageName:{package}")
         else:
-            cmd.append("/PackagePath:{}".format(package))
+            cmd.append(f"/PackagePath:{package}")
 
     out = __salt__["cmd.run"](cmd)
 
@@ -499,9 +499,9 @@ def add_package(
     cmd = [
         bin_dism,
         "/Quiet",
-        "/Image:{}".format(image) if image else "/Online",
+        f"/Image:{image}" if image else "/Online",
         "/Add-Package",
-        "/PackagePath:{}".format(package),
+        f"/PackagePath:{package}",
     ]
 
     if ignore_check:
@@ -554,9 +554,9 @@ def add_provisioned_package(package, image=None, restart=False):
     cmd = [
         bin_dism,
         "/Quiet",
-        "/Image:{}".format(image) if image else "/Online",
+        f"/Image:{image}" if image else "/Online",
         "/Add-ProvisionedAppxPackage",
-        "/PackagePath:{}".format(package),
+        f"/PackagePath:{package}",
         "/SkipLicense",
     ]
 
@@ -597,7 +597,7 @@ def remove_package(package, image=None, restart=False):
     cmd = [
         bin_dism,
         "/Quiet",
-        "/Image:{}".format(image) if image else "/Online",
+        f"/Image:{image}" if image else "/Online",
         "/Remove-Package",
     ]
 
@@ -605,9 +605,9 @@ def remove_package(package, image=None, restart=False):
         cmd.append("/NoRestart")
 
     if "~" in package:
-        cmd.append("/PackageName:{}".format(package))
+        cmd.append(f"/PackageName:{package}")
     else:
-        cmd.append("/PackagePath:{}".format(package))
+        cmd.append(f"/PackagePath:{package}")
 
     return __salt__["cmd.run_all"](cmd)
 
@@ -639,9 +639,9 @@ def get_kb_package_name(kb, image=None):
         salt '*' dism.get_kb_package_name 1231231
     """
     packages = installed_packages(image=image)
-    search = kb.upper() if kb.lower().startswith("kb") else "KB{}".format(kb)
+    search = kb.upper() if kb.lower().startswith("kb") else f"KB{kb}"
     for package in packages:
-        if "_{}~".format(search) in package:
+        if f"_{search}~" in package:
             return package
     return None
 
@@ -677,7 +677,7 @@ def remove_kb(kb, image=None, restart=False):
     """
     pkg_name = get_kb_package_name(kb=kb, image=image)
     if pkg_name is None:
-        msg = "{} not installed".format(kb)
+        msg = f"{kb} not installed"
         raise CommandExecutionError(msg)
     log.debug("Found: %s", pkg_name)
     return remove_package(package=pkg_name, image=image, restart=restart)
@@ -760,14 +760,14 @@ def package_info(package, image=None):
     cmd = [
         bin_dism,
         "/English",
-        "/Image:{}".format(image) if image else "/Online",
+        f"/Image:{image}" if image else "/Online",
         "/Get-PackageInfo",
     ]
 
     if "~" in package:
-        cmd.append("/PackageName:{}".format(package))
+        cmd.append(f"/PackageName:{package}")
     else:
-        cmd.append("/PackagePath:{}".format(package))
+        cmd.append(f"/PackagePath:{package}")
 
     out = __salt__["cmd.run_all"](cmd)
 

salt/states/win_appx.py

@@ -81,9 +81,11 @@ def absent(name, query, include_store=False, frameworks=False, deprovision_only=
 
     CLI Example:
 
-    .. code-block:: bash
+    .. code-block:: yaml
 
-        salt
+        remove_candy_crush:
+          appx.absent:
+            query: *candy*
     """
     ret = {"name": name, "result": True, "comment": "", "changes": {}}
 

salt/states/win_servermanager.py

@@ -28,7 +28,7 @@ def installed(
     restart=False,
     source=None,
     exclude=None,
-    **kwargs
+    **kwargs,
 ):
     """
     Install the windows feature. To install a single feature, use the ``name``
@@ -137,7 +137,7 @@ def installed(
     for feature in features:
 
         if feature not in old:
-            ret["changes"][feature] = "Will be installed recurse={}".format(recurse)
+            ret["changes"][feature] = f"Will be installed recurse={recurse}"
         elif recurse:
             ret["changes"][feature] = "Already installed but might install sub-features"
         else:
@@ -168,13 +168,13 @@ def installed(
     for feature in status["Features"]:
         # Features that failed to install or be removed
         if not status["Features"][feature].get("Success", True):
-            fail_feat.append("- {}".format(feature))
+            fail_feat.append(f"- {feature}")
         # Features that installed
         elif "(exclude)" not in status["Features"][feature]["Message"]:
-            new_feat.append("- {}".format(feature))
+            new_feat.append(f"- {feature}")
         # Show items that were removed because they were part of `exclude`
         elif "(exclude)" in status["Features"][feature]["Message"]:
-            rem_feat.append("- {}".format(feature))
+            rem_feat.append(f"- {feature}")
 
     if fail_feat:
         fail_feat.insert(0, "Failed to install the following:")
@@ -302,10 +302,10 @@ def removed(name, features=None, remove_payload=False, restart=False):
         # feature is already uninstalled
         if not status["Features"][feature].get("Success", True):
             # Show items that failed to uninstall
-            fail_feat.append("- {}".format(feature))
+            fail_feat.append(f"- {feature}")
         else:
             # Show items that uninstalled
-            rem_feat.append("- {}".format(feature))
+            rem_feat.append(f"- {feature}")
 
     if fail_feat:
         fail_feat.insert(0, "Failed to remove the following:")