Welcome to dokomoforms’s documentation!

Contents:

dokomoforms package

Subpackages

dokomoforms.handlers package

Subpackages
dokomoforms.handlers.api package
Subpackages
dokomoforms.handlers.api.v0 package
Submodules
dokomoforms.handlers.api.v0.base module
dokomoforms.handlers.api.v0.nodes module
dokomoforms.handlers.api.v0.photos module
dokomoforms.handlers.api.v0.serializer module
dokomoforms.handlers.api.v0.submissions module
dokomoforms.handlers.api.v0.surveys module
Module contents
dokomoforms.handlers.user package
Submodules
dokomoforms.handlers.user.admin module
dokomoforms.handlers.user.enumerate module
Module contents
Submodules
dokomoforms.handlers.auth module
dokomoforms.handlers.debug module
dokomoforms.handlers.root module
dokomoforms.handlers.util module
Module contents

dokomoforms.models package

Submodules
dokomoforms.models.answer module

Answer models.

class dokomoforms.models.answer.Answer(**kwargs)[source]

Bases: dokomoforms.models.util.Base

An Answer is a response to a SurveyNode.

An Answer can be one of an answer, an “other” response or a “don’t know” response. Answer.response abstracts over these 3 possibilites.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer

The answer. Could be the same as main_answer in simple cases.

This property is the most useful representation available of the answer. In the simplest case it is just a synonym for main_answer. It could otherwise be a dictionary or another model.

answer_metadata
answer_number
answer_type
deleted
dont_know

A text field containing “don’t know” responses.

id
last_update_time
main_answer

The representative part of a provided answer.

The main_answer is the only answer for simple types (integer, text, etc.) and for other types is the part of the answer that is most important. In practice, the main_answer is special only in that all Answer models have it, which is necessary for certain constraints and for the response property.

other

A text field containing “other” responses.

question_id
question_title
repeatable
response = OrderedDict([('type_constraint', <sqlalchemy.orm.attributes.InstrumentedAttribute object at 0x7fa94a2e27d8>), ('response_type', 'answer'), ('response', <property object at 0x7fa94a2c88b8>)])
save_time
submission_id
survey_containing_id
survey_id
survey_node
survey_node_containing_survey_id
survey_node_id
type_constraint
class dokomoforms.models.answer.DateAnswer(**kwargs)[source]

Bases: dokomoforms.models.answer._AnswerMixin, dokomoforms.models.answer.Answer

A DATE answer.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer
answer_metadata
answer_number
answer_type
deleted
dont_know
id
last_update_time
main_answer
other
question_id
question_title
repeatable
save_time
submission_id
survey_containing_id
survey_id
survey_node
survey_node_containing_survey_id
survey_node_id
the_allow_dont_know
the_allow_other
type_constraint
class dokomoforms.models.answer.DecimalAnswer(**kwargs)[source]

Bases: dokomoforms.models.answer._AnswerMixin, dokomoforms.models.answer.Answer

A NUMERIC answer.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer
answer_metadata
answer_number
answer_type
deleted
dont_know
id
last_update_time
main_answer
other
question_id
question_title
repeatable
save_time
submission_id
survey_containing_id
survey_id
survey_node
survey_node_containing_survey_id
survey_node_id
the_allow_dont_know
the_allow_other
type_constraint
class dokomoforms.models.answer.FacilityAnswer(**kwargs)[source]

Bases: dokomoforms.models.answer._AnswerMixin, dokomoforms.models.answer.Answer

A facility answer (a la Revisit).

FacilityAnswer.answer is a dictionary with 4 keys: facility_location, facility_id, facility_name, facility_sector

facility_location accepts input in the form {

‘lng’: <longitude>, ‘lat’: <latitude>

} and outputs a GeoJSON.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer = OrderedDict([('facility_location', <sqlalchemy.orm.attributes.InstrumentedAttribute object at 0x7fa94a266eb8>), ('facility_id', <sqlalchemy.orm.attributes.InstrumentedAttribute object at 0x7fa94a2770a0>), ('facility_name', <sqlalchemy.orm.attributes.InstrumentedAttribute object at 0x7fa94a277150>), ('facility_sector', <sqlalchemy.orm.attributes.InstrumentedAttribute object at 0x7fa94a277200>)])
answer_metadata
answer_number
answer_type
deleted
dont_know
facility_id
facility_name
facility_sector
geo_json
id
last_update_time
main_answer
other
question_id
question_title
repeatable
save_time
submission_id
survey_containing_id
survey_id
survey_node
survey_node_containing_survey_id
survey_node_id
the_allow_dont_know
the_allow_other
type_constraint
class dokomoforms.models.answer.IntegerAnswer(**kwargs)[source]

Bases: dokomoforms.models.answer._AnswerMixin, dokomoforms.models.answer.Answer

An INTEGER answer (signed 4 byte).

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer
answer_metadata
answer_number
answer_type
deleted
dont_know
id
last_update_time
main_answer
other
question_id
question_title
repeatable
save_time
submission_id
survey_containing_id
survey_id
survey_node
survey_node_containing_survey_id
survey_node_id
the_allow_dont_know
the_allow_other
type_constraint
class dokomoforms.models.answer.LocationAnswer(**kwargs)[source]

Bases: dokomoforms.models.answer._AnswerMixin, dokomoforms.models.answer.Answer

A GEOMETRY(‘POINT’, 4326) answer.

Accepts input in the form {

‘lng’: <longitude>, ‘lat’: <latitude>

}

