pypyrslack 0.3.0

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.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.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.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.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.