Package: botstory
# State [![support python versions](https://img.shields.io/pypi/pyversions/botstory.svg)](https://pypi.python.org/pypi/botstory/) [![PyPI version](https://img.shields.io/pypi/v/botstory.svg)](https://pypi.python.org/pypi/botstory/) [![Build Status](https://travis-ci.org/botstory/botstory.svg?branch=develop)](https://travis-ci.org/botstory/botstory) [![Coverage Status](https://coveralls.io/repos/github/botstory/botstory/badge.svg?branch=develop)](https://coveralls.io/github/botstory/botstory?branch=develop) [![](https://img.shields.io/pypi/l/botstory.svg)](https://github.com/botstory/botstory/blob/develop/LICENSE.txt)Under active development. API could change so please follow for changes.# Get Started```pythonimport botstoryfrom botstory.integrations import aiohttp, fb, mongodbimport osstory = botstory.Story()# setup modules# facebook integrationstory.use(fb.FBInterface(webhook_url='/webhook{}'.format(os.environ.get('FB_WEBHOOK_URL_SECRET_PART', '')),webhook_token=os.environ.get('FB_WEBHOOK_TOKEN', None),))# http interfacestory.use(aiohttp.AioHttpInterface(port=int(os.environ.get('PORT', 8080)),))# db interfacestory.use(mongodb.MongodbInterface(uri=os.environ.get('MONGODB_URI', 'mongo'),db_name=os.environ.get('MONGODB_DB_NAME', 'todobot'),))# match user queries@story.on('Hello')def hello_story():@story.part()async def say_hi(ctx):await story.say('Hello {}!'.format(ctx['user'].name))# start serviceasyncio.get_event_loop().run_until_complete(story.start())```# Features- **Use frontier features of Python***Botstory is heavily based on brand new Python features, like async/await.We always focus on its evolution and don't support legacy versions (<3.5).*- **All messengers in one place***Right now botstory supports only fb Messengers, but we are going tosupport many others. So you can use common code base for differentplatform and seamlessly organize communication between them. As wellwe always open for contribution. And if you sure that one platformshould be here, just drop PR with unit tests.*- **More than 90% test coverage***Code is covered by tests except few trivial places.That way we are almost sure that any changes won't break otherfunctionality. And any breaking features won't come hidden.*- **Declarative user dialogs***Match user queries, lead, fork and loop dialogs.*- **Store use session***We remember user context and could return it any time and on anyapp instance. So you can scale app, and start and stop it withoutfair of bot amnesia.*- **Easily scale***We focus on micro-services and especially on Docker. So you canvery easy scale any part of the system.*- **Open source***MIT licence gives you many rights. And we are very open for yourcontribution and would love to hear about your experience.*and many other features# News and Changelog[CHANGELOG.md](CHANGELOG.md)# BackgroundWe are developing botstory mindful of the need to have easily reading APIwhich describe dialogues (scenario) of bots in Python language.Key problem is async nature of any dialog -we can wait answer from user for are months and should store contextuntil that. As well dialog structure should be simply and clearand show sequence of questions and reactions.Sure dialog can be made in diagrams but my thought that code shouldclear enough to show story of dialog and should be open for modification.As well it is too hard to use git for store versions of diagrams.# Install```bashpip install botstory```# Examples- [TODO bot](https://github.com/botstory/todo-bot) - support fb messenger## Linear dialog```python"""v0.0.63Bot asks user about destination of space travelling.- stateless story. it stores context of story (current question and results) somewhere (maybe DB)"""@story.on('lets go!')def stateless_story():@story.part()async def ask_destination(ctx):return await story.ask('Where do you go?',user=ctx['user'])@story.part()async def ask_origin(ctx):store_destination(ctx['message']['location'])return await story.ask('Where do you now?',user=ctx['user'])@story.part()async def thanks(ctx):store_origin(ctx['message']['location'])return await story.say('Thanks!\n''Give me a minute I will find you right spaceship!',user=ctx['user'])```## Forking of Dialog (bifurcations)```python"""v0.0.63Bot asks user about destination of space travelling.- stateless story. it stores context of story (current question and results) somewhere (maybe DB)"""@story.on('lets go!')def stateless_story_with_bifurcation():@story.part()async def request_destination(ctx):return await story.ask('Where do you go?',user=ctx['user'])@story.case('stars')def stars():@story.part()async def receive_destination_options(ctx):return await story.ask('Which star do you prefer?',user=ctx['user'])@story.case('planets')def planets():@story.part()async def request_origin(ctx):return await story.ask('Which planet do you prefer?',user=ctx['user'])@story.case(default=True)def other():@story.part()async def choose_from_top10_planets(ctx):return await choose_option(top10_planets,text='Here is the most popular places. Maybe you would like to choose one?',user=ctx['user'])@story.part()async def receive_destination(ctx):store_destination(ctx['message']['location'])return await story.say('Thanks! Give me a minute I will find you right spaceship!',user=ctx['user'])```## Reuse parts of Dialog (callable) and Dialog Loops```pythonfrom botstory.ast import callable, loop, story_contextfrom botstory.middlewares import option, sticker, textimport emojiimport loggingfrom todo import reflection# Loop versionasync def show_list_next_page(ctx):user_data = story_context.get_user_data(ctx)page_index = user_data.get('page_index', 0)list_title = user_data['list_title']title_field = user_data['title_field']page_length = user_data['page_length']list_type = user_data.get('list_type', 'pure')# render page of list ....@story.callable()def pagination_loop():@story.part()async def show_zero_page(ctx):if not await _show_list_next_page(ctx):return callable.EndOfStory()@story.loop()def list_loop():@story.on([option.Match('NEXT_PAGE_OF_A_LIST'),sticker.Like(),text.text.EqualCaseIgnore('more'),text.text.EqualCaseIgnore('next'),])def next_page():@story.part()async def show_part_of_list(ctx):if not await show_list_next_page(ctx):return loop.BreakLoop()return None@story.on([text.EqualCaseIgnore('todo'),])def list_of_tasks_story():@story.part()async def list_of_tasks(ctx):logger.info('list of tasks')return await pagination_list.pagination_loop(ctx,subtitle_renderer=reflection.class_to_str(tasks_document.task_details_renderer),list_title='List of actual tasks:',list_type='template',page_length=os.environ.get('LIST_PAGE_LENGTH', 4),target_document=reflection.class_to_str(tasks_document.TaskDocument),title_field='description',)```# License[MIT](LICENSE.txt)# ContributingContributions of all sizes are welcome.