Metadata-Version: 1.1
Name: aiomonitor
Version: 0.1.0
Summary: aiomonitor adds monitor and python REPL capabilities for asyncio application
Home-page: https://github.com/jettify/aiomonitor
Author: Nikolay Novik
Author-email: nickolainovik@gmail.com
License: Apache 2
Download-URL: https://github.com/jettify/aiomonitor
Description: aiomonitor
        ==========
        .. image:: https://travis-ci.org/jettify/aiomonitor.svg?branch=master
            :target: https://travis-ci.org/jettify/aiomonitor
        .. image:: https://codecov.io/gh/jettify/aiomonitor/branch/master/graph/badge.svg
            :target: https://codecov.io/gh/jettify/aiomonitor
        
        
        **aiomonitor** is Python 3.5+ module that adds monitor and cli capabilities
        for asyncio_ application. Idea and code borrowed from curio_ project.
        Task monitor that runs concurrently to the asyncio_ loop (or fast drop in
        replacement uvloop_) in a separate thread. This can inspect the loop and
        provide debugging capabilities.
        
        Library provides an python console using aioconsole_ module, it is possible
        to execute asynchronous command inside your running application.
        
        
        Installation
        ------------
        Installation process is simple, just::
        
            $ pip install aiomonitor
        
        
        Example
        -------
        Monitor has context manager interface:
        
        .. code:: python
        
            import aiomonitor
        
            loop = asyncio.get_event_loop()
            with aiomonitor.start_monitor(loop=loop):
                loop.run_forever()
        
        Now from separate terminal it is possible to connect to the application::
        
            $ nc localhost 50101
        
        or using included python client::
        
            $ python -m aiomonitor.cli
        
        Tutorial
        --------
        
        Lets create simple aiohttp_ application, and see how ``aiomonitor`` can
        integrates with it.
        
        .. code:: python
        
            import asyncio
        
            import aiomonitor
            from aiohttp import web
        
            # Simple handler that returns response after 100s
            async def simple(request):
                loop = request.app.loop
        
                print('Start sleeping')
                await asyncio.sleep(100, loop=loop)
                return web.Response(text="Simple answer")
        
            loop = asyncio.get_event_loop()
            # create application and register route create route
            app = web.Application(loop=loop)
            app.router.add_get('/simple', simple)
        
            # init monitor just before run_app
            with aiomonitor.start_monitor(loop=loop):
                # run application with built in aiohttp run_app function
                web.run_app(app, port=8090, host='localhost')
        
        Lets save this code in file ``simple_srv.py``, so we can run it with command::
        
            $ python simple_srv.py
            ======== Running on http://localhost:8090 ========
            (Press CTRL+C to quit)
        
        And now one can connect running application from separate terminal, with
        ``nc`` command, immediately ``aiomonitor`` will respond with prompt::
        
            $ nc localhost 50101
            Asyncio Monitor: 1 tasks running
            Type help for commands
            monitor >>>
        
        Now you can type commands, for instance ``help``::
        
            monitor >>> help
            Commands:
                         ps               : Show task table
                         where taskid     : Show stack frames for a task
                         cancel taskid    : Cancel an indicated task
                         signal signame   : Send a Unix signal
                         console          : Switch to async Python REPL
                         quit             : Leave the monitor
        
        ``aiomonitor`` supports also async python console inside running event loop
        so you can explore state of your application::
        
            monitor >>> console
            Python 3.5.2 (default, Oct 11 2016, 05:05:28)
            [GCC 4.2.1 Compatible Apple LLVM 8.0.0 (clang-800.0.38)] on darwin
            Type "help", "copyright", "credits" or "license" for more information.
            ---
            This console is running in an asyncio event loop.
            It allows you to wait for coroutines using the 'await' syntax.
            Try: await asyncio.sleep(1, result=3, loop=loop)
            ---
            >>> await asyncio.sleep(1, result=3, loop=loop)
        
        To leave console type ``exit()``::
        
            >>> exit()
            monitor >>>
        
        
        Requirements
        ------------
        
        * Python_ 3.5+
        * aioconsole_
        * uvloop_ (optional)
        
        
        .. _PEP492: https://www.python.org/dev/peps/pep-0492/
        .. _Python: https://www.python.org
        .. _aioconsole: https://github.com/vxgmichel/aioconsole
        .. _aiohttp: https://github.com/KeepSafe/aiohttp
        .. _asyncio: http://docs.python.org/3.5/library/asyncio.html
        .. _curio: https://github.com/dabeaz/curio
        .. _uvloop: https://github.com/MagicStack/uvloop
        
        CHANGES
        =======
        
        0.1.0 (2016-12-14)
        ------------------
        
        * Added missed LICENSE file
        
        * Updated API, added start_monitor() function
        
        
        0.0.3 (2016-12-11)
        ------------------
        
        * Fixed README.rst
        
        
        0.0.2 (2016-12-11)
        ------------------
        
        * Tests more stable now
        
        * Added simple tutorial to README.rst
        
        
        0.0.1 (2016-12-10)
        ------------------
        
        * Initial release.
Platform: POSIX
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Operating System :: POSIX
Classifier: Environment :: Web Environment
Classifier: Development Status :: 3 - Alpha
