## [v8.9]() (2020-10-21)

**Added**

- added `required` and `excluded` optional parameters to the TopicPage class to methods `addConcept`, `addKeyword`, `addCategory`, `addSource`, `addSourceLocation` and `addSourceGroup`.
- exceptions are now raised by the SDK library in case of status codes 204, 400, 401 and 403. Previously, the requests were repeated if status code was not 200. In  case of these status codes it however doesn't make sense to simply repeat the requests as the query will for sure return the same exception. The meaning of the above status codes is described on the [documentation page](https://eventregistry.org/documentation?tab=introduction).

Author: gregorleban

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change Log
 
+## [v8.9]() (2020-10-21)
+
+**Added**
+
+- added `required` and `excluded` optional parameters to the TopicPage class to methods `addConcept`, `addKeyword`, `addCategory`, `addSource`, `addSourceLocation` and `addSourceGroup`.
+- exceptions are now raised by the SDK library in case of status codes 204, 400, 401 and 403. Previously, the requests were repeated if status code was not 200. In  case of these status codes it however doesn't make sense to simply repeat the requests as the query will for sure return the same exception. The meaning of the above status codes is described on the [documentation page](https://eventregistry.org/documentation?tab=introduction).
+
+
 ## [v8.8]() (2020-08-20)
 
 **Added**

eventregistry/EventRegistry.py

