Migrate prefect-slack to core (#12839)

Author: zzstoatzz

.github/workflows/integration-tests.yaml

@@ -3,7 +3,7 @@ on:
   pull_request:
     paths:
       - .github/workflows/integration-tests.yaml
-      - "**/*.py"
+      - "src/prefect/**/*.py"
       - requirements.txt
       - requirements-client.txt
       - requirements-dev.txt

docs/integrations/catalog/prefect-slack.yaml

@@ -1,6 +1,6 @@
 collectionName: prefect-slack
 author: Prefect
 authorUrl: https://prefect.io
-documentation: https://prefecthq.github.io/prefect-slack/
+documentation: https://docs.prefect.io/integrations/prefect-slack/
 iconUrl: /img/collections/slack.png
 tag: Slack

docs/integrations/prefect-slack/credentials.md

@@ -0,0 +1 @@
+::: prefect_slack.credentials

docs/integrations/prefect-slack/index.md

@@ -0,0 +1,58 @@
+# prefect-slack
+
+## Welcome!
+
+`prefect-slack` is a collection of prebuilt Prefect tasks that can be used to quickly construct Prefect flows.
+
+## Getting Started
+
+### Python setup
+
+Requires an installation of Python 3.8+
+
+We recommend using a Python virtual environment manager such as pipenv, conda or virtualenv.
+
+These tasks are designed to work with Prefect 2.0. For more information about how to use Prefect, please refer to the [Prefect documentation](https://docs.prefect.io/).
+
+### Installation
+
+Install `prefect-slack`
+
+```bash
+pip install prefect-slack
+```
+
+### Slack setup
+
+In order to use tasks in the collection, you'll first need to create an Slack app and install it in your Slack workspace. You can create a Slack app by navigating to the [apps page](https://api.slack.com/apps) for your Slack account and selecting 'Create New App'.
+
+For tasks that require a Bot user OAuth token, you can get a token for your app by navigating to your apps __OAuth & Permissions__ page.
+
+For tasks that require and Webhook URL, you get generate new Webhook URLs by navigating to you apps __Incoming Webhooks__ page.
+
+Slack's [Basic app setup](https://api.slack.com/authentication/basics) guide provides additional details on setting up a Slack app.
+
+### Write and run a flow
+
+```python
+from prefect import flow
+from prefect.context import get_run_context
+from prefect_slack import SlackCredentials
+from prefect_slack.messages import send_chat_message
+
+
+@flow
+def example_send_message_flow():
+   context = get_run_context()
+
+   # Run other tasks and subflows here
+
+   token = "xoxb-your-bot-token-here"
+   send_chat_message(
+         slack_credentials=SlackCredentials(token),
+         channel="#prefect",
+         text=f"Flow run {context.flow_run.name} completed :tada:"
+   )
+
+example_send_message_flow()
+```

docs/integrations/prefect-slack/messages.md

@@ -0,0 +1 @@
+::: prefect_slack.messages

mkdocs.yml

@@ -254,6 +254,10 @@ nav:
                       - Jobs: integrations/prefect-databricks/jobs.md
                       - Rest: integrations/prefect-databricks/rest.md
                       - Flows: integrations/prefect-databricks/flows.md
+                - Slack:
+                      - integrations/prefect-slack/index.md
+                      - Credentials: integrations/prefect-slack/credentials.md
+                      - Messages: integrations/prefect-slack/messages.md
     - API Reference:
           - api-ref/index.md
           - Python SDK:

src/integrations/prefect-slack/README.md

@@ -0,0 +1,58 @@
+# prefect-slack
+
+## Welcome!
+
+`prefect-slack` is a collection of prebuilt Prefect tasks that can be used to quickly construct Prefect flows.
+
+## Getting Started
+
+### Python setup
+
+Requires an installation of Python 3.8+
+
+We recommend using a Python virtual environment manager such as pipenv, conda or virtualenv.
+
+These tasks are designed to work with Prefect 2.0. For more information about how to use Prefect, please refer to the [Prefect documentation](https://docs.prefect.io/).
+
+### Installation
+
+Install `prefect-slack`
+
+```bash
+pip install prefect-slack
+```
+
+### Slack setup
+
+In order to use tasks in the collection, you'll first need to create an Slack app and install it in your Slack workspace. You can create a Slack app by navigating to the [apps page](https://api.slack.com/apps) for your Slack account and selecting 'Create New App'.
+
+For tasks that require a Bot user OAuth token, you can get a token for your app by navigating to your apps __OAuth & Permissions__ page.
+
+For tasks that require and Webhook URL, you get generate new Webhook URLs by navigating to you apps __Incoming Webhooks__ page.
+
+Slack's [Basic app setup](https://api.slack.com/authentication/basics) guide provides additional details on setting up a Slack app.
+
+### Write and run a flow
+
+```python
+from prefect import flow
+from prefect.context import get_run_context
+from prefect_slack import SlackCredentials
+from prefect_slack.messages import send_chat_message
+
+
+@flow
+def example_send_message_flow():
+   context = get_run_context()
+
+   # Run other tasks and subflows here
+
+   token = "xoxb-your-bot-token-here"
+   send_chat_message(
+         slack_credentials=SlackCredentials(token),
+         channel="#prefect",
+         text=f"Flow run {context.flow_run.name} completed :tada:"
+   )
+
+example_send_message_flow()
+```

src/integrations/prefect-slack/prefect_slack/__init__.py

@@ -0,0 +1,4 @@
+from . import _version
+from .credentials import SlackCredentials, SlackWebhook  # noqa
+
+__version__ = _version.__version__

src/integrations/prefect-slack/prefect_slack/credentials.py

@@ -0,0 +1,43 @@
+"""Credential classes used to perform authenticated interacting with Slack"""
+from dataclasses import dataclass
+
+from slack_sdk.web.async_client import AsyncWebClient
+from slack_sdk.webhook.async_client import AsyncWebhookClient
+
+
+@dataclass
+class SlackCredentials:
+    """
+    Class for holding Slack credentials for use in tasks and flows.
+
+    Args:
+        token: Bot user OAuth token for the Slack app used to perform actions.
+    """
+
+    token: str
+
+    def get_client(self) -> AsyncWebClient:
+        """
+        Returns an authenticated `AsyncWebClient` to interact with the Slack API.
+        """
+        return AsyncWebClient(token=self.token)
+
+
+@dataclass
+class SlackWebhook:
+    """
+    Class holding a Slack webhook for use in tasks and flows.
+
+    Args:
+        url: Slack webhook URL which can be used to send messages
+            (e.g. `https://hooks.slack.com/XXX`).
+    """
+
+    url: str
+
+    def get_client(self) -> AsyncWebhookClient:
+        """
+        Returns and authenticated `AsyncWebhookClient` to interact with the configured
+        Slack webhook.
+        """
+        return AsyncWebhookClient(url=self.url)

src/integrations/prefect-slack/prefect_slack/messages.py

@@ -0,0 +1,140 @@
+"""Tasks for sending Slack messages"""
+
+from typing import TYPE_CHECKING, Dict, Optional, Sequence, Union
+
+from prefect import get_run_logger, task
+from prefect_slack.credentials import SlackCredentials, SlackWebhook
+
+if TYPE_CHECKING:  # pragma: no cover
+    import slack_sdk.models.attachments
+    import slack_sdk.models.blocks
+
+
+@task
+async def send_chat_message(
+    channel: str,
+    slack_credentials: SlackCredentials,
+    text: Optional[str] = None,
+    attachments: Optional[
+        Sequence[Union[Dict, "slack_sdk.models.attachments.Attachment"]]
+    ] = None,
+    slack_blocks: Optional[
+        Sequence[Union[Dict, "slack_sdk.models.blocks.Block"]]
+    ] = None,
+) -> Dict:
+    """
+    Sends a message to a Slack channel
+
+    Args:
+        channel: The name of the channel in which to post the chat message
+            (e.g. #general)
+        slack_credentials: Instance of `SlackCredentials` initialized with a Slack
+            bot token
+        text: Contents of the message. It's a best practice to always provide a `text`
+            argument when posting a message. The `text` argument is used in places where
+            content cannot be rendered such as: system push notifications, assistive
+            technology such as screen readers, etc.
+        attachments: List of objects defining secondary context in the posted Slack
+            message. The [Slack API docs](https://api.slack.com/messaging/composing/layouts#building-attachments)
+            provide guidance on building attachments.
+        slack_blocks: List of objects defining the layout and formatting of the posted
+            message. The [Slack API docs](https://api.slack.com/block-kit/building)
+            provide guidance on building messages with blocks.
+
+    Returns:
+        Dict: Response from the Slack API. Example response structures can be found in
+            the [Slack API docs](https://api.slack.com/methods/chat.postMessage#examples)
+
+    Examples:
+        Post a message at the end of a flow run
+
+        ```python
+        from prefect import flow
+        from prefect.context import get_run_context
+        from prefect_slack import SlackCredentials
+        from prefect_slack.messages import send_chat_message
+
+
+        @flow
+        def example_send_message_flow():
+            context = get_run_context()
+
+            # Run other tasks and subflows here
+
+            token = "xoxb-your-bot-token-here"
+            send_chat_message(
+                slack_credentials=SlackCredentials(token),
+                channel="#prefect",
+                text=f"Flow run {context.flow_run.name} completed :tada:"
+            )
+
+        example_send_message_flow()
+        ```
+    """  # noqa
+    logger = get_run_logger()
+    logger.info("Posting chat message to %s", channel)
+
+    client = slack_credentials.get_client()
+    result = await client.chat_postMessage(
+        channel=channel, text=text, blocks=slack_blocks, attachments=attachments
+    )
+    return result.data
+
+
+@task
+async def send_incoming_webhook_message(
+    slack_webhook: SlackWebhook,
+    text: Optional[str] = None,
+    attachments: Optional[
+        Sequence[Union[Dict, "slack_sdk.models.attachments.Attachment"]]
+    ] = None,
+    slack_blocks: Optional[
+        Sequence[Union[Dict, "slack_sdk.models.blocks.Block"]]
+    ] = None,
+) -> None:
+    """
+    Sends a message via an incoming webhook
+
+    Args:
+        slack_webhook: Instance of `SlackWebhook` initialized with a Slack
+            webhook URL.
+        text: Contents of the message. It's a best practice to always provide a `text`
+            argument when posting a message. The `text` argument is used in places where
+            content cannot be rendered such as: system push notifications, assistive
+            technology such as screen readers, etc.
+        attachments: List of objects defining secondary context in the posted Slack
+            message. The [Slack API docs](https://api.slack.com/messaging/composing/layouts#building-attachments)
+            provide guidance on building attachments.
+        slack_blocks: List of objects defining the layout and formatting of the posted
+            message. The [Slack API docs](https://api.slack.com/block-kit/building)
+            provide guidance on building messages with blocks.
+
+    Examples:
+        Post a message at the end of a flow run
+
+        ```python
+        from prefect import flow
+        from prefect_slack import SlackWebhook
+        from prefect_slack.messages import send_incoming_webhook_message
+
+
+        @flow
+        def example_send_message_flow():
+            # Run other tasks and subflows here
+
+            webhook_url = "https://hooks.slack.com/XXX"
+            send_incoming_webhook_message(
+                slack_webhook=SlackWebhook(
+                    url=webhook_url
+                ),
+                text="Warehouse loading flow completed :sparkles:"
+            )
+
+        example_send_message_flow()
+        ```
+    """  # noqa
+    logger = get_run_logger()
+    logger.info("Posting message to provided webhook")
+
+    client = slack_webhook.get_client()
+    await client.send(text=text, attachments=attachments, blocks=slack_blocks)