fsquass Package

FsQuass is a filesystem query and traversing library, a pythonic jQuery for filesystem.

Still work in progress.

class fsquass.__init__.Fs(nodes=None)

Bases: set

Files set. Is a set of File and Dir instances with traversal methods. Besides the methods inherited from set, it has some methods and properties specific to file systems.

nodes can be a string or an iterable. of File and Dir instances.

If nodes is a string, it’s treated differently depending on what it starts with:

• /, files are matched from those in the root directory and further, without scanning the whole filesystem.
• ./, the next name will be searched inside the current directory, without recursive scanning.
• ~, home folder will be opened
• ~/, home folder will be opened, and it’s children will be matched, without recursive scanning.

A space is treated like in CSS, a recursive search for descendants. E.g.

Fs('/home/user tests/__init__.py')

will

• find /home/user,
• then recursively scan both for files and directories named tests,
• then will search for __init__.py inside those directories, but not deeper.

Note: Recursive scans can be expensive. If you

children(pattern=None)

Returns a set of children of all the set items filtered by pattern.

closest(pattern)

Finds the closest ancestors by pattern.

exclude(pattern)

Exclude items that match pattern.

filter(pattern)

Filters items_list by patten.

Filtering a set of paths is equal to an intersection of the set and of a set found by pattern:

dirs = Fs('/home/siberiano;/home;/tmp;/tmp/siberiano')
dirs.filter('siberiano') == dirs & Fs('/').find('. siberiano')

find(pattern)

Searches by pattern inside the set items. Returns a new Fs instance. E.g. if we have a set fs of these paths:

/home/user/
/root

fs.find('.bashrc') will probably output:

/home/user/.bashrc
/root/.bashrc

If you need to find multiple paths, separate them with semicolon:

Fs('/home/siberiano').find('.bashrc;Work/project/templates base.haml')

Will search for .bashrc file in my homefolder (but not deeper) and inside ~/Work/project/templates will recursively search for base.haml files.

To avoid accidental scanning of the entire filesystem, recursive search is made harder. Use dot and space in the beginning if you need it anyway:

# scan the entire filesystem for 'siberiano'
Fs('/').find('. siberiano')
# scans for files & directories named 'project' inside Work
Fs('/home/siberiano/Work').find('. project')

first()

Returns the first item from the set. A shortcut for iter(fs).next()

linkTo(target, multiple_targets=False, name_callback=None)

Makes a hard link to all the set members in target folder.

• target must be a set of 1 or more directories (Dir instances).
• if multiple_targets parameter is True, links will be made in all the target folders. If multiple_targets is False, then will link in the first target folder only.

Optional name_callback should work like this:

def name_callback(source, target):
        # source & target are Fs instances with 1 member each
        return source, target

parents()

Returns a set of parents of all the items, e.g. for

/home/user/.bashrc
/home/user/.hgrc
/tmp/test
/tmp

parents will be

/home/user
/tmp
/

paths

A generator of paths of all the items.

siblings(pattern=None)

Finds all the siblings of the files in set, filtered by pattern. The result will not include any files of the original set.

symlinkTo(target, multiple_targets=False, name_callback=None)

Makes a symbolic link in target folder like Fs.linkTo()

class fsquass.__init__.Dir(full_path)

Bases: fsquass.__init__.File

Directory. Returns its directories and files in children() method.

• Is iterable:

  for i in Dir('/home/siberiano'):
          print i
  

  will print files and directories in the folder.

  This allows using such tricks as using a Dir to get a Fs of it’s children:

  >>> d = Dir('/')
  >>> Fs(d) == d.children()
  True
  

• Can check if contains another File or Dir:

  >>> Dir('/home') in Dir('/')
  True
  >>> Dir('/tmp') in Dir('/home')
  False
  

children(pattern=None)

Lists the directory and returns Fs of the files, filtered by pattern.

delete(sure=False)

Deletes the directory with all files and directories in it if sure is True. If you managed to call it like this, don’t blame the library for any lost data.

open(*args, **kwargs)

Raises TypeError, since directories can’t be opened like files.

class fsquass.__init__.File(full_path)

Bases: object

A file or a directory. Contains self.path, and if an object with the same absolute path is instantiated, an existing item is returned. If full_path is unaccessible, EnvironmentError is raised.

basename

String basename of the file.

children(pattern=None)

Returns an Fs of child nodes. Makes sense in Dir only, but put here for compatibility.

delete(sure=False)

Deletes the file if sure is True. If you managed to call it like this, don’t blame the library for any lost data.

open(*args, **kwargs)

Wrapper to Python open().

parent

Returns an Fs with the parent directory.