@@ -83,6 +83,15 @@ def __init__(self,
         if printHostInfo:
             print("Event Registry host: %s" % (self._host))
             print("Text analytics host: %s" % (self._hostAnalytics))
+
+        # list of status codes - when we get them as a response from the call, we don't want to repeat the query as the response will likely always be the same
+        self._stopStatusCodes = set([
+            204,        # Information not available. Request succeeded, but the requested information is not available.
+            400,        # Bad request. The request was unacceptable, most likely due to invalid or missing parameter.
+            401,        # User's limit reached. The user reached the limit of the tokens in his account. The requests are rejected.
+            403,        # Invalid account. The user's IP or account is disabled, potentially due to misuse.
+        ])
+
         # check what is the version of your module compared to the latest one
         self.checkVersion()
 
@@ -301,9 +310,10 @@ def jsonRequest(self, methodUrl, paramDict, customLogFName = None, allowUseOfArc
                 if self._verboseOutput:
                     print("endpoint: %s\nParams: %s" % (url, json.dumps(paramDict, indent=4)))
                 self.printLastException()
-                # in case of invalid input parameters, don't try to repeat the search
-                if respInfo != None and (respInfo.status_code == 400 or respInfo.status_code == 530 or respInfo.status_code == 204):
-                    break
+                # in case of invalid input parameters, don't try to repeat the search but we simply raise the same exception again
+                if respInfo != None and respInfo.status_code in self._stopStatusCodes:
+                    raise ex
+                # in case of the other exceptions (maybe the service is temporarily unavailable) we try to repeat the query
                 print("The request will be automatically repeated in 3 seconds...")
                 time.sleep(3)   # sleep for X seconds on error
         self._lock.release()

eventregistry/TopicPage.py

@@ -209,67 +209,79 @@ def clearLocations(self):
         self.topicPage["locations"] = []
 
 
-    def addConcept(self, conceptUri, weight, label = None, conceptType = None, required = False):
+    def addConcept(self, conceptUri, weight, label = None, conceptType = None, required = False, excluded = False):
         """
         add a relevant concept to the topic page
         @param conceptUri: uri of the concept to be added
         @param weight: importance of the provided concept (typically in range 1 - 50)
+        @param required: if true, then all results will HAVE TO be annotated with this concept
+        @param excluded: if true, then all results annotated with this concept will be ignored
         """
         assert isinstance(weight, (float, int)), "weight value has to be a positive or negative integer"
-        concept = {"uri": conceptUri, "wgt": weight, "required": required}
+        assert not (required == True and excluded == True), "Parameters required and excluded can not be True at the same time"
+        concept = {"uri": conceptUri, "wgt": weight, "required": required, "excluded": excluded }
         if label != None: concept["label"] = label
         if conceptType != None: concept["type"] = conceptType
         self.topicPage["concepts"].append(concept)
 
 
-    def addKeyword(self, keyword, weight):
+    def addKeyword(self, keyword, weight, required = False, excluded = False):
         """
         add a relevant keyword to the topic page
         @param keyword: keyword or phrase to be added
         @param weight: importance of the provided keyword (typically in range 1 - 50)
+        @param required: if true, then all results will HAVE TO mention this keyword to appear in the results
+        @param excluded: if true, then no results that mention this keyword will be returned
         """
         assert isinstance(weight, (float, int)), "weight value has to be a positive or negative integer"
-        self.topicPage["keywords"].append({"keyword": keyword, "wgt": weight})
+        assert not (required == True and excluded == True), "Parameters required and excluded can not be True at the same time"
+        self.topicPage["keywords"].append({"keyword": keyword, "wgt": weight, "required": required, "excluded": excluded })
 
 
-    def addCategory(self, categoryUri, weight):
+    def addCategory(self, categoryUri, weight, required = False, excluded = False):
         """
         add a relevant category to the topic page
         @param categoryUri: uri of the category to be added
         @param weight: importance of the provided category (typically in range 1 - 50)
+        @param required: if true, then all results will HAVE TO be annotated with this category to appear in the results
+        @param excluded: if true, then no results with this category will be returned
         """
         assert isinstance(weight, (float, int)), "weight value has to be a positive or negative integer"
-        self.topicPage["categories"].append({"uri": categoryUri, "wgt": weight})
+        assert not (required == True and excluded == True), "Parameters required and excluded can not be True at the same time"
+        self.topicPage["categories"].append({"uri": categoryUri, "wgt": weight, "required": required, "excluded": excluded })
 
 
-    def addSource(self, sourceUri, weight):
+    def addSource(self, sourceUri, weight, excluded = False):
         """
         add a news source to the topic page
         @param sourceUri: uri of the news source to add to the topic page
         @param weight: importance of the news source (typically in range 1 - 50)
+        @param excluded: if true, then the results from these sources will be ignored
         """
         assert isinstance(weight, (float, int)), "weight value has to be a positive or negative integer"
-        self.topicPage["sources"].append({"uri": sourceUri, "wgt": weight})
+        self.topicPage["sources"].append({"uri": sourceUri, "wgt": weight, "excluded": excluded })
 
 
-    def addSourceLocation(self, sourceLocationUri, weight):
+    def addSourceLocation(self, sourceLocationUri, weight, excluded = False):
         """
         add a list of relevant sources by identifying them by their geographic location
         @param sourceLocationUri: uri of the location where the sources should be geographically located
         @param weight: importance of the provided list of sources (typically in range 1 - 50)
+        @param excluded: if true, then the results from the sources from this location will be ignored
         """
         assert isinstance(weight, (float, int)), "weight value has to be a positive or negative integer"
-        self.topicPage["sourceLocations"].append({"uri": sourceLocationUri, "wgt": weight})
+        self.topicPage["sourceLocations"].append({"uri": sourceLocationUri, "wgt": weight, "excluded": excluded })
 
 
-    def addSourceGroup(self, sourceGroupUri, weight):
+    def addSourceGroup(self, sourceGroupUri, weight, excluded = False):
         """
         add a list of relevant sources by specifying a whole source group to the topic page
         @param sourceGroupUri: uri of the source group to add
         @param weight: importance of the provided list of sources (typically in range 1 - 50)
+        @param excluded: if true, then the results from sources from this group will be ignored
         """
         assert isinstance(weight, (float, int)), "weight value has to be a positive or negative integer"
-        self.topicPage["sourceGroups"].append({"uri": sourceGroupUri, "wgt": weight})
+        self.topicPage["sourceGroups"].append({"uri": sourceGroupUri, "wgt": weight, "excluded": excluded })
 
 
     def addLocation(self, locationUri, weight):

eventregistry/examples/QueryArticlesExamples.py

@@ -3,8 +3,7 @@
 """
 from eventregistry import *
 
-er = EventRegistry(allowUseOfArchive=False)
-# er = EventRegistry()
+er = EventRegistry(apiKey = "6e8ab56e-b4d8-4032-94cc-db5138e0370c", allowUseOfArchive=False)
 
 
 # search for the phrase "Barack Obama" - both words have to appear together

…entregistry/tests/TestAutoSuggestions.py …tregistry/tests/TestERAutoSuggestions.pyeventregistry/tests/TestAutoSuggestions.py renamed to eventregistry/tests/TestERAutoSuggestions.py eventregistry/tests/TestAutoSuggestions.py renamed to eventregistry/tests/TestERAutoSuggestions.py

@@ -37,6 +37,31 @@ def testGetEventsForTopicPage(self):
                 uriSet.add(event.get("uri"))
 
 
+    def testCreateTopicPage(self):
+        topic = TopicPage(self.er)
+        appleUri = self.er.getConceptUri("apple")
+        msoftUri = self.er.getConceptUri("microsoft")
+        iphoneUri = self.er.getConceptUri("iphone")
+        businessUri = self.er.getCategoryUri("business")
+        topic.addConcept(appleUri, 50, required = False)
+        topic.addConcept(msoftUri, 50, required = True)
+        topic.addConcept(iphoneUri, 50, excluded = True)
+        topic.addCategory(businessUri, 50, required=True)
+        for page in range(1, 10):
+            res = topic.getArticles(page = page, returnInfo = ReturnInfo(articleInfo=ArticleInfoFlags(concepts=True, categories=True, maxConceptsPerType=100)))
+            for art in res.get("articles").get("results"):
+                foundConcept = False
+                foundCategory = False
+                for conceptObj in art.get("concepts", []):
+                    assert iphoneUri != conceptObj["uri"], "Found iphone in the article"
+                    if msoftUri == conceptObj["uri"]:
+                        foundConcept = True
+                for categoryObj in art.get("categories", []):
+                    if categoryObj["uri"].startswith(businessUri):
+                        foundCategory = True
+                assert foundConcept, "Article did not have a required concept"
+                assert foundCategory, "Article did not have a required category"
+
 
 if __name__ == "__main__":
     suite = unittest.TestLoader().loadTestsFromTestCase(TestTopicPage)