# graphtage.utils

Generic utility functions and classes.

## utils classes

### HashableCounter

class graphtage.utils.HashableCounter(*args, **kwargs)

Bases: `Generic`[`T`], `Counter`[`T`], `Counter`

A `Counter` that supports being hashed even though it is mutable.

```>>> Counter('abbb') + Counter('bcc')
Counter({'b': 4, 'c': 2, 'a': 1})
```
__and__(other)

Intersection is the minimum of corresponding counts.

```>>> Counter('abbb') & Counter('bcc')
Counter({'b': 1})
```
__delitem__(elem)

Like dict.__delitem__() but does not raise KeyError for missing values.

Inplace add from another counter, keeping only positive counts.

```>>> c = Counter('abbb')
>>> c += Counter('bcc')
>>> c
Counter({'b': 4, 'c': 2, 'a': 1})
```
__iand__(other)

Inplace intersection is the minimum of corresponding counts.

```>>> c = Counter('abbb')
>>> c &= Counter('bcc')
>>> c
Counter({'b': 1})
```
__init__(*args, **kwargs)
__ior__(other)

Inplace union is the maximum of value from either counter.

```>>> c = Counter('abbb')
>>> c |= Counter('bcc')
>>> c
Counter({'b': 3, 'c': 2, 'a': 1})
```
__isub__(other)

Inplace subtract counter, but keep only results with positive counts.

```>>> c = Counter('abbbc')
>>> c -= Counter('bccd')
>>> c
Counter({'b': 2, 'a': 1})
```
__missing__(key)

The count of elements not in the Counter is zero.

__neg__()

Subtracts from an empty counter. Strips positive and zero counts, and flips the sign on negative counts.

__or__(other)

Union is the maximum of value in either of the input counters.

```>>> Counter('abbb') | Counter('bcc')
Counter({'b': 3, 'c': 2, 'a': 1})
```
__pos__()

Adds an empty counter, effectively stripping negative and zero counts

__sub__(other)

Subtract count, but keep only results with positive counts.

```>>> Counter('abbbc') - Counter('bccd')
Counter({'b': 2, 'a': 1})
```
_keep_positive()

Internal method to strip elements with a negative or zero count

clear() None.  Remove all items from D.
copy()

Return a shallow copy.

elements()

Iterator over elements repeating each as many times as its count.

Examples:

```>>> c = Counter('ABCABC')
>>> sorted(c.elements())
['A', 'A', 'B', 'B', 'C', 'C']

# Knuth's example for prime factors of 1836:  2**2 * 3**3 * 17**1
>>> prime_factors = Counter({2: 2, 3: 3, 17: 1})
>>> product = 1
>>> for factor in prime_factors.elements():     # loop over factors
...     product *= factor                       # and multiply them
>>> product
1836
```

Note

If an element’s count has been set to zero or is a negative number, elements() will ignore it.

classmethod fromkeys(iterable, v=None)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() a set-like object providing a view on D's items
keys() a set-like object providing a view on D's keys
most_common(n=None)

List the n most common elements and their counts from the most common to the least. If n is None, then list all element counts.

```>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]
```
pop(k[, d]) v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

subtract(iterable=None, /, **kwds)

Like dict.update() but subtracts counts instead of replacing them. Counts can be reduced below zero. Both the inputs and outputs are allowed to contain zero and negative counts.

Source can be an iterable, a dictionary, or another Counter instance.

```>>> c = Counter('which')
>>> c.subtract('witch')             # subtract elements from another iterable
>>> c.subtract(Counter('watch'))    # subtract elements from another counter
>>> c['h']                          # 2 in which, minus 1 in witch, minus 1 in watch
0
>>> c['w']                          # 1 in which, minus 1 in witch, minus 1 in watch
-1
```
update(iterable=None, /, **kwds)

Source can be an iterable, a dictionary, or another Counter instance.

```>>> c = Counter('which')
>>> c.update('witch')           # add elements from another iterable
>>> d = Counter('watch')
>>> c.update(d)                 # add elements from another counter
>>> c['h']                      # four 'h' in which, witch, and watch
4
```
values() an object providing a view on D's values

### OrderedCounter

class graphtage.utils.OrderedCounter(iterable=None, /, **kwds)

A counter that remembers the order elements are first encountered

```>>> Counter('abbb') + Counter('bcc')
Counter({'b': 4, 'c': 2, 'a': 1})
```
__and__(other)

Intersection is the minimum of corresponding counts.

```>>> Counter('abbb') & Counter('bcc')
Counter({'b': 1})
```
__delitem__(elem)

Like dict.__delitem__() but does not raise KeyError for missing values.

Inplace add from another counter, keeping only positive counts.

```>>> c = Counter('abbb')
>>> c += Counter('bcc')
>>> c
Counter({'b': 4, 'c': 2, 'a': 1})
```
__iand__(other)

Inplace intersection is the minimum of corresponding counts.

