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: Returns: the created App object
Return type: 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: Returns: the created App object
Return type: Raises: - ValueError – if url is wrong
- NotImplementedError – the swagger version is not supported.
-
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: 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: - jref (str) – a JSON Reference, refer to http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03 for details.
- parser (pyswagger.base.Context) – the parser corresponding to target object.
Returns: the referenced object, wrapped by weakref.ProxyType
Return type: 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:
-
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
-
classmethod
-
class
pyswagger.core.
Security
(app)[source]¶ security handler
-
__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: Return type:
-
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: Returns: return self for chaining
Return type:
-
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
-