Merge pull request #7 from Kronopt/develop

Develop

Author: Kronopt

.pylintrc

@@ -139,7 +139,8 @@ disable=print-statement,
         deprecated-sys-function,
         exception-escape,
         comprehension-escape,
-        wrong-import-position
+        wrong-import-position,
+        too-many-instance-attributes
 
 # Enable the message, report, category or checker with the given id(s). You can
 # either give multiple identifier separated by comma (,) or put this option

README.md

@@ -68,6 +68,3 @@ xkcd_wrapper.Comic(100)
 
 ## Documentation
 Check the documentation for more details: https://xkcd-wrapper.readthedocs.io/en/latest
-
-### Ideas for the Future
-* retrieve comic .jpeg

docs/client-async.md

@@ -39,13 +39,14 @@ Returns: **str**
 
 ### async get
 ```Python
-AsyncClient.get(comic_id)
+AsyncClient.get(comic_id, raw_comic_image=True)
 ```
 Retrieves an xkcd comic by id
 
 | Parameter | Type / Value | Default | Description |
 |:---:|:---:|:---:|---|
 | comic_id | int |  | xkcd comic id |
+| raw_comic_image | bool | True | Indicates if raw comic image should be retrieved or not (implies an extra http request) |
 
 Returns: **xkcd_wrapper.Comic**
 
@@ -57,11 +58,15 @@ Raises:
 
 ### async get_latest
 ```Python
-AsyncClient.get_latest()
-AsyncClient.latest()
+AsyncClient.get_latest(raw_comic_image=True)
+AsyncClient.latest(raw_comic_image=True)
 ```
 Retrieves the latest xkcd comic
 
+| Parameter | Type / Value | Default | Description |
+|:---:|:---:|:---:|---|
+| raw_comic_image | bool | True | Indicates if raw comic image should be retrieved or not (implies an extra http request) |
+
 Returns: **xkcd_wrapper.Comic**
 
 Raises:
@@ -71,12 +76,16 @@ Raises:
 
 ### async get_random
 ```Python
-AsyncClient.get_random()
-AsyncClient.random()
+AsyncClient.get_random(raw_comic_image=True)
+AsyncClient.random(raw_comic_image=True)
 ```
 Retrieves a random xkcd comic.
 Contacts the xkcd API twice: once to know how many comics there are and another to fetch a random comic
 
+| Parameter | Type / Value | Default | Description |
+|:---:|:---:|:---:|---|
+| raw_comic_image | bool | True | Indicates if raw comic image should be retrieved or not (implies an extra http request) |
+
 Returns: **xkcd_wrapper.Comic**
 
 Raises:

docs/client.md

@@ -39,13 +39,14 @@ Returns: **str**
 
 ### get
 ```Python
-Client.get(comic_id)
+Client.get(comic_id, raw_comic_image=True)
 ```
 Retrieves an xkcd comic by id
 
 | Parameter | Type / Value | Default | Description |
 |:---:|:---:|:---:|---|
 | comic_id | int |  | xkcd comic id |
+| raw_comic_image | bool | True | Indicates if raw comic image should be retrieved or not (implies an extra http request) |
 
 Returns: **xkcd_wrapper.Comic**
 
@@ -57,11 +58,15 @@ Raises:
 
 ### get_latest
 ```Python
-Client.get_latest()
-Client.latest()
+Client.get_latest(raw_comic_image=True)
+Client.latest(raw_comic_image=True)
 ```
 Retrieves the latest xkcd comic
 
+| Parameter | Type / Value | Default | Description |
+|:---:|:---:|:---:|---|
+| raw_comic_image | bool | True | Indicates if raw comic image should be retrieved or not (implies an extra http request) |
+
 Returns: **xkcd_wrapper.Comic**
 
 Raises:
@@ -71,12 +76,16 @@ Raises:
 
 ### get_random
 ```Python
-Client.get_random()
-Client.random()
+Client.get_random(raw_comic_image=True)
+Client.random(raw_comic_image=True)
 ```
 Retrieves a random xkcd comic.
 Contacts the xkcd API twice: once to know how many comics there are and another to fetch a random comic
 
+| Parameter | Type / Value | Default | Description |
+|:---:|:---:|:---:|---|
+| raw_comic_image | bool | True | Indicates if raw comic image should be retrieved or not (implies an extra http request) |
+
 Returns: **xkcd_wrapper.Comic**
 
 Raises:

docs/comic.md

@@ -1,17 +1,20 @@
 # xkcd_wrapper.Comic
 xkcd comic representation
 
