API Documentation¶
Documents¶
-
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.
-
mapped_keys
()¶ Return a list of the mapped keys.
-
mapped_attributes
()¶ Return a list of the mapped attributes.
-
for_json
()¶ 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.
-
as_name_map
(base_name)¶ Return this object mapped onto
NameMap
objects.
-
as_reverse_name_map
(base_name)¶ Return this object mapped onto reverse-lookup
NameMap
objects.
-
Indexes¶
-
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()
.Example:
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.
-
ensure
(cls)¶ 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 thatend_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.
-
start
()¶ Public function for manually starting a session/context. Use carefully!
-
end
()¶ 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.
-
config_uri
¶ alias of
UNSET
-
Reports¶
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.Parameters: - 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.
Parameters: - event (str) – A event identifier
- stamp (datetime.datetime) – Datetime for this event
-
classmethod
Arrays¶
-
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.
Parameters: -
all
()¶ Return all entries in this array.
-
append
(entry)¶ Append an entry to this array and return the page count.
Parameters: entry (dict) – New entry Returns: Total number of pages
-
clear
()¶ Remove all documents in this array.
-
length
()¶ Return the total number of items in this array.
-
new_page
(page_number)¶ Creates a new page document.
Parameters: page_number (int) – The page number to create
-
page_id
(page_number=None)¶ 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)
-
pages
()¶ Return the total number of pages in this array.
-
Helpers¶
-
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.
Note
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', increment=10)
Parameters: