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

code_samples/auth_plugin.py

@@ -3,9 +3,9 @@
 from __future__ import annotations
 
 # start example
-from citric import Client
+from citric import RPC
 
-client = Client(
+client = RPC(
     "https://example.com/index.php/admin/remotecontrol",
     "iamadmin",
     "secret",

code_samples/context_manager.py

@@ -3,11 +3,11 @@
 from __future__ import annotations
 
 # start example
-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
     ...
 # end example

code_samples/custom_requests_session.py

@@ -4,14 +4,14 @@
 
 # start example
 import requests_cache
-from citric import Client
+from citric import RPC
 
 cached_session = requests_cache.CachedSession(
     expire_after=60,
     allowable_methods=["POST"],
 )
 
-client = Client(
+client = RPC(
     "https://example.com/index.php/admin/remotecontrol",
     "iamadmin",
     "secret",

code_samples/duckdb_sql.py

@@ -10,7 +10,7 @@
 import citric
 import duckdb
 
-client = citric.Client(
+client = citric.RPC(
     "https://mylimeserver.com/index.php/admin/remotecontrol",
     "iamadmin",
     "secret",

code_samples/get_surveys.py

@@ -5,11 +5,11 @@
 from __future__ import annotations
 
 # start example
-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")

code_samples/pandas_df.py

@@ -6,12 +6,12 @@
 # start example
 import io
 
+import citric
 import pandas as pd
-from citric import Client
 
 survey_id = 123456
 
-client = Client(
+client = citric.RPC(
     "https://mylimeserver.com/index.php/admin/remotecontrol",
     "iamadmin",
     "secret",

code_samples/requests_session_attributes.py

@@ -4,15 +4,15 @@
 
 # start example
 import requests
-from citric import Client
+from citric import RPC
 
 session = requests.Session()
 
 # Set to False to accept any TLS certificate presented by the server
 # https://requests.readthedocs.io/en/latest/api/#requests.Session.verify
 session.verify = False
 
-client = Client(
+client = RPC(
     "https://mylimeserver.com/index.php/admin/remotecontrol",
     "iamadmin",
     "secret",

code_samples/session_attr.py

@@ -1,11 +1,11 @@
-"""Example of using the Client.session attribute to call RPC methods directly."""
+"""Example of using the RPC.session attribute to call RPC methods directly."""
 
 from __future__ import annotations
 
-from citric import Client
+from citric import RPC
 
 # start example
-client = Client(
+client = RPC(
     "https://mylimeserver.com/index.php/admin/remotecontrol",
     "iamadmin",
     "secret",

code_samples/upload_s3.py

@@ -4,11 +4,11 @@
 
 # start example
 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",

docs/conf.py

@@ -196,7 +196,12 @@ def skip_member_filter(
     Returns:
         Whether to skip the member.
     """
-    if name == "citric.rest.client":
+    parts = name.split(".")
+    if (
+        any(part.startswith("_") and part != "_compat" for part in parts)
+        or name == "citric.rest.client"
+        or name.startswith(("citric.client", "citric.session", "citric.method"))
+    ):
         skip = True
     return skip
 

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`.

docs/how-to.md

@@ -9,7 +9,7 @@ For the full JSON-RPC reference, see the [RemoteControl 2 API docs][rc2api].
 :end-before: end example
 ```
 
-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.rpc.client.RPC.close>`.
 
 ## Get surveys and questions
 

docs/index.md

@@ -41,7 +41,7 @@ But also, the latest 5.x and 6.x are tested continuously and are expected to wor
 - [Use a custom `requests` session](how-to.md#use-a-custom-requests-session)
 - [Use a different authentication plugin](how-to.md#use-a-different-authentication-plugin)
 - [Get files uploaded to a survey and move them to S3](how-to.md#get-files-uploaded-to-a-survey-and-move-them-to-s3)
-- [Use the raw `Client.session` for low-level interaction](how-to.md#use-the-session-attribute-for-low-level-interaction)
+- [Use the raw `RPC.session` for low-level interaction](how-to.md#use-the-session-attribute-for-low-level-interaction)
 - [Notebook samples](how-to.md#notebook-samples)
 
 ```{toctree}
@@ -72,6 +72,13 @@ REST endpoints coverage <rest_coverage>
 Python API reference <_api/index>
 ```
 
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+Deprecations <deprecations>
+```
+
 ```{toctree}
 :maxdepth: 1
 :hidden:

docs/notebooks/duckdb.ipynb

@@ -43,7 +43,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",

docs/notebooks/import_s3.ipynb

@@ -182,7 +182,7 @@
    ],
    "source": [
     "# Use your own server's parameters here\n",
-    "with citric.Client(\n",
+    "with citric.RPC(\n",
     "    \"http://localhost:8001/index.php/admin/remotecontrol\",\n",
     "    \"iamadmin\",\n",
     "    \"secret\",\n",
@@ -229,7 +229,7 @@
     "s3.delete_object(Bucket=\"testing\", Key=\"survey.lss\")\n",
     "s3.delete_bucket(Bucket=\"testing\")\n",
     "\n",
-    "with citric.Client(\n",
+    "with citric.RPC(\n",
     "    \"http://localhost:8001/index.php/admin/remotecontrol\",\n",
     "    \"iamadmin\",\n",
     "    \"secret\",\n",

docs/notebooks/pandas_sqlite.ipynb

@@ -58,7 +58,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",

docs/rest_coverage.md

@@ -3,8 +3,8 @@
 
 | Name                                       | Implemented                                         |
 | :----------------------------------------- | :-------------------------------------------------- |
-| `POST /rest/v1/session`                    | [Yes](citric._rest.RESTClient.authenticate)          |
-| `DELETE /rest/v1/session`                  | [Yes](citric._rest.RESTClient.close)                 |
-| `GET /rest/v1/survey`                      | [Yes](citric._rest.RESTClient.get_surveys)           |
-| `GET /rest/v1/survey-detail/{survey_id}`   | [Yes](citric._rest.RESTClient.get_survey_details)    |
-| `PATCH /rest/v1/survey-detail/{survey_id}` | [Yes](citric._rest.RESTClient.update_survey_details) |
+| `POST /rest/v1/session`                    | [Yes](citric.rest.RESTClient.authenticate)          |
+| `DELETE /rest/v1/session`                  | [Yes](citric.rest.RESTClient.close)                 |
+| `GET /rest/v1/survey`                      | [Yes](citric.rest.RESTClient.get_surveys)           |
+| `GET /rest/v1/survey-detail/{survey_id}`   | [Yes](citric.rest.RESTClient.get_survey_details)    |
+| `PATCH /rest/v1/survey-detail/{survey_id}` | [Yes](citric.rest.RESTClient.update_survey_details) |