update Client to v 1.2.1, add fetchAnnotations() function

Change-Id: I8576ccc4ac7ea361a26f09c87ecbd381cffd7e26

Author: feldmueller

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Version history
 
+## 1.2.1
+
+- Updates recommended RKorAPClient version to 1.2.1
+- fetchAnnotations() method added to KorAPQuery class, to fetch annotations for all collected matches
+
 ## 1.1.0
 
 - Updates recommended RKorAPClient version to 1.1.0

KorAPClient/__init__.py

@@ -16,7 +16,7 @@
 from packaging import version
 from rpy2.robjects.methods import RS4
 
-CURRENT_R_PACKAGE_VERSION = "1.1.0"
+CURRENT_R_PACKAGE_VERSION = "1.2.1"
 
 KorAPClient = packages.importr('RKorAPClient')
 if version.parse(KorAPClient.__version__) < version.parse(CURRENT_R_PACKAGE_VERSION):
@@ -395,3 +395,48 @@ def fetchAll(self, *args, **kwargs):
         super().__init__(res)
         return self
 
+    def fetchAnnotations(self, *args, **kwargs):
+            """Fetches and parses linguistic annotations for the collected matches.
+
+            This method enriches the `collectedMatches` DataFrame with additional columns
+            containing linguistic annotations like lemma, part-of-speech (POS), and
+            morphology for each token in the match and its context.
+
+            Args:
+                foundry (str, optional): The foundry (annotation layer) to fetch.
+                                        Defaults to "tt" (TreeTagger).
+                overwrite (bool, optional): If True, existing annotation columns will be
+                                            overwritten. Defaults to False.
+                verbose (bool, optional): If True, prints progress information. Defaults
+                                        to the verbosity setting of the
+                                        KorAPConnection object.
+                *args: Positional arguments passed to the underlying R function.
+                **kwargs: Keyword arguments passed to the underlying R function.
+
+            Returns:
+                KorAPQuery: A new KorAPQuery object with the `collectedMatches` DataFrame
+                            updated to include the fetched annotations.
+
+            Example:
+                ```
+                from KorAPClient import KorAPConnection
+
+                # Authentication might be required for snippets and annotations
+                kcon = KorAPConnection(verbose=True).auth()
+
+                # Perform a query and fetch all matches
+                q = kcon.corpusQuery("Ameisenplage", metadataOnly=False).fetchAll()
+
+                # Fetch annotations for the matches
+                q_annotated = q.fetchAnnotations()
+
+                # Display the collected matches with new annotation columns
+                print(q_annotated.slots['collectedMatches'][['snippet', 'lemma.left', 'lemma.match', 'lemma.right']].head())
+                ```
+            """
+            res = KorAPClient.fetchAnnotations(self, *args, **kwargs)
+            with localconverter(fix_lists_in_dataframes):
+                df = res.slots['collectedMatches']
+            res.slots['collectedMatches'] = df
+            super().__init__(res)
+            return self

Readme.md

@@ -157,6 +157,25 @@ example:
   python -m KorAPClient -v --query "Hello World" "Hallo Welt" --vc "pubDate in 2017" "pubDate in 2018" "pubDate in 2019"
 ```
 
+### Querying and fetching annotations
+To fetch the annotations for all matches in a KorAPQuery object, use the fetchAnnotations() method (defaults to "tt" (TreeTagger) as foundry):
+```python
+from KorAPClient import KorAPConnection
+
+# Authentication might be required for snippets and annotations
+kcon = KorAPConnection(verbose=True).auth()
+
+# Perform a query and fetch all matches
+q = kcon.corpusQuery("Ameisenplage", metadataOnly=False).fetchAll()
+
+# Fetch annotations for the matches
+q = q.fetchAnnotations()
+
+# Display the collected matches with new annotation columns
+q.slots['collectedMatches'][['snippet', 'lemma.left', 'lemma.match', 'lemma.right']].head()
+```
+The annotations (here: lemmas) are stored in `q.slots['collectedMatches'][['lemma.left', 'lemma.match', 'lemma.right']]`.
+
 ### Accessed API Services
 By using the KorAPClient you agree to the respective terms of use of the accessed KorAP API services which will be printed upon opening a connection.
 

pyproject.toml

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