API

Kard

class kardboard.models.Kard(**values)

Represents a card on a Kanban board.

key

A unique string that matches a Kard up to a ticket in a parent system.

title

A unicode string field.

backlog_date

When the card entered the backlog.

start_date

When the card was started.

done_date

When the card was completed.

state

Which column on the kanban board the card is in.

priority

Used when ordering cards in the backlog.

cycle_time

Caclucation of the number of days between the start of a card and its completion. Returns None if the card hasn’t completed yet.

lead_time

Caclucation of the number of days between the backlogging of a card and its completion. Returns None if the card hasn’t completed yet.

current_cycle_time(today=None)

Caclucation of the number of days between the start of a card and a comparison point (defaults to today). Returns None if the card hasn’t started yet.

classmethod in_progress(klass, date=None)

Cards that are in progress as of the supplied date (or now).

In progress is a semi-tricky calculation. If the date is today, it’s easy, it’s any ticket that doesn’t have a done_date. If the date is earlier, then it’s:

a.) Any ticket without a done_date whose backlog_date is lte than the reference date AND

b.) Any ticket with a done_date greater than the reference date and a start_date earlier than the reference date

classmethod backlogged(klass, date=None)

Cards that are backlogged as of the supplied date (or now).

Backlogged is a semi-tricky calculation. If the date is today, it’s easy, it’s any ticket that doesn’t have a done_date or a start_date.

If the date is earlier, then it’s:

a.) Any ticket without a done_date

whose backlog_date is lte than the reference date and who’s start_date is lte the reference date AND

b.) Any ticket with a start_date

greater than the reference date and a backlog_date earlier than the reference date

ticket_system

Instance of TICKET_HELPER

ticket_system_data

Dictionary of data supplied by TICKET_HELPER.

The exact composition of the dictionary varies by the helper used.

class kardboard.models.KardQuerySet(document, collection)

all()

Returns all documents.

all_fields()

Include all fields. Reset all previously calls of .only() and .exclude().

post = BlogPost.objects(...).exclude("comments").only("title").all_fields()

New in version 0.5.

clone()

Creates a copy of the current QuerySet

New in version 0.5.

count()

Count the selected elements in the query.

create(**kwargs)

Create new object. Returns the saved object instance.

New in version 0.4.

delete(safe=False)

Delete the documents matched by the query.

Parameters:safe – check if the operation succeeded before returning

distinct(field)

Return a list of distinct values for a given field.

Parameters:field – the field to select distinct values from

New in version 0.4.

done()

Kards that have been completed.

done_in_month(year=None, month=None, day=None, date=None)

Kards that have been completed in the specified month.

done_in_week(year=None, month=None, day=None, date=None)

Kards that were completed in the week of the specified day.

ensure_index(key_or_list, drop_dups=False, background=False, **kwargs)

Ensure that the given indexes are in place.

Parameters:key_or_list – a single index key or a list of index keys (to construct a multi-field index); keys may be prefixed with a + or a - to determine the index ordering

exclude(*fields)

Opposite to .only(), exclude some document’s fields.

post = BlogPost.objects(...).exclude("comments")

Parameters:fields – fields to exclude

New in version 0.5.

exec_js(code, *fields, **options)

Execute a Javascript function on the server. A list of fields may be provided, which will be translated to their correct names and supplied as the arguments to the function. A few extra variables are added to the function’s scope: collection, which is the name of the collection in use; query, which is an object representing the current query; and options, which is an object containing any options specified as keyword arguments.

As fields in MongoEngine may use different names in the database (set using the db_field keyword argument to a Field constructor), a mechanism exists for replacing MongoEngine field names with the database field names in Javascript code. When accessing a field, use square-bracket notation, and prefix the MongoEngine field name with a tilde (~).

Parameters:

• code – a string of Javascript code to execute
• fields – fields that you will be using in your function, which will be passed in to your function as arguments
• options – options that you want available to the function (accessed in Javascript through the options object)

