refactor!: Restructure package to accomodate both RPC and REST clients

edgarrmondragon · Sep 20, 2023 · d90a191 · d90a191
1 parent 3323ab9
commit d90a191
Show file tree

Hide file tree

Showing 17 changed files with 2,160 additions and 2,006 deletions.
diff --git a/docs/deprecations.md b/docs/deprecations.md
@@ -0,0 +1,8 @@
+# Deprecation timeline
+
+## v1.0.0
+
+* `citric.Client` will be renamed to `citric.RPC`.
+* `citric.client` will be moved to `citric.rpc.client`.
+* `citric.session` will be moved to `citric.rpc.session`.
+* `citric.method` will be moved to `citric.rpc.method`.
diff --git a/docs/how-to.md b/docs/how-to.md
@@ -5,25 +5,25 @@ For the full JSON-RPC reference, see the [RemoteControl 2 API docs][rc2api].
 ## Automatically close the session with a context manager
 
 ```python
-from citric import Client
+from citric import RPC
 
 LS_URL = "http://localhost:8001/index.php/admin/remotecontrol"
 
-with Client(LS_URL, "iamadmin", "secret") as client:
+with RPC(LS_URL, "iamadmin", "secret") as client:
     # Do stuff with the client
     ...
 ```
 
-Otherwise, you can manually close the session with {meth}`client.close() <citric.client.Client.close>`.
+Otherwise, you can manually close the session with {meth}`client.close() <citric.client.RPC.close>`.
 
 ## Get surveys and questions
 
 ```python
-from citric import Client
+from citric import RPC
 
 LS_URL = "http://localhost:8001/index.php/admin/remotecontrol"
 
-client = Client(LS_URL, "iamadmin", "secret")
+client = RPC(LS_URL, "iamadmin", "secret")
 
 # Get all surveys from user "iamadmin"
 surveys = client.list_surveys("iamadmin")
@@ -40,13 +40,13 @@ for s in surveys:
 ## Export responses to a `pandas` dataframe
 
 ```python
+import citric
 import io
 import pandas as pd
-from citric import Client
 
 survey_id = 123456
 
-client = citric.Client(...)
+client = citric.RPC(...)
 
 # Export responses to CSV and read into a Pandas DataFrame
 df = pd.read_csv(
@@ -63,7 +63,7 @@ df = pd.read_csv(
 import citric
 import duckdb
 
-client = citric.Client(...)
+client = citric.RPC(...)
 
 with open("responses.csv", "wb") as file:
     file.write(client.export_responses(<your survey ID>, file_format="csv"))
@@ -93,7 +93,7 @@ cached_session = requests_cache.CachedSession(
     allowable_methods=["POST"],
 )
 
-client = Client(
+client = RPC(
     LS_URL,
     "iamadmin",
     "secret",
@@ -112,7 +112,7 @@ By default, this client uses the internal database for authentication but
 `auth_plugin` argument.
 
 ```python
-client = Client(
+client = RPC(
     LS_URL,
     "iamadmin",
     "secret",
@@ -126,11 +126,11 @@ Common plugins are `Authdb` (default), `AuthLDAP` and `Authwebserver`.
 
 ```python
 import boto3
-from citric import Client
+from citric import RPC
 
 s3 = boto3.client("s3")
 
-client = Client(
+client = RPC(
     "https://mylimeserver.com/index.php/admin/remotecontrol",
     "iamadmin",
     "secret",
@@ -147,14 +147,14 @@ for file in client.get_uploaded_file_objects(survey_id):
     )
 ```
 
-## Use the raw `Client.session` for low-level interaction
+## Use the raw `RPC.session` for low-level interaction
 
 This library doesn't (yet) implement all RPC methods, so if you're in dire need of using a method not currently supported, you can use the `session` attribute to invoke the underlying RPC interface without having to pass a session key explicitly:
 
 ```python
-client = Client(LS_URL, "iamadmin", "secret")
+client = RPC(LS_URL, "iamadmin", "secret")
 
-# Call the copy_survey method, not available in Client
+# Call the copy_survey method, not available in RPC
 new_survey_id = client.session.copy_survey(35239, "copied_survey")
 ```
 

diff --git a/docs/index.md b/docs/index.md
@@ -46,6 +46,13 @@ RPC method coverage <rpc_coverage>
 Python API reference <_api/index>
 ```
 
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+Deprecations <deprecations>
+```
+
 ```{toctree}
 :caption: Contributing
 :hidden:

diff --git a/docs/notebooks/duckdb.ipynb b/docs/notebooks/duckdb.ipynb
@@ -53,7 +53,7 @@
    "outputs": [],
    "source": [
     "# Use your own server's parameters here\n",
-    "client = citric.Client(\n",
+    "client = citric.RPC(\n",
     "    \"http://localhost:8001/index.php/admin/remotecontrol\",\n",
     "    \"iamadmin\",\n",
     "    \"secret\",\n",

diff --git a/docs/notebooks/import_s3.ipynb b/docs/notebooks/import_s3.ipynb
@@ -228,7 +228,7 @@
     }
    ],
    "source": [
-    "with citric.Client(LS_URL, LS_USERNAME, LS_PASSWORD) as client:\n",
+    "with citric.RPC(LS_URL, LS_USERNAME, LS_PASSWORD) as client:\n",
     "    file_object = io.BytesIO()\n",
     "    s3.download_fileobj(\"testing\", \"survey.lss\", file_object)\n",
     "\n",
@@ -271,7 +271,7 @@
     "s3.delete_object(Bucket=\"testing\", Key=\"survey.lss\")\n",
     "s3.delete_bucket(Bucket=\"testing\")\n",
     "\n",
-    "with citric.Client(LS_URL, LS_USERNAME, LS_PASSWORD) as client:\n",
+    "with citric.RPC(LS_URL, LS_USERNAME, LS_PASSWORD) as client:\n",
     "    client.delete_survey(survey_id)"
    ]
   }

diff --git a/docs/notebooks/pandas_sqlite.ipynb b/docs/notebooks/pandas_sqlite.ipynb
@@ -73,7 +73,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "client = citric.Client(LS_URL, LS_USERNAME, LS_PASSWORD)"
+    "client = citric.RPC(LS_URL, LS_USERNAME, LS_PASSWORD)"
    ]
   },
   {