indivo.views.documents package

Submodules

indivo.views.documents.document module

indivo.views.documents.document.__local_document_create(request, record, pha, external_id, existing_doc)

Create a document, or update one in place.

This function serves document_create() and document_create_or_update(), which encompasses record- and/or app-specific documents.

The external_id is expected to be already adjusted.

Arguments:

  • request: The incoming Django HttpRequest object.

  • record: if the document is record-specific, this

    Record instance refers to the document’s record.

  • pha: if the document is application-specific, this

    PHA instance refers to the application to which the document pertains.

  • external_id: the external identifier to assing to the new document,

    if available. The identifier should already have been prepared using prepare_external_id().

  • existing_doc: If the new document will overwrite (via in-place update

    or versioning) an existing document, this Document instance references the old document to be overwritten.

Returns:

  • An HttpResponse object whose body is a string of XML describing the created

    document, ready for return over the wire on success.

  • An instance of django.http.HttpResponseBadRequest if the new

    document failed validation during the creation process.

Raises:

  • django.db.IntegrityError: if the arguments to this function

    violate a database unique constraint (i.e., duplicate external id).

    Warning

    If an IntegrityError is raised, it will invalidate the current database transaction. Calling functions should handle this case and rollback the current transaction.

indivo.views.documents.document._document_create(creator, content, pha, record, replaces_document=None, external_id=None, mime_type=None, status=None)

Create an Indivo Document.

This is the lowest-level creation function called for all record- and/or app-specific documents.

The PHA argument, if non-null, indicates app-specificity only. By this point, the external_id should be fully formed.

If status is specified, then it is used, otherwise it is not specified and the model’s default value is used (i.e. active).

This function creates a new model instance, processing the document if necessary, and storing it in the database (or in the file system, if the document is binary).

Arguments:

  • creator: The Principal

    instance that is responsible for creating the document.

  • content: The raw content (XML or binary) of the document to be created.

  • pha: if the document is application-specific, this

    PHA instance refers to the application to which the document pertains.

  • record: if the document is record-specific, this

    Record instance refers to the document’s record.

  • replaces_document: If the new document will overwrite (via in-place update

    or versioning) an existing document, this Document instance references the old document to be overwritten.

  • external_id: the external identifier to assing to the new document,

    if available. The identifier should already have been prepared using prepare_external_id().

  • mime_type: the mime type of the new document, i.e.

    application/xml.

  • status: The initial status of the new document. active by default.

Returns:

  • A new instance of

    Document, on success. If the document was updated in place, and no new document was created, the old document is returned.

Raises:

  • ValueError: if the document doesn’t validate.

  • django.db.IntegrityError: if the arguments to this function

    violate a database unique constraint (i.e., duplicate external id).

    Warning

    If an IntegrityError is raised, it will invalidate the current database transaction. Calling functions should handle this case and rollback the current transaction.

indivo.views.documents.document._get_document(record=None, carenet=None, document_id=None, pha=None, external_id=None)

Fetch a document from the DB.

EITHER document_id OR external_id must be provided (exclusive or). If a document doesn’t exist matching all passed arguments, this call returns None.

Arguments:

  • record: if the document is record-specific, this

    Record instance refers to the document’s record.

  • carenet: if the document is being found via a carenet, this

    Carenet instance refers to the carenet containing the document.

    Warning

    Carenet membership is NOT checked in this function. That security must be checked elsewhere.

  • document_id: the internal identifier for the document, if available.

    Note

    One of external_id or document_id MUST be passed to this function, or it cannot retrieve a unique document.

  • pha: if the document is application-specific, this

    PHA instance refers to the application to which the document pertains.

  • external_id: the external identifier for the document, if available. The

    identifier should already have been prepared using prepare_external_id().

    Note

    One of external_id or document_id MUST be passed to this function, or it cannot retrieve a unique document.

Returns:

  • An instance of

    Document, on success.

  • None, if a document satisfying all passed arguments could not be found.

indivo.views.documents.document._render_document(document)

Get the raw content of a document, ready to be sent over the wire.

Arguments:

  • document: the

    Document instance to render.

Returns:

  • An HttpResponse object whose body contains the The raw content of the

    document on success.

