Document a little bit MongoEngine fields

docs/conf.py

@@ -52,7 +52,7 @@
 
 # General information about the project.
 project = u'Flask-FS'
-copyright = u'2014, Axel Haustant'
+copyright = u'2016, Axel Haustant'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -322,5 +322,5 @@
     'python': ('http://docs.python.org/', None),
     'werkzeug': ('http://werkzeug.pocoo.org/docs/', None),
     'boto': ('https://boto3.readthedocs.org/en/latest/', None),
-    'mongo': ('http://mongoengine-odm.readthedocs.org/en/latest/', None),
+    'mongo': ('http://docs.mongoengine.org/', None),
 }

docs/mongoengine.rst

@@ -2,3 +2,95 @@ Mongoengine support
 ===================
 
 Flask-FS provides a thin mongoengine integration as :class:`field classes <mongoengine.base.fields.BaseField>`.
+
+Both :class:`~flask_fs.mongo.FileField` and :class:`~flask_fs.mongo.ImageField`
+provides a common interface:
+
+.. code-block:: python
+
+    images = fs.Storage('images', fs.IMAGES,
+                        upload_to=lambda o: 'prefix',
+                        basename=lambda o: 'basename')
+
+    class MyDoc(Document):
+        file = FileField(fs=files)
+
+
+    doc = MyDoc()
+
+    # Test file presence
+    print(bool(doc.file))  # False
+    # Get filename
+    print(doc.file.filename)  # None
+    # Get file URL
+    print(doc.file.url)  # None
+    # Print file URL
+    print(str(doc.file))  # ''
+
+    doc.file.save(io.Bytes(b'xxx'), 'test.file')
+
+    print(bool(doc.file))  # True
+    print(doc.file.filename)  # 'test.file'
+    print(doc.file.url)  # 'http://myserver.com/files/prefix/test.file'
+    print(str(doc.file))  # 'http://myserver.com/files/prefix/test.file'
+
+    # Override Werkzeug Filestorage filename with basename
+    f = FileStorage(io.Bytes(b'xxx'), 'test.file')
+    doc.file.save(f)
+    print(doc.file.filename)  # 'basename.file'
+
+
+The :class:`~flask_fs.mongo.ImageField` provides some extra features.
+
+On declaration:
+
+ - an optionnal `max_size` attribute allows to limit image size
+ - an optionnal `thumbnails` list of thumbnail sizes to be generated
+
+On instance:
+
+ - the `original` property gives the unmodified image filename
+ - the `best_url(size)` method match a thumbnail URL given a size
+ - the `thumbnail(size)` method get a thumbnail filename given a registered size
+ - the `save` method accept an optionnal `bbox` kwarg for to crop the thumbnails
+ - the instance is callable as shortcut for `best_url()`
+
+.. code-block:: python
+
+    images = fs.Storage('images', fs.IMAGES)
+    files = fs.Storage('files', fs.ALL)
+
+    class MyDoc(Document):
+        image = ImageField(fs=images,
+                           max_size=150,
+                           thumbnails=[100, 32])
+
+
+    doc = MyDoc()
+
+    with open(some_image, 'rb') as f:
+        doc.file.save(f, 'test.png')
+
+    print(doc.image.filename)  # 'test.png'
+    print(doc.image.original)  # 'test-original.png'
+    print(doc.image.thumbnail(100))  # 'test-100.png'
+    print(doc.image.thumbnail(32))  # 'test-32.png'
+
+    # Guess best image url for a given size
+    assert doc.image.best_url().endswith(doc.image.filename)
+    assert doc.image.best_url(200).endswith(doc.image.filename)
+    assert doc.image.best_url(150).endswith(doc.image.filename)
+    assert doc.image.best_url(100).endswith(doc.image.thumbnail(100))
+    assert doc.image.best_url(90).endswith(doc.image.thumbnail(100))
+    assert doc.image.best_url(30).endswith(doc.image.thumbnail(32))
+
+    # Call as shortcut for best_url()
+    assert doc.image().endswith(doc.image.filename)
+    assert doc.image(200).endswith(doc.image.filename)
+    assert doc.image(150).endswith(doc.image.filename)
+    assert doc.image(100).endswith(doc.image.thumbnail(100))
+
+    # Save an optionnal bbox for thumbnails cropping
+    bbox = (10, 10, 100, 100)
+    with open(some_image, 'rb') as f:
+        doc.file.save(f, 'test.png', bbox=bbox)

flask_fs/mongo.py

@@ -16,6 +16,7 @@
 
 
 class FileReference(object):
+    '''Implements the FileField interface'''
     def __init__(self, fs=None, filename=None, upload_to=None, basename=None,
                  instance=None, name=None):
         self.fs = fs
@@ -69,6 +70,7 @@ def _mark_as_changed(self):
 
 
 class ImageReference(FileReference):
+    '''Implements the ImageField interface'''
     def __init__(self, original=None, max_size=None, thumbnail_sizes=None, thumbnails=None,
                  bbox=None, **kwargs):
         super(ImageReference, self).__init__(**kwargs)
@@ -144,6 +146,7 @@ def original(self, value):
         self._original = value
 
     def thumbnail(self, size):
+        '''Get the thumbnail filename for a given size'''
         if size in self.thumbnail_sizes:
             return self.thumbnails.get(str(size))
         else: