phial package

Submodules

phial.bot module

The core of phial.

class phial.bot.Phial(token, config={'autoReconnect': True, 'baseHelpText': 'All available commands:', 'hotReload': False, 'loopDelay': 0.001, 'maxThreads': 4, 'prefix': '!', 'registerHelpCommand': True})[source]

Bases: object

The Phial class acts as the main interface to Slack.

It handles registraion and execution of user defined commands, as well as providing a wrapper around slackclient.SlackClient to make sending messages to Slack simpler.

add_command(pattern, func, case_sensitive=False, help_text_override=None, hide_from_help_command=False)[source]

Registers a command with the bot.

This method can be used as a decorator via command()

Parameters
  • pattern (str) – The pattern that a Message’s text must match for the command to be invoked.

  • func (Callable[…, Union[None, str, Response, Attachment]]) – The fucntion to be executed when the command is invoked

  • case_sensitive (bool) –

    Whether the pattern should respect case sensitivity.

    Defaults to False

  • help_text_override (Optional[str]) –

    Text that should be used as a description of the command using the inbuilt help function.

    If not overriden the command’s docstring will be used as the help text.

    Defaults to None

  • hide_from_help_command (Optional[bool]) –

    A flag to specify whether or not the inbuilt help command should hide this command from the list it generates.

    Defaults to False

Raises

ValueError – If command with the same pattern is already registered

Example

def hello():
    return "world"
bot.add_command('hello', world)

Is the same as

@bot.command('hello')
def hello():
    return "world"
Return type

None

add_fallback_command(func)[source]

Add a fallback command.

Registers a ‘fallback’ function to run when a user tries to execute a command that doesn’t exist.

This method can be used as a decorator via fallback_command()

Parameters

func (Callable[[Message], Union[None, str, Response, Attachment]]) – The function to be executed when the user tries to execute a command that doesn’t exist

Example

def error_handler(message: Message) -> str:
    return "Oops that command doesn't seem to exist"

bot.add_fallback_command(error_handler)

Is the same as

@bot.fallback_command()
def error_handler(message: Message) -> str:
    return "Oops that command doesn't seem to exist"
Return type

None

add_middleware(func)[source]

Adds a middleware function to the bot.

Middleware functions get passed every message the bot recieves from slack before the bot process the message itself. Returning None from a middleware function will prevent the bot from processing it.

This method can be used as a decorator via middleware().

Parameters

middleware_func – The function to be added to the middleware pipeline

Example

def intercept(messaage):
    return message
bot.add_middleware(intercept)

Is the same as

@bot.middleware()
def intercept(messaage):
    return message
Return type

None

add_scheduled(schedule, func)[source]

Adds a scheduled function to the bot.

This method can be used as a decorator via scheduled().

Parameters
  • schedule (Schedule) – The schedule used to run the function

  • scheduled_func – The function to be run in accordance to the schedule

Example

def scheduled_beep():
    bot.send_message(Response(text="Beep",
                              channel="channel-id">))
bot.add_scheduled(Schedule().every().day(), scheduled_beep)

Is the same as

@bot.scheduled(Schedule().every().day())
def scheduled_beep():
    bot.send_message(Response(text="Beep",
                              channel="channel-id">))
Return type

None

alias(pattern)[source]

A decorator that is used to register an alias for a command.

Parameters

pattern (str) – The pattern that a Message’s text must match for the command to be invoked.

Example

@bot.command('hello')
@bot.alias('goodbye')
def hello():
    return "world"
Return type

Callable

command(pattern, case_sensitive=False, help_text_override=None, hide_from_help_command=False)[source]

Registers a command with the bot.

This command is a decorator version of add_command()

Parameters
  • pattern (str) – The pattern that a Message’s text must match for the command to be invoked.

  • case_sensitive (bool) –

    Whether the pattern should respect case sensitivity.

    Defaults to False

  • help_text_override (Optional[str]) –

    Text that should be used as a description of the command using the inbuilt help function.

    If not overriden the command’s docstring will be used as the help text.

    Defaults to None

  • hide_from_help_command (Optional[bool]) –

    A flag to specify whether or not the inbuilt help command should hide this command from the list it generates.

    Defaults to False

