add auth function and bump version to 1.0.0
Change-Id: Ib1f7fa0c5bb3c3aafdc2650ec7bc1bbf53b10e44
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c09271e..1e87038 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/KorAPClient/__init__.py b/KorAPClient/__init__.py
index 82f0501..07ecb2a 100644
--- a/KorAPClient/__init__.py
+++ b/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 @@
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.
diff --git a/Readme.md b/Readme.md
index d5b7f1c..dc9f01a 100644
--- a/Readme.md
+++ b/Readme.md
@@ -75,6 +75,18 @@
| 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 @@
```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,
diff --git a/pyproject.toml b/pyproject.toml
index c32b40c..eff2365 100644
--- a/pyproject.toml
+++ b/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 = "kupietz@ids-mannheim.de"},