API reference

class data.Data(arg=None, encoding=None, data=None, file=None)

Dynamically converts between various forms of passed in input data.

Exactly one of arg, data or file must be not-None.

Parameters:

• arg – Dynamic argument. If a bytestring, will be interpreted as raw bytes. A unicode string will be interpreted as text and any object that has a read() method as a file-like. Any instance of Data will be passed through and rendered unusable.
• encoding – The data’s encoding. Will be used for every conversion from bytestrings to text (unicode) if necessary and the other way around.
• data – Buffer argument. If unicode string, will be interpreted as text, otherwise as bytestring.
• file – File argument. Any object with a read() method will be treated as file-like. Everything else is considered a filename.

__bytes__()

Returns the data as bytes (on Python3) or string (on Python2).

__enter__()

Context manager support. If data is a file-like, will close it upon exiting the context manager.

__iter__()

Iterator support. Returns lines (similar to file objects) using readline().

__str__()

Returns the data as unicode (on Python3) or string (on Python2).

__unicode__()

Returns the data as unicode.

close()

Closes input if based on open filelike. Otherwise does nothing.

read(*args, **kwargs)

Read method, implements same interface as file.read(). Always returns unicode.

readb(*args, **kwargs)

Like read(), but returns bytestrings instead.

readline(*args, **kwargs)

Return one line from stream. Always returns unicode.

readlines(*args, **kwargs)

Return list of all lines. Always returns list of unicode.

save_to(file)

Save data to file.

Will copy by either writing out the data or using shutil.copyfileobj().

Parameters:file – A file-like object (with a write method) or a filename.

stream

Returns a stream object (file(), BytesIO or StringIO) on the data.

temp_saved(*args, **kwds)

Saves data to temporary file and returns the relevant instance of NamedTemporaryFile(). The resulting file is not deleted upon closing, but when the context manager exits.

Other arguments are passed on to NamedTemporaryFile().

data.decorators.annotate(*args, **kwargs)

Set function annotations (on Python2 and 3).

data.decorators.auto_instantiate(*classes)

Creates a decorator that will instantiate objects based on function parameter annotations.

The decorator will check every argument passed into f. If f has an annotation for the specified parameter and the annotation is found in classes, the parameter value passed in will be used to construct a new instance of the expression that is the annotation.

An example (Python 3):

@auto_instantiate(int)
def foo(a: int, b: float):
    pass

Any value passed in as b is left unchanged. Anything passed as the parameter for a will be converted to int before calling the function.

Since Python 2 does not support annotations, the annotate() function should can be used:

@auto_instantiate(int)
@annotate(a=int)
def foo(a, b):
    pass

Parameters:classes – Any number of classes/callables for which auto-instantiation should be performed. If empty, perform for all. Note:When dealing with data, it is almost always more convenient to use the data() decorator instead.

data.decorators.data(*argnames)

Designate an argument as a Data argument.

Works by combining calls to auto_instantiate() and :func:~data.decorators.annotate` on the named arguments.

Example:

class Foo(object):
    @data('bar')
    def meth(self, foo, bar):
        pass

Inside meth, bar will always be a Data instance constructed from the original value passed as bar.

Parameters:argnames – List of parameter names that should be data arguments. Returns:A decorator that converts the named arguments to Data instances.