Resource Info¶

Resource information (or info) describes standard file details such as name, type, size, etc., and potentially other less-common information associated with a file or directory.

You can retrieve resource info for a single resource by calling getinfo(), or by calling scandir() which returns an iterator of resource information for the contents of a directory. Additionally, filterdir() can filter the resources in a directory by type and wildcard.

Here’s an example of retrieving file information:

>>> from fs.osfs import OSFS
>>> fs = OSFS('.')
>>> fs.writetext('example.txt', 'Hello, World!')
>>> info = fs.getinfo('example.txt', namespaces=['details'])
>>> info.name
'example.txt'
>>> info.is_dir
False
>>> info.size
13

Info Objects¶

PyFilesystem exposes the resource information via properties of Info objects.

Namespaces¶

All resource information is contained within one of a number of potential namespaces, which are logical key/value groups.

You can specify which namespace(s) you are interested in with the namespaces argument to getinfo(). For example, the following retrieves the details and access namespaces for a file:

resource_info = fs.getinfo('myfile.txt', namespaces=['details', 'access'])

In addition to the specified namespaces, the fileystem will also return the basic namespace, which contains the name of the resource, and a flag which indicates if the resource is a directory.

Basic Namespace¶

The basic namespace is always returned. It contains the following keys:

Name	Type	Description
name	str	Name of the resource.
is_dir	bool	A boolean that indicates if the resource is a directory.

The keys in this namespace can generally be retrieved very quickly. In the case of OSFS the namespace can be retrieved without a potentially expensive system call.

Details Namespace¶

The details namespace contains the following keys.

Name	type	Description
accessed	datetime	The time the file was last accessed.
created	datetime	The time the file was created.
metadata_changed	datetime	The time of the last metadata (e.g. owner, group) change.
modified	datetime	The time file data was last changed.
size	int	Number of bytes used to store the resource. In the case of files, this is the number of bytes in the file. For directories, the size is the overhead (in bytes) used to store the directory entry.
type	ResourceType	Resource type, one of the values defined in `ResourceType`.

The time values (accessed_time, created_time etc.) may be None if the filesystem doesn’t store that information. The size and type keys are guaranteed to be available, although type may be unknown if the filesystem is unable to retrieve the resource type.

Access Namespace¶

The access namespace reports permission and ownership information, and contains the following keys.

Name	type	Description
gid	int	The group ID.
group	str	The group name.
permissions	Permissions	An instance of `Permissions`, which contains the permissions for the resource.
uid	int	The user ID.
user	str	The user name of the owner.

This namespace is optional, as not all filesystems have a concept of ownership or permissions. It is supported by OSFS. Some values may be None if they aren’t supported by the filesystem.

Stat Namespace¶

The stat namespace contains information reported by a call to os.stat. This namespace is supported by OSFS and potentially other filesystems which map directly to the OS filesystem. Most other filesystems will not support this namespace.

LStat Namespace¶

The lstat namespace contains information reported by a call to os.lstat. This namespace is supported by OSFS and potentially other filesystems which map directly to the OS filesystem. Most other filesystems will not support this namespace.

Link Namespace¶

The link namespace contains information about a symlink.

Name	type	Description
target	str	A path to the symlink target, or `None` if this path is not a symlink. Note, the meaning of this target is somewhat filesystem dependent, and may not be a valid path on the FS object.

Other Namespaces¶

Some filesystems may support other namespaces not covered here. See the documentation for the specific filesystem for information on what namespaces are supported.

You can retrieve such implementation specific resource information with the get() method.

Note

It is not an error to request a namespace (or namespaces) that the filesystem does not support. Any unknown namespaces will be ignored.

Missing Namespaces¶

Some attributes on the Info objects require that a given namespace be present. If you attempt to reference them without the namespace being present (because you didn’t request it, or the filesystem doesn’t support it) then a MissingInfoNamespace exception will be thrown. Here’s how you might handle such exceptions:

try:
    print('user is {}'.format(info.user))
except errors.MissingInfoNamespace:
    # No 'access' namespace
    pass

If you prefer a look before you leap approach, you can use use the has_namespace() method. Here’s an example:

if info.has_namespace('access'):
    print('user is {}'.format(info.user))

See Info for details regarding info attributes.

Raw Info¶

The Info class is a wrapper around a simple data structure containing the raw info. You can access this raw info with the info.raw property.

Note

The following is probably only of interest if you intend to implement a filesystem yourself.

Raw info data consists of a dictionary that maps the namespace name on to a dictionary of information. Here’s an example:

{
    'access': {
        'group': 'staff',
        'permissions': ['g_r', 'o_r', 'u_r', 'u_w'],
        'user': 'will'
    },
    'basic': {
        'is_dir': False,
        'name': 'README.txt'
    },
    'details': {
        'accessed': 1474979730.0,
        'created': 1462266356.0,
        'metadata_changed': 1473071537.0,
        'modified': 1462266356.0,
        'size': 79,
        'type': 2
    }
}

Raw resource information contains basic types only (strings, numbers, lists, dict, None). This makes the resource information simple to send over a network as it can be trivially serialized as JSON or other data format.

Because of this requirement, times are stored as epoch times. The Info object will convert these to datetime objects from the standard library. Additionally, the Info object will convert permissions from a list of strings in to a Permissions objects.