Family

Family

class dlkit.services.relationship.Family(provider_manager, catalog, runtime, proxy, **kwargs)

Bases: dlkit.osid.objects.OsidCatalog, dlkit.osid.sessions.OsidSession

A Family represents a collection of relationships.

Like all OSID objects, a Family is identified by its Id and any persisted references should use the Id.

get_family_record(family_record_type)

Gets the famly record corresponding to the given Family record Type.

This method is used to retrieve an object implementing the requested record. The family_record_type may be the Type returned in get_record_types() or any of its parents in a Type hierarchy where has_record_type(family_record_type) is true .

Parameters:family_record_type (osid.type.Type) – the type of family record to retrieve Returns:the family record Return type:osid.relationship.records.FamilyRecord Raise:NullArgument – family_record_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure occurred Raise:Unsupported – has_record_type(family_record_type) is false

compliance: mandatory – This method must be implemented.

Relationship Lookup Methods

Family.family_id

Gets the Familt Id associated with this session.

Returns:the Family Id associated with this session Return type:osid.id.Id

compliance: mandatory – This method must be implemented.

Family.family

Gets the Family associated with this session.

Returns:the family Return type:osid.relationship.Family Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.can_lookup_relationships()

Tests if this user can perform Relationship lookups.

A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PermissionDenied. This is intended as a hint to an application that may not offer lookup operations to unauthorized users.

Returns:false if lookup methods are not authorized, true otherwise Return type:boolean

compliance: mandatory – This method must be implemented.

Family.use_comparative_relationship_view()

The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.

This view is used when greater interoperability is desired at the expense of precision.

compliance: mandatory – This method is must be implemented.

Family.use_plenary_relationship_view()

A complete view of the Relationship returns is desired.

Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.

compliance: mandatory – This method is must be implemented.

Family.use_federated_family_view()

Federates the view for methods in this session.

A federated view will include relationships in families which are children of this family in the family hierarchy.

compliance: mandatory – This method is must be implemented.

Family.use_isolated_family_view()

Isolates the view for methods in this session.

An isolated view restricts retrievals to this family only.

compliance: mandatory – This method is must be implemented.

Family.use_effective_relationship_view()

Only relationships whose effective dates are current are returned by methods in this session.

compliance: mandatory – This method is must be implemented.

Family.use_any_effective_relationship_view()

All relationships of any effective dates are returned by all methods in this session.

compliance: mandatory – This method is must be implemented.

Family.get_relationship(relationship_id)

Gets the Relationship specified by its Id.

Parameters:relationship_id (osid.id.Id) – the Id of the Relationship to retrieve Returns:the returned Relationship Return type:osid.relationship.Relationship Raise:NotFound – no Relationship found with the given Id Raise:NullArgument – relationship_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_by_ids(relationship_ids)

Gets a RelationshipList corresponding to the given IdList.

Parameters:relationship_ids (osid.id.IdList) – the list of Ids to retrieve Returns:the returned Relationship list Return type:osid.relationship.RelationshipList Raise:NotFound – an Id was not found Raise:NullArgument – relationship_ids is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_by_genus_type(relationship_genus_type)

Gets a RelationshipList corresponding to the given relationship genus Type which does not include relationships of types derived from the specified Type.

Parameters:relationship_genus_type (osid.type.Type) – a relationship genus type Returns:the returned Relationship list Return type:osid.relationship.RelationshipList Raise:NullArgument – relationship_genus_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_by_parent_genus_type(relationship_genus_type)

Gets a RelationshipList corresponding to the given relationship genus Type and include any additional relationships with genus types derived from the specified Type.

Parameters:relationship_genus_type (osid.type.Type) – a relationship genus type Returns:the returned Relationship list Return type:osid.relationship.RelationshipList Raise:NullArgument – relationship_genus_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_by_record_type(relationship_record_type)

Gets a RelationshipList containing the given relationship record Type.

Parameters:relationship_record_type (osid.type.Type) – a relationship record type Returns:the returned RelationshipList Return type:osid.relationship.RelationshipList Raise:NullArgument – relationship_record_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_on_date(from_, to)

Gets a RelationshipList effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• from (osid.calendaring.DateTime) – starting date
• to (osid.calendaring.DateTime) – ending date

Returns:

the relationships

Return type:

osid.relationship.RelationshipList

