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
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: loguru

# 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`.


