Api

This part of the documentation lists the full API reference of all public classes and functions.

qjoin.on(collection: Iterable[Any]) → Qjoin

Start a qjoin query on a collection

>>> spacecrafts = [
>>>    {'name': 'Kepler', 'cospar_id': '2009-011A', 'satcat': 34380},
>>>    {'name': 'GRAIL (A)', 'cospar_id': '2011-046', 'satcat': 37801},
>>>    {'name': 'InSight', 'cospar_id': '2018-042a', 'satcat': 43457},
>>>    {'name': 'lucy', 'cospar_id': '2021-093A', 'satcat': 49328},
>>>    {'name': 'Psyche', 'cospar_id': None, 'satcat': None},
>>> ]
>>>
>>> for spacecraft in qjoin.on(spacecrafts):
>>>     print(spacecraft['name'])

Qjoin.join(collection: Iterable[Any], key: int | str | Callable[[Any], Hashable] | None = None, left: int | str | Callable[[Any], Hashable] | None = None, right: int | str | Callable[[Any], Hashable] | None = None) → Qjoin

Performs a join in a qjoin query with the base collection.

join must define a join key. It is possible to use a simple key shared by the base collection and the collection to be joined with key parameter or to use a key specific to each collection with left and right parameters.

A key can either be the name of a field in the collection, or a function that takes an element of the collection as a parameter and returns a value on which to join.

A first technique is to use a simple key as the join key.

>>> spacecrafts = [
>>>    {'name': 'Kepler', 'cospar_id': '2009-011A', 'satcat': 34380},
>>>    {'name': 'GRAIL (A)', 'cospar_id': '2011-046', 'satcat': 37801},
>>>    {'name': 'InSight', 'cospar_id': '2018-042a', 'satcat': 43457},
>>>    {'name': 'lucy', 'cospar_id': '2021-093A', 'satcat': 49328},
>>>    {'name': 'Psyche', 'cospar_id': None, 'satcat': None},
>>> ]
>>>
>>> spacecraft_properties = [
>>>     {'name': 'Kepler', 'dimension': (4.7, 2.7, None), 'power': 1100, 'launch_mass': 1052.4},
>>>     {'name': 'GRAIL (A)', 'launch_mass': 202.4},
>>>     {'name': 'InSight', 'dimension': (6, 1.56, 1), 'power': 600, 'launch_mass': 694},
>>>     {'name': 'lucy', 'dimension': (13, None, None), 'power': 504, 'launch_mass': 1550},
>>> ]
>>>
>>>
>>> global_spacecrafts = qjoin.on(spacecrafts).join(spacecrafts_properties, key='name')
>>> for spacecraft, spacecraft_properties in global_spacecrafts:
>>>     print(spacecraft['name'])
>>>     print('-' * len(spacecraft['name']))
>>>     print(spacecrafts_property['dimension'])
>>>     print('')
>>>     print('')

A second technique is to use a function to generate a more complex join key. This function must return a hashable type in order to be used as a join key.

>>>
>>> global_spacecrafts = qjoin.on(spacecrafts).join(spacecrafts_properties, key=lambda s: s['name'].lower())
>>> for spacecraft, spacecraft_properties in global_spacecrafts:
>>>     print(spacecraft['name'])
>>>     print('-' * len(spacecraft['name']))
>>>     print(spacecrafts_property['dimension'])
>>>     print('')
>>>     print('')

A third technique is to use a different key for each collection. This is useful when the key is different. The join has to be describe with left and right parameters. Parameters may be either a string or a function.

>>> spacecraft_properties = [
>>>     {'spacecraft': 'Kepler', 'dimension': (4.7, 2.7, None), 'power': 1100, 'launch_mass': 1052.4},
>>>     {'spacecraft': 'GRAIL (A)', 'launch_mass': 202.4},
>>>     {'spacecraft': 'InSight', 'dimension': (6, 1.56, 1), 'power': 600, 'launch_mass': 694},
>>>     {'spacecraft': 'lucy', 'dimension': (13, None, None), 'power': 504, 'launch_mass': 1550},
>>> ]
>>> global_spacecrafts = qjoin.on(spacecrafts).join(spacecrafts_properties, left=lambda s: s['name'].lower(), right='spacecraft')

The join function is lazy. Until a render function is called like .all or a loop is used on the QJoin instance, the join is just declared.

Qjoin.all() → List[Tuple[Any, ...]]

Return the result of qjoin query in a list of tuple where the first element of base collection is the first element of the first tuple, the first element of the first join is the second in the tuple

>>> spacecrafts = [
>>>    {'name': 'Kepler', 'cospar_id': '2009-011A', 'satcat': 34380},
>>>    {'name': 'GRAIL (A)', 'cospar_id': '2011-046', 'satcat': 37801},
>>>    {'name': 'InSight', 'cospar_id': '2018-042a', 'satcat': 43457},
>>>    {'name': 'lucy', 'cospar_id': '2021-093A', 'satcat': 49328},
>>>    {'name': 'Psyche', 'cospar_id': None, 'satcat': None},
>>> ]
>>>
>>> for spacecraft in qjoin.on(spacecrafts).all():
>>>     print(spacecraft['name'])

Qjoin.as_aggregate(klass: Type[T], attributes: List[str]) → List[T]

Creates a list of type T objects from the data that has been joined. Data is written to the attributes specified in the attributes list in their join order.

>>> @dataclasses.dataclass
>>> class SpacecraftsAggregate:
>>>   spacecraft: str
>>>   properties: str

>>> spacecrafts = [
>>>   {'name': 'Kepler', 'cospar_id': '2009-011A', 'satcat': 34380},
>>>   {'name': 'GRAIL (A)', 'cospar_id': '2011-046', 'satcat': 37801},
>>>   {'name': 'InSight', 'cospar_id': '2018-042a', 'satcat': 43457},
>>>   {'name': 'lucy', 'cospar_id': '2021-093A', 'satcat': 49328},
>>>   {'name': 'Psyche', 'cospar_id': None, 'satcat': None},
>>> ]

>>> spacecraft_properties = [
>>>   {'spacecraft': 'Kepler', 'dimension': (4.7, 2.7, None), 'power': 1100, 'launch_mass': 1052.4},
>>>   {'spacecraft': 'GRAIL (A)', 'launch_mass': 202.4},
>>>   {'spacecraft': 'InSight', 'dimension': (6, 1.56, 1), 'power': 600, 'launch_mass': 694},
>>>   {'spacecraft': 'lucy', 'dimension': (13, None, None), 'power': 504, 'launch_mass': 1550},
>>> ]
>>>
>>> for spacecraft in qjoin.on(spacecrafts)         >>>                        .join(spacecraft_properties, left='name', right='spacecraft')         >>>                        .as_aggregate(SpacecraftsAggregate, ['spacecraft', 'properties']]):
>>>     print(spacecraft.properties['dimension'])