Ticket #12229: 12229_filefield_docs_patch.diff

File 12229_filefield_docs_patch.diff, 3.9 KB (added by gabrielhurley, 5 years ago)

Updated patch for FileField/ImageField docs that include FieldFile information

  • docs/ref/models/fields.txt

     
    572572
    573573.. _`strftime formatting`: http://docs.python.org/library/time.html#time.strftime
    574574
     575FileField and FieldFile
     576~~~~~~~~~~~~~~~~~~~~~~~
     577
     578Internally, :class:`FileField` instances use a utility class called
     579:class:`FieldFile` to handle the connection between the underlying file and
     580the field instance's attributes. In general you won't need to work with the
     581:class:`FieldFile` class directly, however several convenience methods on
     582:class:`FieldFile` are exposed for general usage when you use a
     583:class:`FileField` on your model:
     584
     585.. method:: FieldFile.open(mode='rb')
     586
     587Behaves like the standard Python ``open()`` method and opens the file
     588associated with this instance in the mode specified by ``mode``.
     589
     590.. method:: FieldFile.close()
     591
     592Behaves like the standard Python ``file.close()`` method and closes the file
     593associated with this instance.
     594
     595.. method:: FieldFile.save(name, content, save=True)
     596
     597This method takes a filename and file contents and passes them to the storage
     598class for this instance, then associates the stored file with this
     599instance. If you want to manually associate files with :class:`FileField`
     600instances on your model, this is the method to use.
     601
     602Takes two required arguments: ``name`` which is the name of the file, and
     603``content`` which is a file-like object containing the file's contents. The
     604optional ``save`` argument controls whether or not the instance is saved after
     605the file has been altered. Defaults to ``True``.
     606
     607.. method:: FieldFile.delete(save=True)
     608
     609Deletes the file associated with this instance and clears all attributes on
     610the field. Note: This method will close the file if it happens to be open when
     611``delete()`` is called.
     612
     613The optional ``save`` argument controls whether or not the instance is saved
     614after the file has been deleted. Defaults to ``True``.
     615
    575616``FilePathField``
    576617-----------------
    577618
     
    632673
    633674.. class:: ImageField(upload_to=None, [height_field=None, width_field=None, max_length=100, **options])
    634675
    635 Like :class:`FileField`, but validates that the uploaded object is a valid
    636 image. Has two extra optional arguments:
     676Inherits all attributes and methods from :class:`FileField`, but validates
     677that the uploaded object is a valid image.
    637678
     679In addition to the special attributes that are available for :class:`FileField`,
     680an :class:`ImageField` also has :attr:`~django.core.files.File.height` and
     681:attr:`~django.core.files.File.width` attributes.
     682
     683To facilitate querying on those attributes, :class:`ImageField` has two extra
     684optional arguments:
     685
    638686.. attribute:: ImageField.height_field
    639687
    640688    Name of a model field which will be auto-populated with the height of the
     
    645693    Name of a model field which will be auto-populated with the width of the
    646694    image each time the model instance is saved.
    647695
    648 In addition to the special attributes that are available for :class:`FileField`,
    649 an :class:`ImageField` also has :attr:`~django.core.files.File.height` and
    650 :attr:`~django.core.files.File.width` attributes.
    651 
    652696Requires the `Python Imaging Library`_.
    653697
    654698.. _Python Imaging Library: http://www.pythonware.com/products/pil/
     
    656700.. versionadded:: 1.0
    657701   The ``max_length`` argument was added in this version.
    658702
    659 By default, :class:`ImageField` instances are
    660 created as ``varchar(100)`` columns in your database. As with other fields, you
    661 can change the maximum length using the :attr:`~CharField.max_length` argument.
     703By default, :class:`ImageField` instances are created as ``varchar(100)``
     704columns in your database. As with other fields, you can change the maximum
     705length using the :attr:`~CharField.max_length` argument.
    662706
    663707``IntegerField``
    664708----------------
Back to Top