file_container¶

FOX.io.file_container¶

An abstract container for reading and writing files.

Index¶

AbstractFileContainer() An abstract container for reading and writing files.

API¶

class FOX.io.file_container.AbstractFileContainer[source]¶

An abstract container for reading and writing files.

Two public methods are defined within this class:

AbstractFileContainer.read(): Construct a new instance from this object’s class by
reading the content to a file or file object. How the content of the to-be read file is parsed has to be defined in the AbstractFileContainer._read_iterate() abstract method.
AbstractFileContainer.write(): Write the content of this instance to an opened
file or file object. How the content of the to-be exported class instance is parsed has to be defined in the AbstractFileContainer._write_iterate()

The opening, closing and en-/decoding of files is handled by two above-mentioned methods; the parsing * AbstractFileContainer._read_iterate() * AbstractFileContainer._write_iterate()

__contains__(value)[source]¶

Check if this instance contains value.

Return type:	`bool`

classmethod read(filename, encoding=None, **kwargs)[source]¶

Construct a new instance from this object’s class by reading the content of filename.

Parameters:

filename (str, bytes, os.PathLike or a file object) – The path+filename or a file object of the to-be read .psf file. In practice, any iterable can substitute the role of file object as long iteration returns either strings or bytes (see encoding).
encoding (str, optional) – Encoding used to decode the input (e.g. "utf-8"). Only relevant when a file object is supplied to filename and the datastream is not in text mode.
**kwargs (Any) – Optional keyword arguments that will be passed to both AbstractFileContainer._read_iterate() and AbstractFileContainer._read_postprocess().

See also

AbstractFileContainer._read_iterate(): An abstract method for parsing the opened file in AbstractFileContainer.read().
AbstractFileContainer._read_postprocess(): Post processing the class instance created by AbstractFileContainer.read().

Return type:	`AbstractFileContainer`

abstract classmethod _read_iterate(iterator, **kwargs)[source]¶

An abstract method for parsing the opened file in read.

Parameters:	iterator (`Iterator` [`str`]) – An iterator that returns `str` instances upon iteration.
Return type:	`Dict`[`str`, `Any`]
Returns:	`dict` [`str`, `Any`] – A dictionary with keyword arguments for a new instance of this objects’ class. **kwargs (`Any`) – Optional keyword arguments.

See also

read(): The main method for reading files.

_read_postprocess(filename, encoding=None, **kwargs)[source]¶

Post processing the class instance created by read().

Parameters:

filename (str, bytes, os.PathLike or a file object) – The path+filename or a file object of the to-be read .psf file. In practice, any iterable can substitute the role of file object as long iteration returns either strings or bytes (see encoding).
encoding (str, optional) – Encoding used to decode the input (e.g. "utf-8"). Only relevant when a file object is supplied to filename and the datastream is not in text mode.
**kwargs (Any) – Optional keyword arguments that will be passed to both AbstractFileContainer._read_iterate() and AbstractFileContainer._read_postprocess().

See also

AbstractFileContainer.read(): The main method for reading files.

Return type:	`None`

write(filename, encoding=None, **kwargs)[source]¶

Write the content of this instance to filename.

Parameters:

filename (str, bytes, os.PathLike or a file object) – The path+filename or a file object of the to-be read .psf file. Contrary to _read_postprocess(), file objects can not be substituted for generic iterables.
encoding (str, optional) – Encoding used to decode the input (e.g. "utf-8"). Only relevant when a file object is supplied to filename and the datastream is not in text mode.
**kwargs (Any) – Optional keyword arguments that will be passed to _write_iterate().

See also

AbstractFileContainer._write_iterate(): Write the content of this instance to an opened datastream.
AbstractFileContainer._get_writer(): Take a write() method and ensure its first argument is properly encoded.

Return type:	`None`

static _get_writer(writer, encoding=None)[source]¶

Take a write() method and ensure its first argument is properly encoded.

Parameters:	writer (`Callable`) – A write method such as `io.TextIOWrapper.write()`. encoding (`str`, optional) – Encoding used to encode the input of writer (e.g. `"utf-8"`). This value will be used in `str.encode()` for encoding the first positional argument provided to instance_method. If `None`, return instance_method unaltered without any encoding.
Returns:	A decorated writer parameter. The first positional argument provided to the decorated callable will be encoded using encoding. writer is returned unalterd if `encoding=None`.
Return type:	`Callable`

See also

AbstractFileContainer.write(): The main method for writing files.

abstract _write_iterate(write, **kwargs)[source]¶

Write the content of this instance to an opened datastream.

The to-be written content of this instance should be passed as str. Any (potential) encoding is handled by the write parameter.

Example

Basic example of a potential _write_iterate() implementation.

>>> iterator = self.as_dict().items()
>>> for key, value in iterator:
...     value: str = f'{key} = {value}'
...     write(value)
>>> return None

Parameters:	writer (`Callable`) – A callable for writing the content of this instance to a file object. An example would be the `io.TextIOWrapper.write()` method. *kwargs (optional*) – Optional keyword arguments.

See also

AbstractFileContainer.write(): The main method for writing files.

Return type:	`None`

classmethod inherit_annotations()[source]¶

A decorator for inheriting annotations and docstrings.

Can be applied to methods of AbstractFileContainer subclasses to automatically inherit the docstring and annotations of identical-named functions of its superclass.

Examples

>>> class sub_class(AbstractFileContainer)
...
...     @AbstractFileContainer.inherit_annotations()
...     def write(filename, encoding=None, **kwargs):
...         pass

>>> sub_class.write.__doc__ == AbstractFileContainer.write.__doc__
True

>>> sub_class.write.__annotations__ == AbstractFileContainer.write.__annotations__
True

Return type:	`type`

__weakref__¶: list of weak references to the object (if defined)