Skip to main content

pypyr slack plug-in: send slack messages from pypyr pipelines

Project description

pypyr-logo
pypyr
pronounce how you like, but I generally say piper as in “piping down the valleys wild”

Send messages to slack from pypyr. This is useful for sending notifications on success or failure conditions in your pipelines. Or for sending a message just because you can.

pypyr is a command line interface to run pipelines defined in yaml.

build status coverage status pypi version

1   Installation

1.1   pip

# pip install --upgrade pypyrslack

pypyrslack depends on pypyr-cli. The above pip will install it for you if you don’t have it already.

1.2   Python version

Tested against Python >=3.6

2   steps

pypyrslack.steps.send

Send a message to slack.

2.1   Required Context

Requires the following context items:

  • slackToken
    • your slack api token. Keep this secure.
  • slackChannel
    • send to this slack channel (include # in front)
  • slackText
    • the body of your message. Use your usual slack formatting chars.

2.2   Text substitutions

For both slackChannel and slackText you can use substitution tokens, aka string interpolation. This substitutes anything between curly braces with the context value for that key. For example, if your context looked like this:

arbitraryValue: pypyrchannel
arbitraryText: down the
moreArbText: wild
slackChannel: "#{arbitraryValue}"
slackText: "piping {arbitraryText} valleys {moreArbText}"

This will result in sending a message to #pypyrchannel with text:

piping down the values wild

Escape literal curly braces with doubles: {{ for {, }} for }

See a worked example for substitutions here.

2.3   Sample pipeline

Here is some sample yaml of what a pipeline using the pypyr-slack plug-in could look like:

steps:
  - name: pypyrslack.steps.echo
    in:
      echoMe: "just an arb step that may or may not fail."
  - name: pypyrslack.steps.send
    in:
      slackToken: supersecurevaluegoeshere
      slackChannel: "#channelnamehere"
      slackText: "pypyr is busy doing things :construction:"

# The slackToken and slackChannel have already been set in steps
# on_success and on_failure are just changing the text for the message.
on_success:
  - name: pypyrslack.steps.send
    in:
      slackText: "that went well! :hotdog:"

on_failure:
  - name: pypyrslack.steps.send
    in:
      slackText: "whoops! :rage1:"

If you saved this yaml as ./pipelines/hoping-for-a-hotdog.yaml, you can run from ./ the following:

pypyr hoping-for-a-hotdog

See a worked example for pypyr slack here.

3   slack authentication

3.1   Get slack api token

To authenticate against your slack, you need to create an api key. There’re various ways of going about this, using legacy tokens, test tokens or a bot.

I generally create a bot. Given you’re likely to use it just to send notifications to slack, rather than consume events from slack, it’s a pretty simple setup just to get your api key.

Remember to invite and add the bot you create to the slack channel(s) to which you want to post. You invite the bot in like you would a normal user.

3.2   Ensure secrets stay secret

Be safe! Don’t hard-code your api token, don’t check it into a public repo. Here are some tips for handling api tokens from slack.

Do remember not to fling the api key around as a shell argument - it could very easily leak that way into logs or expose via a ps. I generally use one of the pypyr built-in context parsers like pypyr.parser.jsonfile or pypyr.parser.yamlfile, see here for details.

4   Testing

4.1   Testing without worrying about dependencies

Run from tox to test the packaging cycle inside a virtual env, plus run all tests:

# just run tests
$ tox -e dev -- tests
# run tests, validate README.rst, run flake8 linter
$ tox -e stage -- tests

4.2   If tox is taking too long

The test framework is pytest. If you only want to run tests:

$ pip install -e .[dev,test]

4.3   Day-to-day testing

  • Tests live under /tests (surprising, eh?). Mirror the directory structure of the code being tested.

  • Prefix a test definition with test_ - so a unit test looks like

    def test_this_should_totally_work():
    
  • To execute tests, from root directory:

    pytest tests
    
  • For a bit more info on running tests:

    pytest --verbose [path]
    
  • To execute a specific test module:

    pytest tests/unit/arb_test_file.py
    

5   Contribute

5.1   Bugs

Well, you know. No one’s perfect. Feel free to create an issue.

5.2   Contribute to the pypyr project

The usual jazz - create an issue, fork, code, test, PR. It might be an idea to discuss your idea via the Issues list first before you go off and write a huge amount of code - you never know, something might already be in the works, or maybe it’s not quite right for this plug-in (you’re still welcome to fork and go wild regardless, of course, it just mightn’t get merged back in here).

Get in touch anyway, would love to hear from you at https://www.345.systems/contact.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
pypyrslack-1.0.0-py3-none-any.whl (6.4 kB) Copy SHA256 hash SHA256 Wheel py3

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page