This module gives access to the extended attributes present in some operating systems/filesystems. You can list attributes, get, set and remove them.
Example:
>>> import xattr
>>> xattr.listxattr("file.txt")
['user.mime_type']
>>> xattr.getxattr("file.txt", "user.mime_type")
'text/plain'
>>> xattr.setxattr("file.txt", "user.comment", "Simple text file")
>>> xattr.listxattr("file.txt")
['user.mime_type', 'user.comment']
>>> xattr.removexattr ("file.txt", "user.comment")
Note
Most or all errors reported by the system while using the xattr library will be reported by raising a EnvironmentError; under Linux, the following errno values are used:
Note
Under Python 3, the namespace argument is a byte string, not a unicode string.
Used as flags value, the target attribute will be created, giving an error if it already exists.
Used as flags value, the target attribute will be replaced, giving an error if it doesn’t exist.
The security namespace, used by kernel security modules.
The system namespace, used by the kernel to store things such as ACLs and capabilities.
The trusted namespace, visible and accessibly only to trusted processes, used to implement mechanisms in user space.
The user namespace; this is the namespace accessible to non-privileged processes.
Return the list of attribute names for a file.
Example:
>>> xattr.list('/path/to/file')
['user.test', 'user.comment', 'system.posix_acl_access']
>>> xattr.list('/path/to/file', namespace=xattr.NS_USER)
['test', 'comment']
Parameters: |
|
---|---|
Returns: | the list of attributes; note that if a namespace argument was passed, it (and the separator) will be stripped from the names returned |
Return type: | list |
Raises EnvironmentError: | |
caused by any system errors |
New in version 0.4.
Changed in version 0.5.1: The namespace argument, if passed, cannot be None anymore; to explicitly specify an empty namespace, pass an empty string (byte string under Python 3).
Get the value of a given extended attribute.
>>> xattr.get('/path/to/file', 'user.comment')
'test'
>>> xattr.get('/path/to/file', 'comment', namespace=xattr.NS_USER)
'test'
Parameters: |
|
---|---|
Returns: | the value of the extended attribute (can contain NULLs) |
Return type: | string |
Raises EnvironmentError: | |
caused by any system errors |
New in version 0.4.
Changed in version 0.5.1: The namespace argument, if passed, cannot be None anymore; to explicitly specify an empty namespace, pass an empty string (byte string under Python 3).
Get all the extended attributes of an item.
This function performs a bulk-get of all extended attribute names and the corresponding value. Example:
>>> xattr.get_all('/path/to/file')
[('user.mime-type', 'plain/text'), ('user.comment', 'test'),
('system.posix_acl_access', '\x02\x00...')]
>>> xattr.get_all('/path/to/file', namespace=xattr.NS_USER)
[('mime-type', 'plain/text'), ('comment', 'test')]
Parameters: |
|
---|---|
Returns: | list of tuples (name, value); note that if a namespace argument was passed, it (and the separator) will be stripped from the names returned |
Return type: | list |
Raises EnvironmentError: | |
caused by any system errors |
Note
Since reading the whole attribute list is not an atomic operation, it might be possible that attributes are added or removed between the initial query and the actual reading of the attributes; the returned list will contain only the attributes that were present at the initial listing of the attribute names and that were still present when the read attempt for the value is made.
New in version 0.4.
Changed in version 0.5.1: The namespace argument, if passed, cannot be None anymore; to explicitly specify an empty namespace, pass an empty string (byte string under Python 3).
Set the value of a given extended attribute.
Example:
>>> xattr.set('/path/to/file', 'user.comment', 'test')
>>> xattr.set('/path/to/file', 'comment', 'test', namespace=xattr.NS_USER)
Parameters: |
|
---|---|
Returns: | None |
Raises EnvironmentError: | |
caused by any system errors |
New in version 0.4.
Changed in version 0.5.1: The namespace argument, if passed, cannot be None anymore; to explicitly specify an empty namespace, pass an empty string (byte string under Python 3).
Remove an attribute from a file.
Example:
>>> xattr.remove('/path/to/file', 'user.comment')
Parameters: |
|
---|---|
Returns: | None |
Raises EnvironmentError: | |
caused by any system errors |
New in version 0.4.
Changed in version 0.5.1: The namespace argument, if passed, cannot be None anymore; to explicitly specify an empty namespace, pass an empty string (byte string under Python 3).
Get the value of a given extended attribute (deprecated).
Parameters: |
|
---|
Deprecated since version 0.4: this function has been deprecated by the get() function.
Set the value of a given extended attribute (deprecated).
Be careful in case you want to set attributes on symbolic links, you have to use all the 5 parameters; use 0 for the flags value if you want the default behaviour (create or replace)
Parameters: |
|
---|
Deprecated since version 0.4: this function has been deprecated by the set() function.
Return the list of attribute names for a file (deprecated).
Parameters: |
|
---|
Deprecated since version 0.4: this function has been deprecated by the list() function.
Remove an attribute from a file (deprecated).
Parameters: |
|
---|
Deprecated since version 0.4: this function has been deprecated by the remove() function.