Skip to main content

An (even) higher-level MongoDB client

Project description

GitHub stars GitHub forks GitHub issues GitHub license Build Status


A convenience-based approach to MongoDB w/ Python that works as a drop-in replacement to the IO pymongo and AIO motor respective clients. Packaged due to excessive reuse in private projects, where it was used to facilitate agile, rapid development of multiple web applications. Database is intentionally loaded by default using URI (can be changed after instance is created), with an optional default collection param. Heads up, most commonly used methods of the client are in UPPERCASE, to ensure names are not taken by the parent classes and keep them nice and short.


Use the package manager pip to install cervmongo.

pip install cervmongo


import cervmongo

col_client = cervmongo.quick_load_client(
                                ) # convenience function

col_recs = col_client.GET() # returns cursor as very cool MongoListResponse
col_recs.count() # returns number of total documents in cursor
col_recs.list() # returns list of documents in cursor
col_recs.distinct() # returns list of unique values, default field "_id"
col_recs.sort() # returns self, allows sorting
# example of creating a document
result = col_client.POST({"key": "value"}) # returns pymongo Response document
# example of fetching a document
col_client.GET(result.inserted_id) # returns the created document as dict
# example of an update (patch)
col_client.PATCH(result.inserted_id, {"$set": {"key": "newvalue"}}) # update the document
# example of a query
col_client.GET({"key": "newvalue"}) # returns the cursor resulting from query
# will replace existing document if exists, else create new document with _id provided
col_client.PUT({"_id": result.inserted_id, "key": "finalvalue"})
# will delete document
col_client.DELETE(result.inserted_id) # returns deleted document

count = col_client.GET(count=True) # returns number of total documents in cursor
count_of_query = col_client.GET({"key": "value"}, count=True)
distinct_values_of_field_key = col_client.GET(distinct="key")
distinct_ids = col_client.GET(distinct=True) # _id is default
distinct_ids_with_query = col_client.GET({"key": "value"}, distinct=True)
sorted_query_one = col_client.GET(key="key", sort=cervmongo.DESC) # sorts in descending order by field 'key'
sorted_query_two = col_client.GET({"key": "value"}, key="key", sort=cervmongo.DESC)

client_class = cervmongo.get_client() # gets client class
client = client_class() # SyncIOClient (subclass of pymongo.MongoClient
# ~ motor.motor_asyncio.AsyncIOMotorClient, if async)
# same functionality as col_client above,
# but collection must be explicitly declared as first arg and
# query or record _id, if any, has to be second arg
# Example:
count = client.GET("test_col", count=True)
query_results = client.GET("test_col", {"key": "value"})

cursor_paged_results = client.PAGINATED_QUERY(after=None, before=None, limit=5) # returns cursor-based initial page
time_paged_results = client.PAGINATED_QUERY(sort="created_date", after=None, before=None, limit=5) # returns time-based initial page
offset_paged_results = client.PAGINATED_QUERY(page=1, limit=5) # returns offset-based initial page
count_of_multi_cols = client.GET(["test_col1", "test_col2"], count=True) # returns list of counts
multi_col_results = client.GET(["test_col1", "test_col2"], {
                "$or": [
                    {"child": "value"},
                    {"related_child": "value"}
                    ]}) # returns list of cursors matching query


  1. full testing on AIO Client & Doc classes
  2. finish type hints, function hints, and docstrings for readability
  3. pydantic first-class treatment
  4. restructuring/refactoring/optimizing
  5. web api
    • datatable mongodb plugin + web endpoint
    • restful fastapi server - extra
    • possible datatable html + javascript code generator


  • python 3.6+
  • python packages:
    • pymongo
    • python-dateutil
    • jsonschema
    • dataclasses


  • motor (for aio options)
  • pydantic (for obj/model validation, ORM)
  • marshmallow (json schema validation)
  • python-dotenv 0.12.0>= (for configuration of MongoDB client and cervmongo)
    • cervmongo Settings

      • DEBUG_LEVEL (default 30, i.e. logging.WARNING)
    • mongodb Settings

      • Can optionally provide either:
        • MONGO_HOST (default "")
        • MONGO_PORT (default 27017)
        • MONGO_DB (default None)
        • MONGO_REPLICA_SET (default None)
        • MONGO_MAX_POOL_SIZE (default 20)
        • MONGO_MIN_POOL_SIZE (default 10)
        • MONGO_USER (default None)
        • MONGO_PASSWORD (default None)
      • or:
        • MONGO_URI (default None, ex. "mongodb://localhost:27017/app?replicaSet=appSet")
        • For more information on a MongoDB URI, see here: Connection String URI Format.


Full documentation available here.


Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cervmongo-0.2.4.tar.gz (39.3 kB view hashes)

Uploaded Source

Built Distributions

cervmongo-0.2.4-py3.8.egg (94.1 kB view hashes)

Uploaded Source

cervmongo-0.2.4-py3-none-any.whl (45.4 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page