asyncmongo package¶

Subpackages¶

asyncmongo.exceptions package

Submodules¶

asyncmongo.auth module¶

class asyncmongo.auth.MongoCredential(mechanism, source, username, password, mechanism_properties, cache)¶

Bases: tuple

A hashable namedtuple of values used for authentication.

cache¶: Alias for field number 5

mechanism¶: Alias for field number 0

mechanism_properties¶: Alias for field number 4

password¶: Alias for field number 3

source¶: Alias for field number 1

username¶: Alias for field number 2

async asyncmongo.auth.try_authenticate(connection, credentials: MongoCredential)[source]¶

asyncmongo.client module¶

class asyncmongo.client.AsyncMongoClient[source]¶

Bases: object

Represents an asynchronous MongoDB client, providing connection management and database access.

connection: AsyncMongoConnection¶

async classmethod create(host: str | None = 'localhost', port: int | None = 27017) → AsyncMongoClient[source]¶

Creates an instance of AsyncMongoClient, initializing the connection to MongoDB.

Parameters:

host (str | None) – The hostname or URI of the MongoDB server. Defaults to “localhost”. If a URI is provided, it will be parsed to extract connection details.
port (int | None) – The port number for the MongoDB server. Defaults to 27017. Ignored if host is a URI.

Returns:

An instance of the MongoDB client.

Return type:

AsyncMongoClient

asyncmongo.client_options module¶

class asyncmongo.client_options.ClientOptions(username: str | None = None, password: str | None = None, database: str | None = None, options: dict | None = None)[source]¶

Bases: object

database: str | None = None¶

options: dict | None = None¶

password: str | None = None¶

username: str | None = None¶

asyncmongo.collection module¶

class asyncmongo.collection.Collection(database, name: str)[source]¶

Bases: object

Represents a MongoDB collection, providing methods to perform CRUD operations.

async drop_collection()[source]¶

Drops the collection from the database.

Returns:: None

find(filter: dict | None = None, skip: int = 0, limit: int = 0) → Cursor[source]¶

Queries the collection for documents matching a filter.

Parameters:

filter (dict | None) – The filter criteria. Defaults to None (no filtering).
skip (int) – Number of documents to skip. Defaults to 0.
limit (int) – Maximum number of documents to return. Defaults to 0 (no limit).

Returns:

A cursor to iterate over the results.

Return type:

Cursor

async find_one(filter: dict | None = None, skip: int = 0) → dict | None[source]¶

Queries the collection for a single document matching a filter.

Parameters:

filter (dict | None) – The filter criteria. Defaults to None (no filtering).
skip (int) – Number of documents to skip. Defaults to 0.

Returns:

The first document matching the filter, or None if no match is found.

Return type:

dict | None

async insert_one(doc) → dict[source]¶

Inserts a single document into the collection.

Parameters:: doc (dict) – The document to insert.
Returns:: The result of the insert operation.
Return type:: dict

async update_one(filter: dict, doc: dict)[source]¶

Updates a single document in the collection.

Parameters:

filter (dict) – The filter criteria to find the document to update.
doc (dict) – The updated document. _id will be removed if present.

Returns:

None

asyncmongo.connection module¶

class asyncmongo.connection.AsyncMongoConnection[source]¶

Bases: object

Manages an asynchronous connection to a MongoDB server, enabling communication and authentication for database operations.

async command(database_name: str, command: dict) → list | None[source]¶

Sends a command to the MongoDB server.

Parameters:

database_name (str) – The name of the database for the command.
command (dict) – The command to execute.

Returns:

The response from the server, parsed as a list of BSON documents.

Return type:

list | None

async classmethod create(host: str | None = 'localhost', port: int | None = 27017, options: ClientOptions | None = None) → AsyncMongoConnection[source]¶

Establishes an asynchronous connection to a MongoDB server.

Parameters:

host (str | None) – Hostname or IP address of the MongoDB server. Defaults to “localhost”.
port (int | None) – Port number of the MongoDB server. Defaults to 27017.
options (ClientOptions | None) – Optional client options for authentication.

Returns:

An instance of the connection.

Return type:

AsyncMongoConnection

async read() → list | None[source]¶

Reads a response from the MongoDB server.

Returns:: A list of BSON documents parsed from the server response, or None if no data is received.
Return type:: list | None

async send(payload: bytes) → list | None[source]¶

Sends a payload to the MongoDB server and reads the response.

Parameters:: payload (bytes) – The serialized payload to send.
Returns:: The parsed response documents, or None if no data is received.
Return type:: list | None

asyncmongo.cursor module¶

class asyncmongo.cursor.Cursor(collection, skip: int = 0, limit: int = 0, batch_size: int = 0, filter: dict | None = None)[source]¶

