API Documentation

class jarjar.jarjar(config=None, **defaults)

A jarjar slack messenger.

This is largely a wrapper around functionality in requests.post() with facilities to store and set default values for the desired message to send, channel to post within, and slack team webhook.

Inference for these values proceeds as follows.

  1. Any argument provided to text() or attach() supersedes all defaults.
  2. Any argument provided to this class at initialization.
  3. Defaults within a config file at a user-specified path (config='...').
  4. Defaults within a config file .jarjar, within the working directory.
  5. Defaults within .jarjar, located in the user’s home directory.

The config files (for numbers 3-5) look like:

channel="@username"
message="Custom message"
webhook="https://hooks.slack.com/services/your/teams/webhook"

If the channel or webhook arguments are never provided, an error is raised. If the channel and webhook are provided but not a message or attachment, jarjar will make something up.

If a value is found in multiple places, the value from the highest priority location is used.

Parameters:
config : str, list

Optional. Path(s) to jarjar configuration file(s). If a list, configs should be in descending order of priority.

message : str

Optional. Default message to send.

channel : str, list

Optional. Name of the default channel to post within.

webhook : str

Optional. Webhook URL for the default slack team.

Methods

attach(attach, channel=None, webhook=None, message=None) Send an attachment. User may also include a text message.
text(message, channel=None, webhook=None, attach=None) Send a text message. User may also include an attachment.
set_webhook(webhook) Set jarjar’s default webhook.
set_channel(channel) Set jarjar’s default channel.
set_message(message) Set jarjar’s default message.
decorate(func=None, **jj_kwargs) Decorate a function to send a message after execution.
register_magic(name=’jarjar’, quiet=False, **kwargs) Register a magic for Jupyter notebooks.
attach(attach=None, **kwargs)

Send an attachment.

This method is largely identical to text(), only differing in the first argument (attach), which is expected to be a dictionary.

Parameters:
attach : dict

Attachment data. Optional but weird if you don’t provide one. All values are converted to string for the slack payload so don’t sweat it.

message : str

Text to send. Optional. If attach is None and there is no default and you don’t provide one here, jarjar just wings it.

channel : str, list

Optional. Name of the channel to post within. Can also be a list of channel names; jarjar will post to each.

webhook : str

Optional. Webhook URL for the slack team.
Returns:
response : requests.models.Response

Requests response object for the POST request to slack.
decorate(func=None, **jj_kwargs)

Decorate a function to send a message after execution.

This is a simple decorator to compute elapsed time and catch exceptions within a function execution. You can set the usual jarjar kwargs within the decorator. Decorate your function like:

jj = jarjar(channel='...')
@jj.decorate
def simulate(x):
    # ...

@jj.decorate(message='...')
def simulate(x):
    # ...
Parameters:
**jj_kwargs : keyword arguments

Arguments passed to attach().
register_magic(name='jarjar', quiet=False, **kwargs)

Register a jarjar Jupyter cell magic.

This magic sends a message whenever its cell executes. The message includes attachments for elapsed time and shows the exception trace if there was one.

Use it like:

jj = jarjar(channel='...')
jj.register_magic(message='Cell executed!')

# %% --- new cell ---
%%jarjar
# ... do some stuff! ...
Parameters:
name : str

Name of the magic to register. Default: ‘jarjar’.

quiet : boolean

Flag indicating whether to print the name of the magic.

**kwargs : keyword arguments

Arguments passed to attach().
set_channel(channel)

Set default channel.

Parameters:
channel : str

Name of the channel to post within.
set_message(message)

Set default message.

Parameters:
message : str

Default message to send.
set_webhook(webhook)

Set default webhook.

Parameters:
webhook : str

Webhook URL for the slack team.
text(message=None, **kwargs)

Send a text message.

This method is largely identical to attach(), only differing in the first argument (message), which is expected to be a string.

Parameters:
message : str

Text to send. Optional but weird if you don’t provide one. If attach is None and there is no default and you don’t provide one here, jarjar just wings it.

attach : dict

Attachment data. Optional. All values are converted to string for the slack payload so don’t sweat it.

channel : str, list

Optional. Name of the channel to post within. Can also be a list of channel names; jarjar will post to each.

webhook : str

Optional. Webhook URL for the slack team.
Returns:
response : requests.models.Response

Requests response object for the POST request to slack.