-A `Comic` represents a single xkcd comic. `xkcd_wrapper.Client` generates `Comic` objects
+A `Comic` represents a single xkcd comic. `xkcd_wrapper.Client` and `xkcd_wrapper.AsyncClient` generate `Comic` objects
 
 ## Parameters
 The `Comic` class can be instantiated with the following parameters:
 ```Python
-Comic(xkcd_dict)
+Comic(xkcd_dict, raw_image=None, comic_url=None, explanation_url=None)
 ```
 
 | Parameter | Type / Value | Default | Description|
 |:---:|:---:|:---:|---|
-| xkcd_dict | dict | | dictionary containing all the fields parsed by the `Client` |
+| xkcd_dict | dict | | dictionary containing the xkcd API response json |
+| raw_image | bytes / None | None | raw comic image |
+| comic_url | str / None | None | xkcd comic url |
+| explanation_url | str / None | None | explainxkcd wiki url |
 
 ## Attributes
 Instances of the `Comic` class have the following attributes. All attributes can be `None` if the value was omitted
@@ -24,9 +27,11 @@ from the xkcd API response, for some reason
 | title | str / None | comic title |
 | description | str / None | comic description |
 | transcript | str / None | comic transcript |
-| image | str / None | image url |
-| link | str / None | comic url |
-| explanation | str / None | url to explainxkcd wiki |
+| image | bytes / None | raw comic image |
+| image_extension | str / None | comic image extension (ex: .png, .jpeg) |
+| image_url | str / None | comic image url |
+| comic_url | str / None | comic url |
+| explanation | str / None | explainxkcd wiki url |
 
 ## Special Methods
 * \_\_repr__

docs/history.md

@@ -1,15 +1,20 @@
 # History
 
+### 1.0.0 (06-09-2020)
+* Reworked xkcd API response json decoding
+* Reworked `Comic`
+* `Client` and `AsyncClient` can now retrieve comic images
+
 ### 0.2.2 (13-08-2020)
-* Fixed failing to import xkcd_wrapper if either only requests or aiohttp were installed
+* Fixed failing to import `xkcd_wrapper` if either only `requests` or `aiohttp` were installed
 
 ### 0.2.1 (11-08-2020)
 * Separate dependencies
     (you can now use the async implementation without having to install the sync dependencies and vice versa)
 
 ### 0.2.0 (08-08-2020)
-* Async implementation
+* Async implementation (`AsyncClient`)
 
 ### 0.1.0 (23-04-2020)
 * First release on PyPI
-* Client and Comic classes
+* `Client` and `Comic` classes

docs/usage.md

@@ -20,21 +20,25 @@ Then you can use one of the available methods to retrieve xkcd comics:
 * `get_random()` -> retrieves a random comic (can also be called as just `random()`)
 
 All methods return a `Comic` object which contains the structured xkcd comic data.
+Each of these methods also take a boolean keyword argument `raw_comic_image` (defaults to True), which is a boolean
+indicating if the raw comic image should be retrieved or not (retrieving the image implies another http request). 
 
 ```python
-comic = client.get_latest()
+comic = client.get(comic_id, raw_comic_image=True)
 ```
 
-The data is accessible as properties. You can access them like so:
+You can access the xkcd comic data like so:
 ```python
-comic.id            # comic number
-comic.date          # date of release
-comic.title         # title
-comic.description   # description
-comic.transcript    # dialog and scene transcript
-comic.image         # image url
-comic.link          # comic webpage url
-comic.explanation   # xkcd explanation wiki url
+comic.id                # comic number
+comic.date              # date of release
+comic.title             # title
+comic.description       # description
+comic.transcript        # dialog and scene transcript
+comic.image             # raw comic image
+comic.image_extension   # comic image extension (ex: .png, .jpeg)
+comic.image_url         # comic image url
+comic.comic_url         # comic webpage url
+comic.explanation       # xkcd explanation wiki url
 ```
 
 ### Async implementation
