Initial commit from jsonrpcclient repo

Author: bcb

.github/workflows/deploy-docs.yml

@@ -0,0 +1,48 @@
+# ⚠️ This workflow deploys docs to explodinglabs.com
+# It is active only in the official repo. Forks won't trigger deployment.
+name: Build and Deploy MkDocs
+
+on:
+  push:
+    branches:
+      - main # or your main development branch
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout source repo
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: pip install mkdocs mkdocs-material
+
+      - name: Build MkDocs site
+        run: mkdocs build
+
+      - name: Clone target repo
+        run: |
+          git clone https://x-access-token:${{ secrets.TARGET_REPO_PAT }}@github.com/explodinglabs/explodinglabs.com.git target-repo
+          rm -rf target-repo/$(basename "$GITHUB_REPOSITORY")
+          mkdir -p target-repo/$(basename "$GITHUB_REPOSITORY")
+          cp -a site/. target-repo/$(basename "$GITHUB_REPOSITORY")/
+        env:
+          GIT_AUTHOR_NAME: GitHub Actions
+          GIT_COMMITTER_NAME: GitHub Actions
+          GIT_AUTHOR_EMAIL: [email protected]
+          GIT_COMMITTER_EMAIL: [email protected]
+
+      - name: Commit and push
+        run: |
+          cd target-repo
+          git config user.name "Exploding Labs Bot"
+          git config user.email "[email protected]"
+          git add .
+          git commit -m "Update site from docs source repo" || echo "No changes to commit"
+          git push

docs/examples.md

@@ -0,0 +1,3 @@
+# Examples
+
+Examples have moved to the [Community Wiki](https://github.com/explodinglabs/jsonrpcclient/wiki).

docs/faq.md

@@ -0,0 +1,18 @@
+# FAQ
+
+## How to use a different json library?
+
+The `request_json` function is simply `json.dumps` after `request`, and the
+`parse_json` function is simply `parse` after `json.loads`.
+
+So here's how one could write their own, using a different json library (ujson
+here):
+
+```python
+from jsonrpcclient import request, parse
+from jsonrpcclient.utils import compose
+import ujson
+
+parse_json = compose(parse, ujson.loads)
+request_json = compose(ujson.dumps, request)
+```

docs/images/logo.png