indivo.views.documents.document._render_documents(docs, record, pha, tdc, format_type='xml')

Lowlevel document rendering to response data.

Arguments:

  • docs: An iterable of

    Document objects to be rendered.

  • record: The

    Record that every document in docs belongs to.

  • pha: The

    PHA that docs are scoped to.

  • tdc: The total document count of objects to render (i.e., len(docs)).

    This can be passed in to avoid recomputing the size of docs if that might be expensive (i.e., a QuerySet which would require an extra DB call).

  • format_type: The format to render into. Options are xml.

Returns:

  • an HTTPResponse whose body is an XML string containing the rendered list of

    documents (which might be empty).

indivo.views.documents.document._set_doc_latest(doc)

Set the ‘latest version’-related fields on a document for rendering.

This is computed at load-time before each rendering of document. It is not pre-computed or stored in the DB.

returns: None

indivo.views.documents.document.app_document_create(*args, **kwargs)

Create an app-specific Indivo document.

Calls into document_create_or_update().

indivo.views.documents.document.app_document_create_or_update(*args, **kwargs)

Create or Overwrite an app-specific Indivo document.

Calls into document_create_or_update().

indivo.views.documents.document.app_document_create_or_update_ext(*args, **kwargs)

Create an app-specific Indivo document with an associated external id.

Calls into document_create_or_update().

indivo.views.documents.document.app_document_list(request, *args, **kwargs)

List app-specific documents.

Calls into document_list().

indivo.views.documents.document.app_specific_document(request, pha, document_id)

Retrive an app-specific document.

Calls into document().

indivo.views.documents.document.document(request, document_id, record=None, pha=None)

Retrieve a document, record- and/or app-specific.

Arguments:

  • request: the incoming Django HttpRequest object.

  • document_id: the internal identifier of the document to retrieve.

  • record: if the document is record-specific, this

    Record instance refers to the document’s record.

  • pha: if the document is application-specific, this

    PHA instance refers to the application to which the document pertains.

Returns:

  • An HttpResponse object whose body contains the raw content of the document

    on success.

Raises:

  • A django.http.Http404 if the document could not be found.
indivo.views.documents.document.document_create(*args, **kwargs)

Create a record-specific Indivo Document.

Calls into __local_document_create().

indivo.views.documents.document.document_create_by_ext_id(*args, **kwargs)

Create a record-specific Indivo Document with an associated external id.

Calls into __local_document_create().

indivo.views.documents.document.document_create_or_update(request, pha, record=None, document_id=None, external_id=None)

Create or Overwrite an app-specific or record-app-specific document, possibly with an associated external id.

Prepares the external id, loads the existing document to overwrite, then calls into __local_document_create().

indivo.views.documents.document.document_list(request, query_options, record=None, pha=None)

List Indivo documents.

Arguments:

  • request: The incoming Django HttpRequest object. request.GET may contain:

    • type: The Indivo document schema type on which to filter the resut set. As

      of 2010-08-16, type is no longer part of the URL, it’s only in the GET query parameters.

  • limit, offset, status, order_by: Standard paging and filtering

    arguments. See marsloader() or API Query Interface.

  • record: if desired documents are record-specific, this

    Record instance refers to the record to filter on.

  • pha: if the desired documents are application-specific, this

    PHA instance refers to the app to filter on.

Returns:

  • an HTTPResponse whose body is an XML string containing the rendered list of

    documents (which might be empty), on success.

Raises:

  • django.http.Http404: if type was passed, but didn’t

    correspond to an existing Indivo schema.

indivo.views.documents.document.record_app_document_create(*args, **kwargs)

Create a record-app-specific Indivo document.

Calls into document_create_or_update().

indivo.views.documents.document.record_app_document_create_or_update_ext(*args, **kwargs)

Create or Overwrite a record-app-specific Indivo document with an associated external id.

Calls into document_create_or_update().

indivo.views.documents.document.record_app_document_list(request, *args, **kwargs)

List record-app-specific documents.

Calls into document_list().

indivo.views.documents.document.record_app_specific_document(request, record, pha, document_id)

Retrieve a record-app-specific document.

Calls into document().