explain(format=False)

Return an explain plan record for the QuerySet‘s cursor.

Parameters:format – format the plan before returning it

fields(**kwargs)

Manipulate how you load this document’s fields. Used by .only() and .exclude() to manipulate which fields to retrieve. Fields also allows for a greater level of control for example:

Retrieving a Subrange of Array Elements:

You can use the $slice operator to retrieve a subrange of elements in an array

post = BlogPost.objects(...).fields(slice__comments=5) // first 5 comments

Parameters:kwargs – A dictionary identifying what to include

New in version 0.5.

filter(*q_objs, **query)

An alias of __call__()

first()

Retrieve the first object matching the query.

get(*q_objs, **query)

Retrieve the the matching object raising MultipleObjectsReturned or DocumentName.MultipleObjectsReturned exception if multiple results and DoesNotExist or DocumentName.DoesNotExist if no results are found.

New in version 0.3.

get_or_create(write_options=None, *q_objs, **query)

Retrieve unique object or create, if it doesn’t exist. Returns a tuple of (object, created), where object is the retrieved or created object and created is a boolean specifying whether a new object was created. Raises MultipleObjectsReturned or DocumentName.MultipleObjectsReturned if multiple results are found. A new document will be created if the document doesn’t exists; a dictionary of default values for the new document may be provided as a keyword argument called defaults.

Parameters:write_options – optional extra keyword arguments used if we have to create a new document. Passes any write_options onto save()

New in version 0.3.

hint(index=None)

Added ‘hint’ support, telling Mongo the proper index to use for the query.

Judicious use of hints can greatly improve query performance. When doing a query on multiple fields (at least one of which is indexed) pass the indexed field as a hint to the query.

Hinting will not do anything if the corresponding index does not exist. The last hint applied to this cursor takes precedence over all others.

New in version 0.5.

in_bulk(object_ids)

Retrieve a set of documents by their ids.

Parameters:object_ids – a list or tuple of ObjectIds Return type:dict of ObjectIds as keys and collection-specific Document subclasses as values.

New in version 0.3.

insert(doc_or_docs, load_bulk=True)

bulk insert documents

Parameters:

• docs_or_doc – a document or list of documents to be inserted
• (optional) (load_bulk) – If True returns the list of document instances

By default returns document instances, set load_bulk to False to return just ObjectIds

New in version 0.5.

item_frequencies(field, normalize=False, map_reduce=True)

Returns a dictionary of all items present in a field across the whole queried set of documents, and their corresponding frequency. This is useful for generating tag clouds, or searching documents.

Note

Can only do direct simple mappings and cannot map across ReferenceField or GenericReferenceField for more complex counting a manual map reduce call would is required.

If the field is a ListField, the items within each list will be counted individually.

Parameters:

• field – the field to use
• normalize – normalize the results so they add to 1.0
• map_reduce – Use map_reduce over exec_js

Changed in version 0.5: defaults to map_reduce and can handle embedded document lookups

limit(n)

Limit the number of returned documents to n. This may also be achieved using array-slicing syntax (e.g. User.objects[:5]).

Parameters:n – the maximum number of objects to return

map_reduce(map_f, reduce_f, output, finalize_f=None, limit=None, scope=None)

Perform a map/reduce query using the current query spec and ordering. While map_reduce respects QuerySet chaining, it must be the last call made, as it does not return a maleable QuerySet.

See the test_map_reduce() and test_map_advanced() tests in tests.queryset.QuerySetTest for usage examples.

Parameters:

• map_f – map function, as Code or string
• reduce_f – reduce function, as Code or string
• output – output collection name, if set to ‘inline’ will try to use inline_map_reduce
• finalize_f – finalize function, an optional function that performs any post-reduction processing.
• scope – values to insert into map/reduce global scope. Optional.
• limit – number of objects from current query to provide to map/reduce method

Returns an iterator yielding MapReduceDocument.

