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'

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.