indivo.views.documents.document.record_document_list(request, *args, **kwargs)

List record-specific documents.

Calls into document_list().

indivo.views.documents.document.record_specific_document(request, record, document_id)

Retrieve a record-specific document.

Calls into document().

indivo.views.documents.document_delete module

indivo.views.documents.document_delete._document_delete(document_id, pha=None, record=None)

Delete a document.

ARGUMENTS:

  • document_id: The internal identifier of the document to delete.
  • pha: If the document to delete is scoped to an app, this PHA instance refers to the app.
  • record: If the document to delete is scoped to a record, this Record instance refers to the record.

RETURNS:

RAISES:

  • django.http.Http404 if the arguments don’t identify an existing document.
indivo.views.documents.document_delete.app_document_delete(request, pha, document_id)

Delete an app-specific document.

No restrictions, since this storage is managed by the app.

Calls into _document_delete().

indivo.views.documents.document_delete.documents_delete(request, record)

Delete all documents associated with a record.

ARGUMENTS:

  • request: The incoming Django HttpRequest object.
  • record: The Record to purge of documents.

RETURNS:

indivo.views.documents.document_delete.record_app_document_delete(request, record, pha, document_id)

Delete a record-app-specific document.

No restrictions, since this storage is managed by the app.

Calls into _document_delete().

indivo.views.documents.document_label module

indivo.views.documents.document_label._document_label(request, record=None, document_id=None, external_id=None, pha=None, app_specific=False)

Set a document’s label.

ARGUMENTS:

  • request: The incoming Django HttpRequest object. request.POST must consist of a raw string containing the new label to assign.

  • record: The Record that the document is scoped to, if applicable.

  • document_id: The internal identifier of the document to re-label.

    Note

    One of external_id or document_id MUST be passed to this function, or it cannot retrieve a unique document.

  • external_id: The external identifier of the document to re-label.

    Note

    One of external_id or document_id MUST be passed to this function, or it cannot retrieve a unique document.

  • pha: The PHA object that the document is scoped to. Also serves to scope external_id, if present and app_specific is True.

  • app_specific: Whether or not the document is app-specific. The mere presence of the pha argument isn’t enough to satisfy this question, as pha might have been passed in only to scope an external id for a non-app-specific document.

RETURNS:

  • An HttpResponse object with an XML string describing the re-labeled document on success.

RAISES:

  • django.http.Http404 if neither document_id nor external_id identify an existing document.
indivo.views.documents.document_label.app_document_label(request, pha, document_id)

Set the label of an app-specific document.

Calls into _document_label().

indivo.views.documents.document_label.record_app_document_label(request, record, pha, document_id)

Set the label of a record-app-specific document.

Calls into _document_label().

indivo.views.documents.document_label.record_document_label(request, record, document_id)

Set the label of a record-specific document.

Calls into _document_label().

indivo.views.documents.document_label.record_document_label_ext(request, record, document=None, external_id=None, pha=None, app_specific=False)

Set the label of a record-specific document, specified by external id.

Calls into _document_label().

indivo.views.documents.document_meta module

indivo.views.documents.document_meta._document_meta(record=None, carenet=None, document=None, pha=None, external_id=None, app_specific=False)

Fetch the metadata of a single document.

Metadata includes:

  • id
  • date created
  • creator
  • the document that replaced this one
  • the document that this one replaces
  • the original document in the version chain
  • the latest document in the version chain
  • label
  • current status
  • nevershare status
  • related documents

ARGUMENTS:

  • record: The Record that the document is scoped to, if applicable.

  • carenet: The Carenet that the document is shared into, if applicable.

  • document: The document to get metadata for, if it has been prefetched.

    Note

    One of external_id or document MUST be passed to this function, or it cannot retrieve a unique document.

  • pha: The PHA object that the document is scoped to. Also serves to scope external_id, if present and app_specific is True.

  • external_id: The external identifier of the document to re-label.

    Note

    One of external_id or document MUST be passed to this function, or it cannot retrieve a unique document.

  • app_specific: Whether or not the document is app-specific. The mere presence of the pha argument isn’t enough to satisfy this question, as pha might have been passed in only to scope an external id for a non-app-specific document.

