:tocdepth: 3

.. |grappelli| replace:: Grappelli
.. |filebrowser| replace:: FileBrowser

.. _fileobject:

FileObject
----------

.. py:class:: FileObject(path)
    
    An object representing a media file.

    :param path: Relative path to a location within `site.storage.location`.

For example::

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

Attributes
^^^^^^^^^^

General Attributes
++++++++++++++++++

.. attribute:: filename

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

        >>> fileobject.filename
        'testimage.jpg'

.. attribute:: filetype

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

        >>> fileobject.filetype
        'Image'

.. attribute:: mimetype

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

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

.. attribute:: filesize

    Filesize in Bytes::

        >>> fileobject.filesize
        870037L

.. attribute:: extension

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

        >>> fileobject.extension
        '.jpg'

.. attribute:: date

    Date, based on ``time.mktime``::

        >>> fileobject.date
        1299760347.0

.. attribute:: datetime

    Datetime object::

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

.. attribute:: exists

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

        >>> fileobject.exists
        True

Path and URL attributes
+++++++++++++++++++++++

.. attribute:: path

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

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

.. attribute:: path_relative_directory

    Path relative to ``site.directory``::

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

.. attribute:: path_full

    Absolute server path (equals ``storage.path``)::

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

.. attribute:: dirname

    .. versionadded:: 3.4

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

        >>> fileobject.dirname
        u'testfolder'

.. attribute:: url

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

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

Image attributes
++++++++++++++++

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

.. attribute:: dimensions

    Image dimensions as a tuple::

        >>> fileobject.dimensions
        (1000, 750)

.. attribute:: width

    Image width in px::

        >>> fileobject.width
        1000

.. attribute:: height

    Image height in px::

        >>> fileobject.height
        750

.. attribute:: aspectratio

    Aspect ratio (float format)::

        >>> fileobject.aspectratio
        1.33534908

.. attribute:: 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).

.. attribute:: directory

    Folder(s) relative from ``site.directory``::

        >>> fileobject.directory
        u'testfolder'

.. attribute:: folder

    Parent folder(s)::

        >>> fileobject.folder
        u'testfolder'

.. attribute:: is_folder

    ``True``, if path is a folder::

        >>> fileobject.is_folder
        False

.. attribute:: is_empty

    ``True``, if the folder is empty::

        >>> fileobject.is_empty
        False

Version attributes
++++++++++++++++++

.. attribute:: is_version

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

        >>> fileobject.is_version
        False

.. attribute:: versions_basedir

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

        >>> fileobject.versions_basedir
        'uploads'

Methods
^^^^^^^

Version methods
+++++++++++++++

.. method:: versions_basedir

    List all filenames based on ``VERSIONS``::

        >>> fileobject.versions
        ['/var/www/testsite/media/uploads/testfolder/testimage_admin_thumbnail.jpg',
        '/var/www/testsite/media/uploads/testfolder/testimage_thumbnail.jpg',
        '/var/www/testsite/media/uploads/testfolder/testimage_small.jpg',
        '/var/www/testsite/media/uploads/testfolder/testimage_medium.jpg',
        '/var/www/testsite/media/uploads/testfolder/testimage_big.jpg',
        '/var/www/testsite/media/uploads/testfolder/testimage_large.jpg']

    .. note::
        The versions are not being generated.

.. method:: admin_versions

    List all filenames based on ``ADMIN_VERSIONS``::

        >>> fileobject.admin_versions
        ['/var/www/testsite/media/uploads/testfolder/testimage_thumbnail.jpg',
        '/var/www/testsite/media/uploads/testfolder/testimage_small.jpg',
        '/var/www/testsite/media/uploads/testfolder/testimage_medium.jpg',
        '/var/www/testsite/media/uploads/testfolder/testimage_big.jpg',
        '/var/www/testsite/media/uploads/testfolder/testimage_large.jpg']

    .. note::
        The versions are not being generated.

.. method:: version_name(version_suffix)

    Get the filename for a version::

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

    .. note::
        The version is not being generated.

.. method:: version_path(version_suffix)

    Get the path for a version::

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

    .. note::
        The version is not being generated.

.. method:: version_generate(version_suffix)

    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
++++++++++++++

.. method:: delete()

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

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

.. method:: delete_versions()

    Delete all ``VERSIONS``.

.. method:: delete_admin_versions()

    Delete all ``ADMIN_VERSIONS``.