Metadata-Version: 2.1
Name: microclient
Version: 0.7.3
Summary: A library for creating REST API clients quick and painless.
Home-page: https://bitbucket.org/biinsight/microclient/
Author: Szymon Nowak
Author-email: snowak@biinsight.pl
License: UNKNOWN
Description: # Microclient
        Microclient is a library for building simple python clients for your REST APIs.
        
        Basic usage:
        ```python
        from microclient import BaseClient, EndpointInfo
        
        class ZOOClient(BaseClient):
            service_name = 'ZOO API'
            endpoints = [
                EndpointInfo("animals", [
                    EndpointInfo("cats", "GET"),
                    EndpointInfo("dogs", "GET"),
                    EndpointInfo("elephants", "GET"),
                ]),
                EndpointInfo("zoo-status", "GET"),
                EndpointInfo("tickets", "GET, POST, DELETE")
            ]
        ```
        
        Which translates into client like this:
        ```python
        zoo_client = ZooClient('http://localhost:8000')
        zoo_client.animals.cats() # sends GET request to http://localhost:8000/animals/cats
        zoo_client.tickets.post(data={'amount': 2})  # sends POST request to http://localhost:8000/tickets with json data
        ```
        
        For now, authorization can be done via Auth Token on client initialization:
        ```python
        zoo_client = ZooClient('http://localhost:8000', auth='some_token')
        ```
        And the token will be appended to every request header. By default the Authorization header prefix is `Token` but it can be set like this:
        ```python
        zoo_client = ZooClient('http://localhost:8000', auth='some_token', auth_prefix="Bearer")
        ```
        Which will send header like this:
        `"Authorization": "Bearer some_token"`
        
        ## Responses
        Every endpoint called on a microclient will return `LazyResponse` object, which is - as the name suggests - lazy loaded. `Lazy Response` has three main properties that are most important:
        `data` (preferably JSON response data, but will fallback to byte-string content on decode failure), `status` (integer status code) and `headers` (response headers).
        
        
        Currently microclient is working with json data only (requests and responses).
        
        ## Testing
        If you want to unit test the client without actually calling the underlying API, use `LazyResponse` properties to check for proper endpoint, method and data sent.
        Example:
        ```python
        zoo_client = ZooClient('http://localhost:8000')
        response = zoo_client.animals.cats()
        print(response.url, response.method, response.request_data)
        # http://localhost:8000/animals/cats, GET, None 
        response = zoo_client.tickets.post(data={'amount': 2})
        print(response.url, response.method, response.request_data)
        # http://localhost:8000/tickets, POST, {'amount': 2}
        ``` 
        #### DECPRECATION NOTICE:
        In previous versions of microclient, you can also test the same things using `debug` to switch between actually calling and testing your client.
        Example:
        
        ```python
        zoo_client = ZooClient('http://localhost:8000')
        zoo_client.debug = True
        print(zoo_client.animals.cats())
        # (http://localhost:8000/animals/cats, GET, None) 
        print(zoo_client.tickets.post(data={'amount': 2}))
        # (http://localhost:8000/tickets, POST, {'amount': 2})
        ``` 
        However, `debug` property will not be available starting with version 1.0 (in a few months probably) and it's recommended to switch to `LazyResponse` approach.
        
        ## Headers
        Headers can be appended on 4 levels:
         - global - will be appended for evey request this client makes:
        ```python
        class ZOOClient(BaseClient):
            service_name = 'ZOO API'
            global_headers = {"Content-Type": "application/*"}
            endpoints = [
                EndpointInfo("animals", "GET")
            ]
        ```
         - on a group of endpoints:
        ```python
        class ZOOClient(BaseClient):
            service_name = 'ZOO API'
            endpoints = [
                EndpointInfo("animals", [
                    EndpointInfo("cats", "GET"),
                    EndpointInfo("dogs", "GET"),
                    EndpointInfo("elephants", "GET"),
                ], headers={"Content-Type": "application/*"}),  
        # Every endpoint inside 'animals' will append these headers ('animals' itself included)
        ]
        ```
         - on a single endpoint:
        ```python
        class ZOOClient(BaseClient):
            service_name = 'ZOO API'
            endpoints = [
                EndpointInfo("animals", [
                    EndpointInfo("cats", "GET", headers={"Content-Type": "application/*"}),
                    EndpointInfo("dogs", "GET"),
                    EndpointInfo("elephants", "GET"),
                ]),  
        ]
        ```
         - on a single request:
        ```python
        zoo_client = ZooClient('http://localhost:8000')
        response = zoo_client.animals.cats(headers={"Content-Type": "application/*"})
        ```
        # ChangeLog
        ## v0.7.3:
         - Fixed formatting query params when provided with only null-like values. Example:
         `{"param1": None, "param2": ''}) -> ''`. Previously was `{"param1": None, "param2": ''}) -> '?'`
        ## v0.7:
         - Added headers support for single request, single endpoint, inner endpoint (group of endpoints) and global for client.
         - Added timing diagnostic for every request (available at `request_time` attribute in `LazyResponse`)
         - Fixed a bug where your IDE could point that `resource_id` parameter must be a `str`.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Description-Content-Type: text/markdown
