Metadata-Version: 2.1
Name: bravado-types
Version: 0.2.0
Summary: Library for generating type stubs for Swagger clients generated by Bravado
Home-page: https://github.com/nickgaya/bravado-types
Author: Nicholas Gaya
Author-email: nickgaya@users.noreply.github.com
License: MIT License
Description: # bravado-types
        
        Tool to generate MyPy type stubs for Bravado-generated classes to support
        static type checking.
        
        ## Motivation
        
        [Bravado](https://github.com/Yelp/Bravado) is a Python client library for
        interacting with APIs defined by Swagger 2.0 schemas. Bravado parses a given
        API schema at runtime and dynamically generates classes to represent the data
        types defined by the schema. This is a nice Pythonic approach, but it means
        that static type-checking tools like MyPy have limited ability to type-check
        code that uses Bravado since the attributes and method signatures of objects
        generated by Bravado are not known until runtime.
        
        Bravado-types addresses this problem by pre-generating type information about
        the generated data for a given schema at build time. Using the generated type
        stubs, MyPy can statically detect errors such as calling a nonexistent
        operation method on a resource, failing to specify a required operation
        parameter, or assigning a wrongly-typed value to a model attribute. This allows
        for a much higher level of confidence in the correctness of code that uses
        Bravado clients than would otherwise be possible.
        
        The validity of this approach relies on the assumption that the same version of
        the schema is used during code generation as at runtime.  Without this
        assumption it is nearly impossible to make any useful assertions about the
        runtime behavior of generated clients.
        
        ## Installation
        
            pip install bravado-types
        
        To install the latest master version directly from GitHub:
        
            pip install -U git+https://github.com/nickgaya/bravado-types.git
        
        ## Usage
        
        ### Code generation
        
        To start using bravado-types, invoke the CLI against your Swagger schema of
        choice:
        
            bravado-types --url 'https://petstore.swagger.io/v2/swagger.json' \
                --name PetStore --path petstore.py
        
        This command will download the PetStore example schema and generate a Python 3
        module, *petstore.py*, along with a MyPy stub file *petstore.pyi*, for that
        schema. The generated module and stub file can then be used in your package.
        The generated code only depends on bravado, not on bravado-types, so you do not
        need to include the latter as a runtime package dependency.
        
        Code generation can also be done programmatically.
        
            from bravado import SwaggerClient
            from bravado_types import RenderConfig, generate_module
        
            client = SwaggerClient.from_url(
                "https://petstore.swagger.io/v2/swagger.json")
            config = RenderConfig(name='PetStore', path='petstore.py')
            generate_module(client, config)
        
        Bravado-types supports several optional parameters to customize code
        generation. See the `bravado_types.render.RenderConfig` docstring or the CLI
        help output (`bravado-types --help`) for details.
        
        ### Using the generated module
        
        To create a type-aware client, import the relevant name from the generated
        module and use its `from_url()` or `from_spec()` method to create an instance.
        
            from petstore import PetStoreSwaggerClient
        
            client = PetStoreSwaggerClient.from_url(
                "https://petstore.swagger.io/v2/swagger.json")
            reveal_type(client)  # petstore.PetStoreSwaggerClient
        
        You can use the client like a regular Bravado client to instantiate model
        objects and make API calls with them.
        
            Pet = client.get_model('Pet')
            reveal_type(Pet)  # Type[petstore.PetModel]
        
            frank = Pet(name='Frank', photoUrls=[])
            reveal_type(frank)  # petstore.PetModel
        
            pet123 = client.pet.getPetById(id=123).response().result
            reveal_type(pet123)  # petstore.PetModel
        
        The generated module also provides importable model, resource, and operation
        types for use in type annotations.
        
            from petstore import PetModel
        
            def get_name(pet: PetModel) -> str:
                reveal_type(pet)  # petstore.PetModel
                return pet.name
        
        Generated model, resource, and operation types are only used for static type
        checking and must not be used for runtime interactions.
        
            # Placeholder for static type-checking
            from petstore import PetModel
        
            # Use placeholder for type annotations and casts
            pet: PetModel = ...
            pet2 = typing.cast(PetModel, ...)
        
            # Runtime model class
            Pet = client.get_model('Pet')
        
            # Use runtime class for model instantiation and runtime type checks
            pet = Pet(name='Boots', photoUrls=[])
            assert isinstance(pet, Pet)
        
        ## Caveats
        
        ### Operation response types
        
        Operations often have multiple different response schemas for different status
        codes, which presents an obstacle to static type analysis.  Bravado-types
        offers three different options for response type annotations, specified by the
        `response_types` configuration parameter.
        
        * `'success'`: The response type will be declared as the union of all response
          types with 2xx status. This is unsound, but may be useful if you are primarily
          concerned with responses when the request was successful.
        
        * `'union'`: The response type will be declared as the union of all response
          types defined in the schema. This is probably the most correct but is
          cumbersome, as the developer must perform manual type checks or casts to
          obtain a useable type.
        
        * `'any'`: The response type will be declared as `Any`. This gives maximum
          flexibility but requires the developer to manually add type hints if they
          want any type checking on the result of an operation.
        
        By default, bravado-types uses the `'success'` option as it is felt to be the
        most pragmatic option, although the least sound.
        
        ### Array types
        
        Bravado accepts either lists or tuples when marshaling values with
        `type: array` in the Swagger schema, and creates lists when unmarshaling. There
        are a few ways we could represent this in the type annotations:
        
        * The most precise description would be `Union[List[T], Tuple[T, ...]]` but
        this is rather verbose and awkward.
        
        * A less precise but more concise alternative is to use `Sequence[T]`. This has
        the downside that MyPy considers `str` a subtype of `Sequence[str]`, which can
        lead to buggy code that passes type-checking but fails schema validation at
        runtime.
        
        * A third alternative is to use only `List[T]` and forbid the use of tuples.
        This is overly restrictive, but leads to simpler annotated types.
        
        By default, we use `List[T]` to represent array types, but this behavior can be
        overridden via the `array_types` configuration parameter.
        
        ### Custom formats
        
        If bravado-types encounters a primitive type spec with an unrecognized `format`
        property, it emits a warning and assigns the variable a type based on the
        `type` property alone.
        
        Future versions of this tool may add support for custom user-defined formats.
        
        ### Model inheritance
        
        Swagger allows composing model definitions with the `allOf` schema property.
        This can be interpreted as a subclass relationship between models. Bravado
        implements this to some extent in its model metaclass,
        `bravado_core.model.ModelMeta`.
        
        By default, bravado-types does not mirror this implied type hierarchy in its
        generated types.  To enable this functionality, set the `model_inheritance`
        configuration parameter to `True`.
        
        ### Additional model properties
        
        Bravado-types does not currently support accessing or setting additional
        properties as attributes of model instances. If you need to set or access
        additional properties, you can use dict-like syntax instead.
        
        For example, given this model schema...
        
            x-model: APExample
            type: object
            additionalProperties:
              type: int
        
        ...you can add a property called "something" to a model instance like this:
        
            model: APExampleModel
            model['something'] = 123
        
        MyPy will not type-check additional properties.
        
        ### File parameters and responses
        
        Bravado's handling of parameters and responses with `type: file` is
        complicated.  This tool simply annotates such values with the `Any` type.
        
        ## Development
        
        This project uses Tox to manage virtual environments for unit tests and other
        self-checks.  Unit tests are written with the Pytest framework.
        
        **Note:** This project is not affiliated with Yelp or the Bravado project.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/markdown