Example

@bot.command('hello')
def hello():
    return "world"

@bot.command('caseSensitive', case_sensitive=True)
def case_sensitive():
    return "You typed caseSensitive"
Return type

Callable

default_config = {'autoReconnect': True, 'baseHelpText': 'All available commands:', 'hotReload': False, 'loopDelay': 0.001, 'maxThreads': 4, 'prefix': '!', 'registerHelpCommand': True}

Default configuration

fallback_command()[source]

A decorator to add a fallback command.

See add_fallback_command() for more information on fallback commands

Example

@bot.fallback_command()
def error_handler(message: Message) -> str:
    return "Oops that command doesn't seem to exist"
Return type

Callable

middleware()[source]

A decorator to add a middleware function to the bot.

See add_middleware() for more information about middleware

Example

@bot.middleware()
def intercept(messaage):
    return message
Return type

Callable

run()[source]

Run the bot.

Return type

None

scheduled(schedule)[source]

A decorator that is used to register a scheduled function.

See add_scheduled() for more information on scheduled jobs.

Parameters

schedule (Schedule) – The schedule used to determine when the function should be run

Example

@bot.scheduled(Schedule().every().day())
def scheduled_beep():
    bot.send_message(Response(text="Beep",
                              channel="channel-id">))
Return type

Callable

send_message(message)[source]

Sends a message to Slack.

Parameters

message (Response) – The message to be sent to Slack

Return type

None

send_reaction(response)[source]

Sends a reaction to a Slack Message.

Parameters

response (Response) – Response containing the reaction to be sent to Slack

Return type

None

upload_attachment(attachment)[source]

Upload a file to Slack.

Parameters

attachment (Attachment) – The attachment to be uploaded to Slack

Return type

None

phial.scheduler module

The classes related to scheduling of regular jobs in phial.

class phial.scheduler.Schedule[source]

Bases: object

A schedule stores the relative time for something to happen.

It can be used to compute when the next instance of an event should occur.

at(hour, minute, second=0)[source]

Specifies the time of day the next occurnce will happen.

NOTE: ‘at’ can only be used with day().

schedule = Schedule().every().day().at(12,00)
Parameters
  • hour (int) – The hour of day the next event should happen, when combined with the minute

  • minute (int) – The minute of day the next event should happen, when combined with the hour

  • second (int) – The second of day the next event should happen, when combined with the hour and minute. Defaults to 0

Return type

Schedule

day()[source]

Adds a day to the relative time till the next event.

schedule = Schedule().every().day()
Return type

Schedule

days(value)[source]

Set the days till the next instance of the event.

Adds the specified number of days to the relative time till the next event.

schedule = Schedule().every().days(2)
Parameters

value (int) – The number of days to wait between events

Return type

Schedule

every()[source]

Syntantic sugar to make schedule declaration more readable.

Syntatic sugar to allow the declaration of schedules to be more like an English sentence.

schedule = Schedule().every().day()
Return type

Schedule

get_next_run_time(last_run)[source]

Get the next time the job should run.

Calculates the next time to run, based on the last time the event was run.

Parameters

last_run (datetime) – The last time the event happened

Return type

datetime

Returns

A datetime of when the event should next happen

hour()[source]

Adds an hour to the relative time till the next event.

schedule = Schedule().every().hour()
Return type

Schedule

hours(value)[source]

Sets the hours till the next instance of the event.

Adds the specified number of hours to the relative time till the next event.

schedule = Schedule().every().hours(2)
Parameters

value (int) – The number of hours to wait between events

Return type

Schedule

minute()[source]

Adds a minute to the relative time till the next event.

schedule = Schedule().every().minute()
Return type

Schedule

minutes(value)[source]

Sets the minutes till the next instance of the event.

Adds the specified number of minutes to the relative time till the next event.

schedule = Schedule().every().minutes(2)
Parameters

value (int) – The number of minutes to wait between events

Return type

Schedule

second()[source]

Adds a second to the relative time till the next event.

schedule = Schedule().every().second()
Return type

Schedule

seconds(value)[source]

Sets the seconds till the next instance of the event.