@@ -45,7 +49,7 @@ instantiate the `AsyncClient`:
 async_client = xkcd_wrapper.AsyncClient() 
 ```
 
-Then the same methods are available as for `Client`, but they are all async:
+Then the same methods with the same parameters are available as for `Client`, but they are all async:
 
 * `get(<id>)` -> retieves comic by id
 * `get_latest()` -> retrieves the latest comic (can also be called as just `latest()`)

setup.py

@@ -51,7 +51,7 @@
     zip_safe=False,
     keywords='xkcd wrapper xkcd-wrapper',
     classifiers=[
-        'Development Status :: 4 - Beta',
+        'Development Status :: 5 - Production/Stable',
         'Intended Audience :: Developers',
         'License :: OSI Approved :: GNU General Public License v3 (GPLv3)',
         'Natural Language :: English',

tests/__init__.py

@@ -9,6 +9,7 @@
 latest_comic_url = 'https://xkcd.com/info.0.json'
 comic_id_url = 'https://xkcd.com/{}/info.0.json'
 explanation_wiki_url = 'https://www.explainxkcd.com/wiki/index.php/'
+raw_comic_image = b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x02\x00\x00\x00\x90wS\xde\x00\x00\x00\x01sRGB\x00\xae\xce\x1c\xe9\x00\x00\x00\x04gAMA\x00\x00\xb1\x8f\x0b\xfca\x05\x00\x00\x00\tpHYs\x00\x00\x16%\x00\x00\x16%\x01IR$\xf0\x00\x00\x00\x0cIDAT\x18Wc\xf8\xff\xff?\x00\x05\xfe\x02\xfe\xa75\x81\x84\x00\x00\x00\x00IEND\xaeB`\x82'
 
 with open('tests/xkcd_api_example_response_628.json') as example_628, \
      open('tests/xkcd_api_example_response_138.json') as example_138, \
@@ -23,7 +24,7 @@
 xkcd_api_example_138_dict = json.loads(xkcd_api_example_138_raw)
 
 
-def check_comic(test_case, comic, example):
+def check_comic(test_case, comic, example, raw_image=True):
     """
     Assert comic has the required values
 
@@ -35,16 +36,27 @@ def check_comic(test_case, comic, example):
         Comic
     example : dict
         parsed xkcd API example json
+    raw_image : bool
+        if Comic was generated with a comic raw image or not
     """
     date = datetime.date(int(example['year']),
                          int(example['month']),
                          int(example['day']))
 
-    test_case.assertEqual(comic.date, date)
     test_case.assertEqual(comic.id, example['num'])
+    test_case.assertEqual(comic.date, date)
     test_case.assertEqual(comic.title, example['safe_title'])
     test_case.assertEqual(comic.description, example['alt'])
     test_case.assertEqual(comic.transcript, example['transcript'])
-    test_case.assertEqual(comic.image, example['img'])
-    test_case.assertEqual(comic.link, '{}{}'.format(base_url, example['num']))
-    test_case.assertEqual(comic.explanation, '{}{}'.format(explanation_wiki_url, example['num']))
+
+    if raw_image:
+        test_case.assertEqual(comic.image, raw_comic_image)
+        test_case.assertEqual(comic.image_extension, 'png')
+    else:
+        test_case.assertIsNone(comic.image)
+        test_case.assertIsNone(comic.image_extension)
+
+    test_case.assertEqual(comic.image_url, example['img'])
+    test_case.assertEqual(comic.comic_url, '{}{}'.format(base_url, example['num']))
+    test_case.assertEqual(comic.explanation_url,
+                          '{}{}'.format(explanation_wiki_url, example['num']))

tests/test_async_client.py

@@ -12,7 +12,7 @@
 import xkcd_wrapper
 from aioresponses import aioresponses
 from nose2.tools.params import params as nose2_params
