Add Webarchive 4.2; add user tracking for webarchive

4 - Webarchive.ipynb

@@ -463,6 +463,30 @@
    "source": [
     "* Make Andreas happy :)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "slideshow": {
+     "slide_type": "slide"
+    }
+   },
+   "source": [
+    "## Tracking"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img src=\"https://purepng.com/public/uploads/large/purepng.com-cute-dog-whelpdogdoggycutehoundwhelpbrownbegging-451520332429trejj.png\" style=\"max-height:200px;\" />\n",
+    "\n",
+    "We'd love to properly count the unique visitors in the Webarchive backend, so we kindly ask you to **opt in to tracking by instantiating `webarchiv.WebarchivSession` with the parameter `allow_tracking=True`**.\n",
+    "\n",
+    "This sends your SHA256-hashed MAC address as a fingerprint to the server on authentication. It is only ever used to count unique users.\n",
+    "\n",
+    "If you leave `allow_tracking` at the default value `False`, an empty string is sent as fingerprint."
+   ]
   }
  ],
  "metadata": {

webarchiv.py

@@ -129,14 +129,13 @@ class WebarchivSession:
     def fulltext_search(self, query_string, from_=None, to_=None):
         """
         Start a fulltext search query in the Webarchive.
-        The current status of running queries can be read via status_open_queries().
 
         :param query_string: String to search for
         :param from_: Optional earliest date bound for the search
           in the format YYYYMM.
         :param to_: Optional latest date bound for the search
           in the format YYYYMM.
-        :return: None
+        :return: HTTP Response object
         """
         params = {'q': query_string}
         if from_:
@@ -152,17 +151,66 @@ class WebarchivSession:
             self._display_http_error(e)
             print('Query for "{}" not added'.format(query_string))
 
+    def fulltext_search_within_domain(self, query_string, domain, from_=None, to_=None):
+        """
+        Start a fulltext seed search query in the Webarchive.
+
+        :param query_string: String to search for
+        :param domain: Search only within this domain name
+        :param from_: Optional earliest date bound for the search
+          in the format YYYYMM.
+        :param to_: Optional latest date bound for the search
+          in the format YYYYMM.
+        :return: HTTP Response object
+        """
+        params = {'q': query_string, 'g': domain}
+        if from_:
+            params['from'] = from_
+        if to_:
+            params['to'] = to_
+
+        try:
+            response = self._get(op='/search/fulltext/seed', params=params)
+            return self.waitForResponse(response)
+
+        except HTTPError as e:
+            self._display_http_error(e)
+
+    def fulltext_search_within_url(self, query_string, url, pagesize=10, from_=None, to_=None):
+        """
+        Start a fulltext capture search query in the Webarchive.
+
+        :param query_string: String to search for
+        :param url: Search only captures starting at this exact web address
+        :param from_: Optional earliest date bound for the search
+          in the format YYYYMM.
+        :param to_: Optional latest date bound for the search
+          in the format YYYYMM.
+        :return: HTTP Response object
+        """
+        params = {'q': query_string, 'g': url, 'pagesize': pagesize}
+        if from_:
+            params['from'] = from_
+        if to_:
+            params['to'] = to_
+
+        try:
+            response = self._get(op='/search/fulltext/capture', params=params)
+            return self.waitForResponse(response)
+
+        except HTTPError as e:
+            self._display_http_error(e)
+
     def wayback_search(self, query_string, from_=None, to_=None):
         """
         Start a wayback search query in the Webarchive.
-        The current status of running queries can be read via status_open_queries().
 
         :param query_string: String to search for
         :param from_: Optional earliest date bound for the search
           in the format YYYYMM.
         :param to_: Optional latest date bound for the search
           in the format YYYYMM.
-        :return: None
+        :return: HTTP Response object
         """
         params = {'q': query_string}
         if from_:
@@ -213,7 +261,6 @@ class WebarchivSession:
     def domain_name_search(self, query_string, page_=1, pagesize_=100):
         """
         Start a domain name search in the Webarchive.
-        The current status of running queries can be read via status_open_queries().
 
         :param query_string: String to search for
         :param page_: The page number parameter works with the page size parameter to control the offset of the records returned in the results. Default value is 1
@@ -237,7 +284,6 @@ class WebarchivSession:
     def histogram_search(self, query_string, interval_=3, from_=None, to_=None):
         """
         Start a domain name search in the Webarchive.
-        The current status of running queries can be read via status_open_queries().
 
         :param query_string: String to search for
         :param page_: The page number parameter works with the page size parameter to control the offset of the records returned in the results. Default value is 1