Skip to main content

DCI lookups in Python (inspired by Netbeans Platform Lookups API)

Project description

PyPI version shields.io PyPI download shields.io PyPI Python version shields.io GitHub license shields.io

GitHub commits since shields.io GitHub build shields.io Codecov shields.io

lookups - Find object instances

DCI lookups for Python (inspired by Netbeans Platform Lookups API)

Principle

A lookup is like a dict where you can store object instances as values. And the search keys are their type classes.

Simply.

But lookups implements a bit more than that:

  • You can also lookup by parent class and not just the most subclasses of an instance.
  • You can get hold of a lookups.Result, which allows you to register a listener for a given class search. You will be notified when an instance of that class is added/removed from the lookup.
  • Deferred instanciation with lookups.Convertor. That is, an 'instance' can appear in a lookup but not be instanciated until it is actually used (ie. looked up). Useful for heavy objects or plugins.
  • lookups.Item can provide you with additional info on an instance: display string, persistence ID string, type, and instance itself.

lookups.GenericLookup

This is the most basic but versatile and dynamic lookup. (HINT: For Java folks, it corresponds to your AbstractLookup ;-) ).

It comes in two main parts:

  • lookups.InstanceContent provide write-access to the lookup: add/set/remove instances.
  • lookups.GenericLookup provide read-access to search in the lookup.
from lookups import InstanceContent, GenericLookup

my_content = InstanceContent()
my_lookup = GenericLookup(my_content)

# Adds some objects
class ParentClass:
    pass

class ChildClass(ParentClass):
    pass

parent = ParentClass()
my_content.add(parent)
child1 = ChildClass()
my_content.add(child1)
child2 = ChildClass()
my_content.add(child2)

...

# lookup(cls): get first matching instance
# a_match will be any of parent, child1 or child2
a_parent_match = my_lookup.lookup(ParentClass)

# lookup_all(cls): get all matching instances
# all_parent_matches is an immutable sequence
#     of parent, child1 and child2
all_parent_matches = my_lookup.lookup_all(ParentClass)
# all_children_matches is an immutable sequence
#     of child1 and child2
all_children_matches = my_lookup.lookup_all(ChildClass)

# lookup_result(cls): get a Result object for the searched class
parent_result = my_lookup.lookup_result(ParentClass)
# all_instances(): all instances corresponding to the searched
#     class (ie. similar to plain lookup_all())
parent_result.all_instances()
# all_classes(): Immutable set of all types in the result.
#     Here it would be set(ParentClass, ChildClass)
parent_result.all_classes()

# Lookup result listener
def call_me_back(result):
    print('Result changed. Instances are now', result.all_instances())

parent_result.add_lookup_listener(call_me_back)

...

my_content.remove(child1)
# -> This will invoke call_me_back()
# You can also provide a `concurrent.futures.Executor` when
# creating the content to control how the listeners are called:
#     InstanceContent(notify_in: Executor = None).

Other lookups

  • lookups.Lookup.get_default(): The default lookup in a system.
  • lookups.ProxyLookup: A lookup that merge results from several lookups.
  • lookups.DelegatedLookup: A lookup that redirects to another (dynamic) lookup, through a LookupProvider.
  • lookups.EntryPointLookup: A lookup loading its instances from a setuptools entry point group (ie. provided by any installed package).
  • lookups.fixed: Simple unmodifiable lookup. Content is set at creation time. Will be one of:
    • lookup.SimpleLookup: A basic lookup with a static content.
    • lookups.singleton: Unmodifiable lookup that contains just one fixed object.
    • lookups.EmptyLookup: A lookup containing nothing.

Individual Contributors

A list of people who have contributed to Lookups in order of their first contribution.

Format: Name-or-Well-known-alias <email@domain.tld> (url)

Please, add yourself when you contribute!

Original Netbeans authors of Lookup API

  • Jaroslav Tulach - Lookup API, AbstractLookup, InstanceContent, ArrayStorage
  • Marian Petras - Singleton lookup
  • David Strupl - Common lookup implementations

CHANGELOG

0.3.0 - XX XXXXXXXX 2021

  • Adds a EntryPointLookup.
  • Adds a DelegatedLookup.
  • Adds a ProxyLookup.
  • Adds a proper resolution for system default lookup Lookup.get_default().
  • Fixes issue with listeners registration disappearing immediately when using object-bound methods.
  • Content of a GenericLookup can now behave like a Container (ie. you can do things like "obj in content").
  • When an instance is not hashable, provides an alternative using id() of the object in order to be able to store it in a hash-based storage (set, dictionary).
  • New syntactic sugar: call directly a lookup object as shortcut for the lookup method. Ie., instead of writing "lookup.lookup(...)" you can now write "lookup(...)".
  • Missing declared dependency in typing_extensions.
  • Abstract methods now raise NotImplementedError

0.2.0 - 06 February 2020

  • Provides GenericLookup and InstanceContent, based on SetStorage. These are the first dynamic lookups. They are based on Netbeans' AbstractLookup, InstanceContent and ArrayStorage.
  • Lookup listeners are just simple callables now.
  • Follows PEP 561 for packages providing typing information.
  • Improved quality assurance process (using Github Workflow as CI).
  • First (proto-)documentation.

0.1.0 - 18 May 2019

  • Initial dump of code.
  • Defines the public API for lookups.
  • Provides fixed lookup: members are defined at instantiation time and never change.
  • Provides singleton lookup: only one member defined at instantiation time and never change.
  • Provides empty lookup: a special lookup with nothing in it.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lookups-0.3.0.tar.gz (41.2 kB view hashes)

Uploaded source

Built Distribution

lookups-0.3.0-py3-none-any.whl (30.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page