pyzim.pointerlist.SimplePointerList

class documentation

class SimplePointerList(ModifiableMixIn):

Known subclasses: pyzim.pointerlist.OnDiskSimplePointerList, pyzim.pointerlist.OrderedPointerList

Constructor: SimplePointerList(pointers)

A pointer list of a ZIM file.

A simple pointer list maps an index to a pointer.

Class Method	`from_bytes`	Load a pointer list from the provided bytestring
Class Method	`from_file`	Load a pointer list from a file.
Class Method	`from_zim_entry`	Load a pointer list from an entry inside a ZIM archive.
Class Method	`from_zim_file`	Load a pointer list from a ZIM file at the specified offset.
Class Method	`new`	Instantiate a new, empty pointerlist.
Method	`__getitem__`	Get the pointer at the specified index.
Method	`__init__`	The default constructor.
Method	`__len__`	The length of this pointer list.
Method	`append`	Append a pointer to the end of pointerlist.
Method	`get_by_index`	Return the pointer for the specified index.
Method	`get_by_pointer`	Return the index of pointer in this list.
Method	`get_disk_size`	Calculate the size of this object when written to a file.
Method	`iter_pointers`	Iterate over all pointers in this pointer list.
Method	`mass_update`	Perform a mass update on all pointers in the specified range, changing their value as specified.
Method	`remove_by_index`	Remove the pointer at the specified index.
Method	`set`	Set the pointer at the specified index.
Method	`to_bytes`	Dump this pointer list into a bytestring and return it.
Constant	`POINTER_FORMAT`	format of a single pointer
Instance Variable	`_lock`	Undocumented
Instance Variable	`_pointers`	list of pointers in this pointer list

Inherited from ModifiableMixIn:

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_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.

@classmethod

def from_bytes(cls, s): ¶

overridden in pyzim.pointerlist.OnDiskSimplePointerList, pyzim.pointerlist.OrderedPointerList

Load a pointer list from the provided bytestring

NOTE: it is not possible to validate that the string contains the whole pointer list.

Parameters
s:`bytes`	bytestring to parse

Returns
`pyzim.pointerlist.SimplePointerList`	the pointerlist parsed from the bytes

@classmethod

def from_file(cls, f, n, seek=None): ¶

overridden in pyzim.pointerlist.OnDiskSimplePointerList, pyzim.pointerlist.OrderedPointerList

Load a pointer list from a file.

Parameters
f:file-like	file-like object to read from
n:`int`	number of entries in the pointer list.
seek:`int` or `None`	if specified, seek this position of the file before reading

Returns
`pyzim.pointerlist.SimplePointerList`	the pointerlist read from the file

@classmethod

def from_zim_entry(cls, zim, full_url): ¶

overridden in pyzim.pointerlist.OnDiskSimplePointerList, pyzim.pointerlist.OrderedPointerList

Load a pointer list from an entry inside a ZIM archive.

NOTE: it is not possible to validate that the string contains the whole pointer list.

Parameters
zim:`pyzim.archive.Zim`	ZIM file to read from
full_url:`str`	full url of entry to read pointerlist from

Returns
`pyzim.pointerlist.SimplePointerList`	the pointerlist parsed from the bytes

@classmethod

def from_zim_file(cls, zim, n, seek=None): ¶

overridden in pyzim.pointerlist.OnDiskSimplePointerList, pyzim.pointerlist.OrderedPointerList

Load a pointer list from a ZIM file at the specified offset.

This usually acquires the file lock and calls SimplePointerList.from_file, but subclasses may behave differently.

Parameters
zim:`pyzim.archive.Zim`	ZIM file to read from
n:`int`	number of entries in the pointer list.
seek:`int` or `None`	if specified, seek this position of the file before reading

Returns
`pyzim.pointerlist.SimplePointerList`	the pointerlist read from the file

@classmethod

def new(cls): ¶

overridden in pyzim.pointerlist.OnDiskSimplePointerList, pyzim.pointerlist.OrderedPointerList

Instantiate a new, empty pointerlist.

Returns
`SimplePointerList`	a new, empty pointerlist

