Improved container classes

The containers module defines improved container classes, such as lists:

• List: a subclass of the builtin list class, with added methods, such as index_append;

• Bijectivelist: a replacement for the list class for use with 1-1 relationships

  where index lookup via dict makes sense; and

• ShelveBijectivelist: a replacement for the list class for use with 1-1 relationships

  where index lookup via shelve makes sense. This class uses shelve to cope with cases where a dict would be too large to store in memory.

AUTHORS:

• Paul Leopardi (2016-08-21): initial version

class boolean_cayley_graphs.containers.BijectiveList(other_list=None)

Bases: sage.structure.sage_object.SageObject, boolean_cayley_graphs.saveable.Saveable

Replacement for the list class with only a few methods, such as __getitem__, index, and index_append.

List lookup for __getitem__ uses a list named _item. Index lookup for index and index_append uses a dict named _index`. This class is used for 1-1 relationships where index lookup via ``dict makes sense.

Warning

Initialization from a non-empty list can easily break the 1-1 relationship between index and item in a BijectiveList.

EXAMPLES:

Initialize from a list.

sage: from boolean_cayley_graphs.containers import BijectiveList
sage: BL = BijectiveList(["1","2","3"])
sage: BL.get_list()
['1', '2', '3']
sage: dict(sorted(BL.get_dict().items()))
{'1': 0, '2': 1, '3': 2}
sage: del BL

TESTS:

sage: from boolean_cayley_graphs.containers import BijectiveList
sage: L = BijectiveList([1,2,4])
sage: print(L)
BijectiveList(1,2,4)

sage: from boolean_cayley_graphs.containers import BijectiveList
sage: L = BijectiveList([1,2,4])
sage: latex(L)
\text{\texttt{BijectiveList(1,2,4)}}

close_dict()

Dummy method to match the interface of ShelveBijectiveList.

TESTS:

sage: from boolean_cayley_graphs.containers import BijectiveList
sage: BL = BijectiveList(["1","2","6"])
sage: BL.close_dict()
sage: BL.remove_dict()

get_dict()

Get the dict part of the BijectiveList.

INPUT:

• self – the current object.

EXAMPLES:

sage: from boolean_cayley_graphs.containers import BijectiveList
sage: BL = BijectiveList([1,2,5])
sage: dict(sorted(BL.get_dict().items()))
{1: 0, 2: 1, 5: 2}
sage: del BL

get_list()

Get the list part of the BijectiveList.

INPUT:

• self – the current object.

EXAMPLES:

sage: from boolean_cayley_graphs.containers import BijectiveList
sage: BL = BijectiveList([1,2,5])
sage: BL.get_list()
[1, 2, 5]
sage: del BL

index(item)

Return the index of a given item.

Use a dict lookup using _index instead of calling index on the list. If the dict lookup yields a KeyError then raise a ValueError.

INPUT:

• self – the current object.

• item – the item to look up.

OUTPUT:

A non-negative integer indicating the index of item within self.

EXAMPLES:

sage: from boolean_cayley_graphs.containers import BijectiveList
sage: BL = BijectiveList([1,2,4])
sage: BL.index(2)
1
sage: BL.get_list()
[1, 2, 4]
sage: dict(sorted(BL.get_dict().items()))
{1: 0, 2: 1, 4: 2}
sage: del BL

TESTS:

sage: from boolean_cayley_graphs.containers import BijectiveList
sage: BL = BijectiveList([1,2,4])
sage: try:
....:     BL.index(3)
....: except ValueError as e:
....:     print("ValueError: {0}".format(e.args[0]))
....: finally:
....:     del BL
ValueError: 3 is not in list

index_append(item)

Return the index of a given item, appending it if necessary.

Use a dict lookup using _index instead of calling index on the list. If the dict lookup yields a KeyError` then set result to the length of self, append item to self, and add result to _index.

INPUT:

• self – the current object.

• item – the item to look up, and append if necessary.

OUTPUT:

A non-negative integer indicating the index of item within self.

EFFECT:

The item item may be appended to self.

EXAMPLES:

sage: from boolean_cayley_graphs.containers import BijectiveList
sage: BL = BijectiveList([1,2,4])
sage: BL.index_append(2)
1
sage: BL.get_list()
[1, 2, 4]
sage: BL.index_append(3)
3
sage: BL.get_list()
[1, 2, 4, 3]
sage: dict(sorted(BL.get_dict().items()))
{1: 0, 2: 1, 3: 3, 4: 2}
sage: del BL

