Merge pull request #10 from salt-extensions/release/100

CHANGELOG.md

@@ -3,3 +3,7 @@ The changelog format is based on [Keep a Changelog](https://keepachangelog.com/e
 This project uses [Semantic Versioning](https://semver.org/) - MAJOR.MINOR.PATCH
 
 # Changelog
+
+## v1.0.0 (2024-09-26)
+
+Initial release of `saltext-mattermost`. This release mostly tracks the functionality in the core Salt code base as of version 3007.1.

docs/index.rst

@@ -9,6 +9,7 @@ Salt Extension for interacting with Mattermost
   :hidden:
 
   topics/installation
+  topics/configuration
 
 .. toctree::
   :maxdepth: 2

docs/ref/utils/index.rst

@@ -4,10 +4,9 @@ _________
 Utilities
 _________
 
-.. currentmodule:: saltext.mattermost
+.. currentmodule:: saltext.mattermost.utils
 
 .. autosummary::
     :toctree:
 
-    utils
-    utils.mattermost
+    mattermost

docs/topics/configuration.md

@@ -0,0 +1,49 @@
+(mattermost-setup)=
+# Configuration
+## Execution and runner modules
+These modules can be used by either passing an `api_url` and `hook`
+directly or by specifying both in a configuration profile in the Salt
+master/minion config. For example:
+
+```yaml
+mattermost:
+  hook: peWcBiMOS9HrZG15peWcBiMOS9HrZG15
+  api_url: https://example.com
+```
+
+## Returner
+To use the returner, the above configuration values are required
+to be set in the minion configuration file. Additionally, `username`
+and `channel` can optionally be configured.
+
+As with all returners, you can specify the values either as
+a nested or a flattened dict:
+
+:::{tab} nested
+
+```yaml
+mattermost:
+  hook: peWcBiMOS9HrZG15peWcBiMOS9HrZG15
+  api_url: https://example.com
+  username: foo
+  channel: bar
+```
+:::
+
+:::{tab} flattened
+```yaml
+mattermost.hook: peWcBiMOS9HrZG15peWcBiMOS9HrZG15
+mattermost.api_url: https://example.com
+mattermost.username: foo
+mattermost.channel: bar
+```
+:::
+
+### Alternative profile
+When invoking the returner, you can request to use an alternative profile name.
+Any values not found in the alternative configuration will be pulled from
+the default location.
+
+```yaml
+mattermost_alternative:
+  api_url: https://example.io

src/saltext/mattermost/modules/__init__.py

@@ -1,3 +0,0 @@
-"""
-Execution Module Directory
-"""

src/saltext/mattermost/modules/mattermost.py

@@ -1,36 +1,25 @@
 """
 Module for sending messages to Mattermost
 
-.. versionadded:: 2017.7.0
+.. important::
 
-:configuration: This module can be used by either passing an api_url and hook
-    directly or by specifying both in a configuration profile in the salt
-    master/minion config. For example:
-
-    .. code-block:: yaml
-
-        mattermost:
-          hook: peWcBiMOS9HrZG15peWcBiMOS9HrZG15
-          api_url: https://example.com
+    You can optionally :ref:`add a configuration profile <mattermost-setup>`
+    to avoid having to pass `hook` and `api_url` to each invocation.
 """
 
 import logging
 
-import salt.utils.json
-import salt.utils.mattermost
 from salt.exceptions import SaltInvocationError
+from salt.utils import json
+
+from saltext.mattermost.utils import mattermost
 
 log = logging.getLogger(__name__)
 
 __virtualname__ = "mattermost"
 
 
 def __virtual__():
-    """
-    Return virtual name of the module.
-
-    :return: The virtual name of the module.
-    """
     return __virtualname__
 
 
@@ -127,9 +116,7 @@ def post_message(message, channel=None, username=None, api_url=None, hook=None):
         parameters["username"] = username
     parameters["text"] = "```" + message + "```"  # pre-formatted, fixed-width text
     log.debug("Parameters: %s", parameters)
-    data = "payload={}".format(  # pylint: disable=consider-using-f-string
-        salt.utils.json.dumps(parameters)
-    )
-    result = salt.utils.mattermost.query(api_url=api_url, hook=hook, data=data)
+    data = f"payload={json.dumps(parameters)}"
+    result = mattermost.query(api_url=api_url, hook=hook, data=data)
 
     return bool(result)

src/saltext/mattermost/returners/mattermost_returner.py

@@ -1,42 +1,19 @@
 """
-Return salt data via mattermost
+Return Salt data via Mattermost
 
-.. versionadded:: 2017.7.0
+.. important::
 
-The following fields can be set in the minion conf file:
+    Using this module requires the :ref:`general setup <mattermost-setup>`.
 
-.. code-block:: yaml
-
-    mattermost.hook (required)
-    mattermost.username (optional)
-    mattermost.channel (optional)
-
-Alternative configuration values can be used by prefacing the configuration.
-Any values not found in the alternative configuration will be pulled from
-the default location:
-
-.. code-block:: yaml
-
-    mattermost.channel
-    mattermost.hook
-    mattermost.username
-
-mattermost settings may also be configured as:
-
-.. code-block:: yaml
-
-    mattermost:
-      channel: RoomName
-      hook: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-      username: user
-
-To use the mattermost returner, append '--return mattermost' to the salt command.
+Usage
+-----
+To use the mattermost returner, append ``--return mattermost`` to the Salt command.
 
 .. code-block:: bash
 
     salt '*' test.ping --return mattermost
 
-To override individual configuration items, append --return_kwargs '{'key:': 'value'}' to the salt command.
+To override individual configuration items, append ``--return_kwargs '{'key:': 'value'}'`` to the Salt command.
 
 .. code-block:: bash
 
@@ -46,8 +23,9 @@
 import logging
 
 import salt.returners
-import salt.utils.json
-import salt.utils.mattermost
+from salt.utils import json
+
+from saltext.mattermost.utils import mattermost
 
 log = logging.getLogger(__name__)
 
@@ -99,8 +77,7 @@ def returner(ret):
         ret.get("id"), ret.get("fun"), ret.get("fun_args"), ret.get("jid"), returns
     )
 
-    mattermost = post_message(channel, message, username, api_url, hook)
-    return mattermost
+    return post_message(channel, message, username, api_url, hook)
 
 
 def event_return(events):
@@ -121,7 +98,7 @@ def event_return(events):
     for event in events:
         log.debug("Event: %s", event)
         log.debug("Event data: %s", event["data"])
-        message = "tag: {}\r\n".format(event["tag"])  # pylint: disable=consider-using-f-string
+        message = f"tag: {event['tag']}\r\n"
         for key, value in event["data"].items():
             message += f"{key}: {value}\r\n"
         result = post_message(channel, message, username, api_url, hook)
@@ -149,10 +126,10 @@ def post_message(channel, message, username, api_url, hook):
         parameters["username"] = username
     parameters["text"] = "```" + message + "```"  # pre-formatted, fixed-width text
     log.debug("Parameters: %s", parameters)
-    result = salt.utils.mattermost.query(
+    result = mattermost.query(
         api_url=api_url,
         hook=hook,
-        data=f"payload={salt.utils.json.dumps(parameters)}",
+        data=f"payload={json.dumps(parameters)}",
     )
 
     log.debug("result %s", result)

src/saltext/mattermost/runners/__init__.py

@@ -1,3 +0,0 @@
-"""
-Runners Directory
-"""

src/saltext/mattermost/runners/mattermost.py

@@ -1,38 +1,25 @@
 """
 Module for sending messages to Mattermost
 
-.. versionadded:: 2017.7.0
+.. important::
 
-:configuration: This module can be used by either passing an api_url and hook
-    directly or by specifying both in a configuration profile in the salt
-    master/minion config. For example:
-
-    .. code-block:: yaml
-
-        mattermost:
-          hook: peWcBiMOS9HrZG15peWcBiMOS9HrZG15
-          api_url: https://example.com
+    You can optionally :ref:`add a configuration profile <mattermost-setup>`
+    to avoid having to pass `hook` and `api_url` to each invocation.
 """
 
 import logging
 
 import salt.utils.json
-import salt.utils.mattermost
 from salt.exceptions import SaltInvocationError
 
-# pylint: disable=import-error,no-name-in-module,redefined-builtin
-# pylint: enable=import-error,no-name-in-module
+from saltext.mattermost.utils import mattermost
 
 log = logging.getLogger(__name__)
 
 __virtualname__ = "mattermost"
 
 
 def __virtual__():
-    """
-    Return virtual name of the module.
-    :return: The virtual name of the module.
-    """
     return __virtualname__
 
 
@@ -89,6 +76,7 @@ def _get_username():
 def post_message(message, channel=None, username=None, api_url=None, hook=None):
     """
     Send a message to a Mattermost channel.
+
     :param channel:     The channel name, either will work.
     :param username:    The username of the poster.
     :param message:     The message to send to the Mattermost channel.
@@ -125,7 +113,7 @@ def post_message(message, channel=None, username=None, api_url=None, hook=None):
     parameters["text"] = "```" + message + "```"  # pre-formatted, fixed-width text
     log.debug("Parameters: %s", parameters)
     data = salt.utils.json.dumps(parameters)
-    result = salt.utils.mattermost.query(api_url=api_url, hook=hook, data=f"payload={data}")
+    result = mattermost.query(api_url=api_url, hook=hook, data=f"payload={data}")
 
     if result:
         return True
@@ -135,6 +123,7 @@ def post_message(message, channel=None, username=None, api_url=None, hook=None):
 def post_event(event, channel=None, username=None, api_url=None, hook=None):
     """
     Send an event to a Mattermost channel.
+
     :param channel:     The channel name, either will work.
     :param username:    The username of the poster.
     :param event:       The event to send to the Mattermost channel.
@@ -159,7 +148,7 @@ def post_event(event, channel=None, username=None, api_url=None, hook=None):
 
     log.debug("Event: %s", event)
     log.debug("Event data: %s", event["data"])
-    message = "tag: {}\r\n".format(event["tag"])  # pylint: disable=consider-using-f-string
+    message = f"tag: {event['tag']}\r\n"
     for key, value in event["data"].items():
         message += f"{key}: {value}\r\n"
     result = post_message(message, channel=channel, username=username, api_url=api_url, hook=hook)

src/saltext/mattermost/utils/__init__.py

@@ -1,8 +0,0 @@
-"""
-Some of the utils used by salt
-
-PLEASE DO NOT ADD ANY NEW FUNCTIONS TO THIS FILE.
-
-New functions should be organized in other files under salt/utils/. Please
-consult the dev team if you are unsure where a new function should go.
-"""

src/saltext/mattermost/utils/mattermost.py

@@ -1,17 +1,5 @@
 """
 Library for interacting with Mattermost Incoming Webhooks
-
-    :configuration: This module can be used by specifying the name of a
-        configuration profile in the minion config, minion pillar, or master
-        config.
-
-    For example:
-
-    .. code-block:: yaml
-
-        mattermost:
-          hook: 3tdgo8restnxiykdx88wqtxryr
-          api_url: https://example.com
 """
 
 import http.client
@@ -27,6 +15,7 @@
 def query(hook=None, api_url=None, data=None):
     """
     Mattermost object method function to construct and execute on the API URL.
+
     :param api_url:     The Mattermost API URL
     :param hook:        The Mattermost hook.
     :param data:        The data to be sent for POST method.