@@ -0,0 +1,24 @@
+<style>
+.md-content__inner h1:first-of-type {
+  display: none;
+}
+</style>
+
+![jsonrpcclient](images/logo.png)
+
+_Generate JSON-RPC requests and parse responses in Python._
+
+Jump to:
+[GitHub](https://github.com/explodinglabs/jsonrpcclient) |
+[Community Wiki](https://github.com/explodinglabs/jsonrpcclient/wiki)
+
+```sh
+pip install jsonrpcclient
+```
+
+## Documentation
+
+- [Requests](requests.md)
+- [Responses](responses.md)
+- [Faq](faq.md)
+- [Examples](examples.md)

docs/index.md

@@ -0,0 +1,105 @@
+# Generating requests
+
+## The request function
+
+Generate a request with the `request` function:
+
+```python
+>>> from jsonrpcclient import request, request_json
+>>> request("ping")
+{'jsonrpc': '2.0', 'method': 'ping', 'id': 1}
+```
+
+`request_json` gives a string:
+
+```py
+>>> request_json("ping")
+'{"jsonrpc": "2.0", "method": "ping", "id": 2}'
+```
+
+It simply applies `str` after `request`.
+
+## Ids
+
+Subsequent calls increment the `id`:
+
+```
+
+> > > request("ping")
+> > > {"jsonrpc": "2.0", "method": "ping", "2.0", "id": 3}
+> > > request("ping")
+> > > {"jsonrpc": "2.0", "method": "ping", "2.0", "id": 4}
+
+```
+
+Use an explicit `id`:
+
+```
+
+> > > request("ping", id="foo")
+> > > {"jsonrpc": "2.0", "method": "ping", "2.0", "id": "foo"}
+
+```
+
+Or generate a different type of `id`:
+
+```python
+>>> from jsonrpcclient import request_hex, request_random, request_uuid
+>>> request_hex("foo")
+{"jsonrpc": "2.0", "method": "foo", "id": "1"}
+>>> request_random("foo")
+{"jsonrpc": "2.0", "method": "foo", "id": "qzsib147"}
+>>> request_uuid("foo")
+{"jsonrpc": "2.0", "method": "foo", "id": "45480a2f-069c-42aa-a67f-f6fdd83d6026"}
+```
+
+## Parameters
+
+Pass `params` to include parameters in the payload. This should be either a
+tuple for positional arguments, or dict for keyword arguments.
+
+```python
+>>> request("ping", params=(1,))
+{"jsonrpc": "2.0", "method": "ping", "2.0", "params": [1], "id": 5}
+>>> request("ping", params={"key": "val"})
+{"jsonrpc": "2.0", "method": "ping", "2.0", "params": {"key": "val"}, "id": 6}
+```
+
+## JSON requests
+
+If you need the request serialized to a string, use `request_json`:
+
+```python
+>>> from jsonrpcclient import request_json
+>>> request_json("foo")
+'{"jsonrpc": "2.0", "method": "foo", "id": 6}'
+```
+
+You can also use request_json_hex etc., for the other id types.
+
+## Batch requests
+
+```python
+>>> import json
+>>> json.dumps([request("foo") for _ in range(3)])
+'[{"jsonrpc": "2.0", "method": "foo", "id": 7}, {"jsonrpc": "2.0", "method": "foo", "id": 8}, {"jsonrpc": "2.0", "method": "foo", "id": 9}]'
+```
+
+## Notifications
+
+Use the `notification` function instead of `request`:
+
+```python
+>>> from jsonrpcclient import notification
+>>> notification("ping")
+{"jsonrpc": "2.0", "method": "ping"}
+```
+
+As with `request_json`, `notification_json` will give you the notification as a
+JSON string.
+
+```python
+>>> from jsonrpcclient import notification_json
+>>> notification_json("ping")
+'{"jsonrpc": "2.0", "method": "ping"}'
+```

docs/requests.md

@@ -0,0 +1,39 @@
+# Parsing responses
+
+The library includes a `parse` function which turns a deserialized response
+into a nice namedtuple.
+
+```python
+>>> parse({"jsonrpc": "2.0", "result": "pong", "id": 1})
+Ok(result='pong', id=1)
+>>> parse({"jsonrpc": "2.0", "error": {"code": 1, "message": "There was an error", "data": None}, "id": 1})
+Error(code=1, message='There was an error', data=None, id=1)
+```
+
+If you have a string, use `parse_json`.
+
+```python
+>>> parse_json('{"jsonrpc": "2.0", "result": "pong", "id": 1}')
+Ok(result='pong', id=1)
+```
+
+To use the result, in Python versions prior to 3.10:
+
+```python
+from jsonrpcclient import Error, Ok
+parsed = parse(response)
+if isinstance(parsed, Ok):
+    print(parsed.result)
+elif isinstance(parse, Error):
+    logging.error(parsed.message)
+```
+
+In Python 3.10+, use pattern matching:
+
+```python
+match parse(response):
+    case Ok(result, id):
+        print(result)
+    case Error(code, message, data, id):
+        logging.error(message)
+```

docs/responses.md

@@ -0,0 +1,38 @@
+site_name: jsonrpcclient
+site_url: https://explodinglabs.com/jsonrpcclient/
+repo_url: https://github.com/explodinglabs/jsonrpcclient
+theme:
+  name: material
+  features:
+    - navigation.footer
+    - palette.toggle
+    - content.code.copy
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.superfences
+nav:
+  - Home: index.md
+  - Requests: requests.md
+  - Responses: responses.md
+  - FAQ: faq.md
+  - Examples: examples.md