def __getitem__(self, i): ¶

Get the pointer at the specified index.

This is basically just a wrapper around SimplePointerList.get_by_index.

Parameters
i:`int`	index of pointer to get

Returns
`int`	the poiner with the specified index

Raises
`IndexError`	when the index is out of bounds.

def __init__(self, pointers): ¶

overrides pyzim.modifiable.ModifiableMixIn.__init__

overridden in pyzim.pointerlist.OnDiskSimplePointerList, pyzim.pointerlist.OrderedPointerList

The default constructor.

Parameters
pointers:`list` of `int`	list of pointers contained in this list

def __len__(self): ¶

overridden in pyzim.pointerlist.OnDiskSimplePointerList

The length of this pointer list.

Returns
`int`	the length of this pointer list

def append(self, pointer): ¶

Append a pointer to the end of pointerlist.

If you are working with a pyzim.pointerlist.OrderedPointerList, you will not want to use this method. Instead, use pyzim.pointerlist.OrderedPointerList.add, which correctly inserts the pointer.

Parameters
pointer:`int`	pointer to add

Raises
`pyzim.exceptions.NonMutable`	if pointer list is not mutable

def get_by_index(self, i): ¶

overridden in pyzim.pointerlist.OnDiskSimplePointerList

Return the pointer for the specified index.

Parameters
i:`int`	index of pointer to get

Returns
`int`	the poiner with the specified index

Raises
`IndexError`	when the index is out of bounds.

def get_by_pointer(self, pointer): ¶

Return the index of pointer in this list.

Parameters
pointer:`int`	the pointer to find index of

Returns
`int`	the index of this pointer

Raises
`KeyError`	if pointer not found in archive

def get_disk_size(self): ¶

overrides pyzim.modifiable.ModifiableMixIn.get_disk_size

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 iter_pointers(self, start=None, end=None): ¶

Iterate over all pointers in this pointer list.

If start and end are specified, they reference the indexes of the first (inclusive) and last (exclusive) pointers to return. In other words, this behavior matches the l[start:end] syntax.

Parameters
start:`int`	index of first pointer to return (inclusive)
end:`int`	index of last pointer to return (exclusive)

Yields
`int`	the pointers in the specified range

def mass_update(self, diff, start=None, end=None): ¶

Perform a mass update on all pointers in the specified range, changing their value as specified.

Each pointer is changed by the 'diff' value.

IMPORTANT: Unlike SimplePointerList.iter_pointers, start and end of this method refer to the pointer values, not the indexes.

If start and end are specified, they reference the pointers of the first (inclusive) and last (exclusive) pointers to modify. In other words, this behavior matches the l[start:end] syntax.

Parameters
diff:`int`	value to add to each pointer
start:`int`	min values of pointers to modify (inclusive)
end:`int`	max values of pointers to modify (exclusive)

def remove_by_index(self, i): ¶

Remove the pointer at the specified index.

Parameters
i:`int`	index of pointer to remove

Raises
`IndexError`	on invalid index

def set(self, i, pointer, add_placeholders=False): ¶

Set the pointer at the specified index.

If i == len(self), append the pointer. IF i > len(self), this will raise a IndexError, unless you also set add_placeholders = True.

If you are working with a pyzim.pointerlist.OrderedPointerList, you will not want to use this method. Instead, use pyzim.pointerlist.OrderedPointerList.add, which correctly inserts the pointer.

Parameters
i:l{int}	position of pointer to set
pointer:`int`	new value for pointer
add_placeholders:`bool`	if nonzero, allow setting i>len(self), adding placeholders

Raises
`IndexError`	on invalid index
`pyzim.exceptions.NonMutable`	if pointer list is not mutable

def to_bytes(self): ¶

Dump this pointer list into a bytestring and return it.

Returns
`bytes`	a bytestring describing this pointer list

POINTER_FORMAT: str = ¶

overridden in pyzim.pointerlist.TitlePointerList

format of a single pointer

Value

'Q'

_lock: threading.Lock = ¶

Undocumented

_pointers: list of int @ivar _lock_ thread safety lock = ¶

list of pointers in this pointer list