FileObject — Django FileBrowser 3.13.2 documentation

# FileObject

class `FileObject`(path, site=None)

  An object representing a media file.

  Parameters

    - path – Relative path to a location within site.storage.location.

    - site – An optional FileBrowser Site.

For example:

    from filebrowser.sites import site
    from filebrowser.base import FileObject
    fileobject = FileObject(os.path.join(site.directory,"testfolder","testimage.jpg"))
    version = FileObject(os.path.join(fileobject.versions_basedir, "testfolder", "testimage_medium.jpg"))

## Attributes

### Initial Attributes

`path`

  Path relative to a storage location (including `site.directory`):

      >>> fileobject.path
      'uploads/testfolder/testimage.jpg'

`head`

  The directory name of pathname `path`:

      >>> fileobject.head
      'uploads/testfolder'

`filename`

  Name of the file (including the extension) or name of the folder:

      >>> fileobject.filename
      'testimage.jpg'

`filename_lower`

  Lower type of `filename`.

`filename_root`

  Filename without extension:

      >>> fileobject.filename_root
      'testimage'

`extension`

  File extension, including the dot. With a folder, the extensions is `None`:

      >>> fileobject.extension
      '.jpg'

`mimetype`

  Mimetype, based on http://docs.python.org/library/mimetypes.html:

      >>> fileobject.mimetype
      ('image/jpeg', None)

### General Attributes

`filetype`

  Type of the file, as defined with `EXTENSIONS`:

      >>> fileobject.filetype
      'Image'

`format`

  Type of the file, as defined with `SELECT_FORMATS`:

      >>> fileobject.format
      'file'

`filesize`

  Filesize in Bytes:

      >>> fileobject.filesize
      870037L

`date`

  Date, based on `time.mktime`:

      >>> fileobject.date
      1299760347.0

`datetime`

  Datetime object:

      >>> fileobject.datetime
      datetime.datetime(2011, 3, 10, 13, 32, 27)

`exists`

  `True`, if the path exists, `False` otherwise:

      >>> fileobject.exists
      True

### Path and URL attributes

`path`

  Path relative to a storage location (including `site.directory`):

      >>> fileobject.path
      'uploads/testfolder/testimage.jpg'

`path_relative_directory`

  Path relative to `site.directory`:

      >>> fileobject.path_relative_directory
      'testfolder/testimage.jpg'

`path_full`

  Absolute server path (based on `storage.path`):

      >>> fileobject.path_full
      '/absolute/path/to/server/location/testfolder/testimage.jpg'

`dirname`

  New in version 3.4.

  The directory (not including `site.directory`):

      >>> fileobject.dirname
      'testfolder'

`url`

  URL for the file/folder (based on `storage.url`):

      >>> fileobject.url
      '/media/uploads/testfolder/testimage.jpg'

### Image attributes

The image attributes are only useful if the `FileObject` represents an image.

`dimensions`

  Image dimensions as a tuple:

      >>> fileobject.dimensions
      (1000, 750)

`width`

  Image width in px:

      >>> fileobject.width
      1000

`height`

  Image height in px:

      >>> fileobject.height
      750

`aspectratio`

  Aspect ratio (float format):

      >>> fileobject.aspectratio
      1.33534908

`orientation`

  Image orientation, either `Landscape` or `Portrait`:

      >>> fileobject.orientation
      'Landscape'

### Folder attributes

The folder attributes make sense when the `FileObject` represents a directory (not a file).

`is_folder`

  `True`, if path is a folder:

      >>> fileobject.is_folder
      False

`is_empty`

  `True`, if the folder is empty. `False` if the folder is not empty or the `FileObject` is not a folder:

      >>> fileobject.is_empty
      False

### Version attributes

`is_version`

  `true` if the File is a `version` of another File:

      >>> fileobject.is_version
      False
      >>> version.is_version
      True

`versions_basedir`

  The relative path (from storage location) to the main versions folder. Either `VERSIONS_BASEDIR` or `site.directory`:

      >>> fileobject.versions_basedir
      '_versions'
      >>> version.versions_basedir
      '_versions'

`original`

  Returns the original FileObject:

      >>> fileobject.original
      <FileObject: uploads/testfolder/testimage.jpg>
      >>> version.original
      <FileObject: uploads/testfolder/testimage.jpg>

`original_filename`

  Get the filename of an original image from a version:

      >>> fileobject.original_filename
      'testimage.jpg'
      >>> version.original_filename
      'testimage.jpg'

## Methods

### Version methods

`versions`()

  List all filenames based on `VERSIONS`:

      >>> fileobject.versions()
      ['_versions/testfolder/testimage_admin_thumbnail.jpg',
      '_versions/testfolder/testimage_thumbnail.jpg',
      '_versions/testfolder/testimage_small.jpg',
      '_versions/testfolder/testimage_medium.jpg',
      '_versions/testfolder/testimage_big.jpg',
      '_versions/testfolder/testimage_large.jpg']
      >>> version.versions()
      []

  Note

  The versions are not being generated.

`admin_versions`()

  List all filenames based on `ADMIN_VERSIONS`:

      >>> fileobject.admin_versions()
      ['_versions/testfolder/testimage_thumbnail.jpg',
      '_versions/testfolder/testimage_small.jpg',
      '_versions/testfolder/testimage_medium.jpg',
      '_versions/testfolder/testimage_big.jpg',
      '_versions/testfolder/testimage_large.jpg']
      >>> version.admin_versions()
      []

  Note

  The versions are not being generated.

`version_name`(version_suffix, extra_options=None)
  Parameters

    - version_suffix – A suffix to compose the version name accordingly to the VERSION_NAMER in use.

    - extra_options – An optional `dict` to be used in the version generation.

  Get the filename for a version:

      >>> fileobject.version_name("medium")
      'testimage_medium.jpg'

  Note

  The version is not being generated.

  See also

  Files names can be customized using VERSION_NAMER.

`version_path`(version_suffix, extra_options=None)
  Parameters

    - version_suffix – A suffix to compose the version name accordingly to the VERSION_NAMER in use.

    - extra_options – An optional `dict` to be used in the version generation.

  Get the path for a version:

      >>> fileobject.version_path("medium")
      '_versions/testfolder/testimage_medium.jpg'

  Note

  The version is not being generated.

`version_generate`(version_suffix, extra_options=None)
  Parameters

    - version_suffix – A suffix to compose the version name accordingly to the VERSION_NAMER in use.

    - extra_options – An optional `dict` to be used in the version generation.

  An image version is generated by passing the source image through a series of image processors. Each processor may alter the image, often dependent on the options it receives.

  The options used in the processors chain is composed of the version definition, if `version_suffix` is a key in VERSIONS, plus any `extra_options` provided. If no version definition was found and no extra options are provided, an empty dict will be used. A key in `extra_options` will take precedence over the version definition.

  Generate a version:

      >>> fileobject.version_generate("medium")
      <FileObject: uploads/testfolder/testimage_medium.jpg>

  Please note that a version is only generated, if it does not already exist or if the original image is newer than the existing version.

### Delete methods

`delete`()

  Delete the `File` or `Folder` from the server.

  Warning

  If you delete a Folder, all items within the folder are being deleted.

`delete_versions`()

  Delete all `VERSIONS`.

`delete_admin_versions`()

  Delete all `ADMIN_VERSIONS`.