Metadata-Version: 2.4
Name: asyncswagger11
Version: 0.21.0
Summary: Asynchronous library for accessing Swagger-1.1-enabled APIs
Author-email: Matt Jordan <mjordan@digium.com>, Matthias Urlichs <matthias@urlichs.de>
License: Copyright (c) 2013, Digium, Inc.
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions
        are met:
        
        	Redistributions of source code must retain the above copyright
        	notice, this list of conditions and the following disclaimer.
        
        	Redistributions in binary form must reproduce the above
        	copyright notice, this list of conditions and the following
        	disclaimer in the documentation and/or other materials
        	provided with the distribution.
        
        	The name of Digium, Inc., or the name of any Contributor,
        	may not be used to endorse or promote products derived from this
        	software without specific prior written permission.
        
        THIS SOFTWARE IS NOT FAULT TOLERANT AND SHOULD NOT BE USED IN ANY
        SITUATION ENDANGERING HUMAN LIFE OR PROPERTY.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
        ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
        LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
        FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
        COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
        INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
        (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
        HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
        STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
        OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/M-o-a-T/asyncswagger11
Keywords: swagger
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: httpx
Provides-Extra: test
Requires-Dist: mocket; extra == "test"
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

About
-----

asyncswagger11 is an anyio-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.

Asyncswagger11 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.

::

    $ pip install asyncswagger11

Or install from source:

::

    $ python3 -mbuild


API
===

asyncswagger11 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 anyio

    from asyncswagger11.client import SwaggerClient
    from asyncswagger11.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 anyio.sleep(3)
        await ari.channels.continueInDialplan(channelId=channelId)

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

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

            async for msg in ws:
                if not isinstance(msg, WebsocketDataMessage):
                    break
                elif not isinstance(msg, WebsocketTextMessage):
                    continue # ignore bytes

                msg_json = json.loads(msg.data)
                if msg_json['type'] == 'StasisStart':
                    await nursery.start_soon(run,ari,msg_json)

    if __name__ == "__main__":
        anyio.run(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 standalone-testing this module currently is not possible.
Previous versions required a hacked version of httpretty.

TODO: use a local server instead.


License
-------

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

asyncswagger11 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.

