impl

The user can define the relationship (one-to-many, many-to-many) between entities.

There are three types of DynamoDB item:

• Entity: the main item that represents the entity.

• OneToManyRelationship: the item that represents the one-to-many relationship.

• ManyToManyRelationship: the item that represents the many-to-many relationship.

Let’s use YouTube as an example:

• Entity: User, Video, Channel, Playlist.

• OneToManyRelationship: Video Ownership, Channel Ownership, Playlist Ownership.

• ManyToManyRelationship: Video Channel Association, Video Playlist Association,

  User Subscription, Channel Subscription.

All three types of items has to have a unique name. The name will be used in partition key, sort key and type attribute naming convention. I recommend to keep the name short and simple.

One the user declared the relationship metadata, the RelationshipSetting will be a helper class to provide lots of utility functions to Create, Update, Delete and Select items by relationship.

class pynamodb_mate.patterns.relationship.impl.BaseLookupIndex

The lookup index uses the sort key as the hash key to provide reverse lookup capability.

class pynamodb_mate.patterns.relationship.impl.BaseEntity(hash_key: Optional[Any] = None, range_key: Optional[Any] = None, **attributes)

Main entity item. Base class for all entity items and relationship items. In DynamoDB, we put all kinds of entities into the same table, and use the type attribute to distinguish them.

It has to have a BaseLookupIndex as the lookup index. You can declare more index as needed.

Parameters:

• pk – partition key can only have alpha letter and hyphen. You can NOT use underscore in the partition key. For entity item, it is the unique id.

• sk – sort key can only have alpha letter and hyphen.

For entity item, it is always “${entity_id}_–root–”. For relationship item,

pk and sk are the two unique ids of the two related entities.

Parameters:

• type – item type, can be used to filter by the type.

• name – human friendly name of the entity.

• create_at – the creation time of the entity.

• update_at – the last update time of the entity.

• deleted – if True, the entity is deleted (softly).

get_vip_attrs() → Dict[str, Any]

Get all important attributes for the entity.

exception DoesNotExist(msg: Optional[str] = None, cause: Optional[Exception] = None)

class pynamodb_mate.patterns.relationship.impl.BaseEntityIterProxy(iterable: Iterable)

class pynamodb_mate.patterns.relationship.impl.EntityType(name: str, klass: Type[ForwardRef('BaseEntity')])

class pynamodb_mate.patterns.relationship.impl.RelationshipType(name: str, klass: Type[ForwardRef('BaseEntity')])

class pynamodb_mate.patterns.relationship.impl.OneToManyRelationshipType(name: str, klass: Type[BaseEntity], one_type: EntityType, many_type: EntityType)

one-to-many relationship. For example, “one” Google account can have “many” YouTube videos.

The “many” entity id, YouTube video id always be the partition key, and the “one” entity id, Google account id always be the sort key.

Parameters:

• one_type – the “one” entity type.

• many_type – the “many” entity type.

class pynamodb_mate.patterns.relationship.impl.ManyToManyRelationshipType(name: str, klass: Type[BaseEntity], left_type: EntityType, right_type: EntityType)

many-to-many relationship. For example, a playlist can have many videos, and a video can be in many playlists. It is critical to know which entity is on the left and which entity is on the right. Because the left entity and the right entity could be the same in certain relationship. For example, user can subscribe another user.

Parameters:

• left_type – the left entity type.

• right_type – the right entity type.

class pynamodb_mate.patterns.relationship.impl.RelationshipSetting(main_model: Type[BaseEntity], entity_types: List[EntityType], one_to_many_relationship_types: List[OneToManyRelationshipType], many_to_many_relationship_types: List[ManyToManyRelationshipType])

The relationship setting class. It contains all the metadata of the entities and relationships. It provides lots of utility functions to Create, Update, Delete and Select items by relationship.

Parameters:

• main_model – the BaseEntity class (NOT instance) or it’s subclass that can be used to create instance and call query / scan API.

• entity_types –

• one_to_many_relationship_types –