Raise:

InvalidArgument – from is greater than to

Raise:

NullArgument – from or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_for_source(source_id)

Gets a RelationshipList corresponding to the given peer Id.

Parameters:source_id (osid.id.Id) – a peer Id Returns:the relationships Return type:osid.relationship.RelationshipList Raise:NullArgument – source_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_for_source_on_date(source_id, from_, to)

Gets a RelationshipList corresponding to the given peer Id and effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• source_id (osid.id.Id) – a peer Id
• from (osid.calendaring.DateTime) – starting date
• to (osid.calendaring.DateTime) – ending date

Returns:

the relationships

Return type:

osid.relationship.RelationshipList

Raise:

InvalidArgument – from is greater than to

Raise:

NullArgument – source_id, from ,or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_by_genus_type_for_source(source_id, relationship_genus_type)

Gets a RelationshipList corresponding to the given peer Id and relationship genus ``Type.

Relationships`` of any genus derived from the given genus are returned.

In plenary mode, the returned list contains all of the relationships corresponding to the given peer, including duplicates, or an error results if a relationship is inaccessible. Otherwise, inaccessible Relationships may be omitted from the list and may present the elements in any order including returning a unique set.

In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.

Parameters:

• source_id (osid.id.Id) – a peer Id
• relationship_genus_type (osid.type.Type) – a relationship genus type

Returns:

the relationships

Return type:

osid.relationship.RelationshipList

Raise:

NullArgument – source_id or relationship_genus_type is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_by_genus_type_for_source_on_date(source_id, relationship_genus_type, from_, to)

Gets a RelationshipList corresponding to the given peer Id and relationship genus Type and effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• source_id (osid.id.Id) – a peer Id
• relationship_genus_type (osid.type.Type) – a relationship genus type
• from (osid.calendaring.DateTime) – starting date
• to (osid.calendaring.DateTime) – ending date

Returns:

the relationships

Return type:

osid.relationship.RelationshipList

Raise:

InvalidArgument – from is greater than to

Raise:

NullArgument – source_id, relationship_genus_type, from or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_for_destination(destination_id)

Gets a RelationshipList corresponding to the given peer Id.

Parameters:destination_id (osid.id.Id) – a peer Id Returns:the relationships Return type:osid.relationship.RelationshipList Raise:NullArgument – destination_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_for_destination_on_date(destination_id, from_, to)

Gets a RelationshipList corresponding to the given peer Id with a starting effective date in the given range inclusive.

Parameters:

• destination_id (osid.id.Id) – a peer Id
• from (osid.calendaring.DateTime) – starting date
• to (osid.calendaring.DateTime) – ending date

Returns:

the relationships

Return type:

osid.relationship.RelationshipList

Raise:

InvalidArgument – from is greater than to

Raise:

NullArgument – destination_id, from ,or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_by_genus_type_for_destination(destination_id, relationship_genus_type)

Gets a RelationshipList corresponding to the given peer Id and relationship genus ``Type.

Relationships`` of any genus derived from the given genus are returned.

In plenary mode, the returned list contains all of the relationships corresponding to the given peer, including duplicates, or an error results if a relationship is inaccessible. Otherwise, inaccessible Relationships may be omitted from the list and may present the elements in any order including returning a unique set.

In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.

Parameters:

• destination_id (osid.id.Id) – a peer Id
• relationship_genus_type (osid.type.Type) – a relationship genus type

Returns:

the relationships

Return type:

osid.relationship.RelationshipList

Raise:

NullArgument – destination_id or relationship_genus_type is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_by_genus_type_for_destination_on_date(destination_id, relationship_genus_type, from_, to)

Gets a RelationshipList corresponding to the given peer Id and relationship genus Type and effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• destination_id (osid.id.Id) – a peer Id
• relationship_genus_type (osid.type.Type) – a relationship genus type
• from (osid.calendaring.DateTime) – starting date
• to (osid.calendaring.DateTime) – ending date

Returns:

the relationships

Return type:

osid.relationship.RelationshipList

Raise:

InvalidArgument – from is greater than to

Raise:

NullArgument – destination_id, relationship_genus_type, from or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_for_peers(source_id, destination_id)

Gets a RelationshipList corresponding to the given peer Ids.

Parameters:

• source_id (osid.id.Id) – a peer Id
• destination_id (osid.id.Id) – a related peer Id

