tools.collections — Container datatypes

Collections datatypes.

exception tools.collections.CombinedError

Bases: KeyError, IndexError

An error that gets caught by both KeyError and IndexError.

Added in version 3.0.

class tools.collections.DequeGenerator

Bases: Iterator, deque

A generator that allows items to be added during generating.

Added in version 3.0.

Changed in version 6.1: Provide a representation string.

tools.collections.EMPTY_DEFAULT = ''

class tools.collections.EmptyDefault

Bases: str, Mapping

A default for a not existing siteinfo property.

It should be chosen if there is no better default known. It acts like an empty collections, so it can be iterated through it safely if treated as a list, tuple, set or dictionary. It is also basically an empty string.

Accessing a value via __getitem__ will result in a combined KeyError and IndexError.

Added in version 3.0.

Changed in version 6.2: empty_iterator() was removed in favour of iter().

Initialise the default as an empty string.

class tools.collections.GeneratorWrapper

Bases: ABC, Generator

A Generator base class which wraps the internal generator property.

This generator iterator also has generator.close() mixin method and it can be used as Iterable and Iterator as well.

Added in version 7.6.

Example:

>>> class Gen(GeneratorWrapper):
...     @property
...     def generator(self):
...         return (c for c in 'Pywikibot')
>>> gen = Gen()
>>> next(gen)  # can be used as Iterator ...
'P'
>>> next(gen)
'y'
>>> ''.join(c for c in gen)  # ... or as Iterable
'wikibot'
>>> next(gen)  # the generator is exhausted ...
Traceback (most recent call last):
    ...
StopIteration
>>> gen.restart()  # ... but can be restarted
>>> next(gen) + next(gen)
'Py'
>>> gen.close()  # the generator may be closed
>>> next(gen)
Traceback (most recent call last):
    ...
StopIteration
>>> gen.restart()  # restart a closed generator
>>> # also send() and throw() works
>>> gen.send(None) + gen.send(None)
'Py'
>>> gen.throw(RuntimeError('Foo'))
Traceback (most recent call last):
    ...
RuntimeError: Foo

See also

PEP 342

abstract property generator: Generator[Any, Any, Any]

Abstract generator property.

restart()

Restart the generator.

Return type:

None

send(value)

Return next yielded value from generator or raise StopIteration.

The value parameter is ignored yet; usually it should be None. If the wrapped generator property exits without yielding another value this method raises StopIteration. The send method works like the next function with a GeneratorWrapper instance as parameter.

Refer generator.send() for its usage.

Raises:

TypeError – generator property is not a generator

Parameters:

value (Any)

Return type:

Any

throw(typ=None, value=None, traceback=None, val='[deprecated name of value]', tb='[deprecated name of traceback]')

Raise an exception inside the wrapped generator.

Refer generator.throw() for various parameter usage.

Changed in version 10.7: The val and tb parameters were renamed to value and traceback.

Deprecated since version 10.7: The (type, value, traceback) signature is deprecated; use single-arg signature throw(value) instead.

Raises:

• RuntimeError – No generator started

• TypeError – Invalid type for typ argument

Parameters:

• typ (BaseException | type[BaseException] | None)

• value (Any)

• traceback (TracebackType | None)

class tools.collections.RateLimit(group='unknown', hits=50, seconds=0)

Bases: NamedTuple

A namedtuple which can hold rate limit content.

This class is used by APISite.ratelimit().

Note

delay() and ratio() properties cannot be sliced or used with tuple indices. They must be used as attributes.

>>> limit = RateLimit('user', 500, 10)
>>> limit
RateLimit(group='user', hits=500, seconds=10)
>>> limit.delay
0.02
>>> limit.ratio
50.0
>>> limit._fields
('group', 'hits', 'seconds')
>>> limit._asdict()
{'group': 'user', 'hits': 500, 'seconds': 10}
>>> limit[0]
'user'
>>> limit[-1]
10
>>> user, hits, seconds = limit
>>> hits, seconds
(500, 10)
>>> newlimit = limit._replace(seconds=0)
>>> newlimit.delay
0.0
>>> newlimit.ratio
inf

Added in version 9.0.

Create new instance of RateLimit(group, hits, seconds)

Parameters:

• group (str)

• hits (int)

• seconds (int)

property delay: float

Calculate a delay value which is the inverse of ratio().

group: str

Alias for field number 0

hits: int

Alias for field number 1

property ratio: float

Calculate a ratio how many hits can be done within one second.

seconds: int

Alias for field number 2

class tools.collections.SizedKeyCollection(keyattr)

Bases: Collection

Structure to hold values where the key is given by the value itself.

A structure like a defaultdict but the key is given by the value itself and cannot be assigned directly. It returns the number of all items with len() but not the number of keys.

Samples:

>>> from pywikibot.tools.collections import SizedKeyCollection
>>> data = SizedKeyCollection('title')
>>> data.append('foo')
>>> data.append('bar')
>>> data.append('Foo')
>>> list(data)
['foo', 'Foo', 'bar']
>>> len(data)
3
>>> 'Foo' in data
True
>>> 'foo' in data
False
>>> data['Foo']
['foo', 'Foo']
>>> list(data.keys())
['Foo', 'Bar']
>>> data.remove_key('Foo')
>>> list(data)
['bar']
>>> data.clear()
>>> list(data)
[]

Added in version 6.1.

Parameters:

keyattr (str) – an attribute or method of the values to be hold with this collection which will be used as key.

append(value)

Add a value to the collection.

Return type:

None

clear()

Remove all elements from SizedKeyCollection.

Return type:

None

filter(key)

Iterate over items for a given key.

iter_values_len()

Yield key, len(values) pairs.

remove(value)

Remove a value from the container.

Return type:

None

remove_key(key)

Remove all values for a given key.

Return type:

None