Metadata-Version: 1.1
Name: py-rest-client
Version: 0.1.1
Summary: Py-Rest-Client is a useful lib for programmers who work with clients for REST API. In simply and easy way you can build Endpoint classes where you put endpoint settings.In that case you have clean structure of endpoints in your code. This lib is only for consume REST API endpoints.
Home-page: UNKNOWN
Author: Sławomir Kabik
Author-email: slawek@redsoftware.pl
License: Copyright (c) 2017, Sławomir Kabik
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

* Neither the name of the {organization} nor the names of its
  contributors may be used to endorse or promote products derived from
  this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Download-URL: https://github.com/slawek87/py-rest-client
Description: # Endpoint
        This is the main thing what you will use in that lib.With this class you can easy create clean structure of you rest api clients.
        
        We recommend create separate file for it i.e. endpoints.py 
        
        To use it you have to put that class as parent in your Endpoint Class.
        
        ### Mandatory objects:
        
        - `endpoint`: the path to your endpoint i.e. `/user/{user_id}/details/`. To use endpoint parameters put them into curly braces: `{endpoint_parameter}` in your endpoint's path.  
        - method: `GET`, `POST`, `PUT`, `PATCH` or `DELETE` method. You can set it as `Request.GET` or as a string `get`.
        
        ### Optional objects:
            
        - `header` (`dict`)  - set it if you need to send request to endpoints with some headers values.       
        - `cookies` (`dict`) - set it when you need include cookies inside your request.
        - `auth` (`tuple`)   - set it when you need authorization in your requests. This field should be set as instance of auth class. Check auth.py file.
        - `payload` (`dict`) - set it when you need to send `GET` or `POST` or `PATCH` or `PUT` or `DELETE` with parameters. You can set it directly as field in Endpoint class or as argument when you create Endpoint's instance.
        
        ### Instance fields:
        - `payload` (`dict`) - definition above.
        - `url_params` (`dict`) - you set this when you use parameters in your endpoint path.
        
        Lets do some example code!
        
        ### HOW TO INSTALL 
        
        `pip install py-rest-client`
        
        ### HOW TO SET SETTINGS
        
        Before you start using `rest-client` lib you have to set correctly your settings variables.
        
        On the first step you have to put correct `REST_CLIENT_SETTINGS_MODULE` in you `__init__.py`.
        
        ```python
        # __init__.py in main dir where you have project.
        import os
        
        os.environ.setdefault("REST_CLIENT_SETTINGS_MODULE", "your_project_name.settings") # this is only example
        ```
        
        Now you can creaet `settings.py` file and set those variables:
        
        ```python
        # Those are only examples of values.
        REST_SERVER_HOST = '0.0.0.0'
        REST_SERVER_PROTOCOL = 'http://'
        REST_SERVER_PORT = '8000'
        ```
        
        Don't worry if you didn't set correct path to `settings module` or `settings variables` in `settings.py`. 
        
        You will be informed about that.
        
        ```python
        # when you set bad path to settings module
        ImportError: No module named 'my_path_to_settings'
        ```
        
        ```python
        # when you didn't set correctly one of variables.
        AttributeError: module 'rest_client.your_project.settings' has no attribute 'REST_SERVER_PROTOCOL'
        ```
        
        
        ### Lesson 1
        
        In first lesson we show you how we handle errors in our `rest-client`. We create endpoint with wrong endpoint url. 
        
        ```python
        class InstagramEndpointGET(Endpoint):
            method = Request.GET
            endpoint = 'api/v1/instagram_404'
            
        istagram = InstagramEndpointGET()
        # raises exception:
        # rest_client.exceptions.EndpointError: 404 Not Found
        ```
        
        It handles all REST API errors.
        
        ### Lesson 2
        
        In this lesson we show you how to create simple endpoint which use method `GET` and `endpoint` path to fetch data from REST API. 
        
        #### Mock response:
        ```json
        {
            "data": [
                {
                    "type": "image",
                    "users_in_photo": [],
                    "filter": "Earlybird",
                    "tags": ["expobar"],
                    "comments": {
                        "count": 0
                    }
                }
            ]
        }
        ```
        
        #### Rest-Client
        ```python
        class InstagramEndpointGET(Endpoint):
            method = Request.GET
            endpoint = 'api/v1/instagram'
        
        
        instagram = InstagramEndpointGET()
        
        print(instagram.objects.values())
        # returns: 
        # {'data': [{'filter': 'Earlybird', 'comments': {'count': 0}, 'type': 'image', 'users_in_photo': [], 'tags': ['expobar']}]}
        
        print(instagram.objects.data) # you can use dot notation to get values from fields.
        # returns:
        # InstagramEndpointGET.data: [TestInstagramEndpointGET.data[0]: {'users_in_photo': [], 'filter': 'Earlybird', 'type': 'image', 'tags': ['expobar'], 'comments': {'count': 0}}]
        
        print(instagram.objects.data[0].type) # you can use dot notation and indexes to get value from fields.
        # returns:
        # InstagramEndpointGET.data[0].type: image
        
        for field, value in testing.objects.data[0].values().items():
            print("{field}: {value}".format(field=field, value=value))
            
        # returns:
        # type: image
        # tags: ['expobar']
        # comments: {'count': 0}
        # filter: Earlybird
        # users_in_photo: []
        ```
        
        In this snippet we've created Endpoint's Class with method `GET` and enpoint's path `api/v1/instagram`. 
        
        The response is in `json` format as we have in all Rest APIs.
        
        To fetch data from this endpoint you have to create instance of your endpoint - in this moment you call endpoint with `GET` request. Fetched data is stored in field `objects`.
        
        To see what the endpoint returned you can use `values()` method by calling it directly on `objects` field. This method returns data as python objects.
        
        ```python
        endpoint_instance.objects.values()
        ```
        
        To get values from `objects` use dot notation to call them. It returns python types: `int`, `float`,`string`, `list` and `dict`. You can use them as standard python fields.
        
        ```python
        endpoint_instance.objects.data
        ```
        
        When endpoint returns `list` you can use dot notation with indexes.
        
        ```python
        endpoint_instance.objects.list_data[0].some_field
        ```
        
        ** In the same way you can use endpoitn with methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. All REST API responses are handle in the same way. You can use `values()` method and dot notation. Response is always stored in `objects` field.
        
        ### Lesson 3
        
        In this lesson we show you how to create simple endpoint which uses method `GET` and `endpoint` path to fetch data from REST API with `url_param`.
        
        #### Rest-Client
        ```python
        class InstagramEndpointGET(Endpoint):
            method = Request.GET
            endpoint = 'api/v1/instagram/user/{user_id}'
           
        instangram = InstagramEndpointGET(url_param={'user_id': 1})
        instagram.values()
        ```
        
        ### Lesson 5
        
        We know that sometimes we need to send `payload` or `body` in your request. In that case you have to create `endpoint` instance with `payload` as `argument`.
        
        #### Rest-Client
        ```python
        class InstagramEndpointGET(Endpoint):
            method = Request.GET
            endpoint = 'api/v1/instagram/user/{user_id}'
        
        instangram = InstagramEndpointGET(url_param={'user_id': 1}, payload={'country': 'UK'})
        instagram.values()
        ```
        
        ### Lesson 6
        
        Now it's time to show you how to create Endpoint when you need to send request with authentication.
        
        We handle 3 types of authentication:
        - `HTTPBasicAuth('user', 'password')`
        - `HTTPDigestAuth('user', 'password')`
        - `OAuth1('YOUR_APP_KEY', 'YOUR_APP_SECRET', 'USER_OAUTH_TOKEN', 'USER_OAUTH_TOKEN_SECRET')`
        
        You need to choose one from above and put it as a `field` in `Endpoint` class.
        
        #### Rest-Client
        ```python
        class InstagramEndpointGET(Endpoint):
            method = Request.GET
            endpoint = 'api/v1/instagram/user/{user_id}'
            auth = HTTPBasicAuth('user', 'password')
        
        instangram = InstagramEndpointGET(url_param={'user_id': 1})
        instagram.values()
        ```
        
        ### Lesson 7
        
        You should read that lesson if you would like to handle `endpoint` with `cookies`. You have to put `cookies` as a field in `Endpoint` class.
        
        #### Rest-Client
        ```python
        class InstagramEndpointGET(Endpoint):
            method = Request.GET
            endpoint = 'api/v1/instagram/user/{user_id}'
            cookies = {'some_cookie`: 'some_cookie_value'}
        
        instangram = InstagramEndpointGET(url_param={'user_id': 1})
        instagram.values()
        ```
        
        ### Lesson 8
        
        Sometimes we have to send request with `headers`. To implement it you need set it as a `Enpoint` class `field`.
        
        #### Rest-Client
        ```python
        class InstagramEndpointGET(Endpoint):
            method = Request.GET
            endpoint = 'api/v1/instagram/user/{user_id}'
            headers = {'some_headers`: 'some_header_value'}
        
        instangram = InstagramEndpointGET(url_param={'user_id': 1})
        instagram.values()
        ```
        
Keywords: rest api client,python rest api client,rest api endpoint,consume rest api
Platform: UNKNOWN
