Metadata-Version: 2.1
Name: atlasq
Version: 0.3.8
Summary: Query proxy that allows the usage of AtlasSearch with mongoengine specific syntax
Home-page: https://github.com/certego/atlasq
Author: Certego S.R.L
Project-URL: Documentation, https://github.com/certego/atlasq
Project-URL: Source, https://github.com/certego/atlasq
Project-URL: Tracker, https://github.com/certego/atlasq/issues
Keywords: certego atlas mongoengine python search textsearch atlassearch
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mongoengine (>=0.22.0)
Requires-Dist: requests (>=2.18.0)
Provides-Extra: dev
Requires-Dist: black (==22.3.0) ; extra == 'dev'
Requires-Dist: isort (==5.10.1) ; extra == 'dev'
Requires-Dist: pylint (==2.13.9) ; extra == 'dev'
Requires-Dist: flake8 (==4.0.1) ; extra == 'dev'
Requires-Dist: pre-commit (==2.19.0) ; extra == 'dev'
Requires-Dist: tox (==3.25.0) ; extra == 'dev'
Requires-Dist: tox-gh-actions (==2.9.1) ; extra == 'dev'
Requires-Dist: codecov (==2.1.12) ; extra == 'dev'
Requires-Dist: coverage (==6.4) ; extra == 'dev'
Requires-Dist: mongomock (==4.0.0) ; extra == 'dev'
Requires-Dist: mongoengine (>=0.22.0) ; extra == 'dev'
Requires-Dist: requests (>=2.18.0) ; extra == 'dev'
Provides-Extra: test
Requires-Dist: black (==22.3.0) ; extra == 'test'
Requires-Dist: isort (==5.10.1) ; extra == 'test'
Requires-Dist: pylint (==2.13.9) ; extra == 'test'
Requires-Dist: flake8 (==4.0.1) ; extra == 'test'
Requires-Dist: pre-commit (==2.19.0) ; extra == 'test'
Requires-Dist: tox (==3.25.0) ; extra == 'test'
Requires-Dist: tox-gh-actions (==2.9.1) ; extra == 'test'
Requires-Dist: codecov (==2.1.12) ; extra == 'test'
Requires-Dist: coverage (==6.4) ; extra == 'test'
Requires-Dist: mongomock (==4.0.0) ; extra == 'test'
Requires-Dist: mongoengine (>=0.22.0) ; extra == 'test'
Requires-Dist: requests (>=2.18.0) ; extra == 'test'

# AtlasQ
AtlasQ allows the usage of [AtlasSearch](https://www.mongodb.com/docs/atlas/atlas-search/) keeping the [MongoEngine](https://github.com/MongoEngine/mongoengine) syntax.

## Structure
The package tries to follow the MongoEngine structure;
the major differences reside in the `transform.py` and `queryset.py` files. 

### Transform
Like in MongoEngine, a step in the pipeline is the creation of a query from a `Q` object: 
we have to find a correspondence between the MongoEngine common syntax and what AtlasSearch allows.
For doing this, we had to find some compromises.

Not every keyword is supported at the moment: if you have an actual use case that you would like to support,
please be free to open an issue or a PR at any moment.

### QuerySet
There are probably a thousand of better implementation, if you actually knew MongoEngine and above all [PyMongo](https://pymongo.readthedocs.io/en/stable/).
Unfortunately, our knowledge is limited, so here we go. If you find a solution that works better, again, feel free to open an issue or a PR.

The main idea, is that the `filter` should work like an `aggregation`. 
For doing so, and with keeping the compatibility on how MongoEngine works (i.e. the filter should return a queryset of `Document`) we had to do some work.  
Calling `.aggregate` instead has to work as MongoEngine expect, meaning a list of dictionaries. 
#### Features

##### Validation
We also decided to have, optionally, a validation of the index.
Two things are checked:
- The index actually exists (If you query a non-existing index, Atlas as default behaviour will not raise any error).
- The fields that you are querying are actually indexed(If you query a field that is not indexed, Atlas as default behaviour will not raise any error, and will return an empty list).
To make these check, you need to call the function `ensure_index` on the queryset:


## Usage
Now the most important part: how do you use this package?


```python3
from mongoengine import Document, fields

from atlasq import AtlasManager, AtlasQ, AtlasQuerySet

index_name = str("my_index")

class MyDocument(Document):
    name = fields.StringField(required=True)
    surname = fields.StringField(required=True)
    atlas = AtlasManager(index_name)

obj = MyDocument.objects.create(name="value", surname="value2")

qs = MyDocument.atlas.filter(name="value")
assert isinstance(qs, AtlasQuerySet)
obj_from_atlas = qs.first()
assert obj == obj_from_atlas

obj2_from_atlas = MyDocument.atlas.get(AtlasQ(name="value") & AtlasQ(surname="value2"))
assert obj == obj2_from_atlas


obj3_from_atlas = MyDocument.atlas.get(AtlasQ(wrong_field="value"))
assert obj3_from_atlas is None

result = MyDocument.atlas.ensure_index("user", "pwd", "group", "cluster")
assert result is True
obj3_from_atlas = MyDocument.atlas.get(AtlasQ(wrong_field="value")) # raises AtlasIndexFieldError



```