Returns:

the relationships

Return type:

osid.relationship.RelationshipList

Raise:

NullArgument – source_id or destination_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_for_peers_on_date(source_id, destination_id, from_, to)

Gets a RelationshipList corresponding to the given peer Ids and effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• source_id (osid.id.Id) – a peer Id
• destination_id (osid.id.Id) – a related peer Id
• from (osid.calendaring.DateTime) – starting date
• to (osid.calendaring.DateTime) – ending date

Returns:

the relationships

Return type:

osid.relationship.RelationshipList

Raise:

InvalidArgument – from is greater than to

Raise:

NullArgument – source_id, destination_id, from or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_by_genus_type_for_peers(source_id, destination_id, relationship_genus_type)

Gets a RelationshipList corresponding between the given peer Ids and relationship genus ``Type.

Relationships`` of any genus derived from the given genus are returned.

In plenary mode, the returned list contains all of the relationships corresponding to the given peer or an error results if a relationship is inaccessible. Otherwise, inaccessible Relationships may be omitted from the list.

In effective mode, relationships are returned that are currently effective. In any effective mode, effective relationships and those currently expired are returned.

Parameters:

• source_id (osid.id.Id) – a peer Id
• destination_id (osid.id.Id) – a related peer Id
• relationship_genus_type (osid.type.Type) – a relationship genus type

Returns:

the relationships

Return type:

osid.relationship.RelationshipList

Raise:

NullArgument – source_id, destination_id, or relationship_genus_type is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.get_relationships_by_genus_type_for_peers_on_date(source_id, destination_id, relationship_genus_type, from_, to)

Gets a RelationshipList effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• source_id (osid.id.Id) – a peer Id
• destination_id (osid.id.Id) – a related peer Id
• relationship_genus_type (osid.type.Type) – a relationship genus type
• from (osid.calendaring.DateTime) – starting date
• to (osid.calendaring.DateTime) – ending date

Returns:

the relationships

Return type:

osid.relationship.RelationshipList

Raise:

InvalidArgument – from is greater than to

Raise:

NullArgument – source_id, destination_id, relationship_genus_type, from or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.relationships

Gets all Relationships.

Returns:a list of Relationships Return type:osid.relationship.RelationshipList Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Relationship Query Methods

Family.family_id

Gets the Familt Id associated with this session.

Returns:the Family Id associated with this session Return type:osid.id.Id

compliance: mandatory – This method must be implemented.

Family.family

Gets the Family associated with this session.

Returns:the family Return type:osid.relationship.Family Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.use_federated_family_view()

Federates the view for methods in this session.

A federated view will include relationships in families which are children of this family in the family hierarchy.

compliance: mandatory – This method is must be implemented.

Family.use_isolated_family_view()

Isolates the view for methods in this session.

An isolated view restricts retrievals to this family only.

compliance: mandatory – This method is must be implemented.

Family.can_search_relationships()

Tests if this user can perform Relationship searches.

A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PermissionDenied. This is intended as a hint to an application that may opt not to offer search operations to unauthorized users.

Returns:false if search methods are not authorized, true otherwise Return type:boolean

compliance: mandatory – This method must be implemented.

Family.relationship_query

Gets a relationship query.

Returns:the relationship query Return type:osid.relationship.RelationshipQuery

compliance: mandatory – This method must be implemented.

Family.get_relationships_by_query(relationship_query)

Gets a list of Relationships matching the given relationship query.

Parameters:relationship_query (osid.relationship.RelationshipQuery) – the relationship query Returns:the returned RelationshipList Return type:osid.relationship.RelationshipList Raise:NullArgument – relationship_query is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure Raise:Unsupported – relationship_query is not of this service

compliance: mandatory – This method must be implemented.

Relationship Admin Methods

Family.family_id

Gets the Familt Id associated with this session.

Returns:the Family Id associated with this session Return type:osid.id.Id

compliance: mandatory – This method must be implemented.

Family.family

Gets the Family associated with this session.

Returns:the family Return type:osid.relationship.Family Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.can_create_relationships()

Tests if this user can create Relationships A return of true does not guarantee successful authorization.

A return of false indicates that it is known creating a Relationship will result in a PermissionDenied. This is intended as a hint to an application that may opt not to offer create operations to an unauthorized user.

