Python Library Documentation: module posix1e

NAME
    posix1e - POSIX.1e ACLs manipulation

FILE
    /home/iusty/work/pylibacl/build/lib.linux-i686-2.2/posix1e.so

DESCRIPTION
    This module provides support for manipulating POSIX.1e ACLS
    
    Depending on the operating system support for POSIX.1e, 
    the ACL type will have more or less capabilities:
      - level 1, only basic support, you can create
        ACLs from files and text descriptions;
        once created, the type is immutable
      - level 2, complete support, you can alter
        the ACL once it is created
    
    Also, in level 2, more types are available, corresponding
    to acl_entry_t (Entry type), acl_permset_t (Permset type).
    
    Example:
    >>> import posix1e
    >>> acl1 = posix1e.ACL(file="file.txt") 
    >>> print acl1
    user::rw-
    group::rw-
    other::r--
    
    >>> b = posix1e.ACL(text="u::rx,g::-,o::-")
    >>> print b
    user::r-x
    group::---
    other::---
    
    >>> b.applyto("file.txt")
    >>> print posix1e.ACL(file="file.txt")
    user::r-x
    group::---
    other::---
    
    >>>

CLASSES
    __builtin__.object
        ACL
        Entry
        Permset
    
    class ACL(__builtin__.object)
     |  Type which represents a POSIX ACL
     |  
     |  Parameters:
     |    Only one keword parameter should be provided:
     |    - file="...", meaning create ACL representing
     |      the access ACL of that file
     |    - filedef="...", meaning create ACL representing
     |      the default ACL of that directory
     |    - fd=<int>, meaning create ACL representing
     |      the access ACL of that file descriptor
     |    - text="...", meaning create ACL from a 
     |      textual description
     |    - acl=<ACL instance>, meaning create a copy
     |      of an existing ACL instance
     |  If no parameters are passed, create an empty ACL; this
     |  makes sense only when your OS supports ACL modification
     |   (i.e. it implements full POSIX.1e support)
     |  
     |  Methods defined here:
     |  
     |  __getstate__(...)
     |      Dumps the ACL to an external format.
     |  
     |  __init__(...)
     |      x.__init__(...) initializes x; see x.__class__.__doc__ for signature
     |  
     |  __iter__(...)
     |      x.__iter__() <==> iter(x)
     |  
     |  __setstate__(...)
     |      Loads the ACL from an external format.
     |  
     |  __str__(...)
     |      x.__str__() <==> str(x)
     |  
     |  append(...)
     |      Append a new Entry to the ACL and return it.
     |      
     |      This is a convenience function to create a new Entry 
     |      and append it to the ACL.
     |      If a parameter of type Entry instance is given, the 
     |      entry will be a copy of that one (as if copied with 
     |      Entry.copy()), otherwise, the new entry will be empty.
     |  
     |  applyto(...)
     |      Apply the ACL to a file or filehandle.
     |      
     |      Parameters:
     |        - either a filename or a file-like object or an integer; this
     |          represents the filesystem object on which to act
     |        - optional flag representing the type of ACL to set, either
     |          ACL_TYPE_ACCESS (default) or ACL_TYPE_DEFAULT
     |  
     |  calc_mask(...)
     |      Compute the file group class mask.
     |      
     |      The calc_mask() method calculates and sets the permissions 
     |      associated with the ACL_MASK Entry of the ACL.
     |      The value of the new permissions is the union of the permissions 
     |      granted by all entries of tag type ACL_GROUP, ACL_GROUP_OBJ, or 
     |      ACL_USER.  If the ACL already contains an ACL_MASK entry, its 
     |      permissions are overwritten; if it does not contain an ACL_MASK 
     |      Entry, one is added.
     |      
     |      The order of existing entries in the ACL is undefined after this 
     |      function.
     |  
     |  delete_entry(...)
     |      Deletes an entry from the ACL.
     |      
     |      Note: Only with level 2
     |      Parameters:
     |       - the Entry object which should be deleted; note that after
     |         this function is called, that object is unusable any longer
     |         and should be deleted
     |  
     |  next(...)
     |      x.next() -> the next value, or raise StopIteration
     |  
     |  valid(...)
     |      Test the ACL for validity.
     |      
     |      This method tests the ACL to see if it is a valid ACL
     |      in terms of the filesystem. More precisely, it checks:
     |      A valid ACL contains exactly one entry with each of the ACL_USER_OBJ,
     |      ACL_GROUP_OBJ, and ACL_OTHER tag types. Entries with ACL_USER and
     |      ACL_GROUP tag types may appear zero or more times in an ACL. An ACL that
     |      contains entries of ACL_USER or ACL_GROUP tag types must contain exactly
     |      one entry of the ACL_MASK tag type. If an ACL contains no entries of
     |      ACL_USER or ACL_GROUP tag types, the ACL_MASK entry is optional.
     |      
     |      All user ID qualifiers must be unique among all entries of ACL_USER tag
     |      type, and all group IDs must be unique among all entries of ACL_GROUP tag
     |      type.
     |      
     |      The method will return 1 for a valid ACL and 0 for an invalid one.
     |      This has been chosen because the specification for acl_valid in POSIX.1e
     |      documents only one possible value for errno in case of an invalid ACL, 
     |      so we can't differentiate between classes of errors. Other suggestions 
     |      are welcome.
     |  
     |  ----------------------------------------------------------------------
     |  Data and non-method functions defined here:
     |  
     |  __doc__ = 'Type which represents a POSIX ACL\n\nParameters:\n ...tion\...
     |      str(object) -> string
     |      
     |      Return a nice string representation of the object.
     |      If the argument is a string, the return value is the same object.
     |  
     |  __new__ = <built-in method __new__ of type object>
     |      T.__new__(S, ...) -> a new object with type S, a subtype of T
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from __builtin__.object:
     |  
     |  __delattr__(...)
     |      x.__delattr__('name') <==> del x.name
     |  
     |  __getattribute__(...)
     |      x.__getattribute__('name') <==> x.name
     |  
     |  __hash__(...)
     |      x.__hash__() <==> hash(x)
     |  
     |  __reduce__(...)
     |      helper for pickle
     |  
     |  __repr__(...)
     |      x.__repr__() <==> repr(x)
     |  
     |  __setattr__(...)
     |      x.__setattr__('name', value) <==> x.name = value
     |  
     |  ----------------------------------------------------------------------
     |  Data and non-method functions inherited from __builtin__.object:
     |  
     |  __class__ = <type 'type'>
     |      the object's class
    
    class Entry(__builtin__.object)
     |  Type which represents an entry in an ACL.
     |  
     |  The type exists only if the OS has full support for POSIX.1e
     |  Can be created either by:
     |    e = posix1e.Entry(myACL) # this creates a new entry in the ACL
     |  or by:
     |    for entry in myACL:
     |        print entry
     |  
     |  Note that the Entry keeps a reference to its ACL, so even if 
     |  you delete the ACL, it won't be cleaned up and will continue to 
     |  exist until its Entry(ies) will be deleted.
     |  
     |  Methods defined here:
     |  
     |  __init__(...)
     |      x.__init__(...) initializes x; see x.__class__.__doc__ for signature
     |  
     |  __str__(...)
     |      x.__str__() <==> str(x)
     |  
     |  copy(...)
     |      Copy an ACL entry.
     |      
     |      This method sets all the parameters to those of another
     |      entry, even one of another's ACL
     |      Parameters:
     |       - src, instance of type Entry
     |  
     |  ----------------------------------------------------------------------
     |  Data and non-method functions defined here:
     |  
     |  __doc__ = 'Type which represents an entry in an ACL.\n\nThe t... to \n...
     |      str(object) -> string
     |      
     |      Return a nice string representation of the object.
     |      If the argument is a string, the return value is the same object.
     |  
     |  __new__ = <built-in method __new__ of type object>
     |      T.__new__(S, ...) -> a new object with type S, a subtype of T
     |  
     |  parent = <attribute 'parent' of 'posix1e.Entry' objects>
     |      The parent ACL of this entry
     |  
     |  
     |  permset = <attribute 'permset' of 'posix1e.Entry' objects>
     |      The permission set of this ACL entry
     |  
     |  
     |  qualifier = <attribute 'qualifier' of 'posix1e.Entry' objects>
     |      The qualifier of the current entry
     |      
     |      If the tag type is ACL_USER, this should be a user id.
     |      If the tag type if ACL_GROUP, this should be a group id.
     |      Else, it doesn't matter.
     |  
     |  
     |  tag_type = <attribute 'tag_type' of 'posix1e.Entry' objects>
     |      The tag type of the current entry
     |      
     |      This is one of:
     |       - ACL_UNDEFINED_TAG
     |       - ACL_USER_OBJ
     |       - ACL_USER
     |       - ACL_GROUP_OBJ
     |       - ACL_GROUP
     |       - ACL_MASK
     |       - ACL_OTHER
     |  
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from __builtin__.object:
     |  
     |  __delattr__(...)
     |      x.__delattr__('name') <==> del x.name
     |  
     |  __getattribute__(...)
     |      x.__getattribute__('name') <==> x.name
     |  
     |  __hash__(...)
     |      x.__hash__() <==> hash(x)
     |  
     |  __reduce__(...)
     |      helper for pickle
     |  
     |  __repr__(...)
     |      x.__repr__() <==> repr(x)
     |  
     |  __setattr__(...)
     |      x.__setattr__('name', value) <==> x.name = value
     |  
     |  ----------------------------------------------------------------------
     |  Data and non-method functions inherited from __builtin__.object:
     |  
     |  __class__ = <type 'type'>
     |      the object's class
    
    class Permset(__builtin__.object)
     |  Type which represents the permission set in an ACL entry
     |  
     |  The type exists only if the OS has full support for POSIX.1e
     |  Can be created either by:
     |    perms = myEntry.permset
     |  or by:
     |    perms = posix1e.Permset(myEntry)
     |  
     |  Note that the Permset keeps a reference to its Entry, so even if 
     |  you delete the entry, it won't be cleaned up and will continue to 
     |  exist until its Permset will be deleted.
     |  
     |  Methods defined here:
     |  
     |  __init__(...)
     |      x.__init__(...) initializes x; see x.__class__.__doc__ for signature
     |  
     |  __str__(...)
     |      x.__str__() <==> str(x)
     |  
     |  add(...)
     |      Add a permission to the permission set.
     |      
     |      The add() function adds the permission contained in 
     |      the argument perm to the permission set.  An attempt 
     |      to add a permission that is already contained in the 
     |      permission set is not considered an error.
     |      Parameters:
     |        - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...
     |      Return value:
     |        None
     |      Can raise: IOError
     |  
     |  clear(...)
     |      Clear all permissions from the permission set.
     |  
     |  delete(...)
     |      Delete a permission from the permission set.
     |      
     |      The delete() function deletes the permission contained in 
     |      the argument perm from the permission set.  An attempt 
     |      to delete a permission that is not contained in the 
     |      permission set is not considered an error.
     |      Parameters:
     |        - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...
     |      Return value:
     |        None
     |      Can raise: IOError
     |  
     |  test(...)
     |      Test if a permission exists in the permission set.
     |      
     |      The test() function tests if the permission contained in 
     |      the argument perm exits the permission set.
     |      Parameters:
     |        - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...
     |      Return value:
     |        Bool
     |      Can raise: IOError
     |  
     |  ----------------------------------------------------------------------
     |  Data and non-method functions defined here:
     |  
     |  __doc__ = 'Type which represents the permission set in an A...nue to \...
     |      str(object) -> string
     |      
     |      Return a nice string representation of the object.
     |      If the argument is a string, the return value is the same object.
     |  
     |  __new__ = <built-in method __new__ of type object>
     |      T.__new__(S, ...) -> a new object with type S, a subtype of T
     |  
     |  execute = <attribute 'execute' of 'posix1e.Permset' objects>
     |      Execute permsission
     |      
     |      This is a convenience method of access; the 
     |      same effect can be achieved using the functions
     |      add(), test(), delete(), and those can take any 
     |      permission defined by your platform.
     |  
     |  
     |  read = <attribute 'read' of 'posix1e.Permset' objects>
     |      Read permsission
     |      
     |      This is a convenience method of access; the 
     |      same effect can be achieved using the functions
     |      add(), test(), delete(), and those can take any 
     |      permission defined by your platform.
     |  
     |  
     |  write = <attribute 'write' of 'posix1e.Permset' objects>
     |      Write permsission
     |      
     |      This is a convenience method of access; the 
     |      same effect can be achieved using the functions
     |      add(), test(), delete(), and those can take any 
     |      permission defined by your platform.
     |  
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from __builtin__.object:
     |  
     |  __delattr__(...)
     |      x.__delattr__('name') <==> del x.name
     |  
     |  __getattribute__(...)
     |      x.__getattribute__('name') <==> x.name
     |  
     |  __hash__(...)
     |      x.__hash__() <==> hash(x)
     |  
     |  __reduce__(...)
     |      helper for pickle
     |  
     |  __repr__(...)
     |      x.__repr__() <==> repr(x)
     |  
     |  __setattr__(...)
     |      x.__setattr__('name', value) <==> x.name = value
     |  
     |  ----------------------------------------------------------------------
     |  Data and non-method functions inherited from __builtin__.object:
     |  
     |  __class__ = <type 'type'>
     |      the object's class

FUNCTIONS
    delete_default(...)
        Delete the default ACL from a directory.
        
        This function deletes the default ACL associated with 
        a directory (the ACL which will be ANDed with the mode
        parameter to the open, creat functions).
        Parameters:
          - a string representing the directory whose default ACL
            should be deleted

DATA
    ACL_EXECUTE = 1
    ACL_GROUP = 8
    ACL_GROUP_OBJ = 4
    ACL_MASK = 16
    ACL_OTHER = 32
    ACL_READ = 4
    ACL_TYPE_ACCESS = 32768
    ACL_TYPE_DEFAULT = 16384
    ACL_UNDEFINED_TAG = 0
    ACL_USER = 2
    ACL_USER_OBJ = 1
    ACL_WRITE = 2
    __file__ = '/home/iusty/work/pylibacl/build/lib.linux-i686-2.2/posix1e...
    __name__ = 'posix1e'

