{"id":13530569,"url":"https://github.com/mongodb-labs/pymongoexplain","last_synced_at":"2025-12-30T02:36:43.522Z","repository":{"id":43395864,"uuid":"277894306","full_name":"mongodb-labs/pymongoexplain","owner":"mongodb-labs","description":"Explainable CRUD API for PyMongo","archived":false,"fork":false,"pushed_at":"2025-02-18T18:40:16.000Z","size":112,"stargazers_count":3,"open_issues_count":8,"forks_count":4,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-03-24T08:59:51.956Z","etag":null,"topics":["mongodb","pymongo","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pymongoexplain/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mongodb-labs.png","metadata":{"files":{"readme":"README.rst","changelog":"changelog.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-07-07T18:34:15.000Z","updated_at":"2025-02-18T18:40:20.000Z","dependencies_parsed_at":"2024-01-07T12:51:46.219Z","dependency_job_id":"816a69fa-6a73-47c4-86d9-c4ebf05f4425","html_url":"https://github.com/mongodb-labs/pymongoexplain","commit_stats":{"total_commits":25,"total_committers":3,"mean_commits":8.333333333333334,"dds":0.12,"last_synced_commit":"03fca5c6da51db7fa4c37317d78805e74311caf1"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb-labs%2Fpymongoexplain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb-labs%2Fpymongoexplain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb-labs%2Fpymongoexplain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongodb-labs%2Fpymongoexplain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mongodb-labs","download_url":"https://codeload.github.com/mongodb-labs/pymongoexplain/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246691662,"owners_count":20818546,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mongodb","pymongo","python"],"created_at":"2024-08-01T07:00:51.952Z","updated_at":"2025-12-30T02:36:43.482Z","avatar_url":"https://github.com/mongodb-labs.png","language":"Python","funding_links":[],"categories":["Libraries"],"sub_categories":["Python"],"readme":"==============\nPyMongoExplain\n==============\n\n:Info: Explain collections in PyMongo. See\n       `GitHub \u003chttps://github.com/mongodb-labs/pymongoexplain\u003e`_\n       for the latest source.\n:Author: Julius Park\n\nAbout\n=====\nThis package provides an ``ExplainableCollection`` class that allows PyMongo's Collection methods to be explained_\n\nPyMongoExplain greatly simplifies the amount of effort needed to explain commands.\nFor example, suppose we wanted to explain the following ``update_one``::\n\n    collection.update_one({\"quantity\": 1057, \"category\": \"apparel\"},{\"$set\": {\"reorder\": True}})\n\n\nBefore PyMongoExplain, one would need to convert the update_one into the equivalent MongoDB command::\n\n    collection.database.command(SON([('explain', SON([('update', 'products'), ('updates', [{'q': {'quantity': 1057, 'category': 'apparel'}, 'upsert': False, 'multi': False, 'u': {'$set': {'reorder': True}}}])])), ('verbosity', 'queryPlanner')]))\n\n\nAfter PyMongoExplain::\n\n    ExplainableCollection(collection).update_one({\"quantity\": 1057, \"category\": \"apparel\"},{\"$set\": {\"reorder\": True}})\n\n.. _explained: https://docs.mongodb.com/master/reference/command/explain/#dbcmd.explain.\n\nInstallation\n============\n\nTo install this package simply use pip::\n\n    pip install pymongoexplain\n\nSupport / Feedback\n==================\n\nFor questions, discussions, or general technical support, visit the `MongoDB Community Forums \u003chttps://developer.mongodb.com/community/forums/tag/python\u003e`_.\nThe MongoDB Community Forums are a centralized place to connect with other MongoDB users, ask questions, and get answers.\n\nBugs / Feature Requests\n=======================\n\nThink you’ve found a bug? Want to see a new feature in PyMongoExplain?\nPlease open an issue on this `GitHub repository \u003chttps://github.com/mongodb-labs/pymongoexplain\u003e`_.\n\nHow To Ask For Help\n-------------------\n\nPlease include all of the following information when opening an issue:\n\n- Detailed steps to reproduce the problem, including full traceback, if possible.\n- The exact python version used, with patch level::\n\n  $ python -c \"import sys; print(sys.version)\"\n\n- The exact version of PyMongo used (if applicable), with patch level::\n\n  $ python -c \"import pymongo; print(pymongo.version); print(pymongo.has_c())\"\n\n- The exact version of PyMongoExplain used::\n\n  $ python -c \"import pymongoexplain; print(pymongoexplain.version)\"\n\n\nDependencies\n============\n\nPyMongoExplain requires CPython 3.7+, and PyPy3.7+.\n\nPyMongoExplain requires `PyMongo\u003e=4.4 \u003chttps://github.com/mongodb/mongo-python-driver/\u003e`_\n\nTesting\n=======\n\nThe easiest way to run the tests is to run **pip install -e \".[test]\"; python -m pytest** in\nthe root of the distribution.\n\nTutorial\n========\n\nPyMongo operations in existing application code can be explained by swapping ``Collection`` objects with ``ExplainableCollection``\nobjects. The ``ExplainableCollection`` class provides all CRUD API methods provided by PyMongo's ``Collection``,\nbut using this class to run operations runs explain on them, instead of executing them.\n\nTo run explain on a command, first instantiate an ``ExplainableCollection`` from the ``Collection`` object originally used to run the command::\n\n    from pymongoexplain import ExplainableCollection\n\n    collection = client.db.products\n    explain = ExplainableCollection(collection)\n\nIf you wish to configure the options for the explain command itself, pass\nthem to the ``ExplainableCollection`` constructor like so::\n\n    explain = ExplainableCollection(collection, verbosity=\"queryPlanner\",\n                                    comment=\"I'm a comment\")\n\nFor more information see the documentation for the explain_ command.\n\n.. _explain: https://docs.mongodb.com/master/reference/command/explain/#dbcmd.explain.\n\nNow you are ready to explain some commands. Remember that explaining a command does not execute it::\n\n    result = explain.update_one({\"quantity\": 1057, \"category\": \"apparel\"}, {\"$set\": {\"reorder\": True}})\n\nNow ``result`` will contain the output of running explain on the given ``update_one`` command::\n\n    {'ok': 1.0,\n     'operationTime': Timestamp(1595603051, 3),\n     'queryPlanner': {'indexFilterSet': False,\n                      'namespace': 'db.products',\n                      'parsedQuery': {'$and': [{'category': {'$eq': 'apparel'}},\n                                               {'quantity': {'$eq': 1057}}]},\n                      'planCacheKey': 'CD8F6D8F',\n                      'plannerVersion': 1,\n                      'queryHash': 'CD8F6D8F',\n                      'rejectedPlans': [],\n                      'winningPlan': {'inputStage': {'direction': 'forward',\n                                                     'filter': {'$and': [{'category': {'$eq': 'apparel'}},\n                                                                         {'quantity': {'$eq': 1057}}]},\n                                                     'stage': 'COLLSCAN'},\n                                      'stage': 'UPDATE'}},\n     'serverInfo': {'gitVersion': '27f5c1ee9f513f29fe30b8ebefed99581428c6e1',\n                    'host': 'Juliuss-MBP.verizon.net',\n                    'port': 27017,\n                    'version': '4.4.0-rc13'}}\n\n\nSince ``ExplainableCollection`` instances provide all the same methods provided by ``Collection`` instances, explaining operations in your application code is a simple matter of replacing ``Collection`` instances in your application code with ``ExplainableCollection`` instances.\n\n\nExplaining commands in a script\n-------------------------------\n\nYou can also run explain on all commands within a Python script using our CLI tool.\nGiven a script that contains ``pymongo`` commands within it, you can simply run::\n\n    python3 -m pymongoexplain \u003cpath/to/your/script.py\u003e\n\nThis will log the explain output for every single command\nwithin the specified script, **in addition to running every command** in the script itself. Do note that because the\nexplain output is generated using the `logging \u003chttps://docs.python.org/3/library/logging.html\u003e`_ module,\nif your script configures logging module there are certain things to keep in mind:\n\n- if your script sets the `logging level \u003chttps://docs.python.org/3/library/logging.html#logging-levels\u003e`_ higher than INFO, the explain output will be suppressed entirely.\n- the explain output will be sent to whatever stream your script configures the logging module to send output to.\n\nAny positional parameters or arguments required by your script can be\nsimply be appended to the invocation as follows::\n\n    python3 -m pymongoexplain \u003cpath/to/your/script.py\u003e [PARAMS] [--optname OPTS]\n\n\nLimitations\n-----------\n\nThis package does not support the fluent `Cursor API \u003chttps://pymongo.readthedocs.io/en/stable/api/pymongo/cursor.html\u003e`_,\nso if you attempt to use it like so::\n\n    ExplainableCollection(collection).find({}).sort(...)\n\nInstead pass all the arguments to the find() call, like so::\n\n    ExplainableCollection(collection).find({}, sort=...)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmongodb-labs%2Fpymongoexplain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmongodb-labs%2Fpymongoexplain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmongodb-labs%2Fpymongoexplain/lists"}