Riffle

Filesystem browser for PySide.

Installation

Installing Riffle is simple with pip:

$ pip install riffle

If the Cheeseshop (a.k.a. PyPI) is down, you can also install Riffle from one of the mirrors:

$ pip install --use-mirrors riffle

Alternatively, you may wish to download manually from Gitlab where Riffle is actively developed.

You can clone the public repository:

$ git clone git@gitlab.com:4degrees/riffle.git

Or download an appropriate zipball

Once you have a copy of the source, you can install it into your site-packages:

$ python setup.py install

Dependencies

Additional For testing

Usage

To use the browser, first create an instance of it and configure the size as desired:

import riffle.browser

browser = riffle.browser.FilesystemBrowser()
browser.setMinimumSize(800, 400)

Then open it in blocking mode and retrieve any selected files chosen by the user:

if browser.exec_():
    selected = browser.selected()
    print('Selected: {0}'.format(selected))
_images/browser.png 
Selected: [u'C:\\Users\\Martin\\data\\scratch\\ftrack_test.mov']

The browser can also identify sequences of files (using Clique). They will be displayed as a special collection item and can be navigated into like a directory to see and select individual files.

_images/browser_sequence.png _images/browser_sequence_item.png

Each browser instance can be configured with a root path. The browser will not be able to navigate above this root path:

browser = riffle.browser.FilesystemBrowser('C:\\Users')
browser.show()
_images/browser_root.png

In addition to a root, a browser also has a location that can be set to change the currently displayed location:

browser.setLocation('C:\\Users\\Martin')
_images/browser_location.png

Note

It is not possible to set a location that is outside the root path tree. An error is raised if attempted.

Icons

Icons displayed for entries in the browser are provided by an IconFactory. You can pass in your own icon factory to the browser to customise the icons used:

class AllFilesIconFactory(object):
    '''Force all icons to be file icons.'''

    def icon(self, specification):
        '''Return appropriate icon for *specification*.

        *specification* should be either:

            * An instance of :py:class:`riffle.model.Item`
            * One of the defined icon types (:py:class:`IconType`)

        '''
        return QtGui.QIcon(':riffle/icon/file')


browser = riffle.browser.FilesystemBrowser(
    iconFactory=AllFilesIconFactory()
)
_images/browser_custom_icons.png

API reference

riffle.browser

riffle.icon_factory

riffle.model

Release and migration notes

Find out what has changed between versions and see important migration notes to be aware of when switching to a new version.

Release Notes

1.0.0

13 October 2020
  • new

    API

    Update code to Python3.X, drop support for Python2.X

  • new

    interface

    Update code to PySide2, drop support for Pyside.

0.3.0

19 July 2016
  • new

    interfaceBackspace key now navigates up a level in the browser.

0.2.1

19 July 2016
  • fixed

    documentationDocumentation fails to build on Read the Docs due to PySide dependency.

0.2.0

18 July 2016
  • fixed

    interfaceEmpty contents displayed when an error occurs navigating to a location interactively. Now a warning dialog is displayed and the navigation aborted.

    See also

    riffle.browser.FilesystemBrowser.setLocation().

  • fixed

    APIriffle.model.FilesystemSortProxy swallowed exceptions incorrectly when fetching additional items from the source model.

  • fixed

    testInteractive test hangs on exit due to second execution loop started.

  • changed

    testInteractive test now sizes test browser to half of current screen dimensions on startup.

  • new

    Added Release and migration notes to documentation.

0.1.0

26 June 2014
  • new

    Initial release supporting navigation of standard filesystems. Also provides support for viewing and navigating file sequences.

Migration notes

This section will show more detailed information when relevant for switching to a new version, such as when upgrading involves backwards incompatibilities.

Glossary

Indices and tables