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 ~fs.base.FS.getinfo
, or by calling ~fs.base.FS.scandir
which returns an iterator of resource information for the contents of a directory. Additionally, ~fs.base.FS.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
PyFilesystem exposes the resource information via properties of ~fs.info.Info
objects.
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 ~fs.base.FS.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.
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 ~fs.osfs.OSFS
the namespace can be retrieved without a potentially expensive system call.
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 |
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 ~fs.ResourceType.unknown
if the filesystem is unable to retrieve the resource type.
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 |
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 ~fs.osfs.OSFS
. Some values may be None
if they aren't supported by the filesystem.
The stat
namespace contains information reported by a call to os.stat. This namespace is supported by ~fs.osfs.OSFS
and potentially other filesystems which map directly to the OS filesystem. Most other filesystems will not support this namespace.
The lstat
namespace contains information reported by a call to os.lstat. This namespace is supported by ~fs.osfs.OSFS
and potentially other filesystems which map directly to the OS filesystem. Most other filesystems will not support this namespace.
The link
namespace contains information about a symlink.
Name | type | Description |
---|---|---|
target |
str |
A path to the symlink target, or |
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 ~fs.info.Info.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.
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 ~fs.errors.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 ~fs.info.Info.has_namespace
method. Here's an example:
if info.has_namespace('access'):
print('user is {}'.format(info.user))
See ~fs.info.Info
for details regarding info attributes.
The ~fs.info.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 ~fs.permissions.Permissions
objects.