4 files changed, 47 insertions, 3 deletions

diff --git a/docs/index.rst b/docs/index.rst
index b5b1ea5..4e95bbb 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -554,6 +554,7 @@ Media dicts
                 # rounded), and a "length" field giving a videos length in a human-readable format.
                 # Note that a video may have an image as preview.
                 # May also contain a 'focus' dict.
+        'blurhash': # The blurhash for the image, used for preview / placeholder generation
     }
     
     # Metadata dicts (image) - all fields are optional:
@@ -1067,6 +1068,12 @@ These functions allow for convenient retrieval of paginated data.
 .. automethod:: Mastodon.fetch_previous
 .. automethod:: Mastodon.fetch_remaining
 
+Blurhash decoding
+-----------------
+This function allows for easy basic decoding of blurhash strings to images.
+
+.. automethod:: Mastodon.decode_blurhash
+
 Streaming
 ---------
 These functions allow access to the streaming API.
diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py
index 181b0e7..174e798 100644
--- a/mastodon/Mastodon.py
+++ b/mastodon/Mastodon.py
@@ -25,6 +25,7 @@ from cryptography.hazmat.primitives.asymmetric import ec
 import http_ece
 import base64
 import json
+import blurhash
 
 try:
     from urllib.parse import urlparse
@@ -2346,7 +2347,42 @@ class Mastodon:
         )
         
         return json.loads(decrypted.decode('utf-8'), object_hook = Mastodon.__json_hooks)
-    
+   
+    ###
+    # Blurhash utilities
+    ###    
+    def decode_blurhash(self, media_dict, out_size = (16, 16), size_per_component = True, return_linear = True):
+        """
+        Basic media-dict blurhash decoding.
+        
+        out_size is the desired result size in pixels, either absolute or per blurhash
+        component (this is the default).
+        
+        By default, this function will return the image as linear RGB, ready for further
+        scaling operations. If you want to display the image directly, set return_linear 
+        to False.
+        
+        Returns the decoded blurhash image as a three-dimensional list: [height][width][3],
+        with the last dimension being RGB colours.
+        
+        For further info and tips for advanced usage, refer to the documentation for the
+        blurhash module: https://github.com/halcy/blurhash-python
+        """
+        # Figure out what size to decode to
+        decode_components_x, decode_components_y = blurhash.components(media_dict["blurhash"])
+        if size_per_component == False:
+            decode_size_x = out_size[0]
+            decode_size_y = out_size[1]
+        else:
+            decode_size_x = decode_components_x * out_size[0]
+            decode_size_y = decode_components_y * out_size[1]
+
+        # Decode
+        decoded_image = blurhash.decode(media_dict["blurhash"], decode_size_x, decode_size_y, linear = return_linear)
+
+        # And that's pretty much it.
+        return decoded_image
+        
     ###
     # Pagination
     ###
diff --git a/setup.py b/setup.py
index 737f6d9..ddb898f 100644
--- a/setup.py
+++ b/setup.py
@@ -17,7 +17,8 @@ setup(name='Mastodon.py',
           'python-magic',
           'decorator>=4.0.0', 
           'http_ece>=1.0.5',
-          'cryptography>=1.6.0'
+          'cryptography>=1.6.0',
+          'blurhash>=1.1.0',
       ],
       tests_require=test_deps,
       extras_require=extras,
diff --git a/tests/test_push.py b/tests/test_push.py
index 2ad215e..ad02cd8 100644
--- a/tests/test_push.py
+++ b/tests/test_push.py
@@ -66,4 +66,4 @@ def test_push_delete(api):
     
     api.push_subscription_delete()
     with pytest.raises(MastodonNotFoundError):
-        api.push_subscription()
\ No newline at end of file
+        api.push_subscription()