Skip to main content

An (even) higher-level MongoDB client

Project description

GitHub stars GitHub forks GitHub issues GitHub license Build Status

cervmongo

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.

Installation

Use the package manager pip to install cervmongo.

pip install cervmongo

Usage

import cervmongo

col_client = cervmongo.quick_load_client(
                                database="test_db",
                                collection="test_col",
                                replica_set=None,
                                async_=False
                                ) # 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


# OPTIONALLY
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)


# OPTIONALLY
cervmongo.get_config().set_mongo_db("test_db")
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"})


# OTHER FUNCTIONALITY
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

TODO:

  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

REQUIRES

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

RECOMMENDED

  • 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 "127.0.0.1")
        • 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.

Documentation

Full documentation available here.

Contributing

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.

License

MIT

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 details)

Uploaded Source

Built Distributions

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

Uploaded Source

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

Uploaded Python 3

File details

Details for the file cervmongo-0.2.4.tar.gz.

File metadata

  • Download URL: cervmongo-0.2.4.tar.gz
  • Upload date:
  • Size: 39.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.4.2 requests/2.22.0 setuptools/45.2.0 requests-toolbelt/0.8.0 tqdm/4.30.0 CPython/3.8.10

File hashes

Hashes for cervmongo-0.2.4.tar.gz
Algorithm Hash digest
SHA256 cc08cf00e6646e069e79365ad32eccc2b16b7bc5c3435898eb14b59581feef56
MD5 818805ee10914a662b7eb4a7791e5b34
BLAKE2b-256 04a2b288ec5e246f0419a2f52cf575b1a34216fb86cc193ceae3e43390f665dd

See more details on using hashes here.

File details

Details for the file cervmongo-0.2.4-py3.8.egg.

File metadata

  • Download URL: cervmongo-0.2.4-py3.8.egg
  • Upload date:
  • Size: 94.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.4.2 requests/2.22.0 setuptools/45.2.0 requests-toolbelt/0.8.0 tqdm/4.30.0 CPython/3.8.10

File hashes

Hashes for cervmongo-0.2.4-py3.8.egg
Algorithm Hash digest
SHA256 778ffa2415d0f5f9a3a84eddcca4502cd9612c51bec4d3c287e2ed346eafa316
MD5 63ae5243fe59e2cea12505d56b2b8b7a
BLAKE2b-256 03df56652de8768edf48977b59a993fc692cd437ba4607c8b1c30939ff167870

See more details on using hashes here.

File details

Details for the file cervmongo-0.2.4-py3-none-any.whl.

File metadata

  • Download URL: cervmongo-0.2.4-py3-none-any.whl
  • Upload date:
  • Size: 45.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.4.2 requests/2.22.0 setuptools/45.2.0 requests-toolbelt/0.8.0 tqdm/4.30.0 CPython/3.8.10

File hashes

Hashes for cervmongo-0.2.4-py3-none-any.whl
Algorithm Hash digest
SHA256 200566b69203305c703fb47f4cb699e88930d649fef8584eecef78623cf29dca
MD5 bfa9b27b5c6196734313880c20c99af9
BLAKE2b-256 164705392f0ba7256c42ac18bc41a9d540916c6739a27c9aa5995dbca654d113

See more details on using hashes here.

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