### namespace high level --------------------------------------------

class CompositeNamespace:
    """ Namespace supporting mounting other namespaces within it -
        either at the root of it or below some name
        API: dict like, see Namespace
    """
    def __init__(self, nstab):
        self.nstab = nstab

    ...

class LayeredNamespace:
    """ Layers of item namespaces, visible is the topmost item
        API: dict like, see Namespace
    """
    def __init__(self, *layers):
        self.layers = layers

    ...


### namespace medium level ------------------------------------------

class Namespace:
    """ A single item namespace
        API: dict like
    """
    def __init__(self, storage):
        self.storage = storage

    def __contains__(self, name):
        return self.has_item(name)

    def has_item(self, name, include_deleted=False):
        """ check if namespace has an item <name>

            (we can use "if itemname in namespace")
        """
        return self.storage.has_item(name, include_deleted)

    def __getitem__(self, name):
        """ get item from namespace """
        return StorageItem(self.storage, name)

    def __setitem__(self, name, item):
        """ put item into namespace """
        ???
    
    def __delitem__(self, name):
        """ nuke item from namespace """
        self.storage.nuke_item(name)

    def __len__(self):
        """ return item count in namespace """
    
    def __str__(self):
        """ for debugging """
    def __unicode__(self):
        """ for debugging """
        
    def iteritems/iterkeys/itervalues(self):
        ...


### item high level -------------------------------------------------

class Item:
    """ proxy to the following mimetype specific *Item classes,
        gets ProtectedItem and dynamically offers appropriate interface for
        the mimetype that item has
    """

class BinaryItem:
    """ have stuff here we need for all item types,
        like:
        .url
        .link_to
        .delete
        .nuke
        .rename
    """

class TextItem(BinaryItem):
    """ as BinaryItem, but with special stuff for text/* """

class WikiItem(TextItem):
    """ as TextItem, but with special stuff for text/moin-wiki """

class ImageItem(BinaryItem):
    """ as BinaryItem, but with special stuff for image/* """


### item medium level -----------------------------------------------

class ProtectedItem(StorageItem):
    """ same as StorageItem, but raises AccessDenied exception when accessing
        data with insufficient user rights
    """
    def __init__(self, storage, name, user, revisioning=True):
        ...

    def may(self, right):
        """ check permissions without trying to do something """

class StorageItem:
    """ a revisioned, generic StorageItem """
    def __init__(self, storage, name, revisioning=True):
        """ create Item <name> instance """
        self.storage = storage
        self.name = name
        self.revisioning = revisioning

    def exists(self, include_deleted=False):
        # redundant with similar function from Namespace
        return self.storage.has_item(self.name, include_deleted)

    current = property(...) # lazy load current Revision

    revisions = property(...) # lazy load older Revision dict
    # dict revno -> Revision
    # add_revision ==:
    #   next_rev = current.meta['rev'] + 1
    #   revisions[next_rev] = newrev
    # del_revision == del revisions[rev]
    # list_revisions == revisions.keys()
    # has_revision == rev in revisions

class Revision:
    """ a single, specific revision of an Item
        API: properties, lazy load
    """
    def __init__(self, rev):
        """ create a revision <rev> """
        self.rev = rev # this is also in the MetaData

    meta = property() # MetaDataComponent
    data = property() # same as content['data']
    content = property() # dict name -> DataComponent obj or None (if deleted)


class MetaDataComponent:
    """ represent meta data component (a Revision has 1 MetaDataComponent)
        API: dict-like
    """


class DataComponent:
    """ represent a single data component (a Revision can have 0..n DataComponents -
        if it has no DataComponent called 'data', it is considered as a deleted Revision,
        TwikiDraw Items have multiple DataComponents)
        API: file-like as well as comfortable properties
    """


### item / namespace low level storage ------------------------------
...