This module provides a short way to attach resizable images to other object-relationally mapped entity classes.
For example, imagine there’s a fictional entity named User and it has its picture and front_cover. So there should be two image entities that subclass Image mixin:
class UserPicture(Base, Image):
'''User's profile picture.'''
user_id = Column(Integer, ForeignKey('User.id'), primary_key=True)
user = relationship('User')
__tablename__ = 'user_picture'
You have to also inherit your own declarative_base() class (Base in the example).
Assume there’s also UserFrontCover in the same way.
Note that the class can override object_id property. Backend storages utilize this to identify images e.g. filename, S3 key. If the primary key of the image entity is integer, object_id automatically uses the primary key value by default, but it can be overridden if needed, and must be implemented if the primary key is not integer or composite key.
There’s also object_type property. Image provides the default value for it as well. It uses the class name (underscores will be replaced by hyphens) by default, but you can override it.
These Image subclasses can be related to the their ‘parent’ entity using image_attachment() function. It’s a specialized version of SQLAlchemy’s built-in relationship() function, so you can pass the same options as relationship() takes:
class User(Base):
'''Users have their profile picture and front cover.'''
id = Column(Integer, primary_key=True)
picture = image_attachment('UserPicture')
front_cover = image_attachment('UserFrontCover')
__tablename__ = 'user'
It’s done, you can store the actual image files using ImageSet.from_file() or ImageSet.from_blob() method:
with store_context(store):
user = User()
with open('picture.jpg', 'rb') as f:
user.picture.from_blob(f.read())
with open('front_cover.jpg', 'rb') as f:
user.front_cover.from_file(f)
with session.begin():
session.add(user)
Or you can resize the image to make thumbnails using ImageSet.generate_thumbnail() method:
with store_context(store):
user.picture.generate_thumbnail(ratio=0.5)
user.picture.generate_thumbnail(height=100)
user.front_cover.generate_thumbnail(width=500)
The image of the particular size.
Note that it implements __html__() method, a de facto standard special method for HTML templating. So you can simply use it in HTML templates like:
{{ user.profile.find_thumbnail(120) }}
The above template is equivalent to:
{% with thumbnail = user.profile.find_thumbnail(120) %}
<img src="{{ thumbnail.locate() }}"
width="{{ thumbnail.width }}"
height="{{ thumbnail.height }}">
{% endwith %}
(basestring) The identifier string of the image type. It uses __tablename__ (which replaces underscores with hyphens) by default, but can be overridden.
(datetime.datetime) The created time.
(numbers.Integral) The image’s height.”“”
Gets the URL of the image from the store.
Parameters: | store (Store) – the storage which contains the image. current_store by default |
---|---|
Returns: | the url of the image |
Return type: | basestring |
Gets the byte string of the image from the store.
Parameters: | store (Store) – the storage which contains the image. current_store by default |
---|---|
Returns: | the binary data of the image |
Return type: | str |
(basestring) The mimetype of the image e.g. 'image/jpeg', 'image/png'.
(numbers.Integral) The identifier number of the image. It uses the primary key if it’s integer, but can be overridden, and must be implemented when the primary key is not integer or composite key.
Opens the file-like object which is a context manager (that means it can used for with statement).
If use_seek is True (though False by default) it guarentees the returned file-like object is also seekable (provides seek() method).
Parameters: | store (Store) – the storage which contains image files. current_store by default |
---|---|
Returns: | the file-like object of the image, which is a context manager (plus, also seekable only if use_seek is True) |
Return type: | file, FileProxy, file-like object |
(bool) Whether it is original or resized.
(numbers.Integral) The image’s width.
The subtype of Query specialized for Image. It provides more methods and properties over Query.
Note that it implements __html__() method, a de facto standard special method for HTML templating. So you can simply use it in Jinja2 like:
{{ user.profile }}
instead of:
<img src="{{ user.profile|permalink }}"
width="{{ user.profile.original.width }}"
height="{{ user.profile.original.height }}">
Finds the thumbnail of the image with the given width and/or height.
Parameters: |
|
---|---|
Returns: | the thumbnail image |
Return type: | |
Raises sqlalchemy.orm.exc.NoResultFound: | |
when there’s no image of such size |
Stores the blob (byte string) for the image into the store.
Parameters: |
|
---|---|
Returns: | the created image instance |
Return type: |
Stores the file for the image into the store.
Parameters: |
|
---|---|
Returns: | the created image instance |
Return type: |
Similar to from_file() except it’s lower than that. It assumes that raw_file is readable and seekable while from_file() only assumes the file is readable. Also it doesn’t make any in-memory buffer while from_file() always makes an in-memory buffer and copy the file into the buffer.
If size and mimetype are passed, it won’t try to read image and will use these values instead.
It’s used for implementing from_file() and from_blob() methods that are higher than it.
Parameters: |
|
---|---|
Returns: | the created image instance |
Return type: |
Resizes the original (scales up or down) and then store the resized thumbnail into the store.
Parameters: |
|
---|---|
Returns: | the resized thumbnail image. it might be an already existing image if the same size already exists |
Return type: | |
Raises exceptions.IOError: | |
when there’s no original image yet |
The shorthand of locate() for the original.
Parameters: | store (Store) – the storage which contains the image files. current_store by default |
---|---|
Returns: | the url of the original image |
Return type: | basestring |
The shorthand of make_blob() for the original.
Parameters: | store (Store) – the storage which contains the image files. current_store by default |
---|---|
Returns: | the byte string of the original image |
Return type: | str |
The shorthand of open_file() for the original.
Parameters: |
|
---|---|
Returns: | the file-like object of the image, which is a context manager (plus, also seekable only if use_seek is True) |
Return type: | file, FileProxy, file-like object |
The helper function, decorates raw relationship() function, sepcialized for relationships between Image subtypes.
It takes the same parameters as relationship().
Parameters: |
|
---|---|
Returns: | the relationship property |
Return type: |