Main Components

App, Security, Client are components you would touch first when adapting pyswagger.

App

App carries Swagger API definition, other components would rely on it but not json files. You need to access Operation object via App.op by providing nickname or resource name plus nickname.

app = App._create_('http://petstore.swagger.wordnik.com/api/api-docs')
assert app.op['getPetsByStatus'] == app.op['pet', 'getPetsByStatus']

# resource name is required when nicknames collid
app.op['user', 'getById']
app.op['pet', 'getById']

The Operation object is callable, and can be provided by a set of Primitives, then return a pair of Request and Response.

Security

Security is a placeholder of authorizations,

# must be initialized with App
auth = Security(app)

# insert autorization information
app.update_with('simple_basicAuth', ('user', 'password'))
app.update_with('simple_apiKey', 'token123')
app.update_with('simple_oath2', 'token123456')

# pass into a client
client = TornadoClient(auth)

# authorization would be applied automatically
client.request(...)

Client

Clients are wrapper layer to hide implementation details from different http-request libraries.

To implement a customized client, please refer to customized client

Below is a code to demostrate the relation between these components.

app = App._create_('http://petstore.swagger.wordnik.com/api/api-docs')
auth = Security(app)
client = Client(auth)

# get Request and Response from Swagger.op
req, resp = app.op['getPetById'](Id=1)

# call request
resp = client.request((req, resp))

# get data back
assert resp.data.id == 1

Reference

class pyswagger.core.App(url=None, url_load_hook=None, sep='!##!', prim=None, mime_codec=None, resolver=None)[source]

Major component of pyswagger

This object is tended to be used in read-only manner. Therefore, all accessible attributes are almost read-only properties.

classmethod _create_(kls, url, strict=True)

factory of App

Parameters:
  • url (str) – url of path of Swagger API definition
  • strict (bool) – when in strict mode, exception would be raised if not valid.
Returns:

the created App object

Return type:

App

Raises:
  • ValueError – if url is wrong
  • NotImplementedError – the swagger version is not supported.
_validate()[source]

check if this Swagger API valid or not.

Parameters:strict (bool) – when in strict mode, exception would be raised if not valid.
Returns:validation errors
Return type:list of tuple(where, type, msg).
classmethod create(kls, url, strict=True)[source]

factory of App

Parameters:
  • url (str) – url of path of Swagger API definition
  • strict (bool) – when in strict mode, exception would be raised if not valid.
Returns:

the created App object

Return type:

App

Raises:
  • ValueError – if url is wrong
  • NotImplementedError – the swagger version is not supported.
dump()[source]

dump into Swagger Document

Return type:dict
Returns:dict representation of Swagger
classmethod load(kls, url, getter=None, parser=None, url_load_hook=None, sep='!##!', prim=None, mime_codec=None, resolver=None)[source]

load json as a raw App

Parameters:
  • url (str) – url of path of Swagger API definition
  • getter (sub class/instance of Getter) – customized Getter
  • parser (pyswagger.base.Context) – the parser to parse the loaded json.
  • app_cache (dict) – the cache shared by related App
  • url_load_hook (func) – hook to patch the url to load json
  • sep (str) – scope-separater used in this App
  • pyswager.primitives.Primitive (prim) – factory for primitives in Swagger
  • pyswagger.primitives.MimeCodec (mime_codec) – MIME codec
  • resolver – pyswagger.resolve.Resolver: customized resolver used as default when none is provided when resolving
Returns:

the created App object

Return type:

App

Raises:
  • ValueError – if url is wrong
  • NotImplementedError – the swagger version is not supported.
load_obj(jref, getter=None, parser=None)[source]

load a object(those in spec._version_.objects) from a JSON reference.

m

backward compatible to access Swagger.definitions in Swagger 2.0, and Resource.Model in Swagger 1.2.

ex. a Model:user in Resource:Users, access it by .m[‘Users’, ‘user’]. For Schema object in Swagger 2.0, just access it by it key in json.

Type:pyswagger.utils.ScopeDict
mime_codec

mime codec used by this app

Type:pyswagger.primitives.MimeCodec
op

list of Operations, organized by utils.ScopeDict

In Swagger 2.0, Operation(s) can be organized with Tags and Operation.operationId. ex. if there is an operation with tag:[‘user‘, ‘security’] and operationId:get_one, here is the combination of keys to access it: - .op[‘user’, ‘get_one’] - .op[‘security’, ‘get_one’] - .op[‘get_one’]

Type:pyswagger.utils.ScopeDict of pyswagger.spec.v2_0.objects.Operation
prepare(strict=True)[source]

preparation for loaded json

Parameters:strict (bool) – when in strict mode, exception would be raised if not valid.
prepare_obj(obj, jref)[source]

basic preparation of an object(those in sepc._version_.objects), and cache the ‘prepared’ object.

prim_factory

primitive factory used by this app

Type:pyswagger.primitives.Primitive
raw

raw objects for original version of loaded resources. When loaded json is the latest version we supported, this property is the same as App.root

Type:ex. when loading Swagger 1.2, the type is pyswagger.spec.v1_2.objects.ResourceList
resolve(jref, parser=None)[source]

JSON reference resolver

Parameters:
Returns:

the referenced object, wrapped by weakref.ProxyType

Return type:

weakref.ProxyType

Raises:

ValueError – if path is not valid

root

schema representation of Swagger API, its structure may be different from different version of Swagger.

There is ‘Schema’ object in swagger 2.0, that’s why I change this property name from ‘schema’ to ‘root’.

Type:pyswagger.spec.v2_0.objects.Swagger
s(p, b=('/', '#/paths'))[source]

shortcut of App.resolve. We provide a default base for ‘#/paths’. ex. to access ‘#/paths/~1user/get’, just call App.s(‘user/get’)

Parameters:
  • p (str) – path relative to base
  • b (tuple) – a tuple (expected_prefix, base) to represent a ‘base’
schemes

supported schemes, refer to Swagger.schemes in Swagger 2.0 for details

Type:list of str, ex. [‘http’, ‘https’]
url
validate(strict=True)[source]

check if this Swagger API valid or not.

Parameters:strict (bool) – when in strict mode, exception would be raised if not valid.
Returns:validation errors
Return type:list of tuple(where, type, msg).
version

original version of loaded json

Type:str
class pyswagger.core.Security(app)[source]

security handler

__init__(app)[source]

constructor

Parameters:app (App) – App
__call__(req)[source]

apply security info for a request.

Parameters:req (Request) – the request to be authorized.
Returns:the updated request
Return type:Request
update_with(name, security_info)[source]

insert/clear authorizations

Parameters:
  • name (str) – name of the security info to be updated
  • security_info ((username, password) for basicAuth, token in str for oauth2, apiKey.) – the real security data, token, ...etc.
Raises:

ValueError – unsupported types of authorizations

class pyswagger.contrib.client.requests.Client(auth=None, send_opt=None)[source]

Client implementation based on requests

class pyswagger.contrib.client.tornado.TornadoClient(auth=None)[source]

Client implementation based on tornado.http.AsyncHTTPClient.

Request

class pyswagger.io.Request(op, params)[source]

Request layer

base_path

base path of this request

Type:str
data

data carried by this request, only valid after ‘prepare’

Type:byte
files

files of this Request

Type:dict of (name, primitives.File)
header

header of this request, only valid after ‘prepare’

Type:dict
method

HTTP verb of this request

Type:str
path

path of this request, only valid after ‘prepare’

Type:str
prepare(scheme='http', handle_files=True, encoding='utf-8')[source]

make this request ready for Clients

Parameters:
  • scheme (str) – scheme used in this request
  • handle_files (bool) – False to skip multipart/form-data encoding
  • encoding (str) – encoding for body content.
Return type:

Request

query

query part of this request

Type:dict
scheme

preferred scheme used in this request

schemes

required schemes for current Operation.

Type:list of str
url

url of this request, only valid after ‘prepare’

Type:str

Response

class pyswagger.io.Response(op)[source]

Response layer

apply_with(status=None, raw=None, header=None)[source]

update header, status code, raw datum, ...etc

Parameters:
  • status (int) – status code
  • raw (str) – body content
  • header (dict) – header section
Returns:

return self for chaining

Return type:

Response

data

responsed data

Type:primitives.Model
header

header of Response

Type:dict of list, ex. {‘Content-Type’: [xxx, xxx]}
raw

raw response

Type:str
status

status code

Type:int