Package: botskeleton
shortskeleton for bot children written in Python.Created by Luné Mercové ahead of #NaBoMaMo 2017longbotskeleton is a framework for content bots,
likeTwitter botsandMastodon botsPublic APIThe public API is contained entirely in botskeleton.py.BotskeletonTheBotSkeletonclass is the main object for a bot,
holding all the send methods and credentials.
It MUST be constructed with asecrets_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 toSECRETS_DIR/log),
a bot_name (defaults to “A bot”),
a history_filename (defaults toSECRETS_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 generateIterationRecords,
update the history,
and save the history.Bot MethodsThese are methods intended to be used to send bot methods.send(self, text, text=TEXT)sendis a plain text send method.
It will send the text to all configured outputs and save the result.textcan 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_mediawill 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, andcaptioncan 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_mediawill 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.textandfilenamescan be provided either as positional arguments,
in which case they MUST be in this order,
or as keyword ones.captionmust be provided as a keyword argument.nap(self)Sleep for the configured amount of seconds.store_extra_info(self, key, value)store_extra_infowill 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_keyswill take an entire dictionary,
and merge it with theextra_keysstorage.
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 theBotSkeletonobject is initialized.Utility MethodsSome utility methods,
exposed frombottilitiesrate_limited(max_per_hour, *args)Annotation to rate-limit a function.
It will sleep such that it is called no more thanmax_per_hourtimes 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 byload_history.IterationRecordRecord 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 InformationOutputsbotskeletonis designed to output to an arbitrary number of outputs.
Outputs need to be in theoutputsproperty inBotSkeleton.
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.pydefines theOutputSkeletonnew outputs must subclass,
and some useful utilities for new outputs.NOTE Outputs are not considered part of the public API.output/output_utils.pymay change without warning,
as may the arguments they take.ActivationOutputs 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 formcredentials_{output_name}.MethodsThese mirror the methods inbotskeleton.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 inself.handled_errors,
a dictionary.OutputRecordobjectOutputs maintain anOutputRecordobject,
representing a single send to the output.
They maintain at least a_typeand 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 OutputsThere 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.pyCredentials directory isSECRETS_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_KEYCONSUMER_SECRETACCESS_TOKENACCESS_SECRETOptionally,
this file can be provided.
This is used to send DMs when errors are encountered.OWNER_HANDLEoutputs/output_mastodon.pyCredentials directory isSECRETS_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_TOKENOptionally,
this file can be provided.
By default,
the output will try to send tohttps://mastodon.social.
It is recommended to change this,
perhaps tohttps://botsin.space,
and make sure you make an account there.INSTANCE_BASE_URLExamplesI operate several bots using this API,
and can attest to its general stability.https://github.com/lunemercove/dirtyunix_bothttps://github.com/lunemercove/weatherbotskeletonhttps://github.com/lunemercove/isthisska_bothttps://github.com/lunemercove/goties_bothttps://github.com/lunemercove/nonogram_bothttps://github.com/lunemercove/tree_bothttps://github.com/lunemercove/knowsska_bot