.. FsQuass documentation master file, created by
   sphinx-quickstart on Thu Sep 27 13:26:30 2012.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

FsQuass, filesystem query and traversing
========================================

.. _why:

Why another filesystem library?
-------------------------------

None of them lets you work with files and paths in an elegant way. By elegant I mean as `jQuery <http://jquery.com>`_ lets you work with DOM. A jQuery for filesystem is not a new idea, though: someone has written *fsquery* library for Node.js. There is a good `pyFileSystem <http://packages.python.org/fs/>`_ library that supports different file systems (like ssh, memory, ftp).

I rather needed a path traversing tool than filesystem.

Let's say, I want to find photos (``*.jp[e]g``) in my pictures folders for 2010 and 2011. The folders for those days end with ``'repairs'``.

.. code-block:: python

    from fsquass import Fs
    photos = Fs('/home/siberiano/Pictures/{2011,2010} *repairs *.jp?g:ignorecase')

Note how syntax is similar to what we're used to in file systems:

* spaces in path stand for descendant, like in CSS
* curly braces ``{x,y}`` mean different masks of a name
* stars and question marks work like in command line
* pseudo-classes (``:ignorecase``) work like in CSS

Now I can proceed, say, find the folders of these files:

.. code-block:: python

	photos.parents().find('*.txt')
	photos.filter('DCIM*')

As you can see, it's quite similar to jQuery. But unlike jQuery, Python's set classes support set operations:

.. code-block:: python

	photos.parents().children() - photos

Everything you can do with :py:class:`set`, you can do with :py:class:`.Fs` objects as well.

Installation
------------

Clone it and install with setuptools::

    hg clone https://bitbucket.org/siberiano/fsquass
    cd fsquass
    python setup.py install

.. _name:

What does the name mean?
------------------------

It's called so to give it a unique name and flavour. 'Quass' has common part with 'query', but means `kvass <http://en.wikipedia.org/wiki/Kvass>`_.

Contents
=========

.. toctree::
   :maxdepth: 2

   tour
   fsquass


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`