efl.ethumb_client.EthumbClient
Class¶
- class efl.ethumb_client.EthumbClient(func, *args, **kargs)¶
Bases:
object
Client for Ethumbd server.
New in version 1.17.
This client is the recommended way to generate thumbnails with Ethumb. All you have to do is create a client instance, wait it to be connected to server, configure thumbnail parameters and then start feed it with file_set(), exists() generate(). Basic steps are:
instantiate EthumbClient, wait for func to be called with success.
set various parameters, like format and size.
loop on original files:
c.file_set(file)
if not c.exists(): c.generate(generated_cb)
It is recommended explicit call to
disconnect()
function when you don’t need the thumbnailer anymore.- Parameters
func – function to call when connection with server is established.
*args – Any other parameters will be passed back in the callback function
**kargs – Any other keyword parameters will be passed back in the callback function
Expected func signature:
func(client, status, *args, **kargs)
with status being True for successful connection or False on error.
- Raises
TypeError – if func is not callable.
SystemError – if it was not possible to connect to server, allocate memory or use DBus.
- aspect¶
The aspect ratio policy.
If aspect is kept (ETHUMB_THUMB_KEEP_ASPECT), then image will be rescaled so the largest dimension is not bigger than it’s specified size (see
size_get()
) and the other dimension is resized in the same proportion. Example: size is 256x256, image is 1000x500, resulting thumbnail is 256x128.If aspect is ignored (ETHUMB_THUMB_IGNORE_ASPECT), then image will be distorted to match required thumbnail size. Example: size is 256x256, image is 1000x500, resulting thumbnail is 256x256.
If crop is required (ETHUMB_THUMB_CROP), then image will be cropped so the smallest dimension is not bigger than its specified size (see
size_get()
) and the other dimension will overflow, not being visible in the final image. How it will overflow is speficied bycrop_set()
alignment. Example: size is 256x256, image is 1000x500, crop alignment is 0.5, 0.5, resulting thumbnail is 256x256 with 250 pixels from left and 250 pixels from right being lost, that is just the 500x500 central pixels of image will be considered for scaling.- Type
- category¶
Category directory to store thumbnails.
Category sub directory to store thumbnail. Default is either “normal” or “large” for FDO compliant thumbnails or
WIDTHxHEIGHT-ASPECT[-FRAMED]-FORMAT
. It can be a string or None to use auto generated names.- Type
str
- compress¶
The thumbnail compression rate.
Value from 0 to 9, default is 9. The effect depends on the format being used, JPEG will not use it.
- Type
int
- crop_align¶
Crop alignment in use.
- Parameters
x – horizontal alignment. 0.0 means left side will be visible or right side is being lost. 1.0 means right side will be visible or left side is being lost. 0.5 means just center is visible, both sides will be lost. Default is 0.5.
y – vertical alignment. 0.0 is top visible, 1.0 is bottom visible, 0.5 is center visible. Default is 0.5
- Type
(float x, float y)
- dir_path¶
Configure where to store thumbnails in future requests.
This is the base folder, a category folder is added to this path as a sub directory. Default is
~/.thumbnails
- Type
str
- disconnect()¶
Explicitly request server disconnection.
After this call object becomes shallow, that is operations will be void.
- document_page¶
The page number to thumbnail in paged documents.
- Type
int
- fdo¶
Configure future requests to use FreeDesktop.Org preset.
This is a preset to provide freedesktop.org (fdo) standard compliant thumbnails. That is, files are stored as JPEG under ~/.thumbnails/SIZE, with size being either normal (128x128) or large (256x256).
- Type
Ethumb_Thumb_FDO_Size writeonly
- file¶
The file to thumbnail.
This is a tuple of 2 strings:
path
andkey
.For convenience you can also assign a single string value (
path
), ignoring the key.- Type
str or (str, str)
- Parameters
path – path to thumbnail subject.
key – path to key inside path, this is used to generate thumbnail of edje groups or images inside EET.
- Raises
RuntimeError – on failure setting the property
Note
setting this property will reset other thumbnail specifications. This is done to avoid one using the last thumb path for new images.
- file_free()¶
Zero/Reset file parameters.
This call will reset file and thumb specifications.
See also
file_set()
andthumb_set()
- format¶
The fileformat for the thumbnails.
Thumbnails are compressed; possible formats are PNG, JPEG and EET.
- Type
- frame¶
The optional edje file used to generate a frame around the thumbnail
This will create an edje object that will have image swallowed in. This can be used to simulate Polaroid or wood frames in the generated image. Remember it is bad to modify the original contents of thumbnails, but sometimes it’s useful to have it composited and avoid runtime overhead.
- Type
(str, str, str) writeonly
- Parameters
file – file path to edje.
group – group inside edje to use.
swallow – name of swallow part.
- Raises
RuntimeError – on failure setting the property
- generate(func, *args, **kargs)¶
Ask EThumb server to generate the specified thumbnail.
Thumbnail generation is asynchronous and depend on ecore main loop running. Given function will be called back with generation status if True is returned by this call. If False is returned, given function will not be called.
Existing thumbnails will be overwritten with this call. Check if they already exist with
exists()
before calling.- Parameters
func –
function to call on generation completion, even if failed or succeeded. Signature is:
func(self, id, file, key, thumb_path, thumb_key, status, *args, **kargs)
with status being True for successful generation or False on failure.
- Returns
request identifier. Request can be canceled calling
cancel()
with given id. If an identifier is returned (>= 0), then func is guaranteed to be called unless it is explicitly canceled.- Raises
TypeError – if func is not callable.
SystemError – if could not generate thumbnail, probably no
file_set()
.
See also
cancel()
,clear()
,exists()
- generate_cancel(id)¶
Cancel thumbnail request given its id.
Calling this function aborts thumbnail generation and func given to
generate()
will not be called!- Parameters
id – identifier returned by
generate()
- generate_cancel_all()¶
Clear request queue, canceling all generation requests.
This will abort all existing requests, no func given to
generate()
will be called.Same as calling
cancel()
in all exising requests.
- on_server_die_callback_set(func, *args, **kargs)¶
Function to call when server dies.
When server is dead there is nothing to do with this client anymore, just create a new one and start over, hope that server could be started and you could generate more thumbnails.
- Parameters
func –
function to call when server dies. Signature:
func(client, *args, **kargs)
- Raises
TypeError – if func is not callable or None.
- orientation¶
The thumbnail rotation or flip.
- quality¶
The thumbnail compression quality.
Value from 0 to 100, default is 80. The effect depends on the format being used, PNG will not use it.
- Type
int
- size¶
The (custom) size of thumbnails.
- Type
(int w, int w)
- Parameters
w – width, default is 128.
h – height, default is 128.
- thumb_exists(callback=None, *args, **kwargs)¶
Checks if thumbnail already exists.
If you want to avoid regenerating thumbnails, check if they already exist with this function.
- thumb_path¶
The complete path of the generated thumbnail.
This is a tuple of 2 strings:
path
andkey
.For convenience you can also assign a single string value (
path
), ignoring the key.- Type
str or (str, str)
- Parameters
path – path to generated thumbnail to use, this is an absolute path to file, overriding directory and category.
key – path to key inside path, this is used to generate thumbnail inside EET files.
- video_fps¶
The thumbnail framerate.
Default to 10.
- Type
int (readonly)
- video_interval¶
The video frame interval, in seconds.
This is useful for animated thumbnail and will define skip time before going to the next frame.
Note
that video backends might not be able to precisely skip that amount as it will depend on various factors, including video encoding.
- Type
float (readonly)
- video_ntimes¶
The number of times the video loops (if applicable).
- Type
int (readonly)
- video_start¶
The start point for video thumbnails.
- Type
float (from 0.0 to 1.0) (readonly)
- video_time¶
The video time (duration) in seconds.
- Type
float (readonly)