Adds the specified number of seconds to the relative time till the next event.

schedule = Schedule().every().seconds(2)
Parameters

value (int) – The number of seconds to wait between events

Return type

Schedule

class phial.scheduler.ScheduledJob(schedule, func)[source]

Bases: object

A function with a schedule.

run()[source]

Runs the function and calculates + stores the next run time.

Return type

None

should_run()[source]

Checks whether the function needs to be run based on the schedule.

Return type

bool

Returns

A bool of whether or not to run

class phial.scheduler.Scheduler[source]

Bases: object

A store for Scheduled Jobs.

add_job(job)[source]

Adds a scheuled job to the scheduler.

Parameters

job (ScheduledJob) – The job to be added to the scheduler

Return type

None

run_pending()[source]

Runs any pending scheduled jobs.

Runs any ScheduledJobs in the store, where job.should_run() returns true

Return type

None

phial.wrappers module

Contains models for phial to use.

class phial.wrappers.Attachment(channel, filename, content)[source]

Bases: object

A file to be uploaded to Slack.

Parameters
  • channel (str) – The Slack channel ID the file will be sent to

  • filename (str) – The filename of the file

  • content (IO'>[AnyStr]) – The file to send to Slack. Open file using open(‘<file>’, ‘rb’)

Example

Attachment('channel', 'file_name', open('file', 'rb'))
class phial.wrappers.Command(pattern, func, case_sensitive=False, help_text_override=None, hide_from_help_command=False)[source]

Bases: object

An action executable from Slack.

Parameters
  • pattern (str) – A string that a Slack Message must match to trigger execution

  • func (Callable[…, Union[None, str, Response, Attachment]]) – The function that will be triggered when the command is invoked

  • case_sensitive (bool) – Whether the pattern should enforce case sensitivity

  • help_text_override (Optional[str]) – Overrides the function’s docstring in the standard help command

  • hide_from_help_command (Optional[bool]) – Prevents function from being displayed by the standard help command

property help_text

A description of the command’s function.

Return type

Optional[str]

pattern_matches(message)[source]

Check if message should invoke the command.

Checks whether the text of a Message matches the command’s pattern, or any of it’s aliased patterns.

Return type

Optional[Dict[str, str]]

class phial.wrappers.Message(text, channel, user, timestamp, team, bot_id=None)[source]

Bases: object

A representation of a Slack message.

Parameters
  • text (str) – The message contents

  • channel (str) – The Slack channel ID the message was sent from

  • user (str) – The user who sent the message

  • timestamp (str) – The message’s timestamp

  • team (Optional[str]) – The Team ID of the Slack workspace the message was sent from

  • bot_id (Optional[str]) – If the message was sent by a bot the ID of that bot. Defaults to None.

phial.wrappers.PhialResponse = typing.Union[NoneType, str, ForwardRef('Response'), ForwardRef('Attachment')]

A union of all response types phial can use

class phial.wrappers.Response(channel, text=None, original_ts=None, reaction=None, ephemeral=False, user=None, attachments=None)[source]

Bases: object

A response to be sent to Slack.

When returned in a command function will send a message, or reaction to Slack depending on contents.

Parameters
  • channel (str) – The Slack channel ID the response will be sent to

  • text (Optional[str]) – The response contents

  • original_ts (Optional[str]) – The timestamp of the original message. If populated will put the text response in a thread

  • reation – A valid slack emoji name. NOTE: will only work when original_ts is populated

  • attachments (Optional[List[Dict[str, Union[str, int, float, bool, List[~T]]]]]) – Any Slack Message Attachments

  • ephemeral (bool) – Whether to send the message as an ephemeral message

  • user (Optional[str]) – The user id to display the ephemeral message to

Examples

The following would send a message to a slack channel when executed

@slackbot.command('ping')
def ping():
    return Response(text="Pong", channel='channel_id')

The following would send a reply to a message in a thread

@slackbot.command('hello')
def hello():
    return Response(text="hi",
                    channel='channel_id',
                    original_ts='original_ts')

The following would send a reaction to a message

@slackbot.command('react')
def react():
    return Response(reaction="x",
                    channel='channel_id',
                    original_ts='original_ts')