From bc768e2b471b707bfbb234c21066a4b0cbbe9258 Mon Sep 17 00:00:00 2001 From: Jacob Kaplan-Moss Date: Tue, 2 Sep 2008 17:33:51 +0000 Subject: A bunch of cleanups to file documentation. Along the way some references to the old file methods were removed - thanks, varikin. Fixes #8642. git-svn-id: http://code.djangoproject.com/svn/django/trunk@8862 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/files/file.txt | 139 ++++++++++++++++++++++++------------------------ 1 file changed, 70 insertions(+), 69 deletions(-) (limited to 'docs/ref/files') diff --git a/docs/ref/files/file.txt b/docs/ref/files/file.txt index aa037f7c2a..e864a7e004 100644 --- a/docs/ref/files/file.txt +++ b/docs/ref/files/file.txt @@ -12,109 +12,110 @@ The ``File`` object Django's ``File`` has the following attributes and methods: -``File.path`` -~~~~~~~~~~~~~ +.. attribute:: File.name -The absolute path to the file's location on a local filesystem. + The name of file including the relative path from :setting:`MEDIA_ROOT`. -:ref:`Custom file storage systems ` may not store -files locally; files stored on these systems will have a ``path`` of ``None``. +.. attribute:: File.path -``File.url`` -~~~~~~~~~~~~ + The absolute path to the file's location on a local filesystem. -The URL where the file can be retrieved. This is often useful in :ref:`templates -`; for example, a bit of a template for displaying a ``Car`` -(see above) might look like:: + :ref:`Custom file storage systems ` may not store + files locally; files stored on these systems will have a ``path`` of + ``None``. - {{ car.name }} +.. attribute:: File.url -``File.size`` -~~~~~~~~~~~~~ + The URL where the file can be retrieved. This is often useful in + :ref:`templates `; for example, a bit of a template for + displaying a ``Car`` (see above) might look like: + + .. code-block:: html+django -The size of the file in bytes. + {{ car.name }} -``File.open(mode=None)`` -~~~~~~~~~~~~~~~~~~~~~~~~ +.. attribute:: File.size -Open or reopen the file (which by definition also does ``File.seek(0)``). The -``mode`` argument allows the same values as Python's standard ``open()``. + The size of the file in bytes. -When reopening a file, ``mode`` will override whatever mode the file was -originally opened with; ``None`` means to reopen with the original mode. +.. method:: File.open(mode=None) -``File.read(num_bytes=None)`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Open or reopen the file (which by definition also does ``File.seek(0)``). + The ``mode`` argument allows the same values as Python's standard + ``open()``. -Read content from the file. The optional ``size`` is the number of bytes to -read; if not specified, the file will be read to the end. + When reopening a file, ``mode`` will override whatever mode the file was + originally opened with; ``None`` means to reopen with the original mode. -``File.__iter__()`` -~~~~~~~~~~~~~~~~~~~ +.. method:: File.read(num_bytes=None) -Iterate over the file yielding one line at a time. + Read content from the file. The optional ``size`` is the number of bytes to + read; if not specified, the file will be read to the end. -``File.chunks(chunk_size=None)`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: File.__iter__() -Iterate over the file yielding "chunks" of a given size. ``chunk_size`` defaults -to 64 KB. + Iterate over the file yielding one line at a time. -This is especially useful with very large files since it allows them to be -streamed off disk and avoids storing the whole file in memory. +.. method:: File.chunks(chunk_size=None) -``File.multiple_chunks(chunk_size=None)`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Iterate over the file yielding "chunks" of a given size. ``chunk_size`` + defaults to 64 KB. -Returns ``True`` if the file is large enough to require multiple chunks to -access all of its content give some ``chunk_size``. + This is especially useful with very large files since it allows them to be + streamed off disk and avoids storing the whole file in memory. -``File.write(content)`` -~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: File.multiple_chunks(chunk_size=None) -Writes the specified content string to the file. Depending on the storage system -behind the scenes, this content might not be fully committed until ``close()`` -is called on the file. + Returns ``True`` if the file is large enough to require multiple chunks to + access all of its content give some ``chunk_size``. -``File.close()`` -~~~~~~~~~~~~~~~~ +.. method:: File.write(content) -Close the file. + Writes the specified content string to the file. Depending on the storage + system behind the scenes, this content might not be fully committed until + ``close()`` is called on the file. + +.. method:: File.close() + + Close the file. Additional ``ImageField`` attributes ------------------------------------ -``File.width`` and ``File.height`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. attribute:: File.width + + Width of the image. + +.. attribute:: File.height -These attributes provide the dimensions of the image. + Heigght of the image. Additional methods on files attached to objects ----------------------------------------------- -Any ``File`` that's associated with an object (as with ``Car.photo``, above) -will also have a couple of extra methods: - -``File.save(name, content, save=True)`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Saves a new file with the file name and contents provided. This will not replace -the existing file, but will create a new file and update the object to point to -it. If ``save`` is ``True``, the model's ``save()`` method will be called once -the file is saved. That is, these two lines:: - - >>> car.photo.save('myphoto.jpg', contents, save=False) - >>> car.save() +.. highlight:: pycon -are the same as this one line:: +Any :class:`File` that's associated with an object (as with ``Car.photo``, +above) will also have a couple of extra methods: - >>> car.photo.save('myphoto.jpg', contents, save=True) +.. method:: File.save(name, content, save=True) -Note that the ``content`` argument must be an instance of -:class:`File` or of a subclass of :class:`File`. + Saves a new file with the file name and contents provided. This will not + replace the existing file, but will create a new file and update the object + to point to it. If ``save`` is ``True``, the model's ``save()`` method will + be called once the file is saved. That is, these two lines:: + + >>> car.photo.save('myphoto.jpg', contents, save=False) + >>> car.save() + + are the same as this one line:: + + >>> car.photo.save('myphoto.jpg', contents, save=True) + + Note that the ``content`` argument must be an instance of + :class:`File` or of a subclass of :class:`File`. -``File.delete(save=True)`` -~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: File.delete(save=True) -Remove the file from the model instance and delete the underlying file. The -``save`` argument works as above. + Remove the file from the model instance and delete the underlying file. The + ``save`` argument works as above. -- cgit v1.3