fsleyes_widgets.utils.typedict

This module provides the TypeDict class, a type-aware dictionary.

class fsleyes_widgets.utils.typedict.TypeDict(initial=None)

Bases: object

A type-aware dictionary.

The purpose of the TypeDict is to allow value lookup using either classes or instances as keys. The TypeDict can be used in the same way that you would use a regular dict, but the get and __getitem__ methods have some extra functionality.

Easy to understand example

Let’s say we have a class with some properties:

import fsleyes_widgets.utils.typedict as td

class Animal(object):
    isMammal = True
    numLegs  = 4

And we want to associate some tooltips with those properties:

tooltips = td.TypeDict({

    'Animal.isMammal' : 'Set this to True for mammals, '
                        'False for reptiles.',
    'Animal.numLegs'  : 'The nuber of legs on this animal.'
})

Because we used a TypeDict, we can now look up those tooltips in a number of ways:

a = Animal()

# Lookup by string (equivalent to a normal dict lookup)
tt = tooltips['Animal.isMammal']

# Lookup by class
tt = tooltips[Animal, 'isMammal']

# Lookup by instance
tt = tooltips[a, 'isMammal']

This functionality also works across class hierarchies:

class Cat(Animal):
   numYoutubeHits = 10

tooltips = td.TypeDict({

    'Animal.isMammal'    : 'Set this to True for mammals, '
                           'False for reptiles.',
    'Animal.numLegs'     : 'The nuber of legs on this animal.',
    'Cat.numYoutubeHits' : 'Number of youtube videos this cat '
                           'has starred in.'
})

c = Cat()

isMammalTooltip    = tooltips[Cat,  'isMammal']
numLegsTooltip     = tooltips[c,    'numLegs']
youtubeHitsTooltip = tooltips[c,    'numYoutubeHits']

# Class-hierachy-aware TypeDict lookups only
# work when you pass in an instance/class as
# the key - the following will result in a
# KeyError:
t = tooltips['Cat.numLegs']

The get() method has some extra functionality for working with class hierarchies:

tooltips = td.TypeDict({

    'Animal.isMammal'    : 'Set this to True for mammals, '
                           'False for reptiles.',

    'Animal.numLegs'     : 'The nuber of legs on this animal.',

    'Cat.numLegs'        : 'This will be equal to four for all cats, '
                            'but could be less for disabled cats, '
                            'or more for lucky cats.',

    'Cat.numYoutubeHits' : 'Number of youtube videos this cat '
                           'has starred in.'
})

print tooltips.get((c, 'numLegs'))
#  'This will be equal to four for all cats, but could '
#  'be less for disabled cats, or more for lucky cats.'

print tooltips.get((c, 'numLegs'), allhits=True)
# ['This will be equal to four for all cats, but could '
#  'be less for disabled cats, or more for lucky cats.',
#  'The nuber of legs on this animal.']

print tooltips.get((c, 'numLegs'), allhits=True, bykey=True)
# {('Animal', 'numLegs'): 'The nuber of legs on this animal.',
#  ('Cat',    'numLegs'): 'This will be equal to four for all cats, '
#                         'but could be less for disabled cats, or '
#                         'more for lucky cats.'}

Boring technical description

The TypeDict is a custom dictionary which allows classes or class instances to be used as keys for value lookups, but internally transforms any class/instance keys into strings. Tuple keys are supported. Value assignment with class/instance keys is not supported. All keys are transformed via the tokenifyKey() method before being internally used and/or stored.

If a class/instance is passed in as a key, and there is no value associated with that class, a search is performed on all of the base classes of that class to see if any values are present for them.

Create a TypeDict.

Parameters:

initial – Dictionary containing initial values.

keys()

values()

items()

tokenifyKey(key)

Turns a dictionary key, which may have been specified as a string, or a combination of strings and types, into a tuple.

get(key, default=None, allhits=False, bykey=False, exact=False)

Retrieve the value associated with the given key. If no value is present, return the specified default value, which itself defaults to None.

If the specified key contains a class or instance, and the exact argument is False (the default), the entire class hierarchy is searched, and the first value present for the class, or any base class, are returned. If exact is True and no value exists for the specific class, the default is returned.

If exact is False and the allhits argument evaluates to True, the entire class hierarchy is searched, and all values present for the class, and any base class, are returned as a sequence.

If allhits is True and the bykey parameter is also set to True, a dictionary is returned rather than a sequence, where the dictionary contents are the subset of this dictionary, containing the keys which equated to the given key, and their corresponding values.