Metadata-Version: 2.1
Name: msgpack-asgi
Version: 1.0.0
Summary: Drop-in MessagePack support for ASGI applications and frameworks
Home-page: http://github.com/florimondmanca/msgpack-asgi
Author: Florimond Manca
Author-email: florimond.manca@gmail.com
License: MIT
Description: # msgpack-asgi
        
        [![Build Status](https://dev.azure.com/florimondmanca/public/_apis/build/status/florimondmanca.msgpack-asgi?branchName=master)](https://dev.azure.com/florimondmanca/public/_build/latest?definitionId=5&branchName=master)
        [![Coverage](https://codecov.io/gh/florimondmanca/msgpack-asgi/branch/master/graph/badge.svg)](https://codecov.io/gh/florimondmanca/msgpack-asgi)
        [![Package version](https://badge.fury.io/py/msgpack-asgi.svg)](https://pypi.org/project/msgpack-asgi)
        
        `msgpack-asgi` allows you to add automatic [MessagePack](https://msgpack.org/) content negotiation to ASGI applications (Starlette, FastAPI, Quart, etc.), with a single line of code:
        
        ```python
        app.add_middleware(MessagePackMiddleware)
        ```
        
        _(You may want to adapt this snippet to your framework-specific middleware API.)_
        
        This gives you the performance benefits of MessagePack (e.g. reduced bandwidth usage) without having to change existing code. See also [How it works](#how-it-works).
        
        ## Installation
        
        Install with pip:
        
        ```bash
        pip install "mspack-asgi==1.*"
        ```
        
        ## Quickstart
        
        First, you'll need an ASGI application. Let's use this sample application, which exposes an endpoint that returns JSON data:
        
        ```python
        # For convenience, we use some ASGI components from Starlette.
        # Install with: `$ pip install starlette`.
        from starlette.requests import Request
        from starlette.responses import JSONResponse
        
        
        async def get_response(request):
            if request.method == "POST":
                data = await request.json()
                return JSONResponse({"data": data})
            else:
                return JSONResponse({"message": "Hello, msgpack!"})
        
        
        async def app(scope, receive, send):
            assert scope["type"] == "http"
            request = Request(scope=scope)
            response = await get_response(request)
            await response(scope, receive, send)
        ```
        
        Then, wrap your application around `MessagePackMiddleware`:
        
        ```python
        from msgpack_asgi import MessagePackMiddleware
        
        app = MessagePackMiddleware(app)
        ```
        
        Serve your application using an ASGI server, for example with [Uvicorn](https://www.uvicorn.org):
        
        ```bash
        uvicorn app:app
        ```
        
        Now, let's make a request that accepts MessagePack data in response:
        
        ```bash
        curl -i http://localhost:8000 -H "Accept: application/x-msgpack"
        ```
        
        You should get the following output:
        
        ```http
        HTTP/1.1 200 OK
        date: Fri, 01 Nov 2019 17:40:14 GMT
        server: uvicorn
        content-length: 25
        content-type: application/x-msgpack
        
        ��message�Hello, msgpack!
        ```
        
        What happened? Since we told the application that we accepted MessagePack-encoded responses, `msgpack-asgi` automatically converted the JSON data returned by the Starlette application to MessagePack.
        
        We can make sure the response contains valid MessagePack data by making the request again in Python, and decoding the response content:
        
        ```python
        >>> import requests
        >>> import msgpack
        >>> url = "http://localhost:8000"
        >>> headers = {"accept": "application/x-msgpack"}
        >>> r = requests.get(url, headers=headers)
        >>> r.content
        b'\x81\xa7message\xafHello, msgpack!'
        >>> msgpack.unpackb(r.content, raw=False)
        {'message': 'Hello, msgpack!'}
        ```
        
        `msgpack-asgi` also works in reverse: it will automatically decode MessagePack-encoded data sent by the client to JSON. We can try this out by making a `POST` request to our sample application with a MessagePack-encoded body:
        
        ```python
        >>> import requests
        >>> import msgpack
        >>> url = "http://localhost:8000"
        >>> data = msgpack.packb({"message": "Hi, there!"})
        >>> headers = {"content-type": "application/x-msgpack"}
        >>> r = requests.post(url, data=data, headers=headers)
        >>> r.json()
        {'data': {'message': 'Hi, there!'}}
        ```
        
        That's all there is to it! You can now go reduce the size of your payloads.
        
        ## Limitations
        
        `msgpack-asgi` does not support request or response streaming. This is because the full request and response body content has to be loaded in memory before it can be re-encoded.
        
        ## How it works
        
        ![](https://github.com/florimondmanca/msgpack-asgi/blob/master/img/msgpack-asgi.png)
        
        An ASGI application wrapped around `MessagePackMiddleware` will perform automatic content negotiation based on the client's capabilities. More precisely:
        
        - If the client sends MessagePack-encoded data with the `application/x-msgpack` content type, `msgpack-asgi` will automatically re-encode it to JSON for your application to consume.
        - If the client sent the `Accept: application/x-msgpack` header, `msgpack-asgi` will automatically re-encode any JSON response data to MessagePack for the client to consume.
        
        (In other cases, `msgpack-asgi` won't intervene at all.)
        
        ## License
        
        MIT
        
        
        # Changelog
        
        All notable changes to this project will be documented in this file.
        
        The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
        
        ## 1.0.0 - 2020-26-03
        
        _First production/stable release._
        
        ### Changed
        
        - Switch to private module naming. Components should now be imported from the root package, e.g. `from msgpack_asgi import MessagePackMiddleware`. (Pull #5)
        
        ### Fixed
        
        - Add missing `MANIFEST.in`. (Pull #4)
        
        ## 0.1.0 - 2019-11-04
        
        Initial release.
        
        ### Added
        
        - Add the `MessagePackMiddleware` ASGI middleware.
        - Add the `MessagePackResponse` ASGI response class.
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.6
Description-Content-Type: text/markdown