remove_dict()

Remove the dictionary.

TESTS:

sage: from boolean_cayley_graphs.containers import BijectiveList
sage: BL = BijectiveList(["1","2","6"])
sage: BL.close_dict()
sage: BL.remove_dict()
sage: try:
....:     BL._index
....: except AttributeError:
....:     pass

sync()

Dummy method to match the interface of ShelveBijectiveList.

TESTS:

sage: from boolean_cayley_graphs.containers import BijectiveList
sage: BL = BijectiveList(["1","2","6"])
sage: BL.sync()
sage: del BL

class boolean_cayley_graphs.containers.List(iterable=(), /)

Bases: list, sage.structure.sage_object.SageObject, boolean_cayley_graphs.saveable.Saveable

Subclass of list with added methods, such as index_append.

TESTS:

sage: from boolean_cayley_graphs.containers import List
sage: L = List([1,2,4])
sage: print(L)
[1, 2, 4]

sage: from boolean_cayley_graphs.containers import List
sage: L = List([1,2,4])
sage: latex(L)
\text{\texttt{[1,{ }2,{ }4]}}

index_append(item)

Return the index of a given item, appending it if necessary.

If the inherited list index method for self yields a ValueError`, then set result to the length of `self, and append item to self.

INPUT:

• self – the current object.

• item – the item to look up, and append if necessary.

OUTPUT:

A non-negative integer indicating the index of item within self.

EFFECT:

The item item may be appended to self.

EXAMPLES:

sage: from boolean_cayley_graphs.containers import List
sage: L = List([1,2,4])
sage: L.index_append(2)
1
sage: L
[1, 2, 4]
sage: L.index_append(3)
3
sage: L
[1, 2, 4, 3]
sage: del L

class boolean_cayley_graphs.containers.ShelveBijectiveList(other_list=None)

Bases: boolean_cayley_graphs.containers.BijectiveList

Replacement for the list class with only a few methods, such as __getitem__, index, and index_append.

List lookup for __getitem__ uses a list named _item. Index lookup for index and index_append uses a shelve named _index. This class is used for 1-1 relationships where index lookup via shelve makes sense.

Note

This class uses shelve to cope with situations where a dict would be too large to fit into memory.

Warning

Initialization from a non-empty list works only for lists of strings.

Warning

Initialization from a non-empty list can easily break the 1-1 relationship between index and item in a ShelveBijectiveList.

EXAMPLES:

Initialize from a list.

sage: from boolean_cayley_graphs.containers import ShelveBijectiveList
sage: SBL = ShelveBijectiveList(["1","2","4"])
sage: SBL.get_list()
['1', '2', '4']
sage: dict(sorted(SBL.get_dict().items()))
{'1': 0, '2': 1, '4': 2}
sage: del SBL

TESTS:

sage: from boolean_cayley_graphs.containers import ShelveBijectiveList
sage: L = ShelveBijectiveList(["1","2","4"])
sage: print(L)
ShelveBijectiveList('1','2','4')

sage: from boolean_cayley_graphs.containers import ShelveBijectiveList
sage: L = ShelveBijectiveList(["1","2","4"])
sage: latex(L)
\text{\texttt{ShelveBijectiveList('1','2','4')}}

close_dict()

Synchronize and close the persistent dictionary on disk.

TESTS:

sage: from boolean_cayley_graphs.containers import ShelveBijectiveList
sage: SBL = ShelveBijectiveList(["1","2","6"])
sage: SBL.close_dict()
sage: SBL.remove_dict()

remove_dict()

Remove the files used for the persistent dictionary on disk.

Warning

Use close_dict first.

TESTS:

sage: import glob
sage: from boolean_cayley_graphs.containers import ShelveBijectiveList
sage: SBL = ShelveBijectiveList(["1","2","6"])
sage: SBL.close_dict()
sage: SBL.remove_dict()
sage: glob.glob(SBL.shelve_file_name + "*")
[]

sync()

Synchronize the persistent dictionary on disk, if feasible.

TESTS:

sage: from boolean_cayley_graphs.containers import ShelveBijectiveList
sage: SBL = ShelveBijectiveList(["1","2","6"])
sage: SBL.sync()
sage: del SBL