```>>> c = Counter('abbb')
>>> c &= Counter('bcc')
>>> c
Counter({'b': 1})
```
__init__(iterable=None, /, **kwds)

Create a new, empty Counter object. And if given, count elements from an input iterable. Or, initialize the count from another mapping of elements to their counts.

```>>> c = Counter()                           # a new, empty counter
>>> c = Counter('gallahad')                 # a new counter from an iterable
>>> c = Counter({'a': 4, 'b': 2})           # a new counter from a mapping
>>> c = Counter(a=4, b=2)                   # a new counter from keyword args
```
__ior__(other)

Inplace union is the maximum of value from either counter.

```>>> c = Counter('abbb')
>>> c |= Counter('bcc')
>>> c
Counter({'b': 3, 'c': 2, 'a': 1})
```
__isub__(other)

Inplace subtract counter, but keep only results with positive counts.

```>>> c = Counter('abbbc')
>>> c -= Counter('bccd')
>>> c
Counter({'b': 2, 'a': 1})
```
__missing__(key)

The count of elements not in the Counter is zero.

__neg__()

Subtracts from an empty counter. Strips positive and zero counts, and flips the sign on negative counts.

__or__(other)

Union is the maximum of value in either of the input counters.

```>>> Counter('abbb') | Counter('bcc')
Counter({'b': 3, 'c': 2, 'a': 1})
```
__pos__()

Adds an empty counter, effectively stripping negative and zero counts

__sub__(other)

Subtract count, but keep only results with positive counts.

```>>> Counter('abbbc') - Counter('bccd')
Counter({'b': 2, 'a': 1})
```
_keep_positive()

Internal method to strip elements with a negative or zero count

clear() None.  Remove all items from od.
copy()

Return a shallow copy.

elements()

Iterator over elements repeating each as many times as its count.

Examples:

```>>> c = Counter('ABCABC')
>>> sorted(c.elements())
['A', 'A', 'B', 'B', 'C', 'C']

# Knuth's example for prime factors of 1836:  2**2 * 3**3 * 17**1
>>> prime_factors = Counter({2: 2, 3: 3, 17: 1})
>>> product = 1
>>> for factor in prime_factors.elements():     # loop over factors
...     product *= factor                       # and multiply them
>>> product
1836
```

Note

If an element’s count has been set to zero or is a negative number, elements() will ignore it.

classmethod fromkeys(iterable, v=None)

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() a set-like object providing a view on D's items
keys() a set-like object providing a view on D's keys
most_common(n=None)

List the n most common elements and their counts from the most common to the least. If n is None, then list all element counts.

```>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]
```
move_to_end(key, last=True)

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

pop(k[, d]) v, remove specified key and return the corresponding

value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem(last=True)

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

