easy_thumbnails.files: 294 total statements, 0.0% covered

Generated: Wed 2013-03-13 10:33 CET

Source file: /media/Envs/Envs/filer-gallery/lib/python2.7/site-packages/easy_thumbnails/files.py

Stats: 0 executed, 283 missed, 11 excluded, 292 ignored

  1. from django.core.files.base import File, ContentFile
  2. from django.core.files.storage import get_storage_class, default_storage, \
  3. Storage
  4. from django.db.models.fields.files import ImageFieldFile, FieldFile
  5. import os
  6. from django.utils.safestring import mark_safe
  7. from django.utils.html import escape
  8. from django.utils.http import urlquote
  9. from easy_thumbnails import engine, exceptions, models, utils, signals
  10. from easy_thumbnails.alias import aliases
  11. from easy_thumbnails.conf import settings
  12. def get_thumbnailer(obj, relative_name=None):
  13. """
  14. Get a :class:`Thumbnailer` for a source file.
  15. The ``obj`` argument is usually either one of the following:
  16. * ``FieldFile`` instance (i.e. a model instance file/image field
  17. property).
  18. * A string, which will be used as the relative name (the source will be
  19. set to the default storage).
  20. * ``Storage`` instance - the ``relative_name`` argument must also be
  21. provided.
  22. Or it could be:
  23. * A file-like instance - the ``relative_name`` argument must also be
  24. provided.
  25. In this case, the thumbnailer won't use or create a cached reference
  26. to the thumbnail (i.e. a new thumbnail will be created for every
  27. :meth:`Thumbnailer.get_thumbnail` call).
  28. If ``obj`` is a ``Thumbnailer`` instance, it will just be returned. If it's
  29. an object with an ``easy_thumbnails_thumbnailer`` then the attribute is
  30. simply returned under the assumption it is a Thumbnailer instance)
  31. """
  32. if hasattr(obj, 'easy_thumbnails_thumbnailer'):
  33. return obj.easy_thumbnails_thumbnailer
  34. if isinstance(obj, Thumbnailer):
  35. return obj
  36. elif isinstance(obj, FieldFile):
  37. if not relative_name:
  38. relative_name = obj.name
  39. return ThumbnailerFieldFile(obj.instance, obj.field, relative_name)
  40. source_storage = None
  41. if isinstance(obj, basestring):
  42. relative_name = obj
  43. obj = None
  44. if not relative_name:
  45. raise ValueError("If object is not a FieldFile or Thumbnailer "
  46. "instance, the relative name must be provided")
  47. if isinstance(obj, File):
  48. obj = obj.file
  49. if isinstance(obj, Storage) or obj == default_storage:
  50. source_storage = obj
  51. obj = None
  52. return Thumbnailer(file=obj, name=relative_name,
  53. source_storage=source_storage, remote_source=obj is not None)
  54. def save_thumbnail(thumbnail_file, storage):
  55. """
  56. Save a thumbnailed file, returning the saved relative file name.
  57. """
  58. filename = thumbnail_file.name
  59. if storage.exists(filename):
  60. try:
  61. storage.delete(filename)
  62. except:
  63. pass
  64. return storage.save(filename, thumbnail_file)
  65. def generate_all_aliases(fieldfile, include_global):
  66. """
  67. Generate all of a file's aliases.
  68. :param fieldfile: A ``FieldFile`` instance.
  69. :param include_global: A boolean which determines whether to generate
  70. thumbnails for project-wide aliases in addition to field, model, and
  71. app specific aliases.
  72. """
  73. all_options = aliases.all(fieldfile, include_global=include_global)
  74. if all_options:
  75. thumbnailer = get_thumbnailer(fieldfile)
  76. for options in all_options.values():
  77. thumbnailer.get_thumbnail(options)
  78. class FakeField(object):
  79. name = 'fake'
  80. def __init__(self, storage=None):
  81. self.storage = storage or default_storage
  82. def generate_filename(self, instance, name, *args, **kwargs):
  83. return name
  84. class FakeInstance(object):
  85. def save(self, *args, **kwargs):
  86. pass
  87. class ThumbnailFile(ImageFieldFile):
  88. """
  89. A thumbnailed file.
  90. This can be used just like a Django model instance's property for a file
  91. field (i.e. an ``ImageFieldFile`` object).
  92. """
  93. def __init__(self, name, file=None, storage=None, thumbnail_options=None,
  94. *args, **kwargs):
  95. fake_field = FakeField(storage=storage)
  96. super(ThumbnailFile, self).__init__(FakeInstance(), fake_field, name,
  97. *args, **kwargs)
  98. del self.field
  99. if file:
  100. self.file = file
  101. self.thumbnail_options = thumbnail_options
  102. def _get_image(self):
  103. """
  104. Get a PIL Image instance of this file.
  105. The image is cached to avoid the file needing to be read again if the
  106. function is called again.
  107. """
  108. if not hasattr(self, '_image_cache'):
  109. from easy_thumbnails.source_generators import pil_image
  110. self.image = pil_image(self)
  111. return self._image_cache
  112. def _set_image(self, image):
  113. """
  114. Set the image for this file.
  115. This also caches the dimensions of the image.
  116. """
  117. if image:
  118. self._image_cache = image
  119. self._dimensions_cache = image.size
  120. else:
  121. if hasattr(self, '_image_cache'):
  122. del self._cached_image
  123. if hasattr(self, '_dimensions_cache'):
  124. del self._dimensions_cache
  125. image = property(_get_image, _set_image)
  126. def tag(self, alt='', use_size=None, **attrs):
  127. """
  128. Return a standard XHTML ``<img ... />`` tag for this field.
  129. :param alt: The ``alt=""`` text for the tag. Defaults to ``''``.
  130. :param use_size: Whether to get the size of the thumbnail image for use in
  131. the tag attributes. If ``None`` (default), it will be ``True`` or
  132. ``False`` depending on whether the file storage is local or not.
  133. All other keyword parameters are added as (properly escaped) extra
  134. attributes to the `img` tag.
  135. """
  136. if use_size is None:
  137. try:
  138. self.storage.path(self.name)
  139. use_size = True
  140. except NotImplementedError:
  141. use_size = False
  142. attrs['alt'] = alt
  143. attrs['src'] = self.url
  144. if use_size:
  145. attrs.update(dict(width=self.width, height=self.height))
  146. attrs = ' '.join(['%s="%s"' % (key, escape(value))
  147. for key, value in sorted(attrs.items())])
  148. return mark_safe('<img %s />' % attrs)
  149. def _get_file(self):
  150. self._require_file()
  151. if not hasattr(self, '_file') or self._file is None:
  152. self._file = self.storage.open(self.name, 'rb')
  153. return self._file
  154. def _set_file(self, value):
  155. if value is not None and not isinstance(value, File):
  156. value = File(value)
  157. self._file = value
  158. self._committed = False
  159. def _del_file(self):
  160. del self._file
  161. file = property(_get_file, _set_file, _del_file)
  162. def _get_url(self):
  163. """
  164. Return the full url of this file.
  165. .. note:: storages should already be quoting the urls, but Django's
  166. built in ``FileSystemStorage`` doesn't.
  167. ``ThumbnailFieldFile`` works around a common case of the file
  168. containing a ``#``, which shouldn't ever be used for a url.
  169. """
  170. url = super(ThumbnailFile, self).url
  171. if '#' in url:
  172. url = urlquote(url)
  173. return url
  174. url = property(_get_url)
  175. def open(self, mode=None, *args, **kwargs):
  176. if self.closed and self.name:
  177. mode = mode or getattr(self, 'mode', None) or 'rb'
  178. self.file = self.storage.open(self.name, mode)
  179. else:
  180. return super(ThumbnailFile, self).open(mode, *args, **kwargs)
  181. class Thumbnailer(File):
  182. """
  183. A file-like object which provides some methods to generate thumbnail
  184. images.
  185. You can subclass this object and override the following properties to
  186. change the defaults (pulled from the default settings):
  187. * source_generators
  188. * thumbnail_processors
  189. """
  190. source_generators = None
  191. thumbnail_processors = None
  192. def __init__(self, file=None, name=None, source_storage=None,
  193. thumbnail_storage=None, remote_source=False, generate=True, *args,
  194. **kwargs):
  195. super(Thumbnailer, self).__init__(file, name, *args, **kwargs)
  196. self.source_storage = source_storage or default_storage
  197. if not thumbnail_storage:
  198. thumbnail_storage = get_storage_class(
  199. settings.THUMBNAIL_DEFAULT_STORAGE)()
  200. self.thumbnail_storage = thumbnail_storage
  201. self.remote_source = remote_source
  202. self.alias_target = None
  203. self.generate = generate
  204. # Set default properties. For backwards compatibilty, check to see
  205. # if the attribute exists already (it could be set as a class property
  206. # on a subclass) before getting it from settings.
  207. for default in ('basedir', 'subdir', 'prefix', 'quality', 'extension',
  208. 'preserve_extensions', 'transparency_extension',
  209. 'check_cache_miss'):
  210. attr_name = 'thumbnail_%s' % default
  211. if getattr(self, attr_name, None) is None:
  212. value = getattr(settings, attr_name.upper())
  213. setattr(self, attr_name, value)
  214. def __getitem__(self, alias):
  215. """
  216. Retrieve a thumbnail matching the alias options (or raise a
  217. ``KeyError`` if no such alias exists).
  218. """
  219. options = aliases.get(alias, target=self.alias_target)
  220. if not options:
  221. raise KeyError(alias)
  222. return self.get_thumbnail(options)
  223. def generate_source_image(self, thumbnail_options):
  224. return engine.generate_source_image(self, thumbnail_options,
  225. self.source_generators)
  226. def generate_thumbnail(self, thumbnail_options):
  227. """
  228. Return an unsaved ``ThumbnailFile`` containing a thumbnail image.
  229. The thumbnail image is generated using the ``thumbnail_options``
  230. dictionary.
  231. """
  232. image = self.generate_source_image(thumbnail_options)
  233. if image is None:
  234. raise exceptions.InvalidImageFormatError(
  235. "The source file does not appear to be an image")
  236. thumbnail_image = engine.process_image(image, thumbnail_options,
  237. self.thumbnail_processors)
  238. quality = thumbnail_options.get('quality', self.thumbnail_quality)
  239. filename = self.get_thumbnail_name(thumbnail_options,
  240. transparent=utils.is_transparent(thumbnail_image))
  241. data = engine.save_image(thumbnail_image, filename=filename,
  242. quality=quality).read()
  243. thumbnail = ThumbnailFile(filename, file=ContentFile(data),
  244. storage=self.thumbnail_storage,
  245. thumbnail_options=thumbnail_options)
  246. thumbnail.image = thumbnail_image
  247. thumbnail._committed = False
  248. return thumbnail
  249. def get_thumbnail_name(self, thumbnail_options, transparent=False):
  250. """
  251. Return a thumbnail filename for the given ``thumbnail_options``
  252. dictionary and ``source_name`` (which defaults to the File's ``name``
  253. if not provided).
  254. """
  255. path, source_filename = os.path.split(self.name)
  256. source_extension = os.path.splitext(source_filename)[1][1:]
  257. filename = '%s%s' % (self.thumbnail_prefix, source_filename)
  258. if self.thumbnail_preserve_extensions == True or \
  259. (self.thumbnail_preserve_extensions and \
  260. source_extension.lower() in self.thumbnail_preserve_extensions):
  261. extension = source_extension
  262. elif transparent:
  263. extension = self.thumbnail_transparency_extension
  264. else:
  265. extension = self.thumbnail_extension
  266. extension = extension or 'jpg'
  267. thumbnail_options = thumbnail_options.copy()
  268. size = tuple(thumbnail_options.pop('size'))
  269. quality = thumbnail_options.pop('quality', self.thumbnail_quality)
  270. initial_opts = ['%sx%s' % size, 'q%s' % quality]
  271. opts = thumbnail_options.items()
  272. opts.sort() # Sort the options so the file name is consistent.
  273. opts = ['%s' % (v is not True and '%s-%s' % (k, v) or k)
  274. for k, v in opts if v]
  275. all_opts = '_'.join(initial_opts + opts)
  276. data = {'opts': all_opts}
  277. basedir = self.thumbnail_basedir % data
  278. subdir = self.thumbnail_subdir % data
  279. filename_parts = [filename]
  280. if ('%(opts)s' in self.thumbnail_basedir or
  281. '%(opts)s' in self.thumbnail_subdir):
  282. if extension != source_extension:
  283. filename_parts.append(extension)
  284. else:
  285. filename_parts += [all_opts, extension]
  286. filename = '.'.join(filename_parts)
  287. return os.path.join(basedir, path, subdir, filename)
  288. def get_thumbnail(self, thumbnail_options, save=True, generate=None):
  289. """
  290. Return a ``ThumbnailFile`` containing a thumbnail.
  291. If a matching thumbnail already exists, it will simply be returned.
  292. By default (unless the ``Thumbnailer`` was instanciated with
  293. ``generate=False``), thumbnails that don't exist are generated.
  294. Otherwise ``None`` is returned.
  295. Force the generation behaviour by setting the ``generate`` param to
  296. either ``True`` or ``False`` as required.
  297. The new thumbnail image is generated using the ``thumbnail_options``
  298. dictionary. If the ``save`` argument is ``True`` (default), the
  299. generated thumbnail will be saved too.
  300. """
  301. opaque_name = self.get_thumbnail_name(thumbnail_options,
  302. transparent=False)
  303. transparent_name = self.get_thumbnail_name(thumbnail_options,
  304. transparent=True)
  305. if opaque_name == transparent_name:
  306. names = (opaque_name,)
  307. else:
  308. names = (opaque_name, transparent_name)
  309. for filename in names:
  310. if self.thumbnail_exists(filename):
  311. return ThumbnailFile(name=filename,
  312. storage=self.thumbnail_storage,
  313. thumbnail_options=thumbnail_options)
  314. if generate is None:
  315. generate = self.generate
  316. if not generate:
  317. signals.thumbnail_missed.send(sender=self,
  318. options=thumbnail_options)
  319. return
  320. thumbnail = self.generate_thumbnail(thumbnail_options)
  321. if save:
  322. save_thumbnail(thumbnail, self.thumbnail_storage)
  323. signals.thumbnail_created.send(sender=thumbnail)
  324. # Ensure the right thumbnail name is used based on the transparency
  325. # of the image.
  326. filename = (utils.is_transparent(thumbnail.image) and
  327. transparent_name or opaque_name)
  328. self.get_thumbnail_cache(filename, create=True, update=True)
  329. return thumbnail
  330. def thumbnail_exists(self, thumbnail_name):
  331. """
  332. Calculate whether the thumbnail already exists and that the source is
  333. not newer than the thumbnail.
  334. If both the source and thumbnail file storages are local, their
  335. file modification times are used. Otherwise the database cached
  336. modification times are used.
  337. """
  338. if self.remote_source:
  339. return False
  340. # Try to use the local file modification times first.
  341. source_modtime = self.get_source_modtime()
  342. thumbnail_modtime = self.get_thumbnail_modtime(thumbnail_name)
  343. # The thumbnail modification time will be 0 if there was an OSError,
  344. # in which case it will still be used (but always return False).
  345. if source_modtime and thumbnail_modtime is not None:
  346. return thumbnail_modtime and source_modtime <= thumbnail_modtime
  347. # Fall back to using the database cached modification times.
  348. source = self.get_source_cache()
  349. if not source:
  350. return False
  351. thumbnail = self.get_thumbnail_cache(thumbnail_name)
  352. return thumbnail and source.modified <= thumbnail.modified
  353. def get_source_cache(self, create=False, update=False):
  354. if self.remote_source:
  355. return None
  356. modtime = self.get_source_modtime()
  357. update_modified = modtime and utils.fromtimestamp(modtime)
  358. if update:
  359. update_modified = update_modified or utils.now()
  360. return models.Source.objects.get_file(
  361. create=create, update_modified=update_modified,
  362. storage=self.source_storage, name=self.name,
  363. check_cache_miss=self.thumbnail_check_cache_miss)
  364. def get_thumbnail_cache(self, thumbnail_name, create=False, update=False):
  365. if self.remote_source:
  366. return None
  367. modtime = self.get_thumbnail_modtime(thumbnail_name)
  368. update_modified = modtime and utils.fromtimestamp(modtime)
  369. if update:
  370. update_modified = update_modified or utils.now()
  371. source = self.get_source_cache(create=True)
  372. return models.Thumbnail.objects.get_file(
  373. create=create, update_modified=update_modified,
  374. storage=self.thumbnail_storage, source=source, name=thumbnail_name,
  375. check_cache_miss=self.thumbnail_check_cache_miss)
  376. def get_source_modtime(self):
  377. try:
  378. path = self.source_storage.path(self.name)
  379. return os.path.getmtime(path)
  380. except OSError:
  381. return 0
  382. except NotImplementedError:
  383. return None
  384. def get_thumbnail_modtime(self, thumbnail_name):
  385. try:
  386. path = self.thumbnail_storage.path(thumbnail_name)
  387. return os.path.getmtime(path)
  388. except OSError:
  389. return 0
  390. except NotImplementedError:
  391. return None
  392. def open(self, mode=None):
  393. if self.closed:
  394. mode = mode or getattr(self, 'mode', None) or 'rb'
  395. self.file = self.source_storage.open(self.name, mode)
  396. else:
  397. self.seek(0)
  398. # open() doesn't alter the file's contents, but it does reset the pointer.
  399. open.alters_data = True
  400. class ThumbnailerFieldFile(FieldFile, Thumbnailer):
  401. """
  402. A field file which provides some methods for generating (and returning)
  403. thumbnail images.
  404. """
  405. def __init__(self, *args, **kwargs):
  406. super(ThumbnailerFieldFile, self).__init__(*args, **kwargs)
  407. self.source_storage = self.field.storage
  408. thumbnail_storage = getattr(self.field, 'thumbnail_storage', None)
  409. if thumbnail_storage:
  410. self.thumbnail_storage = thumbnail_storage
  411. self.alias_target = self
  412. def save(self, name, content, *args, **kwargs):
  413. """
  414. Save the file, also saving a reference to the thumbnail cache Source
  415. model.
  416. """
  417. super(ThumbnailerFieldFile, self).save(name, content, *args, **kwargs)
  418. self.get_source_cache(create=True, update=True)
  419. def delete(self, *args, **kwargs):
  420. """
  421. Delete the image, along with any generated thumbnails.
  422. """
  423. source_cache = self.get_source_cache()
  424. # First, delete any related thumbnails.
  425. self.delete_thumbnails(source_cache)
  426. # Next, delete the source image.
  427. super(ThumbnailerFieldFile, self).delete(*args, **kwargs)
  428. # Finally, delete the source cache entry.
  429. if source_cache:
  430. source_cache.delete()
  431. delete.alters_data = True
  432. def delete_thumbnails(self, source_cache=None):
  433. """
  434. Delete any thumbnails generated from the source image.
  435. :arg source_cache: An optional argument only used for optimisation
  436. where the source cache instance is already known.
  437. :returns: The number of files deleted.
  438. """
  439. source_cache = self.get_source_cache()
  440. deleted = 0
  441. if source_cache:
  442. thumbnail_storage_hash = utils.get_storage_hash(
  443. self.thumbnail_storage)
  444. for thumbnail_cache in source_cache.thumbnails.all():
  445. # Only attempt to delete the file if it was stored using the
  446. # same storage as is currently used.
  447. if thumbnail_cache.storage_hash == thumbnail_storage_hash:
  448. self.thumbnail_storage.delete(thumbnail_cache.name)
  449. # Delete the cache thumbnail instance too.
  450. thumbnail_cache.delete()
  451. deleted += 1
  452. return deleted
  453. delete_thumbnails.alters_data = True
  454. def get_thumbnails(self, *args, **kwargs):
  455. """
  456. Return an iterator which returns ThumbnailFile instances.
  457. """
  458. # First, delete any related thumbnails.
  459. source_cache = self.get_source_cache()
  460. if source_cache:
  461. thumbnail_storage_hash = utils.get_storage_hash(
  462. self.thumbnail_storage)
  463. for thumbnail_cache in source_cache.thumbnails.all():
  464. # Only iterate files which are stored using the current
  465. # thumbnail storage.
  466. if thumbnail_cache.storage_hash == thumbnail_storage_hash:
  467. yield ThumbnailFile(name=thumbnail_cache.name,
  468. storage=self.thumbnail_storage)
  469. class ThumbnailerImageFieldFile(ImageFieldFile, ThumbnailerFieldFile):
  470. """
  471. A field file which provides some methods for generating (and returning)
  472. thumbnail images.
  473. """
  474. def save(self, name, content, *args, **kwargs):
  475. """
  476. Save the image.
  477. The image will be resized down using a ``ThumbnailField`` if
  478. ``resize_source`` (a dictionary of thumbnail options) is provided by
  479. the field.
  480. """
  481. options = getattr(self.field, 'resize_source', None)
  482. if options:
  483. if not 'quality' in options:
  484. options['quality'] = self.thumbnail_quality
  485. content = Thumbnailer(content, name).generate_thumbnail(options)
  486. super(ThumbnailerImageFieldFile, self).save(name, content, *args,
  487. **kwargs)