Note

Map/Reduce changed in server version >= 1.7.4. The PyMongo map_reduce() helper requires PyMongo version >= 1.11.

Changed in version 0.5: - removed keep_temp keyword argument, which was only relevant for MongoDB server versions older than 1.7.4

New in version 0.3.

moving_cycle_time(year=None, month=None, day=None, weeks=4)

The moving average of cycle time for every day in the last N weeks.

moving_lead_time(year=None, month=None, day=None, weeks=4)

The moving average of lead time for every day in the last N weeks.

next()

Wrap the result in a Document object.

only(*fields)

Load only a subset of this document’s fields.

post = BlogPost.objects(...).only("title", "author.name")

Parameters:fields – fields to include

New in version 0.3.

Changed in version 0.5: - Added subfield support

order_by(*keys)

Order the QuerySet by the keys. The order may be specified by prepending each of the keys by a + or a -. Ascending order is assumed.

Parameters:keys – fields to order the query results by; keys may be prefixed with + or - to determine the ordering direction

rewind()

Rewind the cursor to its unevaluated state.

New in version 0.3.

select_related(max_depth=1)

Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.

New in version 0.5.

skip(n)

Skip n documents before returning the results. This may also be achieved using array-slicing syntax (e.g. User.objects[5:]).

Parameters:n – the number of objects to skip before returning results

slave_okay(enabled)

Enable or disable the slave_okay when querying.

Parameters:enabled – whether or not the slave_okay is enabled

snapshot(enabled)

Enable or disable snapshot mode when querying.

Parameters:enabled – whether or not snapshot mode is enabled

..versionchanged:: 0.5 - made chainable

sum(field)

Sum over the values of the specified field.

Parameters:field – the field to sum over; use dot-notation to refer to embedded document fields

Changed in version 0.5: - updated to map_reduce as db.eval doesnt work with sharding.

timeout(enabled)

Enable or disable the default mongod timeout when querying.

Parameters:enabled – whether or not the timeout is used

..versionchanged:: 0.5 - made chainable

update(safe_update=True, upsert=False, multi=True, write_options=None, **update)

Perform an atomic update on the fields matched by the query. When safe_update is used, the number of affected documents is returned.

Parameters:

• safe_update – check if the operation succeeded before returning
• upsert – Any existing document with that “_id” is overwritten.
• write_options – extra keyword arguments for update()

New in version 0.2.

update_one(safe_update=True, upsert=False, write_options=None, **update)

Perform an atomic update on first field matched by the query. When safe_update is used, the number of affected documents is returned.

Parameters:

• safe_update – check if the operation succeeded before returning
• upsert – Any existing document with that “_id” is overwritten.
• write_options – extra keyword arguments for update()
• update – Django-style update keyword arguments

New in version 0.2.

where(where_clause)

Filter QuerySet results with a $where clause (a Javascript expression). Performs automatic field name substitution like mongoengine.queryset.Queryset.exec_js().

Note

When using this mode of query, the database will call your function, or evaluate your predicate clause, for each object in the collection.

New in version 0.5.

with_id(object_id)

Retrieve the object matching the id provided.

Parameters:object_id – the value for the id of the document to look up

Ticket Helpers

class kardboard.tickethelpers.TicketHelper(config, kard)

actually_update()

Method called by the scheduled task. Updates the ticket from the originating system.

get_service_class()

Method called to extract, if any, the service class from the upstream ticket system. For example: Bug, Feature, Expedite, etc.

get_ticket_url(key=None)

A URL to the ticket in the orignating system.

get_title(key=None)

The title of the ticket

get_version()

Method called to extract, if any, the version from the upstream ticket system.

login(username, password)

Method used to authenticate a user. If successfull, it returns True.

update(sync=False)

Schedules a job to update the ticket from its originating system.

If sync is True, then the call is executed immediately as a blocking IO task.

class kardboard.tickethelpers.JIRAHelper(config, kard)