# 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:

- `ENODATA` means 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 name space, used by kernel security modules to store (for example) capabilities information.

xattr.NS_SYSTEM

  The system name space, used by the kernel to store (for example) ACLs.

xattr.NS_TRUSTED

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

xattr.NS_USER

  The user name space; this is the name space 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, a file-like object, a file descriptor, or (in Python 3.6+) a path-like object; 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

  Added 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, a file-like object, a file descriptor, or (in Python 3.6+) a path-like object; 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

  Added 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, a file-like object, a file descriptor, or (in Python 3.6+) a path-like object; 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.

  Added 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, a file-like object, a file descriptor, or (in Python 3.6+) a path-like object; 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

  Added 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, a file-like object, a file descriptor, or (in Python 3.6+) a path-like object; 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

  Added 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, a file-like object, a file descriptor, or (in Python 3.6+) a path-like object; 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, a file-like object, a file descriptor, or (in Python 3.6+) a path-like object; 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, a file-like object, a file descriptor, or (in Python 3.6+) a path-like object; 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, a file-like object, a file descriptor, or (in Python 3.6+) a path-like object; 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.