Book

Book

class dlkit.services.commenting.Book(provider_manager, catalog, runtime, proxy, **kwargs)

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

A Book represents a collection of comments.

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

get_book_record(book_record_type)

Gets the book record corresponding to the given Book record Type.

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

Parameters:book_record_type (osid.type.Type) – the type of book record to retrieve Returns:the book record Return type:osid.commenting.records.BookRecord Raise:NullArgument – book_record_type is null Raise:OperationFailed – unable to complete request Raise:Unsupported – has_record_type(book_record_type) is false

compliance: mandatory – This method must be implemented.

Comment Lookup Methods

Book.book_id

Gets the Book Id associated with this session.

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

compliance: mandatory – This method must be implemented.

Book.book

Gets the Book associated with this session.

Returns:the book Return type:osid.commenting.Book Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.can_lookup_comments()

Tests if this user can examine this book.

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 these operations.

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

compliance: mandatory – This method must be implemented.

Book.use_comparative_comment_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.

Book.use_plenary_comment_view()

A complete view of the Comment 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.

Book.use_federated_book_view()

Federates the view for methods in this session.

A federated view will include comments in books which are children of this book in the book hierarchy.

compliance: mandatory – This method is must be implemented.

Book.use_isolated_book_view()

Isolates the view for methods in this session.

An isolated view restricts searches to this book only.

compliance: mandatory – This method is must be implemented.

Book.use_effective_comment_view()

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

compliance: mandatory – This method is must be implemented.

Book.use_any_effective_comment_view()

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

compliance: mandatory – This method is must be implemented.

Book.get_comment(comment_id)

Gets the Comment specified by its Id.

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

compliance: mandatory – This method must be implemented.

Book.get_comments_by_ids(comment_ids)

Gets a CommentList corresponding to the given IdList.

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

compliance: mandatory – This method must be implemented.

Book.get_comments_by_genus_type(comment_genus_type)

Gets a CommentList corresponding to the given comment genus Type which does not include comments of genus types derived from the specified Type.

Parameters:comment_genus_type (osid.type.Type) – a comment genus type Returns:the returned Comment list Return type:osid.commenting.CommentList Raise:NullArgument – comment_genus_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_by_parent_genus_type(comment_genus_type)

Gets a CommentList corresponding to the given comment genus Type and include any additional comments with genus types derived from the specified Type.

Parameters:comment_genus_type (osid.type.Type) – a comment genus type Returns:the returned Comment list Return type:osid.commenting.CommentList Raise:NullArgument – comment_genus_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_by_record_type(comment_record_type)

Gets a CommentList containing the given comment record Type.

Parameters:comment_record_type (osid.type.Type) – a comment record type Returns:the returned Comment list Return type:osid.commenting.CommentList Raise:NullArgument – comment_record_type is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_on_date(from_, to)

Gets a CommentList 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 returned Comment list

Return type:

osid.commenting.CommentList

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.

Book.get_comments_by_genus_type_on_date(comment_genus_type, from_, to)

Gets a CommentList of a given genus type and effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• comment_genus_type (osid.type.Type) – a comment genus type
• from (osid.calendaring.DateTime) – starting date
• to (osid.calendaring.DateTime) – ending date

Returns:

the returned Comment list

Return type:

osid.commenting.CommentList

Raise:

InvalidArgument – from is greater than to

Raise:

NullArgument – comment_genus_type, from, or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_for_commentor(resource_id)

Gets a list of comments corresponding to a resource Id.

Parameters:resource_id (osid.id.Id) – the Id of the resource Returns:the returned CommentList Return type:osid.commenting.CommentList Raise:NullArgument – resource_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_for_commentor_on_date(resource_id, from_, to)

Gets a list of all comments corresponding to a resource Id and effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• resource_id (osid.id.Id) – the Id of the resource
• from (osid.calendaring.DateTime) – from date
• to (osid.calendaring.DateTime) – to date

Returns:

the returned CommentList

Return type:

osid.commenting.CommentList

Raise:

InvalidArgument – to is less than from

Raise:

NullArgument – resource_id, from, or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_by_genus_type_for_commentor(resource_id, comment_genus_type)

Gets a list of comments of the given genus type corresponding to a resource Id.

Parameters:

