pyzim.modifiable.ModifiableMixIn

class documentation

class ModifiableMixIn(object):

Known subclasses: pyzim.archive.Zim, pyzim.cluster.ModifiableClusterWrapper, pyzim.counter.Counter, pyzim.entry.BaseEntry, pyzim.header.Header, pyzim.mimetypelist.MimeTypeList, pyzim.pointerlist.SimplePointerList

Constructor: ModifiableMixIn()

View In Hierarchy

A mix-in class for modifiable objects.

This class contains the logic to mark objects as "dirty" (modified). It also defines an interface for getting the disk size of such objects.

A Modifiable can have child objects ("sub-modifiables"). If any such object is dirty, this instance will also be considered dirty.

This class also provides a simple check to make an object read-only, but this still requires ModifiableMixIn.ensure_mutable to be called before each change.

Method	`__init__`	The default constructor.
Method	`add_submodifiable`	Add another modifiable object as a child of this one.
Method	`after_flush_or_read`	This method should be called after this object has been read and/or flushed to disk. In other words, it should be called at least once whenever this object matches the state of the object on the disk.
Method	`dirty.setter`	Setter for `ModifiableMixIn.dirty`
Method	`ensure_mutable`	If this object is non-mutable, raise an Exception.
Method	`get_disk_size`	Calculate the size of this object when written to a file.
Method	`get_initial_disk_size`	Return the size of this object on disk as it has been read.
Method	`get_unmodified_disk_size`	Return the size of this object when written to a file before any modifications has been made since the last read/flush.
Method	`mark_dirty`	Convenience function to mark this object as dirty.
Method	`remove_submodifiable`	Remove a submodifiable from this object.
Instance Variable	`dirty`	True if this object or a sub-modifiable has been modified.
Instance Variable	`mutable`	if not nonzero, prevent modifications of this object.
Instance Variable	`_dirty`	a boolean flag that's nonzero if this object has been modified
Instance Variable	`_old_disk_size`	the size of this object on disk before any modifications since the last flush/read
Instance Variable	`_submodifiables`	a list of child objects, whose dirty state will affect this objects dirty state.

def __init__(self): ¶

overridden in pyzim.archive.Zim, pyzim.cluster.ModifiableClusterWrapper, pyzim.counter.Counter, pyzim.entry.BaseEntry, pyzim.header.Header, pyzim.mimetypelist.MimeTypeList, pyzim.pointerlist.SimplePointerList

The default constructor.

Don't forget to call this constructor in subclasses!

def add_submodifiable(self, child): ¶

Add another modifiable object as a child of this one.

Parameters
child:`ModifiableMixIn`	modifiable object to add as an child

Raises
`TypeError`	if the passed object is not a `ModifiableMixIn`

def after_flush_or_read(self): ¶

overridden in pyzim.cluster.ModifiableClusterWrapper, pyzim.entry.BaseEntry

This method should be called after this object has been read and/or flushed to disk. In other words, it should be called at least once whenever this object matches the state of the object on the disk.

This method sets the old disk size, which allows us to late free the allocated space of the old object on disk. Thus, this method requires ModifiableMixIn.get_disk_size to work.

In addition, the object will be marked as non-dirty afterwards.

@dirty.setter

def dirty(self, value): ¶

Setter for ModifiableMixIn.dirty

Parameters
value:`bool`	new value to set

def ensure_mutable(self): ¶

If this object is non-mutable, raise an Exception.

Raises
`pyzim.exceptions.NonMutable`	if `self.mutable = False`.

def get_disk_size(self): ¶

Calculate the size of this object when written to a file.

NOTE: in this context, size refers to the direct size of the object. If this object contains references to other objects, their sizes will not be included. For example, a pyzim.entry.ContentEntry also links to a blob, but this function will only return the size of the entry itself, excluding the referenced blob.

Returns
`int`	the size, in bytes

def get_initial_disk_size(self): ¶

overridden in pyzim.cluster.ModifiableClusterWrapper

Return the size of this object on disk as it has been read.

This differs from ModifiableMixIn.get_disk_size and ModifiableMixIn.get_unmodified_disk_size, as both methods return the size this object would have it would be written. This is important, because sometimes we can not guarantee that an object has the same size it would have when we write it without any further modification. An example would be a pyzim.cluster.Cluster, which may have a different size due to a mismatch in configuration parameters even when using the same compression type.

This method should be implemented by subclasses if the previously mentioned behavior is possible. By default, this just returns the same value as ModifiableMixIn.get_disk_size.

Returns
`int`	the disk size as the object had when it was read from disk in bytes

def get_unmodified_disk_size(self): ¶

Return the size of this object when written to a file before any modifications has been made since the last read/flush.

This value is thus equal to the value returned by ModifiableMixIn.get_disk_size at the time of the last call to ModifiableMixIn.after_flush_or_read.

Returns
`int` or `None`	the size in bytes before any modifications since last flush/read or `None` if not set.

def mark_dirty(self): ¶

Convenience function to mark this object as dirty.

You can also simply set ModifiableMixIn.dirty to True.

def remove_submodifiable(self, child): ¶

Remove a submodifiable from this object.

Parameters
child:`ModifiableMixIn`	child to remove

Raises
`TypeError`	if the passed object is not a `ModifiableMixIn`
`ValueError`	if the submodifiable has not yet been registered

@property

dirty: bool = ¶

True if this object or a sub-modifiable has been modified.

mutable: bool = ¶

overridden in pyzim.archive.Zim, pyzim.pointerlist.OnDiskSimplePointerList

if not nonzero, prevent modifications of this object.

_dirty: bool = ¶

a boolean flag that's nonzero if this object has been modified

_old_disk_size: int or None = ¶

the size of this object on disk before any modifications since the last flush/read

_submodifiables: list of ModifiableMixIn = ¶

a list of child objects, whose dirty state will affect this objects dirty state.