MongoDB

MongoResources Instance

The MongoResources instance provides access to the MongoDB resource configs, client and database connections. This instance is available under the SuperdeskAsyncApp.mongo attribute.

There are two groups of functions to use: one for standard synchronous connections and another for asynchronous connections. The functions ending in _async provide the asynchronous version.

For example:

from superdesk.core.app import get_current_async_app

def test():
    users = get_current_async_app().mongo.get_db("users")
    user = users.find_one({"_id": "abcd123"})

async def test_async()
    users = get_current_async_app().mongo.get_db_async("users")
    user = await users.find_one({"_id": "abcd123"})

The get_db method returns an instance of a PyMongo Database.

The get_db_async method returns an instance of a Motor AsyncIOMotorDatabase.

Mongo References

class MongoResourceConfig(prefix: str = 'MONGO', indexes: List[MongoIndexOptions] | None = None, version_indexes: List[MongoIndexOptions] | None = None, versioning: bool = False)[source]

Resource config for use with MongoDB, to be included with the ResourceConfig

prefix: str = 'MONGO'

Config prefix to be used

indexes: List[MongoIndexOptions] | None = None

Optional list of mongo indexes to be created for this resource

version_indexes: List[MongoIndexOptions] | None = None

Optional list of mongo indexes to be created for the versioning resource

versioning: bool = False

Boolean determining if this resource supports versioning

class MongoIndexOptions(name: str, keys: list[tuple[str, Literal[1, -1]]], unique: bool = True, background: bool = True, sparse: bool = True, collation: MongoIndexCollation | None = None, partialFilterExpression: Dict[str, Any] | None = None)[source]

Dataclass for easy construction of Mongo Index options

See https://mongodb.com/docs/manual/reference/method/db.collection.createIndex

name: str

Name of the MongoDB Index

keys: list[tuple[str, Literal[1, -1]]]

List of keys to be used for the MongoDB Index

unique: bool = True

Ensures that the indexed fields do not store duplicate values

background: bool = True

Create index in the background, allowing read and write operations to the database while the index builds

sparse: bool = True

If True, the index only references documents with the specified field.

collation: MongoIndexCollation | None = None

allows users to specify language-specific rules for string comparison

partialFilterExpression: Dict[str, Any] | None = None

allows to filter documents for this index

class MongoIndexCollation[source]

TypedDict class for collation config

See https://www.mongodb.com/docs/manual/core/index-case-insensitive

locale: str

Specifies language rules

strength: int

Determines comparison rules. A strength value of 1 or 2 indicates case-insensitive collation

class MongoResources(app: SuperdeskAsyncApp)[source]
app: SuperdeskAsyncApp

A reference back to the parent app, for configuration purposes

register_resource_config(name: str, config: MongoResourceConfig)

Register a Mongo resource config

Raises:

KeyError – if a resource with the same name already exists

get_resource_config(resource_name: str) → MongoResourceConfig

Gets a resource config from a registered resource

Returns a deepcopy of the config, so the original cannot be modified

Raises:

KeyError – if a resource with the provided name is not registered

get_all_resource_configs() → Dict[str, MongoResourceConfig]

Get configs from all registered resources

Returns a deepcopy of all configs, so the originals cannot be modified

close_all_clients()

Closes all clients (sync and async) to the Mongo database(s)

stop()

Disconnects all clients and de-registers all resource configs

get_client(resource_name: str, versioning: bool = False) → Tuple[MongoClient, Database]

Get a synchronous client and a database connection from a registered resource

Caches the client connection based on the resource_name, so subsequent calls re-use the same connection.

Parameters:

  • resource_name – The name of the registered resource

  • versioning – If True, will provide client to the versioned collection

Raises:

KeyError – if a resource with the provided resource_name is not registered

get_db(resource_name: str, versioning: bool = False) → Database

Get a synchronous database connection from a registered resource

Caches the database connection based on the resource_name, so subsequent calls re-use the same connection.

Parameters:

  • resource_name – The name of the registered resource

  • versioning – If True, will provide client to the versioned collection

Raises:

KeyError – if a resource with the provided resource_name is not registered

get_collection(resource_name, versioning: bool = False) → Collection

Get a collection connection from a registered resource

Caches the database connection based on the resource_name, so subsequent calls re-use the same connection.

Parameters:

  • resource_name – The name of the registered resource

  • versioning – If True, will provide client to the versioned collection

Raises:

KeyError – if a resource with the provided resource_name is not registered

create_resource_indexes(resource_name: str, ignore_duplicate_keys=False)

Creates indexes for a resource

If the resource config has versioning == True, then indexes will also be created for the versioning collection.

Parameters:

  • resource_name – The name of the registered resource

  • ignore_duplicate_keys – If True, will ignore duplicate key errors

Raises:

KeyError – if a resource with the provided resource_name is not registered

create_indexes_for_all_resources() → set[str]

Creates indexes for all registered resources

get_client_async(resource_name: str, versioning: bool = False) → Tuple[AsyncIOMotorClient, AsyncIOMotorDatabase]

Get an asynchronous client and a database connection from a registered resource

Caches the client connection based on the resource_name, so subsequent calls re-use the same connection.

Raises:

KeyError – if a resource with the provided resource_name is not registered

get_db_async(resource_name: str, versioning: bool = False) → AsyncIOMotorDatabase

Get an asynchronous database connection from a registered resource

Caches the database connection based on the resource_name, so subsequent calls re-use the same connection.

Raises:

KeyError – if a resource with the provided resource_name is not registered

get_collection_async(resource_name: str, versioning: bool = False) → AsyncIOMotorCollection

Get an asynchronous collection connection from a registered resource

Caches the database connection based on the resource_name, so subsequent calls re-use the same connection.

Raises:

KeyError – if a resource with the provided resource_name is not registered