• resource_id (osid.id.Id) – the Id of the resource
• comment_genus_type (osid.type.Type) – the comment genus type

Returns:

the returned CommentList

Return type:

osid.commenting.CommentList

Raise:

NullArgument – resource_id or comment_genus_type is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_by_genus_type_for_commentor_on_date(resource_id, comment_genus_type, from_, to)

Gets a list of all comments of the given genus type corresponding to a resource Id and effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• resource_id (osid.id.Id) – the Id of the resource
• comment_genus_type (osid.type.Type) – the comment genus type
• from (osid.calendaring.DateTime) – from date
• to (osid.calendaring.DateTime) – to date

Returns:

the returned CommentList

Return type:

osid.commenting.CommentList

Raise:

InvalidArgument – to is less than from

Raise:

NullArgument – resource_id, comment_genus_type, from, or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_for_reference(reference_id)

Gets a list of comments corresponding to a reference Id.

Parameters:reference_id (osid.id.Id) – the Id of the reference Returns:the returned CommentList Return type:osid.commenting.CommentList Raise:NullArgument – reference_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_for_reference_on_date(reference_id, from_, to)

Gets a list of all comments corresponding to a reference Id and effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• reference_id (osid.id.Id) – a reference Id
• from (osid.calendaring.DateTime) – from date
• to (osid.calendaring.DateTime) – to date

Returns:

the returned CommentList

Return type:

osid.commenting.CommentList

Raise:

InvalidArgument – to is less than from

Raise:

NullArgument – reference_id, from, or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_by_genus_type_for_reference(reference_id, comment_genus_type)

Gets a list of comments of the given genus type corresponding to a reference Id.

Parameters:

• reference_id (osid.id.Id) – the Id of the reference
• comment_genus_type (osid.type.Type) – the comment genus type

Returns:

the returned CommentList

Return type:

osid.commenting.CommentList

Raise:

NullArgument – reference_id or comment_genus_type is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_by_genus_type_for_reference_on_date(reference_id, comment_genus_type, from_, to)

Gets a list of all comments of the given genus type corresponding to a reference Id and effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• reference_id (osid.id.Id) – a reference Id
• comment_genus_type (osid.type.Type) – the comment genus type
• from (osid.calendaring.DateTime) – from date
• to (osid.calendaring.DateTime) – to date

Returns:

the returned CommentList

Return type:

osid.commenting.CommentList

Raise:

InvalidArgument – to is less than from

Raise:

NullArgument – reference_id, comment_genus_type, from, or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_for_commentor_and_reference(resource_id, reference_id)

Gets a list of comments corresponding to a resource and reference Id.

Parameters:

• resource_id (osid.id.Id) – the Id of the resource
• reference_id (osid.id.Id) – the Id of the reference

Returns:

the returned CommentList

Return type:

osid.commenting.CommentList

Raise:

NullArgument – resource_id or reference_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_for_commentor_and_reference_on_date(resource_id, reference_id, from_, to)

Gets a list of all comments corresponding to a resource and reference Id and effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• resource_id (osid.id.Id) – the Id of the resource
• reference_id (osid.id.Id) – a reference Id
• from (osid.calendaring.DateTime) – from date
• to (osid.calendaring.DateTime) – to date

Returns:

the returned CommentList

Return type:

osid.commenting.CommentList

Raise:

InvalidArgument – to is less than from

Raise:

NullArgument – resource_id, reference_id, from, or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_by_genus_type_for_commentor_and_reference(resource_id, reference_id, comment_genus_type)

Gets a list of comments of the given genus type corresponding to a resource and reference Id.

Parameters:

• resource_id (osid.id.Id) – the Id of the resource
• reference_id (osid.id.Id) – the Id of the reference
• comment_genus_type (osid.type.Type) – the comment genus type

Returns:

the returned CommentList

Return type:

osid.commenting.CommentList

Raise:

NullArgument – resource_id, reference_id or comment_genus_type is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.get_comments_by_genus_type_for_commentor_and_reference_on_date(resource_id, reference_id, comment_genus_type, from_, to)

Gets a list of all comments corresponding to a resource and reference Id and effective during the entire given date range inclusive but not confined to the date range.

Parameters:

