PageRenderTime 42ms CodeModel.GetById 18ms RepoModel.GetById 0ms app.codeStats 0ms

/docs/topics/files.txt

https://code.google.com/p/mango-py/
Plain Text | 145 lines | 107 code | 38 blank | 0 comment | 0 complexity | 118e0ef3ff6cacbc7bf5116080e6d5f2 MD5 | raw file
Possible License(s): BSD-3-Clause
  1. ==============
  2. Managing files
  3. ==============
  4. This document describes Django's file access APIs.
  5. By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and
  6. :setting:`MEDIA_URL` settings. The examples below assume that you're using these
  7. defaults.
  8. However, Django provides ways to write custom `file storage systems`_ that
  9. allow you to completely customize where and how Django stores files. The
  10. second half of this document describes how these storage systems work.
  11. .. _file storage systems: `File storage`_
  12. Using files in models
  13. =====================
  14. When you use a :class:`~django.db.models.FileField` or
  15. :class:`~django.db.models.ImageField`, Django provides a set of APIs you can use
  16. to deal with that file.
  17. Consider the following model, using an :class:`~django.db.models.ImageField` to
  18. store a photo::
  19. class Car(models.Model):
  20. name = models.CharField(max_length=255)
  21. price = models.DecimalField(max_digits=5, decimal_places=2)
  22. photo = models.ImageField(upload_to='cars')
  23. Any ``Car`` instance will have a ``photo`` attribute that you can use to get at
  24. the details of the attached photo::
  25. >>> car = Car.objects.get(name="57 Chevy")
  26. >>> car.photo
  27. <ImageFieldFile: chevy.jpg>
  28. >>> car.photo.name
  29. u'cars/chevy.jpg'
  30. >>> car.photo.path
  31. u'/media/cars/chevy.jpg'
  32. >>> car.photo.url
  33. u'http://media.example.com/cars/chevy.jpg'
  34. This object -- ``car.photo`` in the example -- is a ``File`` object, which means
  35. it has all the methods and attributes described below.
  36. The ``File`` object
  37. ===================
  38. Internally, Django uses a :class:`django.core.files.File` instance any time it
  39. needs to represent a file. This object is a thin wrapper around Python's
  40. `built-in file object`_ with some Django-specific additions.
  41. .. _built-in file object: http://docs.python.org/library/stdtypes.html#bltin-file-objects
  42. Most of the time you'll simply use a ``File`` that Django's given you (i.e. a
  43. file attached to a model as above, or perhaps an uploaded file).
  44. If you need to construct a ``File`` yourself, the easiest way is to create one
  45. using a Python built-in ``file`` object::
  46. >>> from django.core.files import File
  47. # Create a Python file object using open()
  48. >>> f = open('/tmp/hello.world', 'w')
  49. >>> myfile = File(f)
  50. Now you can use any of the documented attributes and methods
  51. of the :class:`~django.core.files.File` class.
  52. File storage
  53. ============
  54. Behind the scenes, Django delegates decisions about how and where to store files
  55. to a file storage system. This is the object that actually understands things
  56. like file systems, opening and reading files, etc.
  57. Django's default file storage is given by the :setting:`DEFAULT_FILE_STORAGE`
  58. setting; if you don't explicitly provide a storage system, this is the one that
  59. will be used.
  60. See below for details of the built-in default file storage system, and see
  61. :doc:`/howto/custom-file-storage` for information on writing your own file
  62. storage system.
  63. Storage objects
  64. ---------------
  65. Though most of the time you'll want to use a ``File`` object (which delegates to
  66. the proper storage for that file), you can use file storage systems directly.
  67. You can create an instance of some custom file storage class, or -- often more
  68. useful -- you can use the global default storage system::
  69. >>> from django.core.files.storage import default_storage
  70. >>> from django.core.files.base import ContentFile
  71. >>> path = default_storage.save('/path/to/file', ContentFile('new content'))
  72. >>> path
  73. u'/path/to/file'
  74. >>> default_storage.size(path)
  75. 11
  76. >>> default_storage.open(path).read()
  77. 'new content'
  78. >>> default_storage.delete(path)
  79. >>> default_storage.exists(path)
  80. False
  81. See :doc:`/ref/files/storage` for the file storage API.
  82. The built-in filesystem storage class
  83. -------------------------------------
  84. Django ships with a built-in ``FileSystemStorage`` class (defined in
  85. ``django.core.files.storage``) which implements basic local filesystem file
  86. storage. Its initializer takes two arguments:
  87. ====================== ===================================================
  88. Argument Description
  89. ====================== ===================================================
  90. ``location`` Optional. Absolute path to the directory that will
  91. hold the files. If omitted, it will be set to the
  92. value of your :setting:`MEDIA_ROOT` setting.
  93. ``base_url`` Optional. URL that serves the files stored at this
  94. location. If omitted, it will default to the value
  95. of your :setting:`MEDIA_URL` setting.
  96. ====================== ===================================================
  97. For example, the following code will store uploaded files under
  98. ``/media/photos`` regardless of what your :setting:`MEDIA_ROOT` setting is::
  99. from django.db import models
  100. from django.core.files.storage import FileSystemStorage
  101. fs = FileSystemStorage(location='/media/photos')
  102. class Car(models.Model):
  103. ...
  104. photo = models.ImageField(storage=fs)
  105. :doc:`Custom storage systems </howto/custom-file-storage>` work the same way:
  106. you can pass them in as the ``storage`` argument to a
  107. :class:`~django.db.models.FileField`.