• many_to_many_relationship_types –

new_entity(e_type: EntityType, id: str, name: str, save: bool = True, **kwargs) → Optional[T_BASE_ENTITY]

Create a new entity.

Parameters:

• e_type –

• id – unique id for the entity.

• name – human-friendly name for the entity.

• save – if True, save the entity to DynamoDB. Otherwise, just create the in-memory entity.

• kwargs – additional parameters for the constructor.

set_one_to_many(conn: Connection, one_to_many_r_type: OneToManyRelationshipType, many_entity_id: str, one_entity_id: str, client_request_token: Optional[str] = None)

For example, in YouTube use case, one user has many videos, one video only belongs to one user. Then, this function is used to set ownership of a video. In this case, the video is the many entity, the user is the one entity.

If a video already has an owner, this function will delete the old relationship first then create a new relationship.

Parameters:

• conn – pynamodb_mate.Connection object.

• one_to_many_r_type – the one-to-many relationship type.

• many_entity_id – the many entity id.

• one_entity_id – the one entity id.

unset_one_to_many(conn: Connection, one_to_many_r_type: OneToManyRelationshipType, many_entity_id: str, client_request_token: Optional[str] = None)

Unset the one-to-many relationship.

Parameters:

• conn – pynamodb_mate.Connection object.

• one_to_many_r_type – the one-to-many relationship type.

• many_entity_id – the many entity id.

find_one_by_many(one_to_many_r_type: OneToManyRelationshipType, many_entity_id: str) → BaseEntityIterProxy

For example, in YouTube use case, one user has “many” YouTube videos. This function will find the owner of the given YouTube video.

Parameters:

• one_to_many_r_type – the one-to-many relationship type.

• many_entity_id – the many entity id.

find_many_by_one(one_to_many_r_type: OneToManyRelationshipType, one_entity_id: str) → BaseEntityIterProxy

For example, in YouTube use case, one user has “many” YouTube videos. This function will find the all videos owned by the given user.

Parameters:

• one_to_many_r_type – the one-to-many relationship type.

• one_entity_id – the one entity id.

set_many_to_many(many_to_many_r_type: ManyToManyRelationshipType, left_entity_id: str, right_entity_id: str)

For example, in YouTube use case, one playlist has “many” videos. One video can be in “many” playlists. This function will add the video to the playlist.

Parameters:

• many_to_many_r_type – the many-to-many relationship type.

• left_entity_id – the left entity id.

• right_entity_id – the right entity id.

unset_many_to_many(many_to_many_r_type: ManyToManyRelationshipType, left_entity_id: str, right_entity_id: str)

For example, in YouTube use case, one playlist has “many” videos. One video can be in “many” playlists. This function will remove the video from the playlist.

Parameters:

• many_to_many_r_type – the many-to-many relationship type.

• left_entity_id – the left entity id.

• right_entity_id – the right entity id.

find_many_by_many(many_to_many_r_type: ManyToManyRelationshipType, entity_id: str, lookup_by_left: bool) → BaseEntityIterProxy

In many-to-many relationship, for example, “one” Youtube viewer can subscribe “many” Youtube channels, and “one” Youtube channel can be subscribed by “many” Youtube viewers. In this relationship, the viewer is on the left and channel is on the right.

If lookup_by_left is True, this function will find all channels that the given viewer has subscribed. If lookup_by_left is False, this function will find all viewers who have subscribed the given channel.

Parameters:

• many_to_many_r_type – the many-to-many relationship type.

• entity_id – the entity id.

• lookup_by_left – if True, find all items by the left entity id. otherwise, find all items by the right entity id.

clear_many_by_many(many_to_many_r_type: ManyToManyRelationshipType, entity_id: str, lookup_by_left: bool)

Clear all many-to-many relationship items.

Parameters:

• many_to_many_r_type – the many-to-many relationship type.

• entity_id – the entity id.

• lookup_by_left – if True, find all items by the left entity id. otherwise, find all items by the right entity id.