ananas The Python Bot Framework for Mastodon开源项目

Ananasallowsyoutowritesimple(orcomplicated!)mastodonbotswithouthavingtorewriteconfigfileloading,interval-basedposting,scheduledposting,auto-replying,andsoon.

Somebotsareassimpleasaconfigurationfile:

Butit'seasytowriteonewithcustomizedbehavior:

Runmultiplebotsonmultipleinstancesoutofasingleconfigfile:

AndusetheDEFAULTsectiontosharecommonconfigurationoptionsbetweenthem:

Theananaspippackagecomeswithascripttohelpyoumanageyourbots.

Simplygiveitaconfigfileandit'llloadyourbotsandclosethemsafelywhenitreceivesakeyboardinterrupt,SIGINT,SIGTERM,orSIGKILL.

Ifyouhaven'tspecifiedaclientid/secretoraccesstoken,thescriptwillexitunlessyourunitwiththe--interactiveflag,whichallowsittopromptyoufortheinstancelogininformation.(Theonlypartoftheinputyouenterherethat'sstoredintheconfigfileistheinstancename--theemailandpasswordareonlyusedtogeneratetheaccesstoken).

ThefollowingfieldsareinterpretedbythePineappleBotbaseclasssandwillworkforeverybot:

class:thefully-specifiedpythonclassthattherunnerscriptshouldinstantiatetostartyourbot.e.g."ananas.default.TraceryBot"

domain¹:thedomainoftheinstancetoruntheboton.Mustsupporthttpsconnections.Onlyincludethedomain,noprotocolorslashes.e.g."mastodon.social"

client_id¹,client_secret¹:thetokensthattheinstanceusestoidentifywhatclientthisbotispostingfrom/as.Willbeusedtodeterminewhat'sdisplayedunderneathallthepostsmadebythisbot.

access_token¹:theaccesstokenusedtoauthenticateAPIrequestswiththeinstance.Makesurethisissecret,don'tdistributeconfigfileswiththisfieldfilledoutorpeoplewillbeabletopostundertheaccountthistokenwascreatedwith.

admin:thefullusername(withoutleading@)oftheusertoDMerrorreportsto.Canbeleftunspecified,butisusefulforkeepinganeyeonthehealthofthebotwithoutconstantlymonitoringthescriptlogs.e.g.admin@example.town

¹:Filledoutautomaticallyifthebotisrunininteractivemode.

Additionalfieldsarespecifictothetypeofbot,refertothedocumentationforthebot'sclassformoreinformationaboutthefieldsitexpects.

Custombotclassesshouldbesubclassesofananas.PineappleBot.Ifyouoverride__init__,besuretocallthebaseclass's__init__.

Inorderforthebottodoanything,youshouldaddamethoddecoratedwithatleastoneofthefollowingdecorators:

@ananas.reply:Callsthedecoratedfunctionwhenthebotismentionedbyanyotheruser.Decoratortakesnoparameters,butshouldonlybecalledonfunctionsmatchingthissignature:defreply_fn(self,mention,user).mentionwillbethedictionarycorrespondingtothestatuscontainingthemention(asreturnedbythemastodonAPI,userwillbethedictionarycorrespondingtotheuserthatmentionedthebot.

@ananas.interval(secs):Callsthedecoratedfunctioneverysecsseconds,startingwhenthebotisinitialized.Forintervalslongerthan~anhour,youmaywanttouse@scheduleinstead.e.g.@ananas.interval(60)

@ananas.schedule(**kwargs):Allowsyoutoschedule,cron-style,thedecoratedfunction.Acceptedkeywordsare"second","minute","hour","day_of_week"or"day_of_month"(butnotboth),"month",and"year".Ifanyofthesekeywordsarenotspecified,theywillbetreatedlikecrontreatsan*,thatis,aslongasthetimematchestheothervalues,anyvaluewillbeaccepted.Speakingofwhich,thecron-likesyntax"*"aswellas"*/3"arebothaccepted,andwillexpandtotheexpectedthing:forexample,schedule(hour="*/2",minute="*/10")willpostevery10minutesduringhourswhicharemultiplesof2.

@ananas.hourly(minute=0),@ananas.daily(hour=0,minute=0):Shortcutsfor@ananas.schedule()thatcallthedecoratedfunctiononceanhouratthespecifiedminuteoronceadayatthespecifiedhourandminute.Ifparametersareomittedthey'llpostatthetopofthehourormidnight(UTC).

@ananas.error_reporter:specifiescustombehaviorforreportingerrors.Thedecoratedfunctionshouldmatchthissignature:deferr(self,error)whereerrorisastringrepresentationoftheerror.

Youcanalsodefinethefollowingfunctionsandtheywillbecalledattherelevantpointsinthebot'slifecycle:

init(self):calledbeforetheconfigurationfilehasbeenloaded,sothatyoucansetdefaultvaluesforconfigfieldsincasetheconfigfiledoesn'tspecifythem.

start(self):calledafteralloftheinternalPineappleBotinitializationiscompleteandthemastodonAPIisreadytouse.Agoodplacetoloadfilesspecifiedintheconfig,postastartupnotice,orotherwisedobot-specificsetup.

stop(self):calledwhenthebothasreceivedashutdownsignalandneedstostop.Theconfigfilewillbesavedafterthis,soifyouneedtomakeanylastminutechangestotheconfig,dothathere.

Alloftheconfigurationfieldsforthecurrentbotareavailablethroughtheself.configobject,whichexposesthemwithbothfield-accessorsyntaxanddictionary-accessorsyntax,forexample:

Thesecanberead(togettheuser'sconfigurationdata)orwrittento(toaffecttheconfigfileonnextsave)ordeleted(toremovethatfieldfromtheconfigfile).

Youcancallself.config.load()togetthelatestvaluesfromtheconfigfile.loadtakesanoptionalparametername,whichisthenameofthesectiontoloadintheconfigfileincaseyouwanttoloadadifferentonethanthebotwasstartedwith.

Youcanalsocallself.config.save()towriteanychangesmadesincethelastloadbacktotheconfigfile.

Notethatifyoucallself.config.load()duringbotoperation,withoutfirstcallingself.config.save(),youwilldiscardanychangesmadetotheconfigurationsincethelastload.

Youcandistributebotshoweveryouwant;aslongastheclassisavailableinsomemoduleinpython'ssys.pathoramoduleaccessiblefromthecurrentdirectory,therunnerscriptwillbeabletoloadit.

Ifyouthinkyourbotmightbegenerallyusefultootherpeople,feelfreetocreateapullrequestonthisrepositorytogetitaddedtothecollectionofdefaultbots.

Questions?PingmeonMastodonat@chr@cybre.spaceorshootmeanemailatchr@cybre.spaceandI'llanswerasbestIcan!