setdefault(key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

subtract(iterable=None, /, **kwds)

Like dict.update() but subtracts counts instead of replacing them. Counts can be reduced below zero. Both the inputs and outputs are allowed to contain zero and negative counts.

Source can be an iterable, a dictionary, or another Counter instance.

```>>> c = Counter('which')
>>> c.subtract('witch')             # subtract elements from another iterable
>>> c.subtract(Counter('watch'))    # subtract elements from another counter
>>> c['h']                          # 2 in which, minus 1 in witch, minus 1 in watch
0
>>> c['w']                          # 1 in which, minus 1 in witch, minus 1 in watch
-1
```
update(iterable=None, /, **kwds)

Source can be an iterable, a dictionary, or another Counter instance.

```>>> c = Counter('which')
>>> c.update('witch')           # add elements from another iterable
>>> d = Counter('watch')
>>> c.update(d)                 # add elements from another counter
>>> c['h']                      # four 'h' in which, witch, and watch
4
```
values() an object providing a view on D's values

### Sized

class graphtage.utils.Sized(*args, **kwargs)

Bases: `Protocol`

A protocol for objects that have a `getsizeof` function.

__init__(*args, **kwargs)
getsizeof: Callable[[], int]

Returns the size of this object.

### SparseMatrix

class graphtage.utils.SparseMatrix(num_rows: = None, num_cols: = None, default_value: T | None = None)

Bases: `Sized`, `Generic`[`T`], `Mapping`[`int`, `MutableMapping`[`int`, `Optional`[`T`]]]

A sparse matrix that can store arbitrary Python objects.

For sparse matrices storing homogeneous items and/or native types, it is more efficient to use an implementation like a scipy sparse matrix.

class SparseMatrixRow(row_num: int, num_cols: = None, default_value: T | None = None)

Bases: `Sized`, `MutableMapping`[`int`, `Optional`[`T`]]

A row of a sparse matrix.

__getitem__(col: int) T | None

Returns the value of the given column of this row.

Parameters:

col – The index of the column to get.

Returns:

The value of the column, or the default value if it has not yet been set.

Return type:

Optional[T]

Raises:

IndexError – If `self.num_cols` is not `None` and `col` is greater than or equal to it.

__init__(row_num: int, num_cols: = None, default_value: T | None = None)

Initializes a sparse matrix row.

Parameters:
• row_num – The index of this row.

• num_cols – An optional number of columns in this row. If omitted, this row will be unbounded and allow insertion and access at any column index.

• default_value – An optional default value to use if a column is accessed before it is assigned.

__iter__()

Iterates over the indexes of columns that have been set in this row.

__len__() int

Returns the number of cells defined this row.

clear()

Clears the contents of this row.

default_value: T | None

The default value for this row.

get(k[, d]) D[k] if k in D, else d.  d defaults to None.
getsizeof() int

Returns an approximation of the number of bytes used by this row in memory.

This is equivalent to:

```return sys.getsizeof(self) + getsizeof(self.row)
```
items() a set-like object providing a view on D's items
keys() a set-like object providing a view on D's keys
num_cols: int | None

The number of columns in this row.

pop(k[, d]) v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

row: Dict[int, T | None]

Data structure holding the contents of this row.

row_num: int

The index of this row.

setdefault(k[, d]) D.get(k,d), also set D[k]=d if k not in D
shape() int

The number of columns in this row.

This is equivalent to:

```if self.num_cols is None:
if self.row:
return max(self.row.keys()) + 1
else:
return 0
else:
return self.num_cols
```
update([E, ]**F) None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() an object providing a view on D's values
__getitem__(row: int)

Returns the value of the given row of this matrix.

Parameters:

row – The index of the row to get.

Returns:

The contents of the row.

Return type:

MutableMapping[int, Optional[T]]

Raises:

IndexError – If `self.num_rows` is not `None` and `row` is greater than or equal to it.

__init__(num_rows: = None, num_cols: = None, default_value: T | None = None)

Initializes a sparse matrix.

Parameters:
• num_rows – An optional bound on the number of rows.

• num_cols – An optional bound on the number of columns.

• default_value – An optional default value to return if cells are accessed before they are set.

__len__() int

Returns the number of rows in this matrix.

If `self.num_rows` is `None`, this will return the maximum row index of a cell that has been set, plus one.

clear()

Clears the contents of this matrix.

default_value: T | None

The default value to return if cells are accessed before they are set.

get(k[, d]) D[k] if k in D, else d.  d defaults to None.
getsizeof() int

Calculates the approximate memory footprint of this matrix in bytes.

items() a set-like object providing a view on D's items
keys() a set-like object providing a view on D's keys
num_cols: int | None

The number of columns in this matrox, or `None` if there is no bound.

num_filled_elements() int

Counts the number of elements in this matrix that have been explicitly set.

num_rows: int | None

The number of rows in this matrix, or `None` if there is no bound.

rows: Dict[int, SparseMatrixRow]

The rows of this matrix.

shape() Tuple[int, int]

Returns the (number of rows, number of columns) of this matrix.

values() an object providing a view on D's values

### Tempfile

class graphtage.utils.Tempfile(contents: bytes, prefix: = None, suffix: = None)

Bases: `object`

Creates a temporary file containing a given byte sequence.

The file will automatically be cleaned up after its use. This is useful for interacting with functions and libraries that only accept a path and not a stream object.

Examples

```>>> from graphtage.utils import Tempfile
>>> with Tempfile(b"foo") as tmp:
...     print(tmp)
/var/folders/bs/hrvzrctx6tg2_j17gb6wckph0000gn/T/tmpkza5fvr_
>>> with Tempfile(b"foo") as tmp:
...     with open(tmp, 'r') as f:
foo
```
__enter__() str

Constructs a tempfile, returning the path to the file.

__exit__(type, value, traceback)

Automatically cleans up the tempfile.

__init__(contents: bytes, prefix: = None, suffix: = None)

Initializes a Tempfile

Parameters:
• contents – The contents to be populated in the file.

• prefix – An optional prefix for the filename.

• suffix – An optional suffix for the filename.

## utils functions

### getsizeof

graphtage.utils.getsizeof(obj) int

A function to calculate the memory footprint of an object.

If the object implements the `Sized` protocol (i.e., if it implements a `getsizeof` method), then this is used:

```if hasattr(obj, 'getsizeof'):
return obj.getsizeof()
```

If the object is a list or tuple, then:

```return sys.getsizeof(obj) + sum(getsizeof(i) for i in obj)
```

If the object is a dict, then:

```return sys.getsizeof(obj) + sum(getsizeof(key) + getsizeof(value) for key, value in obj.items())
```

Otherwise:

```return sys.getsizeof(obj)
```
Parameters:

obj – The object to measure.

Returns:

An approximation of the memory footprint of the object, in bytes.

Return type:

int

### largest

graphtage.utils.largest(*sequence: T | Iterable[T], n: int = 1, key: Callable[[T], Any] | None = None) Iterator[T]

### smallest

graphtage.utils.smallest(*sequence: T | Iterable[T], n: int = 1, key: Callable[[T], Any] | None = None) Iterator[T]