Add API for RichMenu Control (#85)

* Add API for RichMenu Control

* Add create rich menu function and function will return a rich menu id

* Add function to delete rich menu

* Add function to get rich menu by rich menu id

* Add comments for new functions

* add  function link_rich_menu_to_user but not test yet

* add function to get rich menu list

* add function to upload rich menu image

* add function to get rich menu id of user

* add function to unlink rich menu from user

* fix typo in comment

* Fix for flake8 check result

* Add test case for get_rich_menu_id_of_user, unlink_rich_menu_from_user, link_rich_menu_to_user, delete_rich_menu

* add api to download_rich_menu_image

* add test case for create_rich_menu and get_rich_menu_list

* Update README.rst for Rich menu apis

* Update README.rst

* Update URL

* Remove py33 from tox.ini (#88)

* Fix arg_parser option for examples (#87)

* modify after PR review

Author: quts

README.rst

@@ -241,6 +241,135 @@ https://developers.line.me/en/docs/messaging-api/reference/#leave-room
 
     line_bot_api.leave_room(room_id)
 
+create\_rich\_menu(self, data, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Create a rich menu object through a group of given data and return rich menu id.
+The data is an rich menu object to create.
+
+https://developers.line.me/en/docs/messaging-api/reference/#create-rich-menu
+
+.. code:: python
+    
+    rich_menu_to_create = RichMenu(
+                                size=RichMenuBound(
+                                    width=2500,
+                                    height=1686
+                                ),
+                                selected= False,
+                                name="nice richmenu",
+                                chatBarText="touch me",
+                                areas=[
+                                    RichMenuArea(
+                                        RichMenuBound(
+                                            x=0,
+                                            y=0,
+                                            width=2500,
+                                            height=1686 
+                                        ),
+                                        URITemplateAction(
+                                            uri='line://nv/location'
+                                        )                    
+                                    )
+                                ]
+                            )
+    rich_menu_id = line_bot_api.create_rich_menu(data=rich_menu_to_create)
+    print(rich_menu_id)
+
+delete\_rich\_menu(self, rich\_menu\_id, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Delete rich menu object through a given rich_menu_id.
+
+https://developers.line.me/en/docs/messaging-api/reference/#delete-rich-menu
+        
+.. code:: python
+
+    line_bot_api.delete_rich_menu(rich_menu_id)
+
+set\_rich\_menu\_image(self, rich\_menu\_id, content\_type, content, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Uploads and attaches an image to a rich menu through id and image path.
+
+https://developers.line.me/en/docs/messaging-api/reference/#upload-rich-menu-image
+
+.. code:: python
+
+    line_bot_api.set_rich_menu_image(rich_menu_id, content_type, content)
+
+link\_rich\_menu\_to\_user(self, user\_id, rich\_menu\_id, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Links a rich menu to a user. Only one rich menu can be linked to a user at one time.
+
+https://developers.line.me/en/docs/messaging-api/reference/#link-rich-menu-to-user
+
+.. code:: python
+
+    line_bot_api.link_rich_menu_to_user(user_id, rich_menu_id)
+
+get\_rich\_menu\_list(self, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Gets a list of all uploaded rich menus.
+
+https://developers.line.me/en/docs/messaging-api/reference/#get-rich-menu-list
+
+.. code:: python
+
+    lst_rich_menu_obj = line_bot_api.get_rich_menu_list()
+    for rich_menu_obj in lst_rich_menu_obj:
+        print(rich_menu_obj.rich_menu_id)
+
+get\_rich\_menu(self, rich\_menu\_id, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get rich menu object through a given Rich menu ID.
+
+https://developers.line.me/en/docs/messaging-api/reference/#get-rich-menu
+
+.. code:: python
+
+    rich_menu_object = line_bot_api.get_rich_menu(rich_menu_id)
+    print(rich_menu_obj.rich_menu_id)
+
+get\_rich\_menu\_id\_of\_user(self, user\_id, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Gets the ID of the rich menu linked to a user.
+
+https://developers.line.me/en/docs/messaging-api/reference/#get-rich-menu-id-of-user
+
+.. code:: python
+
+    rich_menu_object = ine_bot_api.get_rich_menu_id_of_user(user_id)
+    print(rich_menu_object.rich_menu_id)
+
+unlink\_rich\_menu\_from\_user(self, user\_id, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Unlinks a rich menu from a user.
+
+https://developers.line.me/en/docs/messaging-api/reference/#unlink-rich-menu-from-user
+
+.. code:: python
+
+    line_bot_api.unlink_rich_menu_from_user(user_id)
+
+get_rich_menu_image(self, rich\_menu\_id, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Downloads an image associated with a rich menu.
+
+https://developers.line.me/en/docs/messaging-api/reference/#download-rich-menu-image
+
+.. code:: python
+
+    message_content = line_bot_api.get_rich_menu_image(rich_menu_id)
+    with open(file_path, 'wb') as fd:
+        for chunk in message_content.iter_content():
+            fd.write(chunk)
+
 ※ Error handling
 ^^^^^^^^^^^^^^^^
 

linebot/api.py

@@ -22,7 +22,7 @@
 from .exceptions import LineBotApiError
 from .http_client import HttpClient, RequestsHttpClient
 from .models.error import Error
-from .models.responses import Profile, MemberIds, MessageContent
+from .models.responses import Profile, MemberIds, MessageContent, RichMenuResponse
 
 
 class LineBotApi(object):
@@ -124,6 +124,206 @@ def push_message(self, to, messages, timeout=None):
             '/v2/bot/message/push', data=json.dumps(data), timeout=timeout
         )
 
+    def get_rich_menu(self, rich_menu_id, timeout=None):
+        """Call get rich menu API.
+
+        https://developers.line.me/en/docs/messaging-api/reference/#get-rich-menu
+
+        Get rich menu object through a given rich_menu_id
+
+        :param str rich_menu_id: ID of the rich menu
+        :param timeout: (optional) How long to wait for the server
+            to send data before giving up, as a float,
+            or a (connect timeout, read timeout) float tuple.
+            Default is self.http_client.timeout
+        :type timeout: float | tuple(float, float)
+        :return: RichMenuResponse instance
+        :type RichMenuResponse: T <= :py:class:`linebot.models.reponse.RichMenuResponse`
+        """
+        response = self._get(
+            '/v2/bot/richmenu/{rich_menu_id}'.format(rich_menu_id=rich_menu_id),
+            timeout=timeout
+        )
+
+        return RichMenuResponse.new_from_json_dict(response.json)
+
+    def delete_rich_menu(self, rich_menu_id, timeout=None):
+        """Call delete rich menu API.
+
+        https://developers.line.me/en/docs/messaging-api/reference/#delete-rich-menu
+
+        Delete rich menu object through a given rich_menu_id
+
+        :param str rich_menu_id: ID of the rich menu
+        :param timeout: (optional) How long to wait for the server
+            to send data before giving up, as a float,
+            or a (connect timeout, read timeout) float tuple.
+            Default is self.http_client.timeout
+        :type timeout: float | tuple(float, float)
+        """
+        self._delete(
+            '/v2/bot/richmenu/{rich_menu_id}'.format(rich_menu_id=rich_menu_id),
+            timeout=timeout
+        )
+
+    def create_rich_menu(self, rich_menu, timeout=None):
+        """Call delete rich menu API.
+
+        https://developers.line.me/en/docs/messaging-api/reference/#create-rich-menu
+
+        Create a rich menu object through a group of given rich_menu data
+
+        :param rich_menu: Inquired to create a rich menu.
+        :type rich_menu: T <= :py:class:`linebot.models.rich_menu.RichMenu`
+        :param timeout: (optional) How long to wait for the server
+            to send data before giving up, as a float,
+            or a (connect timeout, read timeout) float tuple.
+            Default is self.http_client.timeout
+        :type timeout: float | tuple(float, float)
+        :return: rich menu id
+        """
+        response = self._post(
+            '/v2/bot/richmenu', data=rich_menu.as_json_string(), timeout=timeout
+        )
+
+        return response.json.get('richMenuId')
+
+    def link_rich_menu_to_user(self, user_id, rich_menu_id, timeout=None):
+        """Call link rich menu to user API.
+
+        https://developers.line.me/en/docs/messaging-api/reference/#link-rich-menu-to-user
+
+        Links a rich menu to a user. Only one rich menu can be linked to a user at one time.
+
+        :param str user_id: ID of an uploaded rich menu
+        :param str rich_menu_id: ID of the user
+        :type timeout: float | tuple(float, float)
+        """
+        self._post(
+            '/v2/bot/user/{user_id}/richmenu/{rich_menu_id}'.format(
+                user_id=user_id,
+                rich_menu_id=rich_menu_id
+            ),
+            timeout=timeout
+        )
+
+    def get_rich_menu_list(self, timeout=None):
+        """Call get rich menu list API.
+
+        https://developers.line.me/en/docs/messaging-api/reference/#get-rich-menu-list
+
+        Gets a list of all uploaded rich menus.
+
+        :return: An list of RichMenuResponse instances
+        :type RichMenuResponse: T <= :py:class:`linebot.models.reponse.RichMenuResponse`
+        :param timeout: (optional) How long to wait for the server
+            to send data before giving up, as a float,
+            or a (connect timeout, read timeout) float tuple.
+            Default is self.http_client.timeout
+        :type timeout: float | tuple(float, float)
+        """
+        response = self._get(
+            '/v2/bot/richmenu/list',
+            timeout=timeout
+        )
+
+        lst_result = []
+        for richmenu in response.json['richmenus']:
+            lst_result.append(RichMenuResponse.new_from_json_dict(richmenu))
+
+        return lst_result
+
+    def set_rich_menu_image(self, rich_menu_id, content_type, content, timeout=None):
+        """Call upload rich menu image API.
+
+        https://developers.line.me/en/docs/messaging-api/reference/#upload-rich-menu-image
+
+        Uploads and attaches an image to a rich menu.
+
+        :param str rich_menu_id: IDs of the rechmenu
+        :param str content_type: image/jpeg or image/png
+        :param str content: image content as request body in bytes
+        :param timeout: (optional) How long to wait for the server
+            to send data before giving up, as a float,
+            or a (connect timeout, read timeout) float tuple.
+            Default is self.http_client.timeout
+        :type timeout: float | tuple(float, float)
+        """
+        self.headers['Content-Type'] = content_type
+
+        # send request
+        self._post(
+            '/v2/bot/richmenu/{rich_menu_id}/content'.format(rich_menu_id=rich_menu_id),
+            data=content,
+            timeout=timeout
+        )
+
+        # remove added header to avoid side effect in other apis
+        del self.headers['Content-Type']
+
+    def get_rich_menu_id_of_user(self, user_id, timeout=None):
+        """Call get rich menu ID of user API.
+
+        https://developers.line.me/en/docs/messaging-api/reference/#get-rich-menu-id-of-user
+
+        Gets the ID of the rich menu linked to a user.
+
+        :param str user_id: IDs of the user
+        :param timeout: (optional) How long to wait for the server
+            to send data before giving up, as a float,
+            or a (connect timeout, read timeout) float tuple.
+            Default is self.http_client.timeout
+        :type timeout: float | tuple(float, float)
+        """
+        response = self._get(
+            '/v2/bot/user/{user_id}/richmenu'.format(user_id=user_id),
+            timeout=timeout
+        )
+
+        return response.json.get('richMenuId')
+
+    def unlink_rich_menu_from_user(self, user_id, timeout=None):
+        """Call unlink rich menu from user API.
+
+        https://developers.line.me/en/docs/messaging-api/reference/#unlink-rich-menu-from-user
+
+        Unlinks a rich menu from a user.
+
+        :param str user_id: ID of the user
+        :param timeout: (optional) How long to wait for the server
+            to send data before giving up, as a float,
+            or a (connect timeout, read timeout) float tuple.
+            Default is self.http_client.timeout
+        :type timeout: float | tuple(float, float)
+        """
+        self._delete(
+            '/v2/bot/user/{user_id}/richmenu'.format(user_id=user_id),
+            timeout=timeout
+        )
+
+    def get_rich_menu_image(self, rich_menu_id, timeout=None):
+        """Call download rich menu image API.
+
+        https://developers.line.me/en/docs/messaging-api/reference/#download-rich-menu-image
+
+        Downloads an image associated with a rich menu.
+
+        :param str rich_menu_id: ID of the rich menu with the image to be downloaded
+        :param timeout: (optional) How long to wait for the server
+            to send data before giving up, as a float,
+            or a (connect timeout, read timeout) float tuple.
+            Default is self.http_client.timeout
+        :type timeout: float | tuple(float, float)
+        :rtype: :py:class:`linebot.models.responses.MessageContent`
+        :return: MessageContent instance
+        """
+        response = self._get(
+            '/v2/bot/richmenu/{rich_menu_id}/content'.format(rich_menu_id=rich_menu_id),
+            timeout=timeout
+        )
+
+        return MessageContent(response)
+
     def multicast(self, to, messages, timeout=None):
         """Call multicast API.
 
@@ -372,6 +572,18 @@ def _post(self, path, data=None, timeout=None):
         self.__check_error(response)
         return response
 
+    def _delete(self, path, data=None, timeout=None):
+        url = self.endpoint + path
+        headers = {'Content-Type': 'application/json'}
+        headers.update(self.headers)
+
+        response = self.http_client.delete(
+            url, headers=headers, data=data, timeout=timeout
+        )
+
+        self.__check_error(response)
+        return response
+
     @staticmethod
     def __check_error(response):
         if 200 <= response.status_code < 300: