API Documentation


class humbledb.document.Document

This is the base class for a HumbleDB document. It should not be used directly, but rather configured via subclassing.

Example subclass:

class BlogPost(Document):
    config_database = 'db'
    config_collection = 'example'

    meta = Embed('m')
    meta.tags = 't'
    meta.slug = 's'
    meta.published = 'p'

    author = 'a'
    title = 't'
    body = 'b'

See Working with Documents for more information.


Return a list of the mapped keys.


Return a list of the mapped attributes.


Return this document as a dictionary, with short key names mapped to long names. This method is used by pytools.json.as_json().

Embedded Documents

class humbledb.document.Embed

This class is used to map attribute names on embedded subdocuments.

Example usage:

class MyDoc(Document):
    config_database = 'db'
    config_collection = 'example'

    embed = Embed('e')
    embed.val = 'v'
    embed.time = 't'

See Embedding Documents for more information.


Return this object mapped onto NameMap objects.


Return this object mapped onto reverse-lookup NameMap objects.


class humbledb.index.Index(index, cache_for=86400, background=True, **kwargs)

This class is used to create more complex indices. Takes the same arguments and keyword arguments as ensure_index().


class MyDoc(Document):
    config_database = 'db'
    config_collection = 'example'
    config_indexes = [Index('value', sparse=True)]

    value = 'v'

New in version 2.2.

See Specifying Indexes for more information.


Does an ensure_index call for this index with the given cls.

Parameters:cls – A Document subclass

MongoDB Connections

class humbledb.mongo.Mongo

Singleton context manager class for managing a single pymongo.connection.Connection instance. It is necessary that there only be one connection instance for pymongo to work efficiently with gevent or threading by using its built in connection pooling.

This class also manages connection scope, so that we can prevent Document instances from accessing the connection outside the context manager scope. This is so that we always ensure that end_request() is always called to release the socket back into the connection pool, and to restrict the scope where a socket is in use from the pool to the absolute minimum necessary.

This class is made to be thread safe.

Example subclass:

class MyConnection(Mongo):
    config_host = 'cluster1.mongo.mydomain.com'
    config_port = 27017

Example usage:

with MyConnection:
    doc = MyDoc.find_one()

See Configuring Connections for more information.


Public function for manually starting a session/context. Use carefully!


Public function for manually closing a session/context. Should be idempotent. This must always be called after Mongo.start() to ensure the socket is returned to the connection pool.


alias of UNSET


The report module contains the HumbleDB reporting framework.

class humbledb.report.Report

A report document.

classmethod record(event, stamp=None, safe=False, count=1)

Record an instance of event that happened at stamp.

If safe is True, then this method will wait for write acknowledgement from the server. The safe keyword has no effect for pymongo >= 3.0.0.

  • event (str) – Event identifier string
  • stamp (datetime.datetime) – Datetime stamp for this event (default: now)
  • safe (bool) – Safe write option passed to pymongo
  • count (int) – Number to increment
classmethod record_id(event, stamp)

Return a string suitable for use as the document id.



report.YEAR = 5
report.MONTH = 4
report.DAY = 3
report.HOUR = 2
report.MINUTE = 1


class humbledb.array.Array(_id, page_count=UNSET)

HumbleDB Array object. This helps manage paginated array documents in MongoDB. This class is designed to be inherited from, and not instantiated directly.

If you know the page_count for this array ahead of time, passing it in to the constructor will save an extra query on the first append for a given instance.

  • _id (str) – Sets the array’s shared id
  • page_count (int) – Total number of pages that already exist (optional)

Return all entries in this array.


Append an entry to this array and return the page count.

Parameters:entry (dict) – New entry
Returns:Total number of pages

Remove all documents in this array.


Return the total number of items in this array.


Creates a new page document.

Parameters:page_number (int) – The page number to create

Return the document ID for page_number. If page number is not specified the Array.page_count is used.

Parameters:page_number (int) – A page number (optional)

Return the total number of pages in this array.

class humbledb.array.Page

Document class used by Array.


humbledb.helpers.auto_increment(database, collection, _id, field='value', increment=1)

Factory method for creating a stored default value which is auto-incremented.

This uses a sidecar document to keep the increment counter sync’d atomically. See the MongoDB documentation for more information about how this works.


If a Document subclass is inherited and has an auto_increment helper, it will share the counter unless it’s overriden in the inheriting Document.

Example: using auto_increment fields

from humbledb.helpers import auto_increment

class MyDoc(Document):
    config_database = 'humbledb'
    config_collection = 'examples'

    # The auto_increment helper needs arguments:
    #     - database name: Database to store the sidecar document
    #     - collection name: Collection name that stores the sidecar
    #     - Id: A unique identifier for this document and field
    auto_id = auto_increment('humbledb', 'counters', 'MyDoc_auto_id')

    # The auto_increment helper can take an increment argument
    big_auto = auto_increment('humbledb', 'counters', 'MyDoc_big_auto',
  • database (str) – Database name
  • collection (str) – Collection name
  • _id (str) – Unique identifier for auto increment field
  • field (str) – Sidecar document field name (default: "value")
  • increment (int) – Amount to increment counter by (default: 1)