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.settext('example.txt', 'Hello, World!')
>>> info = fs.getinfo('example.txt', namespaces=['details'])
>>> info.name
'example.txt'
>>> info.is_dir
False
>>> info.size
13
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 as positional
arguments to getinfo()
. For example, the following
retrieves the details
and access
namespaces for a file:
resource_info = fs.getinfo('myfile.txt', '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 the 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.
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.
注解
It is not an error to request a namespace (or namespaces) that the filesystem does not support. Any unknown namespaces will be ignored.
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.
注解
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 class:fs.permissions.Permissions` objects.