Skip to content

Commit

Permalink
refactor!: Restructure package to accomodate both RPC and REST clients
Browse files Browse the repository at this point in the history
  • Loading branch information
edgarrmondragon committed Sep 20, 2023
1 parent 3323ab9 commit 5002f6d
Show file tree
Hide file tree
Showing 15 changed files with 2,145 additions and 2,006 deletions.
30 changes: 15 additions & 15 deletions docs/how-to.md
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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(
Expand All @@ -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"))
Expand Down Expand Up @@ -93,7 +93,7 @@ cached_session = requests_cache.CachedSession(
allowable_methods=["POST"],
)

client = Client(
client = RPC(
LS_URL,
"iamadmin",
"secret",
Expand All @@ -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",
Expand All @@ -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",
Expand All @@ -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")
```

Expand Down
2 changes: 1 addition & 1 deletion docs/notebooks/duckdb.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
4 changes: 2 additions & 2 deletions docs/notebooks/import_s3.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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)"
]
}
Expand Down
2 changes: 1 addition & 1 deletion docs/notebooks/pandas_sqlite.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -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)"
]
},
{
Expand Down
116 changes: 58 additions & 58 deletions docs/rpc_coverage.md

Large diffs are not rendered by default.

6 changes: 5 additions & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -245,7 +245,11 @@ convention = "google"
max-args = 10

[tool.pytest.ini_options]
addopts = ["-vvv", "-W error"]
addopts = ["-vvv"]
filterwarnings = [
"error",
"always::citric._compat.CitricDeprecationWarning",
]
markers = [
"integration_test: Integration and end-to-end tests",
"xfail_mysql: Mark a test as expected to fail on MySQL",
Expand Down
24 changes: 22 additions & 2 deletions src/citric/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,33 @@

from __future__ import annotations

import typing as t
import warnings
from importlib import metadata

from citric.client import Client
from citric._compat import CitricDeprecationWarning
from citric.rpc.client import RPC

if t.TYPE_CHECKING:
from citric.rpc.client import RPC as Client # noqa: N811, F401


__version__ = metadata.version(__package__)
"""Package version"""

del annotations, metadata

__all__ = ["Client"]
__all__ = ["RPC"]


def __getattr__(name: str) -> t.Any: # noqa: ANN401
if name == "Client":
warnings.warn(
"citric.Client is deprecated, use citric.RPC instead",
CitricDeprecationWarning,
stacklevel=2,
)
return RPC

message = f"module {__name__!r} has no attribute {name!r}"
raise AttributeError(message)
4 changes: 4 additions & 0 deletions src/citric/_compat.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,10 @@ def _warning_message(next_version: str) -> tuple[str, ...]:
)


class CitricDeprecationWarning(DeprecationWarning):
"""Warning for deprecated APIs in Citric."""


class FutureVersionWarning(UserWarning):
"""Warning for features only available in an unreleased version of LimeSurvey."""

Expand Down
Loading

0 comments on commit 5002f6d

Please sign in to comment.