better documentation

[rmundkowsky]

For a naïve user (myself), I have no idea what your software does. I do not know what "switchy" is and there is no link to that. A better written Readme.md with info on what your tool does would be helpful. I am guessing it can tall to FreeSWITCH using its event socket.

[goodboy]

Hi @rmundkowsky thanks for the input. I see the link to the switchy project is indeed broken; fixing that shortly.

The intro example in the readme, namely,

import switchio
from switchio.apps.routers import Router

router = Router(guards={
    'Call-Direction': 'inbound',
    'variable_sofia_profile': 'external'})

@router.route('(.*)')
async def welcome(sess, match, router):
    """Say hello to inbound calls.
    """
    await sess.answer()  # resumes once call has been fully answered

    sess.playback('ivr/ivr-welcome_to_freeswitch.wav') # non-blocking
    sess.log.info("Playing welcome message")
    await sess.recv("PLAYBACK_STOP")

    await sess.hangup()  # resumes once call has been fully hungup

Run this app (assuming it's in dialplan.py) from the shell:

$ switchio serve my-fs-host.com --app ./dialplan.py:router

Shows how you can build a routing system for a FreeSWITCH cluster and the API should be mostly familiar to anyone who's used one of the mentioned python frameworks (i.e. flask is a similar API but for a web server). The whole point is to not get into the gritty details of how switchio controls FreeSWITCH since it's not all that relevant to the user at the inset.

The point about ESL should be mentioned in the section How do I deploy my FreeSWITCH cluster?. But yes you are correct, this projects contains an asyncio protocol for inbound ESL.

The full docs (which as mentioned in the introductory email are still out of date and yes need a revamp) are also linked to from the readme and project url. They can be found here.

Hope that helps. If you have any further questions or criticisms we appreciate the feedback 👍

[rmundkowsky]

Thanks for you response. I am familiar with flask and some telephony, but not your tool. Routing means a lot of different things and in terms of VoIP telephony I guess usually refers to SIP routing and not a dial plan. I am curious how much of the FreeSWITCH ESL is covered by switchio or switchy. Anyways I would suggest language like:

switchio is a Python (3.x) library that allows you to use function decorators to create FreeSWITCH dial plans fully in Python in a similar manner as Flask is used for creating web services.

[goodboy]

Closing as there is already an outstanding docs issue #33.