aioswagger11


Nameaioswagger11 JSON
Version 0.9.1 PyPI version JSON
download
home_pagehttps://github.com/M-o-a-T/aioswagger11
SummaryAsynchronous library for accessing Swagger-1.1-enabled APIs
upload_time2018-04-13 12:35:32
maintainer
docs_urlNone
authorMatthias Urlichs
requires_python
licenseBSD 3-Clause License
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            About
-----

aioswagger11 is an asyncio-compatible clone of swagger.py, capable of
understanding Swagger 1.1 definitions (only).

As swagger has been renamed to OpenAPI which by now has version 3.0
(and has an actual specification – unlike Swagger 1.1) this library is
(mostly) only usable with Asterisk, which still uses Swagger 1.1
declarations.

Aioswagger11 supports a WebSocket extension, allowing a WebSocket to
be documented, and auto-generated WebSocket client code.

from swagger.py:
================

Swagger.py is a Python library for using
`Swagger <https://developers.helloreverb.com/swagger/>`__ defined APIs.

Swagger itself is best described on the Swagger home page:

    Swagger is a specification and complete framework implementation for
    describing, producing, consuming, and visualizing RESTful web
    services.

The `Swagger
specification <https://github.com/wordnik/swagger-core/wiki>`__ defines
how APIs may be described using Swagger.

Usage
-----

Install the latest release from PyPI.

::

    $ sudo pip install aioswagger11

Or install from source using the ``setup.py`` script.

::

    $ sudo ./setup.py install

API
===

aioswagger11 will dynamically build an object model from a Swagger-enabled
RESTful API.

Here is a simple example using the `Asterisk REST
Interface <https://wiki.asterisk.org/wiki/display/AST/Asterisk+12+ARI>`__

.. code:: Python

    #!/usr/bin/env python3

    import json
    import asyncio
    import aiohttp

    from aioswagger11.client import SwaggerClient
    from aioswagger11.http_client import AsynchronousHttpClient

    http_client = AsynchronousHttpClient()
    http_client.set_api_key('localhost', 'hey:peekaboo')

    async def run(ari,msg_json):
        channelId = msg_json['channel']['id']
        await ari.channels.answer(channelId=channelId)
        await ari.channels.play(channelId=channelId,
                        media='sound:hello-world')
        # In a real program you should wait for the PlaybackFinished event instead
        await asyncio.sleep(3)
        await ari.channels.continueInDialplan(channelId=channelId)

    async def main():
        ari = SwaggerClient(
            "http://localhost:8088/ari/api-docs/resources.json",
            http_client=http_client)

        ws = ari.events.eventWebsocket(app='hello')

        async for msg_str in ws:
            if msg.type in {aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.CLOSING}:
                break
            elif msg.type != aiohttp.WSMsgType.TEXT:
                continue # ignore

            msg_json = json.loads(msg_str)
            if msg_json['type'] == 'StasisStart':
                asyncio.ensure_future(run(ari,msg_json))

    if __name__ == "__main__":
        loop = asyncio.get_event_loop()
        loop.run_until_complete(main())

Data model
==========

The data model presented by the ``swagger_model`` module is nearly
identical to the original Swagger API resource listing and API
declaration. This means that if you add extra custom metadata to your
docs (such as a ``_author`` or ``_copyright`` field), they will carry
forward into the object model. I recommend prefixing custom fields with
an underscore, to avoid collisions with future versions of Swagger.

There are a few meaningful differences.

-  Resource listing
-  The ``file`` and ``base_dir`` fields have been added, referencing the
   original ``.json`` file.
-  The objects in a ``resource_listing``'s ``api`` array contains a
   field ``api_declaration``, which is the processed result from the
   referenced API doc.
-  API declaration
-  A ``file`` field has been added, referencing the original ``.json``
   file.

Development
-----------

The code is documented using `Sphinx <http://sphinx-doc.org/>`__, which
allows `IntelliJ IDEA <http://confluence.jetbrains.net/display/PYH/>`__
to do a better job at inferring types for autocompletion.

To keep things isolated, I also recommend installing (and using)
`virtualenv <http://www.virtualenv.org/>`__.

::

    $ sudo pip install virtualenv
    $ mkdir -p ~/virtualenv
    $ virtualenv ~/virtualenv/swagger
    $ . ~/virtualenv/swagger/bin/activate