RETURNS:

  • An HttpResponse object with an XML string describing the document metadata on success.

RAISES:

  • django.http.Http404 if document isn’t passed and external_id doesn’t identify an existing document.
indivo.views.documents.document_meta.app_document_meta(request, pha, document_id)

Fetch the metadata of an app-specific document.

Calls into _document_meta().

indivo.views.documents.document_meta.app_document_meta_ext(request, pha, external_id)

Fetch the metadata of an app-specific document identified by external id.

Calls into _document_meta().

indivo.views.documents.document_meta.carenet_document_meta(request, carenet, document_id)

Fetch the metadata of a record-specific document via a carenet.

Calls into _document_meta().

indivo.views.documents.document_meta.record_app_document_meta(request, record, pha, document_id)

Fetch the metadata of a record-app-specific document.

Calls into _document_meta().

indivo.views.documents.document_meta.record_app_document_meta_ext(request, record, pha, external_id)

Fetch the metadata of a record-app-specific document identified by external id.

Calls into _document_meta().

indivo.views.documents.document_meta.record_document_meta(request, record, document_id)

Fetch the metadata of a record-specific document.

Calls into _document_meta().

indivo.views.documents.document_meta.record_document_meta_ext(request, record, pha, external_id)

Fetch the metadata of a record-specific document identified by external id.

Calls into _document_meta().

indivo.views.documents.document_meta.update_document_meta(request, record, document_id)

Set metadata fields on a document. NOT IMPLEMENTED.

indivo.views.documents.document_rels module

indivo.views.documents.document_rels._document_create_by_rel(request, record, document_id, rel, pha=None, external_id=None)

Create a document and relate it to an existing document.

ARGUMENTS:

  • request: The incoming Django HttpRequest object. request.POST must contain the raw content of the new document.
  • record: The Record to which to scope the new document, and to which the source document is scoped.
  • document_id: The internal document identifier for the source document.
  • rel: The relationship type to establish between the source document and the new document (as a string).
  • pha: The PHA object that scopes the external_id, if present.
  • external_id: The external identifier to assign to the newly created document.

RETURNS:

  • An HttpResponse object whose body is a string of XML describing the created document, ready for return over the wire on success.
  • 400 Bad Request if the new document content is invalid

RAISES:

  • django.http.Http404 if document_id doesn’t identify an existing document scoped to record, or if rel doesn’t identify a valid relationship type.
indivo.views.documents.document_rels.document_create_by_rel(*args, **kwargs)

Create a document and relate it to an existing document.

Calls into _document_create_by_rel().

indivo.views.documents.document_rels.document_create_by_rel_with_ext_id(*args, **kwargs)

Create a document, assign it an external id, and relate it to an existing document.

Calls into _document_create_by_rel().

indivo.views.documents.document_rels.document_rels(request, record, document_id_0, rel, document_id_1)

Create a new relationship between two existing documents.

ARGUMENTS:

  • request: The incoming Django HttpRequest object.
  • record: The Record that the documents are scoped to.
  • document_id_0: The internal document identifier for the source document.
  • rel: The relationship type between the two documents (as a string).
  • document_id_1: The internal document identifier for the related document.

RETURNS:

RAISES:

  • django.http.Http404 if either document_id_0 or document_id_1 don’t identify an existing document scoped to record, or if rel doesn’t identify a valid relationship type.
indivo.views.documents.document_rels.get_documents_by_rel(request, *args, **kwargs)

Get all documents related to the passed document_id by a relation of the passed relation-type.

Includes relationships to other versions of document_id. Paging operators are NOT IMPLEMENTED.

ARGUMENTS:

  • request: The incoming Django HttpRequest object.

  • record: The Record that the document is scoped to.

  • document_id: The internal document identifier for the source document.

  • rel: The relationship type to filter related documents by (as a string).

  • limit, offset, status, order_by: Standard paging and filtering arguments. See marsloader() or API Query Interface.

    Note

    Paging operators are not implemented for this call currently. Passing them into the function will have no effect on output.

  • pha: The PHA object that the source document is scoped to, if applicable.

RETURNS:

  • An HttpResponse object with an XML string listing related documents on success.

