Module xattr
[hide private]
[frames] | no frames]

Module xattr

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:

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:

Version: 0.4.0

Author: Iustin Pop

Contact: iusty@k1024.org

License: GNU Lesser General Public License (LGPL)

Functions [hide private]
list
list(...)
Return the list of attribute names for a file.
string
get(...)
Get the value of a given extended attribute.
list
get_all(...)
Get all the extended attributes of an item.
None
set(...)
Set the value of a given extended attribute.
None
remove(...)
Remove an attribute from a file.
    Deprecated API
 
listxattr(...)
Return the list of attribute names for a file (deprecated).
 
getxattr(...)
Get the value of a given extended attribute (deprecated).
 
setxattr(...)
Set the value of a given extended attribute (deprecated).
 
removexattr(...)
Remove an attribute from a file (deprecated).
Variables [hide private]
    Namespace constants
  NS_SECURITY = 'security'
  NS_SYSTEM = 'system'
  NS_TRUSTED = 'trusted'
  NS_USER = 'user'
    set function flags
  XATTR_CREATE = 1
  XATTR_REPLACE = 2
Function Details [hide private]

list(...)

 

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 - the item to query; either a string representing the filename, or a file-like object, or a file descriptor
  • nofollow (boolean) - if given and True, and the function is passed a filename that points to a symlink, the function will act on the symlink itself instead of its target
  • namespace (string) - if given, the attribute must not contain the namespace itself, but instead the namespace will be taken from this parameter
Returns: list
list of strings; note that if a namespace argument was passed, it (and the separator) will be stripped from the names returned
Raises:
  • EnvironmentError - caused by any system errors

Since: 0.4

get(...)

 

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 - the item to query; either a string representing the filename, or a file-like object, or a file descriptor
  • name (string) - the attribute whose value to set; usually in form of system.posix_acl or user.mime_type
  • nofollow (boolean) - if given and True, and the function is passed a filename that points to a symlink, the function will act on the symlink itself instead of its target
  • namespace (string) - if given, the attribute must not contain the namespace itself, but instead the namespace will be taken from this parameter
Returns: string
the value of the extended attribute (can contain NULLs)
Raises:
  • EnvironmentError - caused by any system errors

Since: 0.4

get_all(...)

 

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 - the item to query; either a string representing the filename, or a file-like object, or a file descriptor
  • namespace (string) - an optional namespace for filtering the attributes; for example, querying all user attributes can be accomplished by passing namespace=NS_USER
  • nofollow (boolean) - if passed and true, if the target file is a symbolic link, the attributes for the link itself will be returned, instead of the attributes of the target
Returns: list
list of tuples (name, value); note that if a namespace argument was passed, it (and the separator) will be stripped from the names returned
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.

Since: 0.4

set(...)

 

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 - the item to query; either a string representing the filename, or a file-like object, or a file descriptor
  • name (string) - the attribute whose value to set; usually in form of system.posix_acl or user.mime_type
  • value (string) - a 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 ommited 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 exists;
  • nofollow (boolean) - if given and True, and the function is passed a filename that points to a symlink, the function will act on the symlink itself instead of its target
  • namespace (string) - if given, the attribute must not contain the namespace itself, but instead the namespace will be taken from this parameter
Returns: None
Raises:
  • EnvironmentError - caused by any system errors

Since: 0.4

remove(...)

 

Remove an attribute from a file.

Example:

>>> xattr.remove('/path/to/file', 'user.comment')
Parameters:
  • item - the item to query; either a string representing the filename, or a file-like object, or a file descriptor
  • name (string) - the attribute whose value to set; usually in form of system.posix_acl or user.mime_type
  • nofollow (boolean) - if given and True, and the function is passed a filename that points to a symlink, the function will act on the symlink itself instead of its target
  • namespace (string) - if given, the attribute must not contain the namespace itself, but instead the namespace will be taken from this parameter
Returns: None
Raises:
  • EnvironmentError - caused by any system errors

Since: 0.4

listxattr(...)

 

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

Parameters:

  • a string representing filename, or a file-like object, or a file descriptor; this represents the file to be queried
  • (optional) a boolean value (defaults to false), which, if the file name given is a symbolic link, makes the function operate on the symbolic link itself instead of its target;

Deprecated: since version 0.4, this function has been deprecated by the list function

getxattr(...)

 

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

Parameters:

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

Deprecated: since version 0.4, this function has been deprecated by the get function

setxattr(...)

 

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

Be carefull 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 behavior (create or replace)

Parameters:

  • a string representing filename, or a file-like object, or a file descriptor; this represents the file on which to act
  • a string, representing the attribute whose value to set; usually in form of system.posix_acl or user.mime_type
  • a 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
  • (optional) flags; if 0 or ommited the attribute will be created or replaced; if XATTR_CREATE, the attribute will be created, giving an error if it already exists; of XATTR_REPLACE, the attribute will be replaced, giving an error if it doesn't exists;
  • (optional) a boolean value (defaults to false), which, if the file name given is a symbolic link, makes the function operate on the symbolic link itself instead of its target;

Deprecated: since version 0.4, this function has been deprecated by the set function

removexattr(...)

 

Remove an attribute from a file (deprecated).

Parameters:

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

Deprecated: since version 0.4, this function has been deprecated by the remove function