Returns:false if Relationship creation is not authorized, true otherwise Return type:boolean

compliance: mandatory – This method must be implemented.

Family.can_create_relationship_with_record_types(relationship_record_types)

Tests if this user can create a single Relationship using the desired record types.

While RelationshipManager.getRelationshipRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Relationship. Providing an empty array tests if a Relationship can be created with no records.

Parameters:relationship_record_types (osid.type.Type[]) – array of relationship record types Returns:true if Relationship creation using the specified record Types is supported, false otherwise Return type:boolean Raise:NullArgument – relationship_record_types is null

compliance: mandatory – This method must be implemented.

Family.get_relationship_form_for_create(source_id, destination_id, relationship_record_types)

Gets the relationship form for creating new relationships.

A new form should be requested for each create transaction.

Parameters:

• source_id (osid.id.Id) – Id of a peer
• destination_id (osid.id.Id) – Id of the related peer
• relationship_record_types (osid.type.Type[]) – array of relationship record types

Returns:

the relationship form

Return type:

osid.relationship.RelationshipForm

Raise:

NotFound – source_id or destination_id is not found

Raise:

NullArgument – source_id or destination_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

Raise:

Unsupported – unable to get form for requested recod types

compliance: mandatory – This method must be implemented.

Family.create_relationship(relationship_form)

Creates a new Relationship.

Parameters:relationship_form (osid.relationship.RelationshipForm) – the form for this Relationship Returns:the new Relationship Return type:osid.relationship.Relationship Raise:IllegalState – relationship_form already used in a create transaction Raise:InvalidArgument – one or more of the form elements is invalid Raise:NullArgument – relationship_form is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure Raise:Unsupported – relationship_form did not originate from get_relationship_form_for_create()

compliance: mandatory – This method must be implemented.

Family.can_update_relationships()

Tests if this user can update Relationships.

A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Relationship will result in a PermissionDenied. This is intended as a hint to an application that may opt not to offer update operations to an unauthorized user.

Returns:false if Relationship modification is not authorized, true otherwise Return type:boolean

compliance: mandatory – This method must be implemented.

Family.get_relationship_form_for_update(relationship_id)

Gets the relationship form for updating an existing relationship.

A new relationship form should be requested for each update transaction.

Parameters:relationship_id (osid.id.Id) – the Id of the Relationship Returns:the relationship form Return type:osid.relationship.RelationshipForm Raise:NotFound – relationship_id is not found Raise:NullArgument – relationship_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.update_relationship(relationship_form)

Updates an existing relationship.

Parameters:relationship_form (osid.relationship.RelationshipForm) – the form containing the elements to be updated Raise:IllegalState – relationship_form already used in an update transaction Raise:InvalidArgument – the form contains an invalid value Raise:NullArgument – relationship_form is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure Raise:Unsupported – relationship_form did not originate from get_relationship_form_for_update()

compliance: mandatory – This method must be implemented.

Family.can_delete_relationships()

Tests if this user can delete Relationships.

A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Relationship will result in a PermissionDenied. This is intended as a hint to an application that may opt not to offer delete operations to an unauthorized user.

Returns:false if Relationship deletion is not authorized, true otherwise Return type:boolean

compliance: mandatory – This method must be implemented.

Family.delete_relationship(relationship_id)

Deletes a Relationship.

Parameters:relationship_id (osid.id.Id) – the Id of the Relationship to remove Raise:NotFound – relationship_id not found Raise:NullArgument – relationship_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Family.can_manage_relationship_aliases()

Tests if this user can manage Id aliases for Relationships.

A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PermissionDenied. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.

Returns:false if Relationship aliasing is not authorized, true otherwise Return type:boolean

compliance: mandatory – This method must be implemented.

Family.alias_relationship(relationship_id, alias_id)

Adds an Id to a Relationship for the purpose of creating compatibility.

The primary Id of the Relationship is determined by the provider. The new Id performs as an alias to the primary Id. If the alias is a pointer to another relationship, it is reassigned to the given relationship Id.

Parameters:

• relationship_id (osid.id.Id) – the Id of a Relationship
• alias_id (osid.id.Id) – the alias Id

Raise:

AlreadyExists – alias_id is already assigned

Raise:

NotFound – relationship not found

Raise:

NullArgument – relationship_id or alias_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.