pyzim.pointerlist.OrderedPointerList

class documentation

class OrderedPointerList(SimplePointerList):

Known subclasses: pyzim.pointerlist.OnDiskOrderedPointerList, pyzim.pointerlist.TitlePointerList

Constructor: OrderedPointerList(pointers, key_func)

An ordered pointer list of a ZIM file.

This is used by the URL pointer list and title pointer list.

An ordered pointer list is used to map ordered entries to their locations. The order is determined by an external attribute (e.g. the URLs of the entry pointed at). The pointer list itself only contains the pointers, finding a pointer for a key requires the loading of the entries via the pointers.

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	`__init__`	The default constructor.
Method	`add`	Add a key/pointer pair to this pointer list.
Method	`check_sorted`	Check that this list is actually ordered correctly.
Method	`find_first_greater_equals`	Return the index of the first value greater or equal to the key.
Method	`get`	Return the pointer for the specified key.
Method	`get_index`	Return the index of the pointer for the specified key.
Method	`has`	Check if this pointer list has a pointer matching the key.
Method	`iter_values`	Iterate over all values referenced by the pointers in this pointer list.
Method	`print_content`	Print the content of this pointerlist, including the keys.
Method	`remove`	Remove a pointer from this pointer list.
Instance Variable	`_keyf`	a function that returns the bytestring by which this pointer list is sorted

Inherited from SimplePointerList:

Method	`__getitem__`	Get the pointer at the specified index.
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 (via SimplePointerList):

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, key_func): ¶

overrides pyzim.pointerlist.SimplePointerList.from_bytes

overridden in pyzim.pointerlist.OnDiskOrderedPointerList

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
key_func:a callable returning `bytes`	a function that returns the bytestring by which this pointer list is sorted.

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

@classmethod

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

overrides pyzim.pointerlist.SimplePointerList.from_file

overridden in pyzim.pointerlist.OnDiskOrderedPointerList

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.
key_func:a callable returning `bytes`	a function that returns the bytestring by which this pointer list is sorted.
seek:`int` or `None`	if specified, seek this position of the file before reading

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

@classmethod

def from_zim_entry(cls, zim, full_url, key_func): ¶

overrides pyzim.pointerlist.SimplePointerList.from_zim_entry

overridden in pyzim.pointerlist.OnDiskOrderedPointerList

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
key_func:a callable returning `bytes`	a function that returns the bytestring by which this pointer list is sorted.

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

@classmethod

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

overrides pyzim.pointerlist.SimplePointerList.from_zim_file

overridden in pyzim.pointerlist.OnDiskOrderedPointerList

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.
key_func:a callable returning `bytes`	a function that returns the bytestring by which this pointer list is sorted.
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, key_func): ¶

overrides pyzim.pointerlist.SimplePointerList.new

overridden in pyzim.pointerlist.OnDiskOrderedPointerList

Instantiate a new, empty pointerlist.

Parameters
key_func:a callable returning `bytes`	a function that returns the bytestring by which this pointer list is sorted.

Returns
`OrderedPointerList`	a new, empty pointerlist

def __init__(self, pointers, key_func): ¶

overrides pyzim.pointerlist.SimplePointerList.__init__

overridden in pyzim.pointerlist.OnDiskOrderedPointerList

The default constructor.

Parameters
pointers:`list` of `int`	list of pointers contained in this list
key_func:a callable returning `bytes`	a function that returns the bytestring by which this pointer list is sorted.

def add(self, key, pointer): ¶

Add a key/pointer pair to this pointer list.

Parameters
key:`str` or `bytes`	key of pointer to add
pointer:`int`	pointer to add

Returns
`int`	the new index in the pointer list

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

def check_sorted(self): ¶

Check that this list is actually ordered correctly.

Raises
`pyzim.exceptions.UnsortedList`	when the pointers are not correctly ordered.

def find_first_greater_equals(self, key): ¶

Return the index of the first value greater or equal to the key.

This is used as a utilty function to restrict the search to specific namespaces, but may have some other uses as well.

The behavior mirrors bisect.bisect_left.

Parameters
key:`str` or `bytes`	key to find the index of the next greater entry for

Returns
`int`	the index of the first key/pointer larger than the entry

def get(self, key): ¶

Return the pointer for the specified key.

The key must be in the same format as returned by the keyfunc.

Parameters
key:`str` or `bytes`	key to search for

Returns
`int`	the pointer matching the key

Raises
`KeyError`	when no matching key was found.

def get_index(self, key): ¶

Return the index of the pointer for the specified key.

The key must be in the same format as returned by the keyfunc.

Parameters
key:`str` or `bytes`	key to search for

Returns
`int`	the index of the pointer matching the key

Raises
`KeyError`	when no matching key was found.

def has(self, key): ¶

Check if this pointer list has a pointer matching the key.

This method calls OrderedPointerList.get internally, so it's faster to not call this before get().

Parameters
key:`bytes` or `str`	key to check the presence of a matching pointer for

Returns
`bool`	True if the key is present, False otherwise

def iter_values(self, start=None, end=None): ¶

Iterate over all values referenced by the 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 the value of. In other words, this behavior matches the l[start:end] syntax.

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

Yields
`int`	the pointers in the specified range

def print_content(self): ¶

Print the content of this pointerlist, including the keys.

def remove(self, key): ¶

Remove a pointer from this pointer list.

Parameters
key:`str` or `bytes`	key of pointer to remove

Raises
`KeyError`	when no matching key was found.
`pyzim.exceptions.NonMutable`	if pointer list is not mutable

_keyf: a callable returning bytes = ¶

a function that returns the bytestring by which this pointer list is sorted