zope.filerepresentation

https://travis-ci.org/zopefoundation/zope.filerepresentation.png?branch=master Documentation Status

The interfaces defined here are used for file-system and file-system-like representations of objects, such as file-system synchronization, FTP, PUT, and WebDAV.

Contents:

zope.filerepresentation API

File-system representation interfaces

The interfaces defined here are used for file-system and file-system-like representations of objects, such as file-system synchronization, FTP, PUT, and WebDAV.

There are three issues we need to deal with:

File system representation

Every object is either a directory or a file.

Properties

There are two kinds of proprties:

  • Data properties

    Data properties are handled directly by the object implementation.

  • Meta-data properties

    Meta data properties are handled via annotations.

Completeness

We must have a complete lossless data representation for file-system synchronization. This is achieved through serialization of:

  • All annotations (not just properties), and
  • Extra data.

Strategies for common access mechanisms:

FTP

  • For getting directory info (statish) information:
    • Use Zope DublinCore to get modification times
    • Show as readable if we can access a read method.
    • Show as writable if we can access a write method.

FTP and WebDAV

  • Treat as a directory if there is an adapter to IReadDirectory. Treat as a file otherwise.

  • For creating objects:

    • Directories:

      Look for an IDirectoryFactory adapter.

    • Files

      First lookj for a IFileFactory adapter with a name that is the same as the extention (e.g. ”.pt”).

      Then look for an unnamed IFileFactory adapter.

File-system synchronization

Because this must be lossless, we will use class-based adapters for this, but we want to make it as easy as possible to use other adapters as well.

For reading, there must be a class adapter to IReadSync. We will then apply rules similar to those above.

interface zope.filerepresentation.interfaces.ICommonFileOperations

Common file operations used by IRawReadFile and IRawWriteFile

mimeType

File MIME type

Provided if it makes sense for this file data. May be set prior to writing data to a file that is writeable. It is an error to set this on a file that is not writable.

name

A representative file name

Provided if it makes sense for this file data. May be set prior to writing data to a file that is writeable. It is an error to set this on a file that is not writable.

encoding

The encoding that this file uses

Provided if it makes sense for this file data. May be set prior to writing data to a file that is writeable. It is an error to set this on a file that is not writable.

tell()

Return the file’s current position.

closed

Is the file closed?

close()

Close the file. See Python documentation for io.IOBase for details.

seek(offset, whence=None)

Seek the file. See Python documentation for io.IOBase for details.

interface zope.filerepresentation.interfaces.IDirectoryFactory

Factory for IReadDirectory/IWriteDirectory objects.

__call__(name)

Create a directory

where a directory is an object with adapters to IReadDirectory and IWriteDirectory.

interface zope.filerepresentation.interfaces.IFileFactory

Factory for IReadFile/IWriteFile objects.

__call__(name, content_type, data)

Create a file

where a file is an object with adapters to IReadFile and IWriteFile.

The file name, content type, and data are provided to help create the object.

interface zope.filerepresentation.interfaces.IRawReadFile

Extends: zope.filerepresentation.interfaces.IReadFile, zope.filerepresentation.interfaces.ICommonFileOperations

Specialisation of IReadFile to make it act more like a Python file object.

read(size=None)

Read at most size bytes of file data. If size is None, return all the file data.

readlines(sizehint=None)

Read until EOF using readline() and return a list containing the lines thus read. See Python documentation for io.IOBase for details.

next()

Iterator protocol. See Python documentation for io.IOBase for details.

__iter__()

Return an iterator for the file.

Note that unlike a Python standard file, this does not necessarily have to return data line-by-line if doing so is inefficient.

readline(size=None)

Read one entire line from the file. See Python documentation for io.IOBase for details.

interface zope.filerepresentation.interfaces.IRawWriteFile

Extends: zope.filerepresentation.interfaces.IWriteFile, zope.filerepresentation.interfaces.ICommonFileOperations

Specialisation of IWriteFile to make it act more like a Python file object.

writelines(sequence)

Write a sequence of strings to the file. See Python documentation for io.IOBase for details.

truncate(size)

Truncate the file. See Python documentation for io.IOBase for details.

write(data)

Write a chunk of data to the file. See Python documentation for io.RawIOBase for details.

flush()

Flush the file. See Python documentation for io.IOBase for details.

interface zope.filerepresentation.interfaces.IReadDirectory

Extends: zope.interface.common.mapping.IEnumerableMapping, zope.interface.common.mapping.IItemMapping, zope.interface.common.mapping.IReadMapping

Objects that should be treated as directories for reading

interface zope.filerepresentation.interfaces.IReadFile

Provide read access to file data

read()

Return the file data

size()

Return the data length in bytes.

interface zope.filerepresentation.interfaces.IWriteDirectory

Objects that should be treated as directories for writing

__setitem__(name, object)

Add the given object to the directory under the given name.

__delitem__(name)

Delete the named object from the directory.

interface zope.filerepresentation.interfaces.IWriteFile

Provide write access to file data.

write(data)

Update the file data

Changes

4.2.0 (unreleased)

  • Add support for Python 3.5.
  • Drop support for Python 2.6.

4.1.0 (2014-12-27)

  • Add support for PyPy3.
  • Add support for Python 3.4.

4.0.2 (2013-03-08)

  • Add Trove classifiers indicating CPython and PyPy support.

4.0.1 (2013-02-11)

  • Add tox.ini to release.

4.0.0 (2013-02-11)

  • Add support for Python 3.3 and PyPy.
  • Drop support for Python 2.4 / 2.5.

3.6.1 (2011-11-29)

  • Add undeclared zope.schema dependency.
  • Remove zope.testing test dependency and test extra.

3.6.0 (2009-10-08)

  • Add IRawReadFile and IRawWriteFile interfaces. These extend IReadFile and IWritefile, respectively, to behave pretty much like a standard Python file object with a few embellishments. This in turn allows efficient, iterator- based implementations of file reading and writing.
  • Remove dependency on zope.container: IReadDirectory and IWriteDirectory inherit only from interfaces defined in zope.interface and zope.interface.common.mapping.

3.5.0 (2009-01-31)

  • Change use of zope.app.container to zope.container.

3.4.0 (2007-10-02)

  • Initial Zope-independent release.

Development

zope.filerepresentation is hosted at GitHub:

Project URLs

Indices and tables