12.1 Usage

The programming interface of itools.vfs appears as a set of global functions. To be used this way:

    >>> from itools import vfs
    >>> import itools.http
    >>>
    >>> uri = 'http://example.com/'
    >>> if vfs.exists(uri):
    ...     file = vfs.open(uri)
    ...     print file.read()
    ...     file.close()

A resource is identified by a URI. That is what most functions in the programming interface expect as parameters: URIs; either as byte strings (like in the example above), or instances of the URI Reference class (see Chapter 11 for the details).

If the URI given is relative, it will be resolved relative to the current working directory.

12.1.1 Files

The function vfs.open, seen in the example above, returns an object that offers the same programming interface of Python files. Actually, for resources in the file system the object returned by vfs.open is a Python file.

We are not going to explain what this programming interface is, just check the Python’s documentation.

12.1.2 Folders

From the point of view of itools.vfs a folder is an object which offers exactly the same programming interface of itools.vfs, but which resolves relative URIs not to the current working directory, but to some URI.

For example:

    # Use the global API
    >>> for name in vfs.get_names('.'):
    ...     print name
    ... 
    README
    gettext
    stl

    # Use the folder's API
    >>> folder = vfs.open('.')
    >>> for name in folder.get_names():
    ...     print name
    ... 
    README
    gettext
    stl

As this example shows the folder’s method get_names not even requires to pass a URI. In this case the action affects the URI associated with the folder.