The output is a GeoJSON.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer
answer_metadata
answer_number
answer_type
deleted
dont_know
geo_json
id
last_update_time
main_answer
other
question_id
question_title
repeatable
save_time
submission_id
survey_containing_id
survey_id
survey_node
survey_node_containing_survey_id
survey_node_id
the_allow_dont_know
the_allow_other
type_constraint
class dokomoforms.models.answer.MultipleChoiceAnswer(**kwargs)[source]

Bases: dokomoforms.models.answer._AnswerMixin, dokomoforms.models.answer.Answer

A Choice answer.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer
answer_metadata
answer_number
answer_type
choice
deleted
dont_know
id
last_update_time
main_answer
other
question_id
question_title
repeatable
save_time
submission_id
survey_containing_id
survey_id
survey_node
survey_node_containing_survey_id
survey_node_id
the_allow_dont_know
the_allow_other
the_question_id
the_submission_id
the_survey_node_id
type_constraint
class dokomoforms.models.answer.Photo(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A BYTEA holding an image.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_on
deleted
id
image
mime_type
class dokomoforms.models.answer.PhotoAnswer(**kwargs)[source]

Bases: dokomoforms.models.answer._AnswerMixin, dokomoforms.models.answer.Answer

A photo answer (the id of a Photo).

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

actual_photo_id
allow_dont_know
allow_multiple
allow_other
answer
answer_metadata
answer_number
answer_type
deleted
dont_know
id
last_update_time
main_answer
other
photo
question_id
question_title
repeatable
save_time
submission_id
survey_containing_id
survey_id
survey_node
survey_node_containing_survey_id
survey_node_id
the_allow_dont_know
the_allow_other
type_constraint
class dokomoforms.models.answer.TextAnswer(**kwargs)[source]

Bases: dokomoforms.models.answer._AnswerMixin, dokomoforms.models.answer.Answer

A TEXT answer.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer
answer_metadata
answer_number
answer_type
deleted
dont_know
id
last_update_time
main_answer
other
question_id
question_title
repeatable
save_time
submission_id
survey_containing_id
survey_id
survey_node
survey_node_containing_survey_id
survey_node_id
the_allow_dont_know
the_allow_other
type_constraint
class dokomoforms.models.answer.TimeAnswer(**kwargs)[source]

Bases: dokomoforms.models.answer._AnswerMixin, dokomoforms.models.answer.Answer

A TIME WITH TIME ZONE answer.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer
answer_metadata
answer_number
answer_type
deleted
dont_know
id
last_update_time
main_answer
other
question_id
question_title
repeatable
save_time
submission_id
survey_containing_id
survey_id
survey_node
survey_node_containing_survey_id
survey_node_id
the_allow_dont_know
the_allow_other
type_constraint
class dokomoforms.models.answer.TimestampAnswer(**kwargs)[source]

Bases: dokomoforms.models.answer._AnswerMixin, dokomoforms.models.answer.Answer

A TIMESTAMP WITH TIME ZONE answer.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer
answer_metadata
answer_number
answer_type
deleted
dont_know
id
last_update_time
main_answer
other
question_id
question_title
repeatable
save_time
submission_id
survey_containing_id
survey_id
survey_node
survey_node_containing_survey_id
survey_node_id
the_allow_dont_know
the_allow_other
type_constraint
dokomoforms.models.answer.add_new_photo_to_session(session, *, id, **kwargs)[source]

Create a new Photo and update the referenced PhotoAnswer.

dokomoforms.models.answer.construct_answer(*, type_constraint: str, **kwargs) → dokomoforms.models.answer.Answer[source]

Return a subclass of dokomoforms.models.answer.Answer.

The subclass is determined by the type_constraint parameter. This utility function makes it easy to create an instance of an Answer subclass based on external input.

See http://stackoverflow.com/q/30518484/1475412

Parameters:
  • type_constraint – the type of the answer. Must be one of the keys of dokomoforms.models.answer.ANSWER_TYPES
  • kwargs – the keyword arguments to pass to the constructor
Returns:

an instance of one of the Answer subtypes

Raies:

dokomoforms.exc.NotAnAnswerTypeError

dokomoforms.models.column_properties module

Extra properties for models.

These could not be defined inline with the models do to import issues. See http://docs.sqlalchemy.org/en/rel_1_0/orm/mapped_sql_expr.html #using-column-property

dokomoforms.models.column_properties.answer_avg(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the average of the answers.

dokomoforms.models.column_properties.answer_max(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the maximum answer.

dokomoforms.models.column_properties.answer_min(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the minimum answer.

dokomoforms.models.column_properties.answer_mode(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the mode of the answers.

dokomoforms.models.column_properties.answer_stddev_pop(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the population standard deviation of the answers.

dokomoforms.models.column_properties.answer_stddev_samp(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the sample standard deviation of the answers.

dokomoforms.models.column_properties.answer_sum(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the sum of the answers.

dokomoforms.models.column_properties.generate_question_stats(survey)[source]

Get answer statistics for the nodes in a survey.

dokomoforms.models.node module

A Node is either a note or a question and is independent of a Survey.

class dokomoforms.models.node.Choice(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A choice for a MultipleChoiceQuestion.

Models a choice for a dokomoforms.models.survey.MultipleChoiceQuestion.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

choice_number
choice_text
deleted
id
last_update_time
question_id
question_languages
class dokomoforms.models.node.DateQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A date question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.node.DecimalQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A decimal question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.node.FacilityQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A facility question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.node.IntegerQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A integer question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.node.LocationQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A location question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.node.MultipleChoiceQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A multiple_choice question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
choices
deleted
hint
id
languages
last_update_time
logic
node_languages
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.node.Node(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A node is a Note or Question independent of any Survey.

A node is its own entity. A node can be a dokomoforms.models.survey.Note or a dokomoforms.models.survey.Question.

You can use this class for querying, e.g.
session.query(Node).filter_by(title=’Some Title’)

To create the specific kind of Node you want, use dokomoforms.models.survey.node.construct_node.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

deleted
hint
id
languages
last_update_time
logic
title
type_constraint
class dokomoforms.models.node.Note(**kwargs)[source]

Bases: dokomoforms.models.node.Node

Notes provide information interspersed with survey questions.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

deleted
hint
id
languages
last_update_time
logic
the_type_constraint
title
type_constraint
class dokomoforms.models.node.PhotoQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A photo question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.node.Question(**kwargs)[source]

Bases: dokomoforms.models.node.Node

A Question has a response type associated with it.

A Question has a type constraint associated with it (integer, date, text...). Only a dokomoforms.models.survey.MultipleChoiceQuestion has a list of dokomoforms.models.survey.Choice instances.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.node.TextQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A text question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.node.TimeQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A time (with time zone) question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.node.TimestampQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A timestamp (with time zone) question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
dokomoforms.models.node.construct_node(*, type_constraint: str, **kwargs) → dokomoforms.models.node.Node[source]

Return a subclass of dokomoforms.models.node.Node.

The subclass is determined by the type_constraint parameter. This utility function makes it easy to create an instance of a Node or Question subclass based on external input.

See http://stackoverflow.com/q/30518484/1475412

Parameters:
  • type_constraint – the type constraint of the node. Must be one of the keys of dokomoforms.models.survey.NODE_TYPES
  • kwargs – the keyword arguments to pass to the constructor
Returns:

an instance of one of the Node subtypes

Raises:

dokomoforms.exc.NoSuchNodeTypeError

dokomoforms.models.submission module

Submission models.

class dokomoforms.models.submission.EnumeratorOnlySubmission(**kwargs)[source]

Bases: dokomoforms.models.submission.Submission

An EnumeratorOnlySubmission must have an enumerator.

Use an EnumeratorOnlySubmission for an EnumeratorOnlySurvey.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

answers
deleted
enumerator
enumerator_user_id
id
last_update_time
save_time
start_time
submission_time
submission_type
submitter_email
submitter_name
survey_containing_id
survey_default_language
survey_id
survey_title
survey_type
the_survey_id
class dokomoforms.models.submission.PublicSubmission(**kwargs)[source]

Bases: dokomoforms.models.submission.Submission

A PublicSubmission might have an enumerator.

Use a PublicSubmission for a Survey.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

answers
deleted
enumerator
enumerator_user_id
id
last_update_time
save_time
start_time
submission_time
submission_type
submitter_email
submitter_name
survey_containing_id
survey_default_language
survey_id
survey_title
survey_type
class dokomoforms.models.submission.Submission(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A Submission references a Survey and has a list of Answers.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

answers
deleted
id
last_update_time
save_time
start_time
submission_time
submission_type
submitter_email
submitter_name
survey_containing_id
survey_default_language
survey_id
survey_title
survey_type
dokomoforms.models.submission.construct_submission(*, submission_type: str, **kwargs) → dokomoforms.models.submission.Submission[source]

Return a subclass of dokomoforms.models.submission.Submission.

The subclass is determined by the submission_type parameter. This utility function makes it easy to create an instance of a Submission subclass based on external input.

See http://stackoverflow.com/q/30518484/1475412

Parameters:
  • submission_type – the type of submission. Must be either ‘public_submission’ or ‘enumerator_only_submission’
  • kwargs – the keyword arguments to pass to the constructor
Returns:

an instance of one of the Node subtypes

Raises:

dokomoforms.exc.NoSuchSubmissionTypeError

dokomoforms.models.submission.most_recent_submissions(session, user_id, limit=None)[source]

Get an administrator’s surveys’ most recent submissions.

dokomoforms.models.survey module

Survey models.

class dokomoforms.models.survey.AnswerableSurveyNode(**kwargs)[source]

Bases: dokomoforms.models.survey.SurveyNode

Contains a Node which is answerable (.e.g, a Question).

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer_count
answers
containing_survey_id
deleted
id
last_update_time
logic
node
node_id
node_languages
node_number
non_null_repeatable
required
root_survey_id
root_survey_languages
sub_survey_id
sub_survey_repeatable
sub_surveys
survey_node_answerable
the_containing_survey_id
the_node
the_node_id
the_node_languages
the_root_survey_languages
the_sub_survey_repeatable
the_type_constraint
type_constraint
class dokomoforms.models.survey.Bucket(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A Bucket determines how to arrive at a SubSurvey.

A Bucket can be a range or a Choice.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

bucket

The bucket is a range or Choice.

Buckets for a given SubSurvey cannot overlap.

bucket_type
deleted
id
last_update_time
sub_survey_id
sub_survey_parent_node_id
sub_survey_parent_survey_node_id
sub_survey_parent_type_constraint
class dokomoforms.models.survey.DateBucket(**kwargs)[source]

Bases: dokomoforms.models.survey._RangeBucketMixin, dokomoforms.models.survey.Bucket

DATERANGE bucket.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

bucket
bucket_type
deleted
id
last_update_time
sub_survey_id
sub_survey_parent_node_id
sub_survey_parent_survey_node_id
sub_survey_parent_type_constraint
the_survey_node_id
class dokomoforms.models.survey.DecimalBucket(**kwargs)[source]

Bases: dokomoforms.models.survey._RangeBucketMixin, dokomoforms.models.survey.Bucket

NUMRANGE bucket.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

bucket
bucket_type
deleted
id
last_update_time
sub_survey_id
sub_survey_parent_node_id
sub_survey_parent_survey_node_id
sub_survey_parent_type_constraint
the_survey_node_id
class dokomoforms.models.survey.EnumeratorOnlySurvey(**kwargs)[source]

Bases: dokomoforms.models.survey.Survey

Only enumerators (designated Users) can submit to this.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

administrators
containing_id
created_on
creator_id
default_language
deleted
earliest_submission_time
enumerators
id
languages
last_update_time
latest_submission_time
nodes
num_submissions
submissions
survey_metadata
survey_type
title
url_slug
version
class dokomoforms.models.survey.IntegerBucket(**kwargs)[source]

Bases: dokomoforms.models.survey._RangeBucketMixin, dokomoforms.models.survey.Bucket

INT4RANGE bucket.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

bucket
bucket_type
deleted
id
last_update_time
sub_survey_id
sub_survey_parent_node_id
sub_survey_parent_survey_node_id
sub_survey_parent_type_constraint
the_survey_node_id
class dokomoforms.models.survey.MultipleChoiceBucket(**kwargs)[source]

Bases: dokomoforms.models.survey.Bucket

Choice id bucket.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

bucket
bucket_type
choice_id
deleted
id
last_update_time
parent_node_id
parent_survey_node_id
sub_survey_id
sub_survey_parent_node_id
sub_survey_parent_survey_node_id
sub_survey_parent_type_constraint
the_sub_survey_id
class dokomoforms.models.survey.NonAnswerableSurveyNode(**kwargs)[source]

Bases: dokomoforms.models.survey.SurveyNode

Contains a Node which is not answerable (e.g., a Note).

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

containing_survey_id
deleted
id
last_update_time
logic
node
node_id
node_languages
node_number
non_null_repeatable
root_survey_id
root_survey_languages
sub_survey_id
sub_survey_repeatable
survey_node_answerable
the_node
the_node_id
the_type_constraint
type_constraint
class dokomoforms.models.survey.SubSurvey(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A SubSurvey behaves like a Survey but belongs to a SurveyNode.

The way to arrive at a certain SubSurvey is encoded in its buckets.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

buckets
containing_survey_id
deleted
id
nodes
parent_allow_multiple
parent_node_id
parent_survey_node_id
parent_type_constraint
repeatable
root_survey_languages
sub_survey_number
class dokomoforms.models.survey.Survey(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A Survey has a list of SurveyNodes.

Use an EnumeratorOnlySurvey to restrict submissions to enumerators.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

administrators
containing_id
created_on
creator_id
default_language
deleted
earliest_submission_time
id
languages
last_update_time
latest_submission_time
nodes
num_submissions
submissions
survey_metadata
survey_type
title
url_slug
version
class dokomoforms.models.survey.SurveyNode(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A SurveyNode contains a Node and adds survey-specific metadata.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

containing_survey_id
deleted
id
last_update_time
logic
node

The Node instance.

node_id
node_languages
node_number
non_null_repeatable
root_survey_id
root_survey_languages
sub_survey_id
sub_survey_repeatable
survey_node_answerable
the_node
type_constraint
class dokomoforms.models.survey.TimestampBucket(**kwargs)[source]

Bases: dokomoforms.models.survey._RangeBucketMixin, dokomoforms.models.survey.Bucket

TSTZRANGE bucket.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

bucket
bucket_type
deleted
id
last_update_time
sub_survey_id
sub_survey_parent_node_id
sub_survey_parent_survey_node_id
sub_survey_parent_type_constraint
the_survey_node_id
dokomoforms.models.survey.administrator_filter(user_id)[source]

Filter a query by administrator id.

dokomoforms.models.survey.construct_bucket(*, bucket_type: str, **kwargs) → dokomoforms.models.survey.Bucket[source]

Return a subclass of dokomoforms.models.survey.Bucket.

The subclass is determined by the bucket_type parameter. This utility function makes it easy to create an instance of a Bucket subclass based on external input.

See http://stackoverflow.com/q/30518484/1475412

Parameters:
  • bucket_type – the type of the bucket. Must be one of the keys of dokomoforms.models.survey.BUCKET_TYPES
  • kwargs – the keyword arguments to pass to the constructor
Returns:

an instance of one of the Bucket subtypes

Raises:

dokomoforms.exc.NoSuchBucketTypeError

dokomoforms.models.survey.construct_survey(*, survey_type: str, **kwargs)[source]

Construct either a public or enumerator_only Survey.

dokomoforms.models.survey.construct_survey_node(**kwargs) → dokomoforms.models.survey.SurveyNode[source]

Return a subclass of dokomoforms.models.survey.SurveyNode.

The subclass is determined by the type_constraint parameter. This utility function makes it easy to create an instance of a SurveyNode subclass based on external input.

See http://stackoverflow.com/q/30518484/1475412

Parameters:kwargs – the keyword arguments to pass to the constructor
Returns:an instance of one of the Node subtypes
dokomoforms.models.survey.most_recent_surveys(session, user_id, limit=None)[source]

Get an administrator’s most recent surveys.

dokomoforms.models.survey.skipped_required(survey, answers) → str[source]

Return the id of a skipped AnswerableSurveyNode, or None.

dokomoforms.models.user module

User models.

class dokomoforms.models.user.Administrator(**kwargs)[source]

Bases: dokomoforms.models.user.User

A User who can create Surveys and add Users.

Regular users can answer surveys, but only Administrator instances can create surveys.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

deleted
emails
id
last_update_time
name
preferences
role
surveys
token
token_expiration
class dokomoforms.models.user.Email(**kwargs)[source]

Bases: dokomoforms.models.util.Base

Models an e-mail address.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

address
deleted
id
last_update_time
user_id
class dokomoforms.models.user.User(**kwargs)[source]

Bases: dokomoforms.models.util.Base

Models a user. A user has at least one e-mail address.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

deleted
emails
id
last_update_time
name
preferences
role
dokomoforms.models.user.construct_user(*, role: str, **kwargs)[source]

Construct either an enumerator or an administrator.

dokomoforms.models.util module

Useful reusable functions for models.

Models should inherit from dokomforms.models.util.Base, and should almost certainly make use of the dokomoforms.models.util.pk and dokomoforms.models.util.last_update_time

The SQLAlchemy documentation suggests setting those columns in the base class or using class mixins, but it makes it less explicit which columns exist when looking at the models’ definitions.

class dokomoforms.models.util.Base(**kwargs)[source]

Bases: abc.Base

The base class for all Dokomo Forms models.

deleted = Column(None, Boolean(), table=None, nullable=False, server_default=DefaultClause('false', for_update=False))
class dokomoforms.models.util.ModelJSONEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Bases: json.encoder.JSONEncoder

This JSONEncoder handles the models in dokomoforms.models.

To use it manually, call:

json.dumps(
model, cls=dokomoforms.models.util.ModelJSONEncoder, **kwargs

)

default(obj)[source]

Handle special types for json.dumps.

If obj is a model from dokomoforms.models, return a dictionary representation.

If obj is a datetime.date or datetime.time, return an ISO 8601 representation string.

If obj is a psycpg2 Range, return its string representation.

Otherwise, throw a TypeError.

See https://docs.python.org/3/library/json.html#json.JSONEncoder.default

Modify a query to search a column’s values (JSONB or TEXT).

TODO: document this

Parameters:
  • query – a
  • model_cls – aa
  • column – b
  • search_term – c
  • language – d
  • regex – r
Returns:

The modified query.

dokomoforms.models.util.create_engine(pool_size: int=None, max_overflow: int=None, echo: bool=None) → sqlalchemy.engine.base.Engine[source]

Get a connection to the database.

Return a sqlalchemy.engine.Engine configured with the options set in dokomoforms.options.options

Returns:a SQLAlchemy engine
dokomoforms.models.util.fk(column_name: str) → sqlalchemy.sql.schema.Column[source]

A foreign key with ONUPDATE CASCADE and ONDELETE CASCADE.

Return a foreign key of type UUID for use in models.

The relationship CASCADEs on UPDATE and DELETE.

Parameters:column_name – the name of the referenced column
Returns:a SQLAlchemy Column for a UUID primary key.
dokomoforms.models.util.get_fields_subset(model: dokomoforms.models.util.Base, fields: list) → collections.OrderedDict[source]

Return the given fields for the model’s dictionary representation.

dokomoforms.models.util.get_model(session, model_cls, model_id, exception=None)[source]

Throw an error if session.query.get(model_id) returns None.

dokomoforms.models.util.json_column(column_name: str, *, default=None) → sqlalchemy.sql.schema.Column[source]

A JSONB column.

Return a column of type JSONB for use in models. Use this for entries like

<language>: <text>
Parameters:
  • column_name – the name of the column
  • default – the column default (default value None, meaning no column default)
Returns:

a SQLAlchemy Column for a non-null JSONB type.

dokomoforms.models.util.jsonify(obj, *, raise_exception=False) → object[source]

Convert the given object to something JSON can handle.

dokomoforms.models.util.languages_column(column_name) → sqlalchemy.sql.schema.Column[source]

A TEXT[] column of length > 0.

Return an ARRAY(TEXT, as_tuple=True) column.

Parameters:column_name – the name of the column
Returns:a SQLAlchemy Column for a non-null ARRAY(TEXT, as_tuple=True) type.
dokomoforms.models.util.languages_constraint(column_name, languages_column_name) → sqlalchemy.sql.schema.Constraint[source]

CHECK CONSTRAINT for a translatable column.

Checks that all of the languages in the languages column exist as keys in the translatable column.

Parameters:
  • column_name – the name of the translatable column
  • languages_column_name – the name of the TEXT[] column containing the languages.
Returns:

a SQLAlchemy Constraint to ensure that all the required translations are available.

dokomoforms.models.util.last_update_time() → sqlalchemy.sql.schema.Column[source]

A timestamp column set to CURRENT_TIMESTAMP on update.

Return a column containing the time that a record was last updated.

Returns:a SQLAlchemy Column for a datetime with time zone auto-updating column
dokomoforms.models.util.pk(*foreign_key_column_names: str) → sqlalchemy.sql.schema.Column[source]

A UUID primary key.

Return a standard primary key of type UUID for use in models. If the any foreign_key_column_names are supplied, the primary key will reference the given columns.

Parameters:foreign_key_column_names – column names of the referenced foreign keys (should be ‘table_name.column_name’)
Returns:a SQLAlchemy Column for a UUID primary key.
Module contents

All the models used in Dokomo Forms.

class dokomoforms.models.Base(**kwargs)[source]

Bases: abc.Base

The base class for all Dokomo Forms models.

deleted = Column(None, Boolean(), table=None, nullable=False, server_default=DefaultClause('false', for_update=False))
dokomoforms.models.create_engine(pool_size: int=None, max_overflow: int=None, echo: bool=None) → sqlalchemy.engine.base.Engine[source]

Get a connection to the database.

Return a sqlalchemy.engine.Engine configured with the options set in dokomoforms.options.options

Returns:a SQLAlchemy engine
dokomoforms.models.jsonify(obj, *, raise_exception=False) → object[source]

Convert the given object to something JSON can handle.

dokomoforms.models.get_model(session, model_cls, model_id, exception=None)[source]

Throw an error if session.query.get(model_id) returns None.

class dokomoforms.models.ModelJSONEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]

Bases: json.encoder.JSONEncoder

This JSONEncoder handles the models in dokomoforms.models.

To use it manually, call:

json.dumps(
model, cls=dokomoforms.models.util.ModelJSONEncoder, **kwargs

)

default(obj)[source]

Handle special types for json.dumps.

If obj is a model from dokomoforms.models, return a dictionary representation.

If obj is a datetime.date or datetime.time, return an ISO 8601 representation string.

If obj is a psycpg2 Range, return its string representation.

Otherwise, throw a TypeError.

See https://docs.python.org/3/library/json.html#json.JSONEncoder.default

class dokomoforms.models.User(**kwargs)[source]

Bases: dokomoforms.models.util.Base

Models a user. A user has at least one e-mail address.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

deleted
emails
id
last_update_time
name
preferences
role
class dokomoforms.models.Administrator(**kwargs)[source]

Bases: dokomoforms.models.user.User

A User who can create Surveys and add Users.

Regular users can answer surveys, but only Administrator instances can create surveys.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

deleted
emails
id
last_update_time
name
preferences
role
surveys
token
token_expiration
class dokomoforms.models.Email(**kwargs)[source]

Bases: dokomoforms.models.util.Base

Models an e-mail address.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

address
deleted
id
last_update_time
user_id
dokomoforms.models.construct_user(*, role: str, **kwargs)[source]

Construct either an enumerator or an administrator.

class dokomoforms.models.Node(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A node is a Note or Question independent of any Survey.

A node is its own entity. A node can be a dokomoforms.models.survey.Note or a dokomoforms.models.survey.Question.

You can use this class for querying, e.g.
session.query(Node).filter_by(title=’Some Title’)

To create the specific kind of Node you want, use dokomoforms.models.survey.node.construct_node.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

deleted
hint
id
languages
last_update_time
logic
title
type_constraint
class dokomoforms.models.Question(**kwargs)[source]

Bases: dokomoforms.models.node.Node

A Question has a response type associated with it.

A Question has a type constraint associated with it (integer, date, text...). Only a dokomoforms.models.survey.MultipleChoiceQuestion has a list of dokomoforms.models.survey.Choice instances.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
dokomoforms.models.construct_node(*, type_constraint: str, **kwargs) → dokomoforms.models.node.Node[source]

Return a subclass of dokomoforms.models.node.Node.

The subclass is determined by the type_constraint parameter. This utility function makes it easy to create an instance of a Node or Question subclass based on external input.

See http://stackoverflow.com/q/30518484/1475412

Parameters:
  • type_constraint – the type constraint of the node. Must be one of the keys of dokomoforms.models.survey.NODE_TYPES
  • kwargs – the keyword arguments to pass to the constructor
Returns:

an instance of one of the Node subtypes

Raises:

dokomoforms.exc.NoSuchNodeTypeError

class dokomoforms.models.Note(**kwargs)[source]

Bases: dokomoforms.models.node.Node

Notes provide information interspersed with survey questions.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

deleted
hint
id
languages
last_update_time
logic
the_type_constraint
title
type_constraint
class dokomoforms.models.TextQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A text question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.PhotoQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A photo question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.IntegerQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A integer question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.DecimalQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A decimal question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.DateQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A date question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.TimeQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A time (with time zone) question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.TimestampQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A timestamp (with time zone) question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.LocationQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A location question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.FacilityQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A facility question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
deleted
hint
id
languages
last_update_time
logic
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.MultipleChoiceQuestion(**kwargs)[source]

Bases: dokomoforms.models.node._QuestionMixin, dokomoforms.models.node.Question

A multiple_choice question.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_multiple
allow_other
choices
deleted
hint
id
languages
last_update_time
logic
node_languages
the_languages
the_type_constraint
title
type_constraint
class dokomoforms.models.Choice(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A choice for a MultipleChoiceQuestion.

Models a choice for a dokomoforms.models.survey.MultipleChoiceQuestion.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

choice_number
choice_text
deleted
id
last_update_time
question_id
question_languages
class dokomoforms.models.Survey(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A Survey has a list of SurveyNodes.

Use an EnumeratorOnlySurvey to restrict submissions to enumerators.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

administrators
containing_id
created_on
creator_id
default_language
deleted
earliest_submission_time
id
languages
last_update_time
latest_submission_time
nodes
num_submissions
submissions
survey_metadata
survey_type
title
url_slug
version
class dokomoforms.models.EnumeratorOnlySurvey(**kwargs)[source]

Bases: dokomoforms.models.survey.Survey

Only enumerators (designated Users) can submit to this.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

administrators
containing_id
created_on
creator_id
default_language
deleted
earliest_submission_time
enumerators
id
languages
last_update_time
latest_submission_time
nodes
num_submissions
submissions
survey_metadata
survey_type
title
url_slug
version
class dokomoforms.models.SubSurvey(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A SubSurvey behaves like a Survey but belongs to a SurveyNode.

The way to arrive at a certain SubSurvey is encoded in its buckets.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

buckets
containing_survey_id
deleted
id
nodes
parent_allow_multiple
parent_node_id
parent_survey_node_id
parent_type_constraint
repeatable
root_survey_languages
sub_survey_number
class dokomoforms.models.SurveyNode(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A SurveyNode contains a Node and adds survey-specific metadata.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

containing_survey_id
deleted
id
last_update_time
logic
node

The Node instance.

node_id
node_languages
node_number
non_null_repeatable
root_survey_id
root_survey_languages
sub_survey_id
sub_survey_repeatable
survey_node_answerable
the_node
type_constraint
dokomoforms.models.construct_survey(*, survey_type: str, **kwargs)[source]

Construct either a public or enumerator_only Survey.

class dokomoforms.models.NonAnswerableSurveyNode(**kwargs)[source]

Bases: dokomoforms.models.survey.SurveyNode

Contains a Node which is not answerable (e.g., a Note).

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

containing_survey_id
deleted
id
last_update_time
logic
node
node_id
node_languages
node_number
non_null_repeatable
root_survey_id
root_survey_languages
sub_survey_id
sub_survey_repeatable
survey_node_answerable
the_node
the_node_id
the_type_constraint
type_constraint
class dokomoforms.models.AnswerableSurveyNode(**kwargs)[source]

Bases: dokomoforms.models.survey.SurveyNode

Contains a Node which is answerable (.e.g, a Question).

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer_count
answers
containing_survey_id
deleted
id
last_update_time
logic
node
node_id
node_languages
node_number
non_null_repeatable
required
root_survey_id
root_survey_languages
sub_survey_id
sub_survey_repeatable
sub_surveys
survey_node_answerable
the_containing_survey_id
the_node
the_node_id
the_node_languages
the_root_survey_languages
the_sub_survey_repeatable
the_type_constraint
type_constraint
dokomoforms.models.construct_survey_node(**kwargs) → dokomoforms.models.survey.SurveyNode[source]

Return a subclass of dokomoforms.models.survey.SurveyNode.

The subclass is determined by the type_constraint parameter. This utility function makes it easy to create an instance of a SurveyNode subclass based on external input.

See http://stackoverflow.com/q/30518484/1475412

Parameters:kwargs – the keyword arguments to pass to the constructor
Returns:an instance of one of the Node subtypes
dokomoforms.models.construct_bucket(*, bucket_type: str, **kwargs) → dokomoforms.models.survey.Bucket[source]

Return a subclass of dokomoforms.models.survey.Bucket.

The subclass is determined by the bucket_type parameter. This utility function makes it easy to create an instance of a Bucket subclass based on external input.

See http://stackoverflow.com/q/30518484/1475412

Parameters:
  • bucket_type – the type of the bucket. Must be one of the keys of dokomoforms.models.survey.BUCKET_TYPES
  • kwargs – the keyword arguments to pass to the constructor
Returns:

an instance of one of the Bucket subtypes

Raises:

dokomoforms.exc.NoSuchBucketTypeError

dokomoforms.models.skipped_required(survey, answers) → str[source]

Return the id of a skipped AnswerableSurveyNode, or None.

dokomoforms.models.administrator_filter(user_id)[source]

Filter a query by administrator id.

dokomoforms.models.most_recent_surveys(session, user_id, limit=None)[source]

Get an administrator’s most recent surveys.

class dokomoforms.models.Submission(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A Submission references a Survey and has a list of Answers.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

answers
deleted
id
last_update_time
save_time
start_time
submission_time
submission_type
submitter_email
submitter_name
survey_containing_id
survey_default_language
survey_id
survey_title
survey_type
class dokomoforms.models.EnumeratorOnlySubmission(**kwargs)[source]

Bases: dokomoforms.models.submission.Submission

An EnumeratorOnlySubmission must have an enumerator.

Use an EnumeratorOnlySubmission for an EnumeratorOnlySurvey.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

answers
deleted
enumerator
enumerator_user_id
id
last_update_time
save_time
start_time
submission_time
submission_type
submitter_email
submitter_name
survey_containing_id
survey_default_language
survey_id
survey_title
survey_type
the_survey_id
class dokomoforms.models.PublicSubmission(**kwargs)[source]

Bases: dokomoforms.models.submission.Submission

A PublicSubmission might have an enumerator.

Use a PublicSubmission for a Survey.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

answers
deleted
enumerator
enumerator_user_id
id
last_update_time
save_time
start_time
submission_time
submission_type
submitter_email
submitter_name
survey_containing_id
survey_default_language
survey_id
survey_title
survey_type
dokomoforms.models.construct_submission(*, submission_type: str, **kwargs) → dokomoforms.models.submission.Submission[source]

Return a subclass of dokomoforms.models.submission.Submission.

The subclass is determined by the submission_type parameter. This utility function makes it easy to create an instance of a Submission subclass based on external input.

See http://stackoverflow.com/q/30518484/1475412

Parameters:
  • submission_type – the type of submission. Must be either ‘public_submission’ or ‘enumerator_only_submission’
  • kwargs – the keyword arguments to pass to the constructor
Returns:

an instance of one of the Node subtypes

Raises:

dokomoforms.exc.NoSuchSubmissionTypeError

dokomoforms.models.most_recent_submissions(session, user_id, limit=None)[source]

Get an administrator’s surveys’ most recent submissions.

class dokomoforms.models.Answer(**kwargs)[source]

Bases: dokomoforms.models.util.Base

An Answer is a response to a SurveyNode.

An Answer can be one of an answer, an “other” response or a “don’t know” response. Answer.response abstracts over these 3 possibilites.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

allow_dont_know
allow_multiple
allow_other
answer

The answer. Could be the same as main_answer in simple cases.

This property is the most useful representation available of the answer. In the simplest case it is just a synonym for main_answer. It could otherwise be a dictionary or another model.

answer_metadata
answer_number
answer_type
deleted
dont_know

A text field containing “don’t know” responses.

id
last_update_time
main_answer

The representative part of a provided answer.

The main_answer is the only answer for simple types (integer, text, etc.) and for other types is the part of the answer that is most important. In practice, the main_answer is special only in that all Answer models have it, which is necessary for certain constraints and for the response property.

other

A text field containing “other” responses.

question_id
question_title
repeatable
response = OrderedDict([('type_constraint', <sqlalchemy.orm.attributes.InstrumentedAttribute object at 0x7fa94a2e27d8>), ('response_type', 'answer'), ('response', <property object at 0x7fa94a2c88b8>)])
save_time
submission_id
survey_containing_id
survey_id
survey_node
survey_node_containing_survey_id
survey_node_id
type_constraint
class dokomoforms.models.Photo(**kwargs)[source]

Bases: dokomoforms.models.util.Base

A BYTEA holding an image.

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_on
deleted
id
image
mime_type
dokomoforms.models.construct_answer(*, type_constraint: str, **kwargs) → dokomoforms.models.answer.Answer[source]

Return a subclass of dokomoforms.models.answer.Answer.

The subclass is determined by the type_constraint parameter. This utility function makes it easy to create an instance of an Answer subclass based on external input.

See http://stackoverflow.com/q/30518484/1475412

Parameters:
  • type_constraint – the type of the answer. Must be one of the keys of dokomoforms.models.answer.ANSWER_TYPES
  • kwargs – the keyword arguments to pass to the constructor
Returns:

an instance of one of the Answer subtypes

Raies:

dokomoforms.exc.NotAnAnswerTypeError

dokomoforms.models.add_new_photo_to_session(session, *, id, **kwargs)[source]

Create a new Photo and update the referenced PhotoAnswer.

dokomoforms.models.answer_min(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the minimum answer.

dokomoforms.models.answer_max(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the maximum answer.

dokomoforms.models.answer_sum(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the sum of the answers.

dokomoforms.models.answer_avg(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the average of the answers.

dokomoforms.models.answer_mode(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the mode of the answers.

dokomoforms.models.answer_stddev_pop(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the population standard deviation of the answers.

dokomoforms.models.answer_stddev_samp(survey_node: dokomoforms.models.survey.AnswerableSurveyNode)[source]

Get the sample standard deviation of the answers.

dokomoforms.models.generate_question_stats(survey)[source]

Get answer statistics for the nodes in a survey.

Submodules

dokomoforms.exc module

The base exception class is DokomoError.

exception dokomoforms.exc.DokomoError[source]

Bases: Exception

The base class for all exceptions used in Dokomo Forms.

exception dokomoforms.exc.InvalidTypeForOperation[source]

Bases: dokomoforms.exc.DokomoError

Invalid type for the selected aggregation function.

For instance, you can’t find the maximum of a text answer.

exception dokomoforms.exc.NoSuchBucketTypeError[source]

Bases: dokomoforms.exc.DokomoError

Invalid type_constraint for construct_bucket.

Raised when dokomoforms.models.survey.construct_bucket is called with an invalid type_constraint.

The valid type_constraints are the keys of dokomoforms.models.survey.BUCKET_TYPES.

exception dokomoforms.exc.NoSuchNodeTypeError[source]

Bases: dokomoforms.exc.DokomoError

Invalid type_constraint for construct_node.

Raised when dokomoforms.models.node.construct_node is called with an invalid type_constraint.

The valid type_constraints are the keys of dokomoforms.models.node.NODE_TYPES.

exception dokomoforms.exc.NoSuchSubmissionTypeError[source]

Bases: dokomoforms.exc.DokomoError

Invalid submission_type for construct_submission.

Raised when dokomoforms.models.submission.construct_submission is called with an invalid submission_type.

The valid types are ‘unathenticated’ and ‘enumerator_only_submission’

exception dokomoforms.exc.NotAResponseTypeError[source]

Bases: dokomoforms.exc.DokomoError

Invalid response_type Answer.response.setter.

Raised when trying to set the response field on an Answer with an invalid response_type.

The valid response_types are ‘answer’, ‘other’, and ‘dont_know’.

exception dokomoforms.exc.NotAnAnswerTypeError[source]

Bases: dokomoforms.exc.DokomoError

Invalid type_constraint for construct_answer.

Raised when dokomoforms.models.node.construct_answer is called with an invalid type_constraint.

The valid type_constraints are the keys of dokomoforms.models.answer.ANSWER_TYPES.

exception dokomoforms.exc.NotJSONifiableError[source]

Bases: dokomoforms.exc.DokomoError

The jsonify function encountered a strange object.

exception dokomoforms.exc.PhotoIdDoesNotExistError[source]

Bases: dokomoforms.exc.DokomoError

The submitted photo ID does not exist in the database.

exception dokomoforms.exc.RequiredQuestionSkipped[source]

Bases: dokomoforms.exc.DokomoError

A submission has no answer for a required question.

exception dokomoforms.exc.SurveyAccessForbidden[source]

Bases: dokomoforms.exc.DokomoError

The logged-in user does not have access to the survey.

exception dokomoforms.exc.UserRequiresEmailError[source]

Bases: dokomoforms.exc.DokomoError

A user must have at least one e-mail address.

dokomoforms.options module

All the application options are defined here.

If you need to inject options at runtime (for testing, etc...):

from dokomoforms.options import parse_options

parse_options(name1=value1, name2=value2, ...)

Module contents

Top level module for Dokomo Forms.

All of the application code for Dokomoforms (outside of the webapp.py script) lives in this module.

webapp module

Indices and tables