Metadata-Version: 1.2
Name: mongodbshell
Version: 0.1a4
Summary: Python tools for using MongoDB with the Python Shell (3.7)
Home-page: https://github.com/jdrumgoole/mongodbshell
Author: Joe Drumgoole
Author-email: joe@joedrumgoole.com
License: MIT
Description: 
        # mongodbshell - A utility class for the Python Shell
        
        the Python shell is the ideal environment for Python developers to interact
        with MongoDB. However output cursors and interacting with the database requires
        a little more boilerplate than is convenient. the `mongodbshell` package 
        provides a set a convenience functions and objects to allow easier
        interaction with MongoDB via the Python interpreter. 
        
        The easiest way to get started with `mongodbshell` is to import the prebuilt
        `mproxy` object. The `mproxy` object expects to connect to a `mongod` running 
        locally on port 27017 (it uses the [MongoDB URI](https://docs.mongodb.com/manual/reference/connection-string/) 
        `mongodb://localhost:27017` by default)
        
        ```python
        $ python3
        Python 3.6.5 (v3.6.5:f59c0932b4, Mar 28 2018, 03:03:55)
        [GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
        Type "help", "copyright", "credits" or "license" for more information.
        >>> from mongodbshell import mproxy
        >>> mproxy
        Proxy('test', 'test', 'mongodb://localhost:27017')
        >>> mproxy.list_database_names()
        1    config
        2    test
        3    local
        4    admin
        >>>
        ```
        Each proxy object has host of standard properties:
        ```python
        >>> mproxy.client
        MongoClient(host=['localhost:27017'], document_class=dict, tz_aware=False, connect=True)
        >>> mproxy.database
        Database(MongoClient(host=['localhost:27017'], document_class=dict, tz_aware=False, connect=True), 'test')
        >>> mproxy.collection
        Collection(Database(MongoClient(host=['localhost:27017'], document_class=dict, tz_aware=False, connect=True), 'test'), 'test')
        >>> mproxy.uri
        'mongodb://localhost:27017'
        >>>
        ```
        
        There are also convenience functions for the most popular operations:
        
        ```python
        >>> mproxy.is_master()
        {'ismaster': True,
         'localTime': datetime.datetime(2019, 1, 16, 15, 15, 41, 87000),
         'logicalSessionTimeoutMinutes': 30,
         'maxBsonObjectSize': 16777216,
         'maxMessageSizeBytes': 48000000,
         'maxWireVersion': 7,
         'maxWriteBatchSize': 100000,
         'minWireVersion': 0,
         'ok': 1.0,
         'readOnly': False}
        >>> mproxy.insert_one({"name" : "Joe Drumgoole", "twitter_handle" : "@jdrumgoole"})
        ObjectId('5c3f4f2fc3b498d6674b08f0')
        >>> mproxy.find_one( {"name" : "Joe Drumgoole"})
        1    {'_id': ObjectId('5c3f4b04c3b498d4a1c6ce22'),
        2     'name': 'Joe Drumgoole',
        3     'twitter_handle': '@jdrumgoole'}
        ```
        
        ## Line Numbers on Output
        
        Line numbers are added to output by default. You can turn off line numbers by
        setting the `line_numbers` flag to false.
        
        ```python
        >>> mproxy.insert_one({"name" : "Joe Drumgoole", "twitter_handle" : "@jdrumgoole"})
        ObjectId('5c3f4f2fc3b498d6674b08f0')
        >>> mproxy.find_one( {"name" : "Joe Drumgoole"})
        1    {'_id': ObjectId('5c3f4b04c3b498d4a1c6ce22'),
        2     'name': 'Joe Drumgoole',
        3     'twitter_handle': '@jdrumgoole'}
        >>> mproxy.line_numbers = False                      # Turn off line numbers
        >>> mproxy.find_one( {"name" : "Joe Drumgoole"})
        {'_id': ObjectId('5c3f4b04c3b498d4a1c6ce22'),
         'name': 'Joe Drumgoole',
         'twitter_handle': '@jdrumgoole'}
        >>>
        ```
        ## Connecting to a specific MongoDB URI
        
        You can connect to a different database by using the `Proxy` class. Here is an
        example connection to a [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) hosted datbase. 
        
        ```python
        >>> from mongodbshell import Proxy
        >>> atlas=Proxy(uri="mongodb+srv://readonly:readonly@demodata-rgl39.mongodb.net/test?retryWrites=true", database="demo", collection="zipcodes")
        >>> atlas.find_one()
        1    {'_id': '01069',
        2     'city': 'PALMER',
        3     'loc': [-72.328785, 42.176233],
        4     'pop': 9778,
        5     'state': 'MA'}
        
        ```
        
        ## Looking at large volumes of output
        
        If you run a query in the python shell it will return a cursor and to look at
        the objects in the cursor you need to either write a loop to consume the cursor
        or explicitly call `next()` on each cursor item.
        
        ```python
        >>> c=pymongo.MongoClient("mongodb+srv://readonly:readonly@demodata-rgl39.mongodb.net/test?retryWrites=true")
        >>> db=c["demo"]
        >>> collection=db["zipcodes"]
        >>> collection.find()
        <pymongo.cursor.Cursor object at 0x105bf1d68>
        >>> cursor=collection.find()
        >>> next(cursor)
        {'_id': '01069', 'city': 'PALMER', 'loc': [-72.328785, 42.176233], 'pop': 9778, 'state': 'MA'}
        >>> next(cursor)
        {'_id': '01002', 'city': 'CUSHMAN', 'loc': [-72.51565, 42.377017], 'pop': 36963, 'state': 'MA'}
        >>>
        ```
        
        This is tedious and becomes even more so when the objects are large enough to
        scroll off the screen. This is not a problem with the `mongodbshell` as the
        `Proxy` class and the built in `mproxy` object automatically handle 
        pretty printing and paginating outing. 
        
        ```python
        >>> atlas.find()
        1    {'_id': '01069', 'city': 'PALMER', 'loc': [-72.328785, 42.176233], 'pop': 9778, 'state': 'MA'}
        2    {'_id': '01002', 'city': 'CUSHMAN', 'loc': [-72.51565, 42.377017], 'pop': 36963, 'state': 'MA'}
        3    {'_id': '01012', 'city': 'CHESTERFIELD', 'loc': [-72.833309, 42.38167], 'pop': 177, 'state': 'MA'}
        4    {'_id': '01073', 'city': 'SOUTHAMPTON', 'loc': [-72.719381, 42.224697], 'pop': 4478, 'state': 'MA'}
        5    {'_id': '01096', 'city': 'WILLIAMSBURG', 'loc': [-72.777989, 42.408522], 'pop': 2295, 'state': 'MA'}
        6    {'_id': '01262', 'city': 'STOCKBRIDGE', 'loc': [-73.322263, 42.30104], 'pop': 2200, 'state': 'MA'}
        7    {'_id': '01240', 'city': 'LENOX', 'loc': [-73.271322, 42.364241], 'pop': 5001, 'state': 'MA'}
        8    {'_id': '01370', 'city': 'SHELBURNE FALLS', 'loc': [-72.739059, 42.602203], 'pop': 4525, 'state': 'MA'}
        9    {'_id': '01340', 'city': 'COLRAIN', 'loc': [-72.726508, 42.67905], 'pop': 2050, 'state': 'MA'}
        10   {'_id': '01462', 'city': 'LUNENBURG', 'loc': [-71.726642, 42.58843], 'pop': 9117, 'state': 'MA'}
        11   {'_id': '01473', 'city': 'WESTMINSTER', 'loc': [-71.909599, 42.548319], 'pop': 6191, 'state': 'MA'}
        12   {'_id': '01510', 'city': 'CLINTON', 'loc': [-71.682847, 42.418147], 'pop': 13269, 'state': 'MA'}
        13   {'_id': '01569', 'city': 'UXBRIDGE', 'loc': [-71.632869, 42.074426], 'pop': 10364, 'state': 'MA'}
        14   {'_id': '01775', 'city': 'STOW', 'loc': [-71.515019, 42.430785], 'pop': 5328, 'state': 'MA'}
        Hit Return to continue (q or quit to exit)
        ```
        Pagination will dynamically adjust to screen height.
        
        ## Outputting to a file
        
        The `Proxy` class can send output to a file by setting the `output_file` property
        on the `Proxy` class. 
        
        ```python
        >>> atlas.output_file="zipcodes.txt"
        >>> atlas.find()
        Output is also going to 'zipcodes.txt'
        1    {'_id': '01069', 'city': 'PALMER', 'loc': [-72.328785, 42.176233], 'pop': 9778, 'state': 'MA'}
        2    {'_id': '01002', 'city': 'CUSHMAN', 'loc': [-72.51565, 42.377017], 'pop': 36963, 'state': 'MA'}
        3    {'_id': '01012', 'city': 'CHESTERFIELD', 'loc': [-72.833309, 42.38167], 'pop': 177, 'state': 'MA'}
        4    {'_id': '01073', 'city': 'SOUTHAMPTON', 'loc': [-72.719381, 42.224697], 'pop': 4478, 'state': 'MA'}
        5    {'_id': '01096', 'city': 'WILLIAMSBURG', 'loc': [-72.777989, 42.408522], 'pop': 2295, 'state': 'MA'}
        6    {'_id': '01262', 'city': 'STOCKBRIDGE', 'loc': [-73.322263, 42.30104], 'pop': 2200, 'state': 'MA'}
        7    {'_id': '01240', 'city': 'LENOX', 'loc': [-73.271322, 42.364241], 'pop': 5001, 'state': 'MA'}
        8    {'_id': '01370', 'city': 'SHELBURNE FALLS', 'loc': [-72.739059, 42.602203], 'pop': 4525, 'state': 'MA'}
        9    {'_id': '01340', 'city': 'COLRAIN', 'loc': [-72.726508, 42.67905], 'pop': 2050, 'state': 'MA'}
        10   {'_id': '01462', 'city': 'LUNENBURG', 'loc': [-71.726642, 42.58843], 'pop': 9117, 'state': 'MA'}
        11   {'_id': '01473', 'city': 'WESTMINSTER', 'loc': [-71.909599, 42.548319], 'pop': 6191, 'state': 'MA'}
        12   {'_id': '01510', 'city': 'CLINTON', 'loc': [-71.682847, 42.418147], 'pop': 13269, 'state': 'MA'}
        13   {'_id': '01569', 'city': 'UXBRIDGE', 'loc': [-71.632869, 42.074426], 'pop': 10364, 'state': 'MA'}
        14   {'_id': '01775', 'city': 'STOW', 'loc': [-71.515019, 42.430785], 'pop': 5328, 'state': 'MA'}
        >>> print(open('zipcodes.txt').read())
        {'_id': '01069', 'city': 'PALMER', 'loc': [-72.328785, 42.176233], 'pop': 9778, 'state': 'MA'}
        {'_id': '01002', 'city': 'CUSHMAN', 'loc': [-72.51565, 42.377017], 'pop': 36963, 'state': 'MA'}
        {'_id': '01012', 'city': 'CHESTERFIELD', 'loc': [-72.833309, 42.38167], 'pop': 177, 'state': 'MA'}
        {'_id': '01073', 'city': 'SOUTHAMPTON', 'loc': [-72.719381, 42.224697], 'pop': 4478, 'state': 'MA'}
        {'_id': '01096', 'city': 'WILLIAMSBURG', 'loc': [-72.777989, 42.408522], 'pop': 2295, 'state': 'MA'}
        {'_id': '01262', 'city': 'STOCKBRIDGE', 'loc': [-73.322263, 42.30104], 'pop': 2200, 'state': 'MA'}
        {'_id': '01240', 'city': 'LENOX', 'loc': [-73.271322, 42.364241], 'pop': 5001, 'state': 'MA'}
        {'_id': '01370', 'city': 'SHELBURNE FALLS', 'loc': [-72.739059, 42.602203], 'pop': 4525, 'state': 'MA'}
        {'_id': '01340', 'city': 'COLRAIN', 'loc': [-72.726508, 42.67905], 'pop': 2050, 'state': 'MA'}
        {'_id': '01462', 'city': 'LUNENBURG', 'loc': [-71.726642, 42.58843], 'pop': 9117, 'state': 'MA'}
        {'_id': '01473', 'city': 'WESTMINSTER', 'loc': [-71.909599, 42.548319], 'pop': 6191, 'state': 'MA'}
        {'_id': '01510', 'city': 'CLINTON', 'loc': [-71.682847, 42.418147], 'pop': 13269, 'state': 'MA'}
        {'_id': '01569', 'city': 'UXBRIDGE', 'loc': [-71.632869, 42.074426], 'pop': 10364, 'state': 'MA'}
        {'_id': '01775', 'city': 'STOW', 'loc': [-71.515019, 42.430785], 'pop': 5328, 'state': 'MA'}
        ```
        Output will continue to be sent to the `output_file` until the output_file is assigned
        `None` or the empty string ("").
        
        ## Options
        
        You can set the following options on the `mproxy` or `Proxy` class objects. 
        
        `proxy.line_numbers` : Bool. True to display line numbers in output, False to 
        remove them.
        
        `proxy.pretty_print` : Bool. True to use `pprint.pprint` to output documents.
        False to write them out as the database returned them.
        
        `proxy.paginate` : Bool. True to paginate output based on screen height. False to just
        send all output directly to console.
        
        `proxy.output_file` : Str. Define a file to write results to. All output is
        appended to the file. Each line is flushed so content is not lost. Set `output_file`
        ton `None` or the emtpy string ("") to stop output going to a file.
        
        
        
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.5.0
