Metadata-Version: 2.1
Name: mongobase
Version: 0.3.1a0
Summary: A lightweight Pythonic OR Mapper for MongoDB.
Home-page: https://github.com/kazukiotsuka/mongobase
Author: Kazuki Otsuka
Author-email: otsuka.kazuki@googlemail.com
License: MIT
Keywords: mongodb,mongo,pymongo,orm,or mapper
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.7
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development :: Libraries
Requires-Python: ~=3.6
Description-Content-Type: text/markdown
Requires-Dist: pymongo (>=3.6.0)

![MongoBase Logo](https://github.com/kazukiotsuka/mongobase/blob/master/docs/source/img/mongobase.png)


MongoBase is a Python package that provides high-level features:
- Lightweight OR Mapper (ORM) for MongoDB
- Simple DataBase Model structure definition with automatic type checking
- High-level automatic text search indexes generation from multiple keys

### Dependencies
- pymongo_ 3.7+

More About MongoBase
-------------------------

| Component | Description |
| ---- | --- |
|**mongobase** | an high-level interface with model definition system from ModelBase and many database operations|
|**modelbase** | an OR Mapper class with automatic type checking according to the defined structure (MongoBase subclass)|

Philosophies on MongoBase are
- enable to use MongoDB on python easily and programatically safely
- cleary viewable everything about the data model just by a quick looking over the model definition
- easy to learn how to use. for instance, method names correspond to MongoDB to be able to use them as if on the mongoclient.
- high performance. it uses the latest connection pool mechanism so that efficiently use client objects




Basic Interfaces
---------------------------

#### Model Definition

Here is the sample definition of a model.

```python
class Bird(MongoBase):
    __collection__ = 'birds'
    __structure__ = {
        '_id': ObjectId,
        'name': str,
        'age': int,
        'is_able_to_fly': bool,
        'created': dt.datetime,
        'updated': dt.datetime
    }
    __required_fields__ = ['_id', 'name']
    __default_values__ = {
        '_id': ObjectId(),
        'is_able_to_fly': False,
        'created': dt.datetime.now(dt.timezone.utc),
        'updated': dt.datetime.now(dt.timezone.utc)
    }
    __validators__ = {
        'name': validate_length(0, 1000),
    }
    __search_text_keys__ = ['name'] 
    __search_text_index_type__ = 'bigram'
    __indexes__ = [
        [('item_name', ASCENDING),],
    ]
```

The core model structure is defined as `__structure__` by a dictionaly. It is possible to cleary find out how the document structure is.
Other components of the model definition is:

| Component | Description |
| ---- | --- |
| `__collection__`| the collection name of the document. (required)|
| `__structure__`| the core definition of the model. the type is automatically checked everytime when it is written on the db. the key `_id` is required. (required)|
| `__required_fields__`| required properties. (optional)|
| `__default_values__`| set default values for properties. (optional)|
| `__validators__`| validator methods automatically check the value when the document is written on the db. (optional)|
| `__search_text_keys__`| multiple keys can be set for the search text index. automatically written as the `search_text` property. (optional)|
| `__search_text_index_type__`| `bigram`: value of `search_text` is set as bigram strings. `morpheme`: the string in `search_text` is parsed to morphemes (optional)|
| `__search_text_weight_type__`| `uniform`: each string has the same weight. `weighted`: enable to set weights as `[('key1', 3), ('key2', 1)]` (optional)|
| `__indexes__`| indexes can be set. `.createIndex()` method creates the indexes on the db. (optional)|


Now the basic usages are introduced.

#### Insert & Update
```python
>> chicken = Bird({'_id': ObjectId(), 'name': 'chicken', 'age': 3})
>> chicken.save()
{'_id': ObjectId('5c80f4fa16fa0d6c102cd2a6'),
 'name': 'chicken',
 'age': 3,
 'is_able_to_fly': False,
 'created': datetime.datetime(2019, 3, 7, 10, 39, 54, 643685, tzinfo=datetime.timezone.utc),
 'updated': datetime.datetime(2019, 3, 7, 10, 39, 54, 643690, tzinfo=datetime.timezone.utc)}
>> chicken.is_able_to_fly = True
>> chicken.update()
```

#### Find
```python
>>> Bird.findOne({'name': 'mother chicken'})
{'_id': ObjectId('5c79166716fa0d215968d3ba'),
 'name': 'mother chicken',
 'age': 63,
 'is_able_to_fly': False,
 'created': datetime.datetime(2019, 3, 1, 11, 20, 21, 306000),
 'updated': datetime.datetime(2019, 3, 1, 11, 20, 21, 306000)}
>>> mother_chicken.remove()
1
>>> all_chickens = Bird.find({'name': 'chicken'}, sort=[('_id', ASCENDING)])
list of mongobase instances are returned.
>>> len(all_chickens)
18
>>> Bird.count()
201
```

#### Bulk Operations

- bulk_insert
```python
>>> many_pigeon = []
>>> for i in range(10000):
>>>     many_pigeon += [Bird({'_id': ObjectId(), 'name': f'pigeon', 'age': i})]
>>> Bird.bulk_insert(many_pigeon)
10000
```

- bulk_update
```
>>> updates = []
>>> for pigeon in many_pigeon:
>>>    pigeon.age *= 3
>>>    updates += [pigeon]
>>> Bird.bulk_update(updates)
10000
```




#### Contextual Database

```python
with db_context(db_uri='localhost', db_name='test') as db:
    flamingo = Bird({'_id': ObjectId(), 'name': 'flamingo', 'age': 20})
    flamingo.save(db=db)

    flamingo.age = 23
    flamingo = flamingo.update(db=db)
    flamingo = Bird.findAndUpdateById(flamingo._id, {'age': 24}, db=db)

    n_flamingo = Bird.count({'name': 'flamingo'}, db=db)

Bird.count({'name': 'flamingo'})

```

#### Multi Processing
```python
def breed(tasks):
    db = Bird._db()  # create a MongoDB Client for the forked process
    for i in range(len(tasks)):
        sparrow = Bird({'_id': ObjectId(), 'name': f'sparrow', 'age': 0})
        sparrow.save(db=db)

tasks = [[f'task {i}' for i in range(N_BATCH)] for j in range(N_PROCESS)
process_pool = multiprocessing.Pool(N_PROCESS)
process_pool.map(breed, tasks)
```


#### MongoBase has Many Other Features
If you'd like to know other features, please check the file mongobase.py.

DB Settings
---------------------------
simply write to mongobase/config.py
```python
MONGO_DB_URI = "101.21.434.121"
MONGO_DB_URI_TEST = "localhost"
MONGO_DB_NAME = "zoo"
MONGO_DB_NAME_TEST = "zoo-test"
MONGO_DB_CONNECT_TIMEOUT_MS = 3000
MONGO_DB_SERVER_SELECTION_TIMEOUT_MS = 3000
MONGO_DB_SOCKET_TIMEOUT_MS = 300000
MONGO_DB_SOCKET_KEEP_ALIVE = True
MONGO_DB_MAX_IDLE_TIME_MS = 40000
MONGO_DB_MAX_POOL_SIZE = 200
MONGO_DB_MIN_POOL_SIZE = 10
MONGO_DB_WAIT_QUEUE_MULTIPLE = 12
MONGO_DB_WAIT_QUEUE_TIMEOUT_MS = 100
```


Getting Started
------------------
If you start MongoBase, there is a tutorial jupyter notebook here.  
Highly recommend to check it.
https://github.com/kazukiotsuka/mongobase/blob/master/tutorial/MongoBase_starting_guide.ipynb


Release and Contributing
---------------------------
Many methods are the wrapper of pymongo.  
There are a lot of features that this library is covering.  
Would appreciate if you add their methods anytime.



#### version 0.3.0
##### New features
- bulk_insert()
- bulk_update()
- performance improvement with ConnectionPool (single MongoClient for each process)
- MongoBase_start_guide.ipynb
- contextual db client mode by  `with db_context() as db`
- code efficiency improvement
- abolished `insert_if_not_exists` parameter for `save(), update()`
- changed some method names (e.g. remove -> delete)
- using pymongo > 3.5 methods (e.g. insert_one()) 
- enhance documents

#### version 0.2.0
##### New features
- MongoBase and ModelBase class are separated
- enable to use MongoClient instance dynamically
- some useful mongodb operations are added

#### version 0.1.0
##### New features
- The initial implementation
- automatic type checking mechanism
- basic mongodb operations


License
--------------------
MongoBase is MIT-style licensed, as found in the LICENSE file.

