FileSystem product
------------------

/!\ WARNING /!\

  Before using this product, please read all the documentation and source code 
  to ensure it fits your needs and requirements.


Purpose:

  Add transactional capabilities the file system access.


When to use it?

  When file accesses within a Zope transaction should happen at transaction
  commit, and nothing should happen on abort.


How does it works?

  It implements the two-phase commit by storing files into a temporary 
  directory during transaction then move or drop them at commit or abort.


Features:

  - Open/create a file in read/write/append modes
  - Rename/unkink a file
  - Can be imported from restricted python

Usage example:

  # open a directory with FileSystem
  from FileSystem.Directory import Directory
  my_directory = Directory('/my_directory')

  # create a new file and write some data
  my_file = my_directory.open('my_file_name', 'w')
  my_file.write('my_content')

  # close the file then commit to change my_directory's content
  my_file.close()
  get_transaction().commit()


Known issues:

  - Transactionality on top of file system cannot be perfectly achieved, so this
  product *will* break in some cases. It tries to detect those cases at tpc_vote
  time, but there is no way to be sure nothing will change until tpc_finish:
    - lack of disk space or inodes since vote
    - any change happening on temporary directory
    - (...many other cases)
  - No conflict detection: Concurrent accesses are solved by "last write
  (commit) wins".
  - Only single-level-directory file accesses are implemented.
  - No file access rights management accessible from user
  - All file accesses are done with zope process user
  - No path jail mechanism (developper can access what zope process user can
  	  access)
  - Naive Zope security declarations