-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #10 from AusterweilLab/pyshell
merge jarjar 3 !!!
- Loading branch information
Showing
36 changed files
with
1,647 additions
and
381 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| # Minimal makefile for Sphinx documentation | ||
| # | ||
|
|
||
| # You can set these variables from the command line. | ||
| SPHINXOPTS = | ||
| SPHINXBUILD = sphinx-build | ||
| SPHINXPROJ = jarjar | ||
| SOURCEDIR = docs | ||
| BUILDDIR = build | ||
|
|
||
| # Put it first so that "make" without argument is like "make help". | ||
| help: | ||
| @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) | ||
|
|
||
| .PHONY: help Makefile | ||
|
|
||
| # Catch-all target: route all unknown targets to Sphinx using the new | ||
| # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
| %: Makefile | ||
| @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,132 +1,89 @@ | ||
| # Jarjar Slack Notifier | ||
|
|
||
| Jarjar is a collection of scripts that lets you programmatically send notifications to your Slack team. | ||
| Jarjar is a python utility that makes it easy to send slack notifications to your teams. You can import it as a python module or use our command line tool. | ||
|
|
||
| ## What can jarjar do for me? | ||
| [](https://jarjar.readthedocs.io/en/latest/?badge=latest) [](https://badge.fury.io/py/jarjar) | ||
|
|
||
| Here are some things _we_ use it for: | ||
|
|
||
| - Send reminders to yourself/group. | ||
| - Notify users when their jobs (simulations, backups, etc) are completed. | ||
| - Combine jarjar with cron to send out [daily positive vibes](http://i.imgur.com/YkqMwCx.png). | ||
| ## What can jarjar do for me? | ||
|
|
||
| Jarjar was developed at the [Austerweil Lab at UW-Madison](http://alab.psych.wisc.edu/) as a tool for scientists. We use it for all sorts of things, such as: | ||
|
|
||
| ## But How? | ||
| 1. Sending a message so that we know when long-running processes have finished. | ||
|
|
||
| We have designed two interfaces into jarjar: a shell command and a Python Module. | ||
|  | ||
|
|
||
| # The Shell Command | ||
| 2. Sending notices when scheduled tasks have failed. | ||
|
|
||
| The `sh/` directory contains a shell command `jarjar` and a configuration file `.jarjar`. | ||
|  | ||
|
|
||
| Fill the configuration file out with useful defaults. Critically, you'll want to paste in your Slack webhook so that jarjar knows where to send the message. Then put the configuration file in your home directory (`~/`), that's where jarjar will look for it. Don't worry, you can override those defaults later. Here's a sample `.jarjar`: | ||
| 3. Sending out daily positive vibes. | ||
|
|
||
| ```sh | ||
| channel="@my_username" # or "#general" | ||
| message="Hi! Meesa Jar Jar Binks." | ||
| webhook="your-webhook-here" | ||
| ``` | ||
|
|
||
| Then, add the `jarjar` _script_ [to your path](https://stackoverflow.com/questions/20054538/add-a-bash-script-to-path). After that, you can use it like so: | ||
|
|
||
| ```sh | ||
| # echo the default message to the default channel | ||
| jarjar -e | ||
|  | ||
|
|
||
| # echo a message to the #general channel | ||
| jarjar -e -u "#general" -m "Hi, everyone!!" | ||
| ## Quickstart | ||
|
|
||
| # Send yourself a notification when a script is completed | ||
| jarjar -u @username -m "Your job is finished!" python my-script.py | ||
| jarjar ./my-script.sh | ||
| [Installation](docs/install.md) is simple! | ||
|
|
||
| # send a message to the non-default slack team | ||
| jarjar -e -u @username -m "Hi!" -w "their-webhook-url" | ||
| ```shell | ||
| pip install jarjar | ||
| ``` | ||
|
|
||
| ## Modifiers | ||
| My guess is that you'll want to create jarjar's config file, `~/.jarjar`. This tells jarjar what you'd like to use as a default for your slack team's webhook, the channel to post to, and the message it sends. Don't worry, you can over-ride these anytime. | ||
|
|
||
| | Modifier | Description | | ||
| | --- | --- | | ||
| | `-e` | Echo the message. If this flag is not included, jarjar waits until a provided process is completed to send the message. By default (without the `-e` flag), jarjar launches a screen with your script (which terminates when your script ends). You can always resume a screen launched by jarjar by finding the appropriate PID: `screen -ls` and `screen -r PID`. | | ||
| | `-r` | Attaches screen created by jarjar (when `-e` is not used) | | ||
| | `-m` | Message to be sent | | ||
| | `-u` | Username (or channel). Usernames must begin with `@`, channels with `#`. | | ||
| | `-w` | Webhook for the Slack team. | | ||
| Edit this snippet and add it to `~/.jarjar`: | ||
|
|
||
| # The Python Module | ||
|
|
||
| This module implements jarjar's functionality more fluidly within Python scripts. Importing the jarjar module provides a simple class, which can be used to send messages like the shell command. | ||
|
|
||
| Installation is simple: | ||
|
|
||
| 1. `pip install jarjar` | ||
| 2. _Optional_: create a `~/.jarjar` file with some defaults (this is shared with the shell command). | ||
|
|
||
| ```sh | ||
| channel="@my_username" # or "#general" | ||
| message="Hi! Meesa Jar Jar Binks." | ||
| webhook="your-webhook-here" | ||
| ```shell | ||
| channel='@username' | ||
| message='Custom message' | ||
| webhook='https://hooks.slack.com/services/your/teams/webhook' | ||
| ``` | ||
|
|
||
| If you don't know your team's webhook, you might have to [make one](https://api.slack.com/incoming-webhooks) | ||
|
|
||
| ### Python API | ||
|
|
||
| Then, you're good to go! You can use it as follows: | ||
| Use the jarjar python api like: | ||
|
|
||
| ```python | ||
| from jarjar import jarjar | ||
|
|
||
| # initialize with defaults from .jarjar | ||
| jj = jarjar() | ||
|
|
||
| # initialize with custom defaults | ||
| jj = jarjar(channel='#channel', webhook='slack-webhook-url') | ||
|
|
||
| # initialization is not picky -- provide one or both arguments | ||
| jj = jarjar(webhook = 'slack-webhook-url') | ||
| # initialize a jarjar object | ||
| jj = jarjar() # defaults from .jarjar | ||
| jj = jarjar(channel='#channel', webhook='slack-webhook-url') | ||
| jj = jarjar(webhook='slack-webhook-url') | ||
|
|
||
| # send a text message | ||
| jj.text('Hi!') | ||
|
|
||
| # send a message to multiple channels or users | ||
| jj.text('Hi!', channel=["@jeffzemla","#channel"]) | ||
| jj.text('Hi!') | ||
| jj.text('Hi!', channel=["@jeffzemla", "#channel"]) | ||
|
|
||
| # send an attachment | ||
| jj.attach(dict(status='it\'s all good')) | ||
|
|
||
| # send both | ||
| jj.post(text='Hi', attach=dict(status='it\'s all good')) | ||
|
|
||
| # override defaults after initializing | ||
| jj.attach(dict(status='it\'s all good'), channel = '@jeffzemla') | ||
| jj.text('Hi!', channel = '@nolan', webhook = 'another-webhook') | ||
| jj.attach({'meesa': 'jarjar binks'}), text='Hello!') | ||
| ``` | ||
|
|
||
| ## Methods | ||
|
|
||
| ### `text` | ||
|
|
||
| > `jj.text(text, **kwargs)` | ||
| ### Command Line Tool | ||
|
|
||
| Send a text message, specified by a string, `text`. User may optionally supply the channel and webhook in the `kwargs`. | ||
| We also made a [command line tool](docs/clt.md) for use outside of python scripts. The command line tool adds functionality to execute processes and send messages when they are complete. | ||
|
|
||
| ### `attach` | ||
|
|
||
| > `jj.attach(attach, **kwargs)` | ||
| Send attachments, specified by values in a dict, `attach`. User may optionally supply the channel and webhook in the `kwargs`. | ||
|
|
||
| ### `post` | ||
| ```shell | ||
| jarjar sleep 1 -m 'Meesa took a nap!' | ||
| ``` | ||
|
|
||
| > `jj.post(text=None, attach=None, channel=None, webhook=None)` | ||
| And then in your slack team: | ||
|
|
||
| The generic post method. `jj.text(...)` and `jj.attach(...)` are simply convenience functions wrapped around this method. User may supply text and/or attachments, and may override the default channel and webhook url. | ||
|  | ||
|
|
||
| Custom attachments are not supported in the CLT at this time, but everything else is: | ||
|
|
||
| # How to configure a Slack Webhook | ||
| ```sh | ||
| jarjar -m 'Meesa jarjar binks!' | ||
| jarjar -m 'Hi, everyone!!' --webhook '<your-url>' -c '#general' | ||
| ``` | ||
|
|
||
| You'll need to configure [Incoming Webhooks](https://api.slack.com/incoming-webhooks) for your Slack team. You need to specify a default channel (which jarjar overrides), and Slack will give you a webhook url. That's it! | ||
| ## Documentation | ||
|
|
||
| When you're setting things up, you can also specify a custom name and custom icon. We named our webhook robot `jar-jar`, and we used [this icon](http://i.imgur.com/hTHrg6i.png), so messages look like this: | ||
| We're on [Read The Docs](http://jarjar.readthedocs.io/en/latest/)! | ||
|
|
||
|  | ||
| ## Having Trouble? Or a feature request? | ||
|
|
||
| We are terrible developers and you'll probably run into all sorts of problems. Don't be shy, [file an issue on github](https://github.com/AusterweilLab/jarjar/issues/new)! |
Oops, something went wrong.