Bases: object

Represents a cursor for iterating over query results from a MongoDB collection. Supports asynchronous iteration and query options such as skip and limit.

limit(limit) → Cursor[source]¶

Sets the maximum number of documents to retrieve.

Parameters:: limit (int) – Maximum number of documents to retrieve.
Returns:: The current cursor instance.
Return type:: Cursor
Raises:: TypeError – If limit is not an integer.

skip(skip: int) → Cursor[source]¶

Sets the number of documents to skip.

Parameters:

skip (int) – Number of documents to skip.

Returns:

The current cursor instance.

Return type:

Cursor

Raises:

TypeError – If skip is not an integer.
ValueError – If skip is negative.

asyncmongo.database module¶

class asyncmongo.database.Database(client, name: str)[source]¶

Bases: object

Represents a MongoDB database, providing access to collections and database-level operations.

async list_collection_names() → list[str][source]¶

Lists all collection names in the database.

Returns:: A list of collection names.
Return type:: list[str]
Raises:: Any exception that occurs during the command execution. –

property name¶

The name of the database.

Returns:: The name of the database.
Return type:: str

asyncmongo.exceptions module¶

asyncmongo.message module¶

class asyncmongo.message.OP_MSG[source]¶

Bases: Structure

flagBits¶: Structure/Union member

messageLength¶: Structure/Union member

static new(bson_doc: dict) → bytes[source]¶

opCode¶: Structure/Union member

requestID¶: Structure/Union member

responseTo¶: Structure/Union member

sectionType¶: Structure/Union member

asyncmongo.uri_parser module¶

asyncmongo.uri_parser.parse_uri(uri)[source]¶

Parameters:

uri – example would be “mongodb://user:pencil@localhost:27017/admin?retryWrites=true&w=majority”

Returns:

dict of the form {

’nodelist’: <list of (host, port) tuples>, ‘username’: <username> or None, ‘password’: <password> or None, ‘database’: <database name> or None, ‘collection’: <collection name> or None, ‘options’: <dict of MongoDB URI options>, ‘fqdn’: <fqdn of the MongoDB+SRV URI> or None

}

Module contents¶

class asyncmongo.AsyncMongoClient[source]¶

Bases: object

Represents an asynchronous MongoDB client, providing connection management and database access.

connection: AsyncMongoConnection¶

async classmethod create(host: str | None = 'localhost', port: int | None = 27017) → AsyncMongoClient[source]¶

Creates an instance of AsyncMongoClient, initializing the connection to MongoDB.

Parameters:

host (str | None) – The hostname or URI of the MongoDB server. Defaults to “localhost”. If a URI is provided, it will be parsed to extract connection details.
port (int | None) – The port number for the MongoDB server. Defaults to 27017. Ignored if host is a URI.

Returns:

An instance of the MongoDB client.

Return type:

AsyncMongoClient

class asyncmongo.AsyncMongoConnection[source]¶

Bases: object

Manages an asynchronous connection to a MongoDB server, enabling communication and authentication for database operations.

async command(database_name: str, command: dict) → list | None[source]¶

Sends a command to the MongoDB server.

Parameters:

database_name (str) – The name of the database for the command.
command (dict) – The command to execute.

Returns:

The response from the server, parsed as a list of BSON documents.

Return type:

list | None

async classmethod create(host: str | None = 'localhost', port: int | None = 27017, options: ClientOptions | None = None) → AsyncMongoConnection[source]¶

Establishes an asynchronous connection to a MongoDB server.

Parameters:

host (str | None) – Hostname or IP address of the MongoDB server. Defaults to “localhost”.
port (int | None) – Port number of the MongoDB server. Defaults to 27017.
options (ClientOptions | None) – Optional client options for authentication.

Returns:

An instance of the connection.

Return type:

AsyncMongoConnection

async read() → list | None[source]¶

Reads a response from the MongoDB server.

Returns:: A list of BSON documents parsed from the server response, or None if no data is received.
Return type:: list | None

async send(payload: bytes) → list | None[source]¶

Sends a payload to the MongoDB server and reads the response.

Parameters:: payload (bytes) – The serialized payload to send.
Returns:: The parsed response documents, or None if no data is received.
Return type:: list | None

class asyncmongo.Database(client, name: str)[source]¶

Bases: object

Represents a MongoDB database, providing access to collections and database-level operations.

async list_collection_names() → list[str][source]¶

Lists all collection names in the database.

Returns:: A list of collection names.
Return type:: list[str]
Raises:: Any exception that occurs during the command execution. –

property name¶

The name of the database.

Returns:: The name of the database.
Return type:: str