Make PythonKorAPClient a pip-installable package
Change-Id: Icb626551d06fd87540c95d146cc673e6bc33ec8b
diff --git a/KorAPClient/__init__.py b/KorAPClient/__init__.py
new file mode 100644
index 0000000..b74adab
--- /dev/null
+++ b/KorAPClient/__init__.py
@@ -0,0 +1,4 @@
+import rpy2.robjects.pandas2ri as pandas2ri
+import rpy2.robjects.packages as packages
+KorAPClient = packages.importr('RKorAPClient')
+pandas2ri.activate()
diff --git a/KorAPClient/tests/__init__.py b/KorAPClient/tests/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/KorAPClient/tests/__init__.py
diff --git a/KorAPClient/tests/test_korapclient.py b/KorAPClient/tests/test_korapclient.py
new file mode 100644
index 0000000..2b0b7d6
--- /dev/null
+++ b/KorAPClient/tests/test_korapclient.py
@@ -0,0 +1,17 @@
+import unittest
+from KorAPClient import KorAPClient
+
+class TestKorAPClient(unittest.TestCase):
+ def test_query(self):
+ kcon = KorAPClient.KorAPConnection()
+ q = KorAPClient.KorAPQuery(kcon, "Test")
+ self.assertEqual(q.slots['class'], 'KorAPQuery')
+
+ def test_frequency_query(self):
+ kcon = KorAPClient.KorAPConnection()
+ df = KorAPClient.frequencyQuery(kcon, "Ameisenplage")
+ self.assertGreater(df['totalResults'][0], 10)
+ self.assertGreater(10000, df['totalResults'][0])
+
+if __name__ == '__main__':
+ unittest.main()
diff --git a/Readme.md b/Readme.md
index 7676228..2ad71ac 100644
--- a/Readme.md
+++ b/Readme.md
@@ -1,49 +1,55 @@
-# Python Client Support
-Currently, there is no native KorAP client library for Python, yet.
-With [rpy2](https://rpy2.github.io/), however, you can already use the [KorAP client library for R](https://github.com/KorAP/RKorAPClient) from within Python.
+# KorAP web service client package for Python
-## Using the RKorAPClient from within Python
-### Installing Dependencies
+[](https://www.repostatus.org/#wip)
+
+[](https://github.com/KorAP/PythonKorAPClient/issues)
+[](https://github.com/KorAP/PythonKorAPClient/issues)
+[](https://github.com/KorAP/PythonKorAPClient/issues)
+
+
+## Description
+Python client package to access the [web service API](https://github.com/KorAP/Kustvakt/wiki) of the [KorAP Corpus Analysis Platform](https://korap.ids-mannheim.de/) developed at [IDS Mannheim](http://www.ids-mannheim.de/).
+Currently, this is no native Python package. Internally, it uses [KorAP's client package for R](http://github.com/KorAP/RKorAPClient)
+via [rpy2](https://rpy2.github.io/). **Please note that with a native implementation the API might change.**
+
+## Installing Dependencies
#### Linux
```shell script
#### Debian / Ubuntu
sudo apt install r-base r-base-dev libcurl4-gnutls-dev libssl-dev libxml2-dev libsodium-dev python3-pip python3-rpy2 python3-pandas
-echo 'install.packages("RKorAPClient", repos="http://cran.rstudio.com/")' | R --vanilla
-pip3 install plotly-express
+Rscript -e "install.packages('RKorAPClient')"
#### Fedora / CentOS / RHEL
sudo yum install r-base R-devel libcurl-devel openssl-devel libxml2-devel libsodium-devel python3-pandas
-echo 'install.packages("RKorAPClient", repos="http://cran.rstudio.com/")' | R --vanilla
-pip3 install rpy2 plotly-express
+Rscript -e "install.packages('RKorAPClient')"
```
-
-#### Other Operating Systems (currently untested)
+#### Windows, MacOS and other Unix variants
+- install [R](https://cran.r-project.org/bin/)
- install the RKorAP client as described in it's [installation section](https://github.com/KorAP/RKorAPClient#installation)
-- install [rpy2](https://rpy2.github.io/)
- ```shell script
- pip install rpy2
- ```
-- install [Plotly Express](https://plotly.com/python/plotly-express/) to run the [examples](examples) with visualizations:
- ```shell script
- pip install plotly.express
- ```
-#### Examples
+
+## Installing the Package
+```
+python3 -m pip install git+https://github.com/KorAP/PythonKorAPClient
+```
+## Documentation
+Currently, there is no dedicated documentation for the Python variant of the library. Please refer to the [Refernce Manual of RKorAPClient](https://cran.r-project.org/web/packages/RKorAPClient/RKorAPClient.pdf) for now.
+For translating the R syntax to Python and vice versa, pleas refer to the [rpy2 Documentation](https://rpy2.github.io/doc/latest/html/index.html).
+
+
+## Examples
#### Frequencies over years and countries
```python
-import rpy2.robjects.packages as packages
-import rpy2.robjects.pandas2ri as pandas2ri
+from KorAPClient import KorAPClient
import plotly.express as px
-pandas2ri.activate()
QUERY = "Hello World"
YEARS = range(2010, 2019)
COUNTRIES = ["DE", "CH"]
-RKorAPClient = packages.importr('RKorAPClient')
-kcon = RKorAPClient.KorAPConnection(verbose=True)
+kcon = KorAPClient.KorAPConnection(verbose=True)
vcs = ["textType=/Zeit.*/ & pubPlaceKey=" + c + " & pubDate in " + str(y) for c in COUNTRIES for y in YEARS]
-df = RKorAPClient.ipm(RKorAPClient.frequencyQuery(kcon, QUERY, vcs))
+df = KorAPClient.ipm(KorAPClient.frequencyQuery(kcon, QUERY, vcs))
df['Year'] = [y for c in COUNTRIES for y in YEARS]
df['Country'] = [c for c in COUNTRIES for y in YEARS]
@@ -51,7 +57,7 @@
error_y="conf.high", error_y_minus="conf.low")
fig.show()
```
-[Frequency per million words of “Hello World“ in DE vs. AT from 2010 to 2018 in newspapers and magazines](figures/hello-world.png)
+
### 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.
@@ -86,4 +92,3 @@
- Kupietz, Marc / Margaretha, Eliza / Diewald, Nils / Lüngen, Harald / Fankhauser, Peter (2019): [What’s New in EuReCo? Interoperability, Comparable Corpora, Licensing](https://nbn-resolving.org/urn:nbn:de:bsz:mh39-90261). In: Bański, Piotr/Barbaresi, Adrien/Biber, Hanno/Breiteneder, Evelyn/Clematide, Simon/Kupietz, Marc/Lüngen, Harald/Iliadi, Caroline (eds.): [*Proceedings of the International Corpus Linguistics Conference 2019 Workshop "Challenges in the Management of Large Corpora (CMLC-7)"*](https://ids-pub.bsz-bw.de/solrsearch/index/search/searchtype/collection/id/21038), 22nd of July Mannheim: Leibniz-Institut für Deutsche Sprache, 33-39.
- Kupietz, Marc / Diewald, Nils / Margaretha, Eliza (forthcoming): RKorAPClient: An R package for accessing the German Reference Corpus DeReKo via KorAP. In: Proceedings of the Twelfth International Conference on Language Resources and Evaluation (LREC 2020). Marseille/Paris: European Language Resources Association (ELRA).
-
diff --git a/examples/hello_world.py b/examples/hello_world.py
index 1309f3b..126b3bf 100755
--- a/examples/hello_world.py
+++ b/examples/hello_world.py
@@ -1,18 +1,15 @@
#!/usr/bin/env python3
-import rpy2.robjects.packages as packages
-import rpy2.robjects.pandas2ri as pandas2ri
+from KorAPClient import KorAPClient
import plotly.express as px
-pandas2ri.activate()
QUERY = "Hello World"
YEARS = range(2010, 2019)
COUNTRIES = ["DE", "CH"]
-RKorAPClient = packages.importr('RKorAPClient')
-kcon = RKorAPClient.KorAPConnection(verbose=True)
+kcon = KorAPClient.KorAPConnection(verbose=True)
vcs = ["textType=/Zeit.*/ & pubPlaceKey=" + c + " & pubDate in " + str(y) for c in COUNTRIES for y in YEARS]
-df = RKorAPClient.ipm(RKorAPClient.frequencyQuery(kcon, QUERY, vcs))
+df = KorAPClient.ipm(KorAPClient.frequencyQuery(kcon, QUERY, vcs))
df['Year'] = [y for c in COUNTRIES for y in YEARS]
df['Country'] = [c for c in COUNTRIES for y in YEARS]
diff --git a/setup.py b/setup.py
new file mode 100644
index 0000000..72f7166
--- /dev/null
+++ b/setup.py
@@ -0,0 +1,31 @@
+from setuptools import setup, find_packages
+
+with open("Readme.md", "r") as fh:
+ long_description = fh.read()
+
+setup(
+ name="KorAPClient",
+ version="0.0.1",
+ author="Marc Kupietz",
+ author_email="kupietz@ids-mannheim.de",
+ description="Client package to access KorAP's web service API",
+ long_description=long_description,
+ long_description_content_type="text/markdown",
+ url="https://korap.ids-mannheim.de",
+ license="BSD",
+ packages=find_packages(),
+ classifiers=[
+ "Programming Language :: Python :: 3",
+ "License :: OSI Approved :: BSD License",
+ "Operating System :: OS Independent",
+ ],
+ test_suite='nose.collector',
+ tests_require=['nose'],
+ python_requires='>=3.6',
+ install_requires=[
+ 'rpy2',
+ 'plotly-express',
+ 'pandas',
+ 'markdown'
+ ]
+)