pypyr slack plug-in: send slack messages from pypyr pipelines
Project description
- 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.
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.
Source Distributions
Built Distribution
Hashes for pypyrslack-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0c85211d557714eae2553be842a79b38b4f315ae5fae947eeeed180562a758a8 |
|
MD5 | c90002d7c66c7ef70c7b5ceef327ffa6 |
|
BLAKE2b-256 | e74c8e17d151c45310575d6b049880a5f236ac6b1dec681a29b9826d6d9c2bee |