botskeleton 3.3.9

Description:

botskeleton 3.3.9

short
skeleton for bot children written in Python.
Created by Luné Mercové ahead of #NaBoMaMo 2017


long
botskeleton is a framework for content bots,
like Twitter bots
and Mastodon bots


Public API
The public API is contained entirely in botskeleton.py.


Botskeleton
The BotSkeleton class is the main object for a bot,
holding all the send methods and credentials.
It MUST be constructed with a secrets_dir
- this is the directory where it will expect credentials,
and where it will write its history file and log file by default.
You may also provide a log_filename (defaults to SECRETS_DIR/log),
a bot_name (defaults to “A bot”),
a history_filename (defaults to SECRETS_DIR/bot_name-history.json),
and a delay,
which is the time the bot will sleep after posting.
With a botskeleton,
you can send to the outputs in various ways (outputs described later).
All methods will generate IterationRecords,
update the history,
and save the history.


Bot Methods
These are methods intended to be used to send bot methods.

send(self, text, text=TEXT)
send is a plain text send method.
It will send the text to all configured outputs and save the result.
text can be provided either as a positional argument or a keyword one.


send_with_one_media(self, text, filename, caption, text=TEXT, filename=FILENAME, caption=CAPTION)
send_with_one_media will call each output and have them upload the file
(as dictated by the output),
and send a message with the provided text and that image.
If a caption is provided,
it will be uploaded alongside the image as appropriate.
A default caption will be used if none is provided.
text, filename, and caption can be provided either as positional arguments,
in which case they MUST be in this order,
or as keyword ones.


send_with_many_media(self, text, *filenames, text=TEXT, filenames=FILENAMES, caption=CAPTION)
send_with_many_media will call each output and have them upload several files
(as dictated by the output),
and send a message with the provided text and those image.
A current known bug is that the built-in outputs limits how many images they can post at once,
but there is no limiting in this method.
If you post more than four images with this method,
you may see strange results in the outputs.
If captions are provided,
they will be uploaded alongside the images as appropriate.
A default caption will be used for all images ifnone is provided,
and for images with no caption if insufficient captions are provided.
text and filenames can be provided either as positional arguments,
in which case they MUST be in this order,
or as keyword ones.
caption must be provided as a keyword argument.


nap(self)
Sleep for the configured amount of seconds.


store_extra_info(self, key, value)
store_extra_info will take the provided key and value and store them.
When history is updated,
extra_info is also stored in the history file.
The intended use case is to store something related to each post,
like a random seed used to generate the text,
or some related values that might be nice to see alongside it in the history storage.
Feel free to store whatever you like.


store_extra_keys(self, dict)
store_extra_keys will take an entire dictionary,
and merge it with the extra_keys storage.
As before,
this will be stored in thie history logs.


update_history(self)
Save the in-object history to disk,
in the history file.
History is saved as pretty-printed JSON.
This is called automatically by every send method.


load_history(self)
Load the history from disk. Done automatically when the BotSkeleton object is initialized.



Utility Methods
Some utility methods,
exposed from bottilities

rate_limited(max_per_hour, *args)
Annotation to rate-limit a function.
It will sleep such that it is called no more than max_per_hour times per hour.


set_up_logging(log_filename)
Set up a logger with the provided filename.
This is called by the constructor automatically.


random_line(file_path)
Return a random line from the provided file.
Useful for bots.


repair(record)
NOT INTENDED FOR MANUAL USE.
This is a method to repair a particular form of history corruption.
Automatically called by load_history.



IterationRecord
Record of one iteration -
one generation of text and a send to all outputs.
Stores extra keys,
a timestamp,
and records for all outputs (see output section).


Other Information


Outputs
botskeleton is designed to output to an arbitrary number of outputs.
Outputs need to be in the outputs property in BotSkeleton.
They need to have an “active” key,
used to decide whether to output,
and an “obj” key that should be a call to the constructor of the object.
output/output_utils.py defines the OutputSkeleton new outputs must subclass,
and some useful utilities for new outputs.
NOTE Outputs are not considered part of the public API.
output/output_utils.py may change without warning,
as may the arguments they take.

Activation
Outputs are activated if there is a credential directory available for them.
The credential directory is expected to be under “secret_dir”,
and to have a name of the form credentials_{output_name}.


Methods
These mirror the methods in botskeleton.py,
but aren’t guaranteed to be identical,
and,
again,
may change without warning.
Outputs must implement these themselves.


send(self, message)
Send message with text.


send_with_one_media(self, message, filename)
Send message with text and filename.
Output will process file as necessary.


send_with_many_media(self, message, *filenames)
Send message with text and filenames.
Output will process files as necessary.


linfo/ldebug/lerror(self, message)
Log with bot name and message at the given level.


set_duplicate_handler(self, duplicate_handler)
Set duplicate handler.
This is based off of birdsite’s error code and likely will be removed,
in favor of just having it in the birdsite output.
Error handlers are stored in self.handled_errors,
a dictionary.


OutputRecord object
Outputs maintain an OutputRecord object,
representing a single send to the output.
They maintain at least a _type and timestamp.
Individual outputs can add whatever else they like.
Methods are provided here to convert to a pretty string,
and to convert back from a dictionary to an object.


default_duplicate_handler(self)
Default duplicate error handler.
Does nothing.



Built-in Outputs
There are two built-in outputs:
birdsite (twitter.com)
mastodon (mastodon.social)
These are subject to change as necessary by the underlying API wrappers they use.
Some notes:

outputs/output_birdsite.py
Credentials directory is SECRETS_DIR/output_birdsite.
This output expects the following files to be present,
with proper contents.
Creating birdsite accounts and getting keys is beyond the scope of this document.

CONSUMER_KEY
CONSUMER_SECRET
ACCESS_TOKEN
ACCESS_SECRET

Optionally,
this file can be provided.
This is used to send DMs when errors are encountered.

OWNER_HANDLE



outputs/output_mastodon.py
Credentials directory is SECRETS_DIR/output_mastodon.
This output expects the following files to be present,
with proper contents.
Creating mastodon bot accounts and getting keys is beyond the scope of this document.

ACCESS_TOKEN

Optionally,
this file can be provided.
By default,
the output will try to send to https://mastodon.social.
It is recommended to change this,
perhaps to https://botsin.space,
and make sure you make an account there.

INSTANCE_BASE_URL




Examples
I operate several bots using this API,
and can attest to its general stability.

https://github.com/lunemercove/dirtyunix_bot
https://github.com/lunemercove/weatherbotskeleton
https://github.com/lunemercove/isthisska_bot
https://github.com/lunemercove/goties_bot
https://github.com/lunemercove/nonogram_bot
https://github.com/lunemercove/tree_bot
https://github.com/lunemercove/knowsska_bot