Interface to extended filesystem attributes

This module gives access to the extended attributes present in some operating systems/filesystems. You can list attributes, get, set and remove them.

The module exposes two sets of functions:

• the ‘old’ listxattr(), getxattr(), setxattr(), removexattr() functions which are deprecated since version 0.4
• the new list(), get(), get_all(), set(), remove() functions which expose a namespace-aware API and simplify a bit the calling model by using keyword arguments

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:

• ENOATTR and ENODATA mean that the attribute name is invalid
• ENOTSUP and EOPNOTSUPP mean that the filesystem does not support extended attributes, or that the namespace is invalid
• E2BIG mean that the attribute value is too big
• ERANGE mean that the attribute name is too big (it might also mean an error in the xattr module itself)
• ENOSPC and EDQUOT are documented as meaning out of disk space or out of disk space because of quota limits

Note

Under Python 3, the namespace argument is a byte string, not a unicode string.

Constants

xattr.XATTR_CREATE

Used as flags value, the target attribute will be created, giving an error if it already exists.

xattr.XATTR_REPLACE

Used as flags value, the target attribute will be replaced, giving an error if it doesn’t exist.

xattr.NS_SECURITY

The security namespace, used by kernel security modules.

xattr.NS_SYSTEM

The system namespace, used by the kernel to store things such as ACLs and capabilities.

xattr.NS_TRUSTED

The trusted namespace, visible and accessibly only to trusted processes, used to implement mechanisms in user space.

xattr.NS_USER

The user namespace; this is the namespace accessible to non-privileged processes.

Functions

xattr.list(item[, nofollow=False, namespace=None])

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:

• item – a string representing a file-name, or a file-like object, or a file descriptor; this represents the file on which to act
• nofollow (boolean, optional) – if true and if the file name given is a symbolic link, the function will operate on the symbolic link itself instead of its target; defaults to false
• namespace (bytes) – if given, the attribute must not contain the namespace, but instead it will be taken from this parameter

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).

xattr.get(item, name[, nofollow=False, namespace=None])

Get the value of a given extended attribute.

Example:

>>> xattr.get('/path/to/file', 'user.comment')
'test'
>>> xattr.get('/path/to/file', 'comment', namespace=xattr.NS_USER)
'test'

Parameters:

• item – a string representing a file-name, or a file-like object, or a file descriptor; this represents the file on which to act
• name (string) – the attribute whose value to retrieve; usually in the form of system.posix_acl or user.mime_type
• nofollow (boolean, optional) – if true and if the file name given is a symbolic link, the function will operate on the symbolic link itself instead of its target; defaults to false
• namespace (bytes) – if given, the attribute must not contain the namespace, but instead it will be taken from this parameter

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).

xattr.get_all(item[, nofollow=False, namespace=None])

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:

• item – a string representing a file-name, or a file-like object, or a file descriptor; this represents the file on which to act
• namespace (string) – an optional namespace for filtering the attributes; for example, querying all user attributes can be accomplished by passing namespace=:const:NS_USER
• nofollow (boolean, optional) – if true and if the file name given is a symbolic link, the function will operate on the symbolic link itself instead of its target; defaults to false

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).

xattr.set(item, name, value[, flags=0, namespace=None])

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:

• item – a string representing a file-name, or a file-like object, or a file descriptor; this represents the file on which to act
• name (string) – the attribute whose value to set; usually in the form of system.posix_acl or user.mime_type
• value (string) – possibly with embedded NULLs; note that there are restrictions regarding the size of the value, for example, for ext2/ext3, maximum size is the block size
• flags (integer) – if 0 or omitted the attribute will be created or replaced; if XATTR_CREATE, the attribute will be created, giving an error if it already exists; if XATTR_REPLACE, the attribute will be replaced, giving an error if it doesn’t exist;
• nofollow (boolean, optional) – if true and if the file name given is a symbolic link, the function will operate on the symbolic link itself instead of its target; defaults to false
• namespace (bytes) – if given, the attribute must not contain the namespace, but instead it will be taken from this parameter

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).

xattr.remove(item, name[, nofollow=False, namespace=None])

Remove an attribute from a file.

Example:

>>> xattr.remove('/path/to/file', 'user.comment')

Parameters:

• item – a string representing a file-name, or a file-like object, or a file descriptor; this represents the file on which to act
• name (string) – the attribute to remove; usually in the form of system.posix_acl or user.mime_type
• nofollow (boolean, optional) – if true and if the file name given is a symbolic link, the function will operate on the symbolic link itself instead of its target; defaults to false
• namespace (bytes) – if given, the attribute must not contain the namespace, but instead it will be taken from this parameter

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).

Deprecated functions

xattr.getxattr(item, attribute[, nofollow=False])

Get the value of a given extended attribute (deprecated).

Parameters:

• item – a string representing a file-name, or a file-like object, or a file descriptor; this represents the file on which to act
• name (string) – the attribute whose value to retrieve; usually in the form of system.posix_acl or user.mime_type
• nofollow (boolean, optional) – if true and if the file name given is a symbolic link, the function will operate on the symbolic link itself instead of its target; defaults to false

Deprecated since version 0.4: this function has been deprecated by the get() function.

xattr.setxattr(item, name, value[, flags=0, nofollow=False])

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:

• item – a string representing a file-name, or a file-like object, or a file descriptor; this represents the file on which to act
• name (string) – the attribute whose value to set; usually in the form of system.posix_acl or user.mime_type
• value (string) – possibly with embedded NULLs; note that there are restrictions regarding the size of the value, for example, for ext2/ext3, maximum size is the block size
• flags (integer) – if 0 or omitted the attribute will be created or replaced; if XATTR_CREATE, the attribute will be created, giving an error if it already exists; if XATTR_REPLACE, the attribute will be replaced, giving an error if it doesn’t exist;
• nofollow (boolean, optional) – if true and if the file name given is a symbolic link, the function will operate on the symbolic link itself instead of its target; defaults to false

Deprecated since version 0.4: this function has been deprecated by the set() function.

xattr.listxattr(item[, nofollow=False])

Return the list of attribute names for a file (deprecated).

Parameters:

• item – a string representing a file-name, or a file-like object, or a file descriptor; this represents the file on which to act
• nofollow (boolean, optional) – if true and if the file name given is a symbolic link, the function will operate on the symbolic link itself instead of its target; defaults to false

Deprecated since version 0.4: this function has been deprecated by the list() function.

xattr.removexattr(item, name[, nofollow])

Remove an attribute from a file (deprecated).

Parameters:

• item – a string representing a file-name, or a file-like object, or a file descriptor; this represents the file on which to act
• name (string) – the attribute to remove; usually in the form of system.posix_acl or user.mime_type
• nofollow (boolean, optional) – if true and if the file name given is a symbolic link, the function will operate on the symbolic link itself instead of its target; defaults to false

Deprecated since version 0.4: this function has been deprecated by the remove() function.