-from . import (base_url, latest_comic_url, comic_id_url, check_comic,
+from . import (base_url, latest_comic_url, comic_id_url, check_comic, raw_comic_image,
                xkcd_api_example_628_raw,
                xkcd_api_example_138_raw,
                xkcd_api_example_wrong_raw,
@@ -31,6 +31,13 @@ def test_client_init(self):
         self.assertIsInstance(c._base_url, str)
         self.assertIsInstance(c._api, str)
         self.assertIsInstance(c._explanation_wiki_url, str)
+        self.assertIsInstance(c._explanation_wiki_url, str)
+
+        self.assertIsInstance(c._response_int_values, dict)
+        self.assertEqual(c._response_int_values['num'], 'id')
+        self.assertEqual(c._response_int_values['year'], 'date')
+        self.assertEqual(c._response_int_values['month'], 'date')
+        self.assertEqual(c._response_int_values['day'], 'date')
 
     def test_base_url(self):
         c = xkcd_wrapper.AsyncClient()
@@ -50,41 +57,54 @@ def test_get(self):
         loop = asyncio.get_event_loop()
         with aioresponses() as mock:
             mock.get(comic_id_url.format(628), status=200, body=xkcd_api_example_628_raw)
+            mock.get(xkcd_api_example_628_dict['img'], status=200, body=raw_comic_image)
             response = loop.run_until_complete(c.get(628))
             check_comic(self, response, xkcd_api_example_628_dict)
             with self.assertRaises(TypeError):
                 loop.run_until_complete(c.get(''))
             with self.assertRaises(TypeError):
                 loop.run_until_complete(c.get([1, 2, 3]))
 
+    def test_get_without_raw_image(self):
+        c = xkcd_wrapper.AsyncClient()
+        loop = asyncio.get_event_loop()
+        with aioresponses() as mock:
+            mock.get(comic_id_url.format(628), status=200, body=xkcd_api_example_628_raw)
+            response = loop.run_until_complete(c.get(628, raw_comic_image=False))
+            check_comic(self, response, xkcd_api_example_628_dict, raw_image=False)
+            with self.assertRaises(TypeError):
+                loop.run_until_complete(c.get(''))
+            with self.assertRaises(TypeError):
+                loop.run_until_complete(c.get([1, 2, 3]))
+
     def test_get_http_error(self):
         c = xkcd_wrapper.AsyncClient()
         loop = asyncio.get_event_loop()
         with aioresponses() as mock:
             mock.get(comic_id_url.format(628), status=404)
             with self.assertRaises(xkcd_wrapper.exceptions.HttpError):
-                loop.run_until_complete(c.get(628))
+                loop.run_until_complete(c.get(628, raw_comic_image=False))
 
     def test_get_bad_response_fields(self):
         c = xkcd_wrapper.AsyncClient()
         loop = asyncio.get_event_loop()
         with aioresponses() as mock:
             mock.get(comic_id_url.format(628), status=200, body=xkcd_api_example_wrong_raw)
             with self.assertRaises(xkcd_wrapper.exceptions.BadResponseField):
-                loop.run_until_complete(c.get(628))
+                loop.run_until_complete(c.get(628, raw_comic_image=False))
 
     def test_get_latest(self):  # let's assume the example_628 json is the latest comic
         c = xkcd_wrapper.AsyncClient()
         loop = asyncio.get_event_loop()
         with aioresponses() as mock:
             mock.get(latest_comic_url, status=200, body=xkcd_api_example_628_raw)
-            response = loop.run_until_complete(c.get_latest())
-            check_comic(self, response, xkcd_api_example_628_dict)
+            response = loop.run_until_complete(c.get_latest(raw_comic_image=False))
+            check_comic(self, response, xkcd_api_example_628_dict, raw_image=False)
 
             # alias
             mock.get(latest_comic_url, status=200, body=xkcd_api_example_628_raw)
-            response = loop.run_until_complete(c.latest())
-            check_comic(self, response, xkcd_api_example_628_dict)
+            response = loop.run_until_complete(c.latest(raw_comic_image=False))
+            check_comic(self, response, xkcd_api_example_628_dict, raw_image=False)
 
     def test_get_random(self):  # let's assume the example_628 json is the latest comic
         c = xkcd_wrapper.AsyncClient()
@@ -93,17 +113,17 @@ def test_get_random(self):  # let's assume the example_628 json is the latest co
             mock.get(latest_comic_url, status=200, body=xkcd_api_example_628_raw)
             mock.get(comic_id_url.format(138), status=200, body=xkcd_api_example_138_raw)
             random.seed(1)  # with latest comic being 628, random value will be 138
-            response = loop.run_until_complete(c.get_random())
+            response = loop.run_until_complete(c.get_random(raw_comic_image=False))
             self.assertEqual(response.id, xkcd_api_example_138_dict['num'])
-            check_comic(self, response, xkcd_api_example_138_dict)
+            check_comic(self, response, xkcd_api_example_138_dict, raw_image=False)
 
             # alias
             mock.get(latest_comic_url, status=200, body=xkcd_api_example_628_raw)
             mock.get(comic_id_url.format(138), status=200, body=xkcd_api_example_138_raw)
             random.seed(1)
-            response = loop.run_until_complete(c.get_random())
+            response = loop.run_until_complete(c.get_random(raw_comic_image=False))
             self.assertEqual(response.id, xkcd_api_example_138_dict['num'])
-            check_comic(self, response, xkcd_api_example_138_dict)
+            check_comic(self, response, xkcd_api_example_138_dict, raw_image=False)
 
     def test__repr__(self):
         c = xkcd_wrapper.AsyncClient()