add auth function and bump version to 1.0.0

Change-Id: Ib1f7fa0c5bb3c3aafdc2650ec7bc1bbf53b10e44

Author: feldmueller

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Version history
 
+## 1.0.0
+
+- Simplified authorization process for accessing restricted data via the new `auth()` function
+- Fixed issues with tokenized matches in `corpusQuery` results
+- Fixed smoothing constant in `mergeDuplicateCollocates` function
 - Fixed chainability of fetch methods in `corpusQuery`
 
 ## 0.9.0

KorAPClient/__init__.py

@@ -7,6 +7,7 @@
 from rpy2.rinterface_lib.sexp import StrSexpVector, NULLType
 from rpy2.robjects import numpy2ri
 from rpy2.robjects.conversion import localconverter, get_conversion
+from rpy2.rinterface import NULL
 
 import rpy2.robjects as robjects
 import rpy2.robjects.packages as packages
@@ -15,7 +16,7 @@
 from packaging import version
 from rpy2.robjects.methods import RS4
 
-CURRENT_R_PACKAGE_VERSION = "0.9.0"
+CURRENT_R_PACKAGE_VERSION = "1.0.0"
 
 KorAPClient = packages.importr('RKorAPClient')
 if version.parse(KorAPClient.__version__) < version.parse(CURRENT_R_PACKAGE_VERSION):
@@ -24,6 +25,8 @@
 
 korapclient_converter = robjects.conversion.Converter('base empty converter')
 
+# Export NULL
+NULL = NULL
 
 @korapclient_converter.py2rpy.register(list)
 def _rpy2py_robject(listObject):
@@ -116,6 +119,42 @@ def __init__(self, *args, **kwargs):
         kco = KorAPClient.KorAPConnection(*args, **kwargs)
         super().__init__(kco)
 
+    def auth(self, *args, **kwargs):
+        """ Authorize PythonKorAPClient to make KorAP queries and download results on behalf of the user.
+
+        - **kco** - `KorAPConnection` object
+        - **app_id** - OAuth2 application id. Defaults to the generic KorAP client application id.
+        - **app_secret** - OAuth2 application secret. Used with confidential client applications. Defaults to `NULL`.
+        - **scope** - OAuth2 scope. Defaults to "search match_info".
+
+        Returns:
+
+            Potentially authorized `KorAPConnection`|`RS4` with access token in `.slots['accessToken']`.
+
+        Example:
+
+            # Create a KorAPConnection object without an existing access token
+
+            kcon = KorAPConnection(accessToken=None, verbose=True).auth()
+
+            # Perform a query using the authenticated connection
+
+            q = kcon.corpusQuery("Ameisenplage", metadataOnly=False)
+
+            # Fetch all results
+
+            q = q.fetchAll()
+
+            # Access the collected matches
+
+            print(q.slots['collectedMatches'].snippet)
+
+        """
+
+        kco = KorAPClient.auth(self, *args, **kwargs)
+        super().__init__(kco)
+        return self
+
     def corpusStats(self, *args, **kwargs):
         """Query the size of the whole corpus or a virtual corpus specified by the vc argument.
 

Readme.md

@@ -75,6 +75,18 @@ KorAPConnection(verbose=True) \
 |  1 | "Wissenschaftler.*" |         942053 |      | https://korap.ids-mannheim.de/?q=%22Wissenschaftler.%2a%22&ql=poliqarp | 1080268 | 0.872055 |   0.871423 |    0.872684 |
 |  2 | "Wissenschafter.*"  |         138215 |      | https://korap.ids-mannheim.de/?q=%22Wissenschafter.%2a%22&ql=poliqarp  | 1080268 | 0.127945 |   0.127316 |    0.128577 |
 
+
+### Authorization
+
+In order to retrieve KWIC data from copyrighted texts, you need to authenticate yourself and authorize the client to act on behalf of you.
+There are different ways to do this (see [Authorization Section of RKorAPClient](https://github.com/KorAP/RKorAPClient#-authorizing-rkorapclient-applications-to-access-restricted-kwics-from-copyrighted-texts)).
+The easiest way is to use the `auth()` method of the `KorAPConnection` class. This will open a browser window and ask you to log in with your KorAP account.
+
+```python
+from KorAPClient import KorAPConnection
+kcon = KorAPConnection().auth()
+```
+
 ## Examples
 #### Frequencies of "Hello World" over years and countries
 ```python
@@ -99,7 +111,7 @@ alt.Chart(df).mark_line(point=True).encode(y="ipm", x="Year:T", color="Country",
 ```python
 from KorAPClient import KorAPConnection
 
-kcon = KorAPConnection(verbose=True)
+kcon = KorAPConnection(verbose=True).auth()
 results = kcon.collocationAnalysis("focus(in [tt/p=NN] {[tt/l=setzen]})",
                                    leftContextSize=1,
                                    rightContextSize=0,

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "KorAPClient"
-version = "0.9.0"
+version = "1.0.0"
 description = "Client package to access KorAP's web service API"
 authors = [
     {name = "Marc Kupietz",email = "[email protected]"},