| import datetime |
| import os |
| |
| import django.utils.copycompat as copy |
| |
| from django.conf import settings |
| from django.db.models.fields import Field |
| from django.core.files.base import File, ContentFile |
| from django.core.files.storage import default_storage |
| from django.core.files.images import ImageFile, get_image_dimensions |
| from django.core.files.uploadedfile import UploadedFile |
| from django.utils.functional import curry |
| from django.db.models import signals |
| from django.utils.encoding import force_unicode, smart_str |
| from django.utils.translation import ugettext_lazy, ugettext as _ |
| from django import forms |
| from django.db.models.loading import cache |
| |
| class FieldFile(File): |
| def __init__(self, instance, field, name): |
| super(FieldFile, self).__init__(None, name) |
| self.instance = instance |
| self.field = field |
| self.storage = field.storage |
| self._committed = True |
| |
| def __eq__(self, other): |
| # Older code may be expecting FileField values to be simple strings. |
| # By overriding the == operator, it can remain backwards compatibility. |
| if hasattr(other, 'name'): |
| return self.name == other.name |
| return self.name == other |
| |
| def __ne__(self, other): |
| return not self.__eq__(other) |
| |
| def __hash__(self): |
| # Required because we defined a custom __eq__. |
| return hash(self.name) |
| |
| # The standard File contains most of the necessary properties, but |
| # FieldFiles can be instantiated without a name, so that needs to |
| # be checked for here. |
| |
| def _require_file(self): |
| if not self: |
| raise ValueError("The '%s' attribute has no file associated with it." % self.field.name) |
| |
| def _get_file(self): |
| self._require_file() |
| if not hasattr(self, '_file') or self._file is None: |
| self._file = self.storage.open(self.name, 'rb') |
| return self._file |
| |
| def _set_file(self, file): |
| self._file = file |
| |
| def _del_file(self): |
| del self._file |
| |
| file = property(_get_file, _set_file, _del_file) |
| |
| def _get_path(self): |
| self._require_file() |
| return self.storage.path(self.name) |
| path = property(_get_path) |
| |
| def _get_url(self): |
| self._require_file() |
| return self.storage.url(self.name) |
| url = property(_get_url) |
| |
| def _get_size(self): |
| self._require_file() |
| if not self._committed: |
| return self.file.size |
| return self.storage.size(self.name) |
| size = property(_get_size) |
| |
| def open(self, mode='rb'): |
| self._require_file() |
| self.file.open(mode) |
| # open() doesn't alter the file's contents, but it does reset the pointer |
| open.alters_data = True |
| |
| # In addition to the standard File API, FieldFiles have extra methods |
| # to further manipulate the underlying file, as well as update the |
| # associated model instance. |
| |
| def save(self, name, content, save=True): |
| name = self.field.generate_filename(self.instance, name) |
| self.name = self.storage.save(name, content) |
| setattr(self.instance, self.field.name, self.name) |
| |
| # Update the filesize cache |
| self._size = content.size |
| self._committed = True |
| |
| # Save the object because it has changed, unless save is False |
| if save: |
| self.instance.save() |
| save.alters_data = True |
| |
| def delete(self, save=True): |
| # Only close the file if it's already open, which we know by the |
| # presence of self._file |
| if hasattr(self, '_file'): |
| self.close() |
| del self.file |
| |
| self.storage.delete(self.name) |
| |
| self.name = None |
| setattr(self.instance, self.field.name, self.name) |
| |
| # Delete the filesize cache |
| if hasattr(self, '_size'): |
| del self._size |
| self._committed = False |
| |
| if save: |
| self.instance.save() |
| delete.alters_data = True |
| |
| def _get_closed(self): |
| file = getattr(self, '_file', None) |
| return file is None or file.closed |
| closed = property(_get_closed) |
| |
| def close(self): |
| file = getattr(self, '_file', None) |
| if file is not None: |
| file.close() |
| |
| def __getstate__(self): |
| # FieldFile needs access to its associated model field and an instance |
| # it's attached to in order to work properly, but the only necessary |
| # data to be pickled is the file's name itself. Everything else will |
| # be restored later, by FileDescriptor below. |
| return {'name': self.name, 'closed': False, '_committed': True, '_file': None} |
| |
| class FileDescriptor(object): |
| """ |
| The descriptor for the file attribute on the model instance. Returns a |
| FieldFile when accessed so you can do stuff like:: |
| |
| >>> instance.file.size |
| |
| Assigns a file object on assignment so you can do:: |
| |
| >>> instance.file = File(...) |
| |
| """ |
| def __init__(self, field): |
| self.field = field |
| |
| def __get__(self, instance=None, owner=None): |
| if instance is None: |
| raise AttributeError( |
| "The '%s' attribute can only be accessed from %s instances." |
| % (self.field.name, owner.__name__)) |
| |
| # This is slightly complicated, so worth an explanation. |
| # instance.file`needs to ultimately return some instance of `File`, |
| # probably a subclass. Additionally, this returned object needs to have |
| # the FieldFile API so that users can easily do things like |
| # instance.file.path and have that delegated to the file storage engine. |
| # Easy enough if we're strict about assignment in __set__, but if you |
| # peek below you can see that we're not. So depending on the current |
| # value of the field we have to dynamically construct some sort of |
| # "thing" to return. |
| |
| # The instance dict contains whatever was originally assigned |
| # in __set__. |
| file = instance.__dict__[self.field.name] |
| |
| # If this value is a string (instance.file = "path/to/file") or None |
| # then we simply wrap it with the appropriate attribute class according |
| # to the file field. [This is FieldFile for FileFields and |
| # ImageFieldFile for ImageFields; it's also conceivable that user |
| # subclasses might also want to subclass the attribute class]. This |
| # object understands how to convert a path to a file, and also how to |
| # handle None. |
| if isinstance(file, basestring) or file is None: |
| attr = self.field.attr_class(instance, self.field, file) |
| instance.__dict__[self.field.name] = attr |
| |
| # Other types of files may be assigned as well, but they need to have |
| # the FieldFile interface added to the. Thus, we wrap any other type of |
| # File inside a FieldFile (well, the field's attr_class, which is |
| # usually FieldFile). |
| elif isinstance(file, File) and not isinstance(file, FieldFile): |
| file_copy = self.field.attr_class(instance, self.field, file.name) |
| file_copy.file = file |
| file_copy._committed = False |
| instance.__dict__[self.field.name] = file_copy |
| |
| # Finally, because of the (some would say boneheaded) way pickle works, |
| # the underlying FieldFile might not actually itself have an associated |
| # file. So we need to reset the details of the FieldFile in those cases. |
| elif isinstance(file, FieldFile) and not hasattr(file, 'field'): |
| file.instance = instance |
| file.field = self.field |
| file.storage = self.field.storage |
| |
| # That was fun, wasn't it? |
| return instance.__dict__[self.field.name] |
| |
| def __set__(self, instance, value): |
| instance.__dict__[self.field.name] = value |
| |
| class FileField(Field): |
| # The class to wrap instance attributes in. Accessing the file object off |
| # the instance will always return an instance of attr_class. |
| attr_class = FieldFile |
| |
| # The descriptor to use for accessing the attribute off of the class. |
| descriptor_class = FileDescriptor |
| |
| description = ugettext_lazy("File path") |
| |
| def __init__(self, verbose_name=None, name=None, upload_to='', storage=None, **kwargs): |
| for arg in ('primary_key', 'unique'): |
| if arg in kwargs: |
| raise TypeError("'%s' is not a valid argument for %s." % (arg, self.__class__)) |
| |
| self.storage = storage or default_storage |
| self.upload_to = upload_to |
| if callable(upload_to): |
| self.generate_filename = upload_to |
| |
| kwargs['max_length'] = kwargs.get('max_length', 100) |
| super(FileField, self).__init__(verbose_name, name, **kwargs) |
| |
| def get_internal_type(self): |
| return "FileField" |
| |
| def get_prep_lookup(self, lookup_type, value): |
| if hasattr(value, 'name'): |
| value = value.name |
| return super(FileField, self).get_prep_lookup(lookup_type, value) |
| |
| def get_prep_value(self, value): |
| "Returns field's value prepared for saving into a database." |
| # Need to convert File objects provided via a form to unicode for database insertion |
| if value is None: |
| return None |
| return unicode(value) |
| |
| def pre_save(self, model_instance, add): |
| "Returns field's value just before saving." |
| file = super(FileField, self).pre_save(model_instance, add) |
| if file and not file._committed: |
| # Commit the file to storage prior to saving the model |
| file.save(file.name, file, save=False) |
| return file |
| |
| def contribute_to_class(self, cls, name): |
| super(FileField, self).contribute_to_class(cls, name) |
| setattr(cls, self.name, self.descriptor_class(self)) |
| signals.post_delete.connect(self.delete_file, sender=cls) |
| |
| def delete_file(self, instance, sender, **kwargs): |
| file = getattr(instance, self.attname) |
| # If no other object of this type references the file, |
| # and it's not the default value for future objects, |
| # delete it from the backend. |
| if file and file.name != self.default and \ |
| not sender._default_manager.filter(**{self.name: file.name}): |
| file.delete(save=False) |
| elif file: |
| # Otherwise, just close the file, so it doesn't tie up resources. |
| file.close() |
| |
| def get_directory_name(self): |
| return os.path.normpath(force_unicode(datetime.datetime.now().strftime(smart_str(self.upload_to)))) |
| |
| def get_filename(self, filename): |
| return os.path.normpath(self.storage.get_valid_name(os.path.basename(filename))) |
| |
| def generate_filename(self, instance, filename): |
| return os.path.join(self.get_directory_name(), self.get_filename(filename)) |
| |
| def save_form_data(self, instance, data): |
| # Important: None means "no change", other false value means "clear" |
| # This subtle distinction (rather than a more explicit marker) is |
| # needed because we need to consume values that are also sane for a |
| # regular (non Model-) Form to find in its cleaned_data dictionary. |
| if data is not None: |
| # This value will be converted to unicode and stored in the |
| # database, so leaving False as-is is not acceptable. |
| if not data: |
| data = '' |
| setattr(instance, self.name, data) |
| |
| def formfield(self, **kwargs): |
| defaults = {'form_class': forms.FileField, 'max_length': self.max_length} |
| # If a file has been provided previously, then the form doesn't require |
| # that a new file is provided this time. |
| # The code to mark the form field as not required is used by |
| # form_for_instance, but can probably be removed once form_for_instance |
| # is gone. ModelForm uses a different method to check for an existing file. |
| if 'initial' in kwargs: |
| defaults['required'] = False |
| defaults.update(kwargs) |
| return super(FileField, self).formfield(**defaults) |
| |
| class ImageFileDescriptor(FileDescriptor): |
| """ |
| Just like the FileDescriptor, but for ImageFields. The only difference is |
| assigning the width/height to the width_field/height_field, if appropriate. |
| """ |
| def __set__(self, instance, value): |
| previous_file = instance.__dict__.get(self.field.name) |
| super(ImageFileDescriptor, self).__set__(instance, value) |
| |
| # To prevent recalculating image dimensions when we are instantiating |
| # an object from the database (bug #11084), only update dimensions if |
| # the field had a value before this assignment. Since the default |
| # value for FileField subclasses is an instance of field.attr_class, |
| # previous_file will only be None when we are called from |
| # Model.__init__(). The ImageField.update_dimension_fields method |
| # hooked up to the post_init signal handles the Model.__init__() cases. |
| # Assignment happening outside of Model.__init__() will trigger the |
| # update right here. |
| if previous_file is not None: |
| self.field.update_dimension_fields(instance, force=True) |
| |
| class ImageFieldFile(ImageFile, FieldFile): |
| def delete(self, save=True): |
| # Clear the image dimensions cache |
| if hasattr(self, '_dimensions_cache'): |
| del self._dimensions_cache |
| super(ImageFieldFile, self).delete(save) |
| |
| class ImageField(FileField): |
| attr_class = ImageFieldFile |
| descriptor_class = ImageFileDescriptor |
| description = ugettext_lazy("File path") |
| |
| def __init__(self, verbose_name=None, name=None, width_field=None, height_field=None, **kwargs): |
| self.width_field, self.height_field = width_field, height_field |
| FileField.__init__(self, verbose_name, name, **kwargs) |
| |
| def contribute_to_class(self, cls, name): |
| super(ImageField, self).contribute_to_class(cls, name) |
| # Attach update_dimension_fields so that dimension fields declared |
| # after their corresponding image field don't stay cleared by |
| # Model.__init__, see bug #11196. |
| signals.post_init.connect(self.update_dimension_fields, sender=cls) |
| |
| def update_dimension_fields(self, instance, force=False, *args, **kwargs): |
| """ |
| Updates field's width and height fields, if defined. |
| |
| This method is hooked up to model's post_init signal to update |
| dimensions after instantiating a model instance. However, dimensions |
| won't be updated if the dimensions fields are already populated. This |
| avoids unnecessary recalculation when loading an object from the |
| database. |
| |
| Dimensions can be forced to update with force=True, which is how |
| ImageFileDescriptor.__set__ calls this method. |
| """ |
| # Nothing to update if the field doesn't have have dimension fields. |
| has_dimension_fields = self.width_field or self.height_field |
| if not has_dimension_fields: |
| return |
| |
| # getattr will call the ImageFileDescriptor's __get__ method, which |
| # coerces the assigned value into an instance of self.attr_class |
| # (ImageFieldFile in this case). |
| file = getattr(instance, self.attname) |
| |
| # Nothing to update if we have no file and not being forced to update. |
| if not file and not force: |
| return |
| |
| dimension_fields_filled = not( |
| (self.width_field and not getattr(instance, self.width_field)) |
| or (self.height_field and not getattr(instance, self.height_field)) |
| ) |
| # When both dimension fields have values, we are most likely loading |
| # data from the database or updating an image field that already had |
| # an image stored. In the first case, we don't want to update the |
| # dimension fields because we are already getting their values from the |
| # database. In the second case, we do want to update the dimensions |
| # fields and will skip this return because force will be True since we |
| # were called from ImageFileDescriptor.__set__. |
| if dimension_fields_filled and not force: |
| return |
| |
| # file should be an instance of ImageFieldFile or should be None. |
| if file: |
| width = file.width |
| height = file.height |
| else: |
| # No file, so clear dimensions fields. |
| width = None |
| height = None |
| |
| # Update the width and height fields. |
| if self.width_field: |
| setattr(instance, self.width_field, width) |
| if self.height_field: |
| setattr(instance, self.height_field, height) |
| |
| def formfield(self, **kwargs): |
| defaults = {'form_class': forms.ImageField} |
| defaults.update(kwargs) |
| return super(ImageField, self).formfield(**defaults) |
