Merge branch 'main' into stable

README.md

@@ -70,12 +70,26 @@ The examples below are used with the 'accounts' endpoint. Replace them with thei
 ### List
 
 ```python
+journals = api.journals.list()
+
+for journal in journals.items():
+    print(journal.ID)
+```
+
+Some endpoints require you to use a filter. If you do not filter, it will return an error.
+
+```python
+# raises ValueError
 accounts = api.accounts.list()
 
+# uses mandatory filtering
+accounts = api.accounts.list(filter={ 'Blocked' : 'false' })
+
 for account in accounts.items():
-    print(account.ID, account.Name)
+    print(account.ID)
 ```
 
+
 ### Get
 ```python
 accounts = api.accounts.get('uid')

exactonline/api.py

@@ -49,7 +49,7 @@ def doRequest(self, method, url, data=None, headers=None, files=None):
         else: headers = self.headers
 
         reqUrl = '{base}/{division}/{url}'.format(base=self.baseUrl, division=self.division, url=url)
-
+        
         if method == 'GET':
             response = requests.get(reqUrl, params=data, headers=headers)
         elif method == 'POST':

exactonline/endpoints/accounts.py

@@ -1,8 +1,8 @@
-from .base import APIEndpoint
+from .base import APIEndpoint, RequiresFiltering
 
 from exactonline.models.accounts import Account, AccountList
 
-class AccountMethods(APIEndpoint):
+class AccountMethods(RequiresFiltering, APIEndpoint):
 
     def __init__(self, api):
         super().__init__(api, 'crm/Accounts', Account, AccountList)

exactonline/endpoints/base.py

@@ -13,11 +13,32 @@ def __init__(self,
         self.singleObject = singleObject
         self.listObject = listObject
         self.pkField = pkField
-
-    def list(self, select=[]):
-        url = self.endpoint
-        if select: url = '{url}&$select={select}'.format(url=url, select=",".join(select))
-
+
+    def list(self, select=[], filter=None, filter_operator='and'):
+        url = '{0}'.format(self.endpoint)
+
+        if filter:
+            if filter_operator not in ['and', 'or']:
+                raise ValueError("'filter_operator' can only be 'and' or 'or'.")
+
+            url = '{url}?$filter='.format(url=url)
+            count = 0
+            for field, value in filter.items():
+
+                # if not boolean, put single quotes around value
+                if value.lower() not in ['false', 'true']:
+                    value = "'{value}'".format(value=value)
+
+                if count == 0:
+                    url = "{url}{field} eq {value}".format(url=url, field=field, value=value)
+                else:
+                    url = "{url} {operator} {field} eq {value}".format(url=url, operator=filter_operator, field=field, value=value)
+
+                count += 1
+
+        if select:
+            url = '{url}&$select={select}'.format(url=url, select=",".join(select))
+
         status, headers, respJson = self.api.get(url)
         if status != 200: return self.listObject().parseError(respJson)
         listObj = self.listObject().parse(respJson['d']['results'])
@@ -94,4 +115,12 @@ def delete(self, id):
         status, headers, respJson = self.api.delete(url, data)
 
         if status not in [200, 204]: return self.singleObject().parseError(respJson)
-        return True
+        return True
+
+class RequiresFiltering:
+
+   def list(self, select=[], filter=None, filter_operator='and'):
+        if not filter:
+            raise ValueError("Listing requires mandatory filtering. Specify a filter using the filter param. Syntax: { 'filter_field' : 'filter_value' }. ")
+
+        return super().list(select, filter, filter_operator)