• resource_id (osid.id.Id) – the Id of the resource
• reference_id (osid.id.Id) – a reference Id
• comment_genus_type (osid.type.Type) – the comment genus type
• from (osid.calendaring.DateTime) – from date
• to (osid.calendaring.DateTime) – to date

Returns:

the returned CommentList

Return type:

osid.commenting.CommentList

Raise:

InvalidArgument – to is less than from

Raise:

NullArgument – resource_id, reference_id, comment_genus_type, from, or to is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.comments

Gets all comments.

Returns:a list of comments Return type:osid.commenting.CommentList Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Comment Query Methods

Book.book_id

Gets the Book Id associated with this session.

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

compliance: mandatory – This method must be implemented.

Book.book

Gets the Book associated with this session.

Returns:the book Return type:osid.commenting.Book Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.can_search_comments()

Tests if this user can perform comment 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 not wish 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.

Book.use_federated_book_view()

Federates the view for methods in this session.

A federated view will include comments in books which are children of this book in the book hierarchy.

compliance: mandatory – This method is must be implemented.

Book.use_isolated_book_view()

Isolates the view for methods in this session.

An isolated view restricts searches to this book only.

compliance: mandatory – This method is must be implemented.

Book.comment_query

Gets a comment query.

Returns:the comment query Return type:osid.commenting.CommentQuery

compliance: mandatory – This method must be implemented.

Book.get_comments_by_query(comment_query)

Gets a list of comments matching the given search.

Parameters:comment_query (osid.commenting.CommentQuery) – the search query array Returns:the returned CommentList Return type:osid.commenting.CommentList Raise:NullArgument – comment_query is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure Raise:Unsupported – comment_query is not of this service

compliance: mandatory – This method must be implemented.

Comment Admin Methods

Book.book_id

Gets the Book Id associated with this session.

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

compliance: mandatory – This method must be implemented.

Book.book

Gets the Book associated with this session.

Returns:the book Return type:osid.commenting.Book Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.can_create_comments()

Tests if this user can create comments.

A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Comment will result in a PermissionDenied. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.

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

compliance: mandatory – This method must be implemented.

Book.can_create_comment_with_record_types(comment_record_types)

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

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

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

compliance: mandatory – This method must be implemented.

Book.get_comment_form_for_create(reference_id, comment_record_types)

Gets the comment form for creating new comments.

A new form should be requested for each create transaction.

Parameters:

• reference_id (osid.id.Id) – the Id for the reference object
• comment_record_types (osid.type.Type[]) – array of comment record types

Returns:

the comment form

Return type:

osid.commenting.CommentForm

Raise:

NullArgument – reference_id or comment_record_types is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

Raise:

Unsupported – unable to get form for requested record types

compliance: mandatory – This method must be implemented.

Book.create_comment(comment_form)

Creates a new Comment.

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

compliance: mandatory – This method must be implemented.

Book.can_update_comments()

Tests if this user can update comments.

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

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

compliance: mandatory – This method must be implemented.

Book.get_comment_form_for_update(comment_id)

Gets the comment form for updating an existing comment.

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

Parameters:comment_id (osid.id.Id) – the Id of the Comment Returns:the comment form Return type:osid.commenting.CommentForm Raise:NotFound – comment_id is not found Raise:NullArgument – comment_id is null Raise:OperationFailed – unable to complete request Raise:PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.

Book.update_comment(comment_form)

Updates an existing comment.

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

compliance: mandatory – This method must be implemented.

Book.can_delete_comments()

Tests if this user can delete comments.

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

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

compliance: mandatory – This method must be implemented.

Book.delete_comment(comment_id)

Deletes a Comment.

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

compliance: mandatory – This method must be implemented.

Book.can_manage_comment_aliases()

Tests if this user can manage Id aliases for Comnents.

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 Comment aliasing is not authorized, true otherwise Return type:boolean

compliance: mandatory – This method must be implemented.

Book.alias_comment(comment_id, alias_id)

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

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

Parameters:

• comment_id (osid.id.Id) – the Id of a Comment
• alias_id (osid.id.Id) – the alias Id

Raise:

AlreadyExists – alias_id is already assigned

Raise:

NotFound – comment_id not found

Raise:

NullArgument – comment_id or alias_id is null

Raise:

OperationFailed – unable to complete request

Raise:

PermissionDenied – authorization failure

compliance: mandatory – This method must be implemented.