`Setuptools <http://pypi.python.org/pypi/setuptools>`__ is used for
building. `Pytest <http://pytest.readthedocs.org/en/latest/>`__ is used
for unit testing, with the `coverage
<http://nedbatchelder.com/code/coverage/>`__ plugin installed to
generated code coverage reports. Pass ``--with-coverage`` to generate
the code coverage report. HTML versions of the reports are put in
``cover/index.html``.

::

    $ ./setup.py develop   # prep for development (install deps, launchers, etc.)
    $ ./setup.py pytest    # run unit tests
    $ ./setup.py bdist_egg # build distributable


Testing
=======

Simply run ``python3 setup.py pytest``.

Note that testing this module requires a version of httpretty that's been
fixed to work with aiohttp.

License
-------

Copyright (c) 2013, Digium, Inc.
Copyright (c) 2018, Matthias Urlichs

aioswagger11 is licensed with a `BSD 3-Clause
License <http://opensource.org/licenses/BSD-3-Clause>`__.

The current author humbly requests that you share any further bug fixes or
enhancements to this code.


            

Raw data

            {
    "maintainer": "", 
    "docs_url": null, 
    "requires_python": "", 
    "maintainer_email": "", 
    "cheesecake_code_kwalitee_id": null, 
    "keywords": "", 
    "upload_time": "2018-04-13 12:35:32", 
    "author": "Matthias Urlichs", 
    "home_page": "https://github.com/M-o-a-T/aioswagger11", 
    "github_user": "M-o-a-T", 
    "download_url": "https://pypi.python.org/packages/ed/42/6badef3819b597622f95a3c35d1bd6d1ab9d7218c60bcc538cf7eeb9025e/aioswagger11-0.9.1.tar.gz", 
    "platform": "", 
    "version": "0.9.1", 
    "cheesecake_documentation_id": null, 
    "description": "About\n-----\n\naioswagger11 is an asyncio-compatible clone of swagger.py, capable of\nunderstanding Swagger 1.1 definitions (only).\n\nAs swagger has been renamed to OpenAPI which by now has version 3.0\n(and has an actual specification \u2013 unlike Swagger 1.1) this library is\n(mostly) only usable with Asterisk, which still uses Swagger 1.1\ndeclarations.\n\nAioswagger11 supports a WebSocket extension, allowing a WebSocket to\nbe documented, and auto-generated WebSocket client code.\n\nfrom swagger.py:\n================\n\nSwagger.py is a Python library for using\n`Swagger <https://developers.helloreverb.com/swagger/>`__ defined APIs.\n\nSwagger itself is best described on the Swagger home page:\n\n    Swagger is a specification and complete framework implementation for\n    describing, producing, consuming, and visualizing RESTful web\n    services.\n\nThe `Swagger\nspecification <https://github.com/wordnik/swagger-core/wiki>`__ defines\nhow APIs may be described using Swagger.\n\nUsage\n-----\n\nInstall the latest release from PyPI.\n\n::\n\n    $ sudo pip install aioswagger11\n\nOr install from source using the ``setup.py`` script.\n\n::\n\n    $ sudo ./setup.py install\n\nAPI\n===\n\naioswagger11 will dynamically build an object model from a Swagger-enabled\nRESTful API.\n\nHere is a simple example using the `Asterisk REST\nInterface <https://wiki.asterisk.org/wiki/display/AST/Asterisk+12+ARI>`__\n\n.. code:: Python\n\n    #!/usr/bin/env python3\n\n    import json\n    import asyncio\n    import aiohttp\n\n    from aioswagger11.client import SwaggerClient\n    from aioswagger11.http_client import AsynchronousHttpClient\n\n    http_client = AsynchronousHttpClient()\n    http_client.set_api_key('localhost', 'hey:peekaboo')\n\n    async def run(ari,msg_json):\n        channelId = msg_json['channel']['id']\n        await ari.channels.answer(channelId=channelId)\n        await ari.channels.play(channelId=channelId,\n                        media='sound:hello-world')\n        # In a real program you should wait for the PlaybackFinished event instead\n        await asyncio.sleep(3)\n        await ari.channels.continueInDialplan(channelId=channelId)\n\n    async def main():\n        ari = SwaggerClient(\n            \"http://localhost:8088/ari/api-docs/resources.json\",\n            http_client=http_client)\n\n        ws = ari.events.eventWebsocket(app='hello')\n\n        async for msg_str in ws:\n            if msg.type in {aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.CLOSING}:\n                break\n            elif msg.type != aiohttp.WSMsgType.TEXT:\n                continue # ignore\n\n            msg_json = json.loads(msg_str)\n            if msg_json['type'] == 'StasisStart':\n                asyncio.ensure_future(run(ari,msg_json))\n\n    if __name__ == \"__main__\":\n        loop = asyncio.get_event_loop()\n        loop.run_until_complete(main())\n\nData model\n==========\n\nThe data model presented by the ``swagger_model`` module is nearly\nidentical to the original Swagger API resource listing and API\ndeclaration. This means that if you add extra custom metadata to your\ndocs (such as a ``_author`` or ``_copyright`` field), they will carry\nforward into the object model. I recommend prefixing custom fields with\nan underscore, to avoid collisions with future versions of Swagger.\n\nThere are a few meaningful differences.\n\n-  Resource listing\n-  The ``file`` and ``base_dir`` fields have been added, referencing the\n   original ``.json`` file.\n-  The objects in a ``resource_listing``'s ``api`` array contains a\n   field ``api_declaration``, which is the processed result from the\n   referenced API doc.\n-  API declaration\n-  A ``file`` field has been added, referencing the original ``.json``\n   file.\n\nDevelopment\n-----------\n\nThe code is documented using `Sphinx <http://sphinx-doc.org/>`__, which\nallows `IntelliJ IDEA <http://confluence.jetbrains.net/display/PYH/>`__\nto do a better job at inferring types for autocompletion.\n\nTo keep things isolated, I also recommend installing (and using)\n`virtualenv <http://www.virtualenv.org/>`__.\n\n::\n\n    $ sudo pip install virtualenv\n    $ mkdir -p ~/virtualenv\n    $ virtualenv ~/virtualenv/swagger\n    $ . ~/virtualenv/swagger/bin/activate\n\n`Setuptools <http://pypi.python.org/pypi/setuptools>`__ is used for\nbuilding. `Pytest <http://pytest.readthedocs.org/en/latest/>`__ is used\nfor unit testing, with the `coverage\n<http://nedbatchelder.com/code/coverage/>`__ plugin installed to\ngenerated code coverage reports. Pass ``--with-coverage`` to generate\nthe code coverage report. HTML versions of the reports are put in\n``cover/index.html``.\n\n::\n\n    $ ./setup.py develop   # prep for development (install deps, launchers, etc.)\n    $ ./setup.py pytest    # run unit tests\n    $ ./setup.py bdist_egg # build distributable\n\n\nTesting\n=======\n\nSimply run ``python3 setup.py pytest``.\n\nNote that testing this module requires a version of httpretty that's been\nfixed to work with aiohttp.\n\nLicense\n-------\n\nCopyright (c) 2013, Digium, Inc.\nCopyright (c) 2018, Matthias Urlichs\n\naioswagger11 is licensed with a `BSD 3-Clause\nLicense <http://opensource.org/licenses/BSD-3-Clause>`__.\n\nThe current author humbly requests that you share any further bug fixes or\nenhancements to this code.\n\n", 
    "lcname": "aioswagger11", 
    "bugtrack_url": null, 
    "github": true, 
    "coveralls": true, 
    "name": "aioswagger11", 
    "license": "BSD 3-Clause License", 
    "travis_ci": false, 
    "github_project": "aioswagger11", 
    "summary": "Asynchronous library for accessing Swagger-1.1-enabled APIs", 
    "split_keywords": [], 
    "author_email": "matthias@urlichs.de", 
    "urls": [
        {
            "has_sig": false, 
            "upload_time": "2018-04-13T12:35:32", 
            "comment_text": "", 
            "python_version": "source", 
            "url": "https://pypi.python.org/packages/ed/42/6badef3819b597622f95a3c35d1bd6d1ab9d7218c60bcc538cf7eeb9025e/aioswagger11-0.9.1.tar.gz", 
            "md5_digest": "71009c2ab49c6b92a19872f754d367ad", 
            "downloads": 0, 
            "filename": "aioswagger11-0.9.1.tar.gz", 
            "packagetype": "sdist", 
            "path": "ed/42/6badef3819b597622f95a3c35d1bd6d1ab9d7218c60bcc538cf7eeb9025e/aioswagger11-0.9.1.tar.gz", 
            "digests": {
                "sha256": "6d7ac31699d5e5db0287e143226545d02a689ab4ce10af506a0872f2a8489a03", 
                "md5": "71009c2ab49c6b92a19872f754d367ad"
            }, 
            "sha256_digest": "6d7ac31699d5e5db0287e143226545d02a689ab4ce10af506a0872f2a8489a03", 
            "size": 28229
        }
    ], 
    "_id": null, 
    "cheesecake_installability_id": null
}