Loads data from a file. Determines the file type automatically ``"file"``,
    ``"fifo"``, ``"socket"``, but allows to specify the representation type 
    ``"string"`` or ``"mmap"`` for memory mapped access to the file. Returns 
    the  loaded item as a ``str`` or ``mmap`` object. Internally creates an item
    from a ``file``.

    Arguments:

      - type(``"string"`` or ``"mmap"``) [default: ``"string"``] Determines the
        type of ``object`` the worker returns i.e. the ``file`` is read as a 
        string or a memmory map. FIFOs cannot be memory mapped. 
      - remove(``bool``) [default: ``True``] Should the file be removed from the
        filesystem? This is mandatory for FIFOs and sockets. Only Files can be 
        used to store data persistantly.

def load_item(inbox, type="string", remove=True, buffer=None):
    """
    Loads data from a file. Determines the file type automatically ``"file"``,
    ``"fifo"``, ``"socket"``, but allows to specify the representation type 
    ``"string"`` or ``"mmap"`` for memory mapped access to the file. Returns 
    the  loaded item as a ``str`` or ``mmap`` object. Internally creates an item
    from a ``file``.

    Arguments:

      - type(``"string"`` or ``"mmap"``) [default: ``"string"``] Determines the
        type of ``object`` the worker returns i.e. the ``file`` is read as a 
        string or a memmory map. FIFOs cannot be memory mapped. 
      - remove(``bool``) [default: ``True``] Should the file be removed from the
        filesystem? This is mandatory for FIFOs and sockets. Only Files can be 
        used to store data persistantly.
    
    """
    is_file, is_fifo, is_socket = False, False, False

    file = inbox[0]
    try:
        file_type = file[0]
    except:
        raise ValueError("invalid inbox item")
    if file_type == "file":
        is_file = os.path.exists(file[1])
    elif file_type == "fifo":
        is_fifo = stat.S_ISFIFO(os.stat(file[1]).st_mode)
    elif file_type == "socket":
        # how to test is valid socket?
        is_socket = True
    else:
        raise ValueError("type: %s not undertood" % file_type)


    if (is_fifo or is_socket) and (type == 'mmap'):
        raise ValueError("mmap is not supported for FIFOs and sockets")
    if (is_fifo or is_socket) and not remove:
        raise ValueError("FIFOs and sockets have to be removed")

    # get a fd and start/stop
    start = 0
    if is_fifo or is_file:
        stop = os.stat(file[1]).st_size - 1
        fd = os.open(file[1], os.O_RDONLY)
        BUFFER = (buffer or PAPY_DEFAULTS['PIPE_BUF'])
    elif is_socket:
        host, port = socket.gethostbyname(file[1]), file[2]
        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        sock.connect((host, port))
        stop = -1
        fd = sock.fileno()
        BUFFER = (buffer or PAPY_DEFAULTS['TCP_RCVBUF'])
    else:
        raise ValueError("got unknown inbox: %s" % (repr(inbox)))

    # get the data
    if type == 'mmap':
        offset = start - (start % (getattr(mmap, 'ALLOCATIONGRANULARITY', None)\
                                   or getattr(mmap, 'PAGESIZE')))
        start = start - offset
        stop = stop - offset + 1
        try:
            data = mmap.mmap(fd, stop, access=mmap.ACCESS_READ, offset=offset)
        except TypeError:
            # we're on Python 2.5
            data = mmap.mmap(fd, stop, access=mmap.ACCESS_READ)
        data.seek(start)

    elif type == 'string':
        data = []
        if stop == -1:
            while True:
                buffer_ = os.read(fd, BUFFER)
                if not buffer_:
                    break
                data.append(buffer_)
            data = "".join(data)
            # data = sock.recv(socket.MSG_WAITALL) 
            # this would read all the data from a socket
        else:
            os.lseek(fd, start, 0)
            data = os.read(fd, stop - start + 1)
    else:
        raise ValueError('type: %s not understood.' % type)

    # remove the file or close the socket
    if remove:
        if is_socket:
            # closes client socket
            sock.close()
        else:
            # pipes and files are just removed
            os.close(fd)
            os.unlink(file[1])
    else:
        os.close(fd)
    # returns a string or mmap
    return data