RAISES:

  • django.http.Http404 if document_id doesn’t identify an existing document scoped to record.

indivo.views.documents.document_status module

indivo.views.documents.document_status.document_set_status(*args, **kwargs)

Set the status of a record-specific document.

ARGUMENTS:

  • request: The incoming Django HttpRequest object. request.POST must contain:
    • status The new status for the document. Must identify an existing StatusName object.
    • reason The reason for the status change
  • record: The Record that the document is scoped to.
  • document_id: The internal identifier of the document whose status is being altered.

RETURNS:

RAISES:

  • django.http.Http404 if document_id doesn’t identify an existing document scoped to record.
indivo.views.documents.document_status.document_status_history(request, record, document_id)

List all changes to a document’s status over time.

ARGUMENTS:

  • request: The incoming Django HttpRequest object.
  • record: The Record that the document is scoped to.
  • document_id: The internal identifier of the document for which to get status history.

RETURNS:

  • A django.http.HttpResponse object containing an XML string listing status changes for the document.

RAISES:

  • django.http.Http404 if document_id doesn’t identify an existing document scoped to record.

indivo.views.documents.document_versions module

indivo.views.documents.document_versions._document_version(request, record, document_id, pha=None, external_id=None)

Create a new version of a record-specific document.

ARGUMENTS:
  • request: The incoming Django HttpRequest object. request.POST must consist of a raw string containing the new document content.
  • record: The Record to which the old document is scoped, and to which the new document will be scoped.
  • document_id: The internal identifier of the old document. The old document must be at the latest version, or the call will fail.
  • external_id: The external identifier to assign to the new document.
  • pha: The PHA object used to scope external_id, if present.

RETURNS:

  • An HttpResponse object with an XML string containing metadata on the new document on success.
  • 400 Bad Request if the old document has previously been replaced by a newer version.

RAISES:

  • django.http.Http404 if document_id doesn’t identify an existing document, or if document creation fails (odd behavior).
indivo.views.documents.document_versions.document_version(*args, **kwargs)

Create a new version of a record-specific document.

Calls into _document_version().

indivo.views.documents.document_versions.document_version_by_ext_id(*args, **kwargs)

Create a new version of a record-specific document and assign it an external id.

Calls into _document_version().

indivo.views.documents.document_versions.document_versions(request, *args, **kwargs)

Retrieve the versions of a document.

ARGUMENTS:

  • request: The incoming Django HttpRequest object.
  • record: The Record to which the document is scoped.
  • document_id: The internal identifier of the document.
  • limit, offset, status, order_by: Standard paging and filtering arguments. See marsloader() or API Query Interface.

RETURNS:

  • An HttpResponse object with an XML string containing metadata on all versions of the document, including the passed document_id, on success.

RAISES:

  • django.http.Http404 if document_id doesn’t identify an existing document.

indivo.views.documents.special_documents module

indivo.views.documents.special_documents._read_demographics(request, record_or_carenet)

Read demographics from a record or carenet.

Calls into get_demographics().

indivo.views.documents.special_documents.get_demographics(record_or_carenet)

Fetch the demographics from either a record or a carenet.

ARGUMENTS:

  • record_or_carenet: The Record or Carenet from which to fetch the demographics.

RETURNS:

  • The demographics as a Demographics instance, if they exist.
  • None, if record or carenet hasn’t been assigned demographics

RAISES:

  • ValueError if record_or_carenet is None.
indivo.views.documents.special_documents.read_demographics(request, record)

Read demographics from a record.

Calls into _read_demographics().

indivo.views.documents.special_documents.read_demographics_carenet(request, carenet)

Read demographics from a carenet.

Calls into _read_demographics().

indivo.views.documents.special_documents.set_demographics(*args, **kwargs)

Create or update demographics on a record.

ARGUMENTS:

  • request: The incoming Django HttpRequest object. request.POST must consist of a raw string containing the demographics content.
  • record: The Record from which to fetch the demographics.

RETURNS:

  • a django.http.HttpResponse containing Metadata XML on the newly created document. TODO: what should we return now that we have a model
  • 400 Bad Request if the new demographics content didn’t validate.

Module contents

Indivo Document Views.

The views that implement document-related API calls.