Merge pull request #13 from smkent/dev

Add usage examples and development status information

README.md

@@ -1,6 +1,46 @@
-# jmapc
+# A [JMAP][jmapio] client library for Python
 
-A [JMAP][jmapio] client library for Python
+jmapc is in initial development.
+
+Currently implemented:
+
+* Basic models
+* Request methods:
+  * `Core/echo`
+  * `Email/get`
+  * `Email/query`
+  * `Identity/get`
+  * `Thread/get`
+  * `Mailbox/get`
+  * `Mailbox/query`
+* Combined requests with support for result references
+* Basic JMAP method response error handling
+* Unit tests for basic functionality and methods
+
+Todo list:
+
+* Implement `EmailSubmission` methods for sending email
+* Write documentation
+
+## Examples
+
+First, run `poetry install` to set up your local repository.
+
+[Any of the examples](/examples) can be invoked with `poetry run`:
+
+```sh
+JMAP_HOST=jmap.example.com \
+JMAP_USER=ness \
+JMAP_PASSWORD=pk_fire \
+poetry run examples/identity_get.py
+```
+
+If successful, `examples/identity_get.py` should output something like:
+
+```
+Identity 12345 is for Ness at ness@onett.example.com
+Identity 67890 is for Ness at ness-alternate@onett.example.com
+```
 
 ## Development
 

examples/echo.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+
+import os
+
+from jmapc import Client
+from jmapc.methods import CoreEcho
+
+# Create and configure client
+client = Client(
+    host=os.environ["JMAP_HOST"],
+    user=os.environ["JMAP_USER"],
+    password=os.environ["JMAP_PASSWORD"],
+)
+
+# Prepare a request for the JMAP Core/echo method with some sample data
+method = CoreEcho(data=dict(hello="world"))
+
+# Call JMAP API with the prepared request
+result = client.call_method(method)
+
+# Print result
+print(result)
+
+# Example output:
+#
+# CoreEchoResponse(data={'hello': 'world'})

examples/identity_get.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+
+import os
+
+from jmapc import Client
+from jmapc.methods import IdentityGet
+
+# Create and configure client
+client = Client(
+    host=os.environ["JMAP_HOST"],
+    user=os.environ["JMAP_USER"],
+    password=os.environ["JMAP_PASSWORD"],
+)
+
+# Prepare Identity/get request
+# To retrieve all of the user's identities, no arguments are required.
+method = IdentityGet()
+
+# Call JMAP API with the prepared request
+result = client.call_method(method)
+
+# Print some information about each retrieved identity
+for identity in result.data:
+    print(
+        f"Identity {identity.id} is for "
+        f"{identity.name} at {identity.email}"
+    )
+
+# Example output:
+#
+# Identity 12345 is for Ness at ness@onett.example.com
+# Identity 67890 is for Ness at ness-alternate@onett.example.com

examples/mailbox.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+
+import os
+
+from jmapc import Client, MailboxQueryFilterCondition, ResultReference
+from jmapc.methods import MailboxGet, MailboxQuery
+
+# Create and configure client
+client = Client(
+    host=os.environ["JMAP_HOST"],
+    user=os.environ["JMAP_USER"],
+    password=os.environ["JMAP_PASSWORD"],
+)
+
+# Prepare two methods to be submitted in one request
+# The first method, Mailbox/query, will locate the ID of the Inbox folder
+# The second method, Mailbox/get, uses a result reference to retrieve the Inbox
+# mailbox details
+methods = [
+    MailboxQuery(filter=MailboxQueryFilterCondition(name="Inbox")),
+    MailboxGet(
+        ids=ResultReference(
+            name=MailboxQuery.name(),
+            path="/ids",
+            result_of="0",
+        ),
+    ),
+]
+
+# Call JMAP API with the prepared request
+results = client.call_methods(methods)
+
+# Retrieve the result tuple for the second method. The result tuple contains
+# the client-provided method ID, and the result data model.
+method_2_result = results[1]
+
+# Retrieve the result data model from the result tuple
+method_2_result_data = method_2_result[1]
+
+# Retrieve the Mailbox data from the result data model
+mailboxes = method_2_result_data.data
+
+# Although multiple mailboxes may be present in the results, we only expect a
+# single match for our query. Retrieve the first Mailbox from the list.
+mailbox = mailboxes[0]
+
+# Print some information about the mailbox
+print(f"Found the mailbox named {mailbox.name} with ID {mailbox.id}")
+print(
+    f"This mailbox has {mailbox.total_emails} emails, "
+    f"{mailbox.unread_emails} of which are unread"
+)
+
+# Example output:
+#
+# Found the mailbox named Inbox with ID deadbeef-0000-0000-0000-000000000001
+# This mailbox has 42 emails, 4 of which are unread

jmapc/methods/base.py

@@ -45,8 +45,8 @@ class Get(MethodWithAccount):
 
 @dataclass
 class GetResponse(ResponseWithAccount):
-    state: str
-    not_found: List[str]
+    state: Optional[str]
+    not_found: Optional[List[str]]
 
 
 @dataclass

pyproject.toml

@@ -16,6 +16,9 @@ classifiers = [
     "Topic :: Office/Business :: Groupware",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
+include = [
+    "examples",
+]
 
 [tool.poetry.dependencies]
 python = "^3.8"
@@ -46,12 +49,12 @@ style = "semver"
 lt = ["lint", "test"]
 
 lint = ["isort_lint", "black_lint"]
-black_lint = { cmd = "black -l 79 -- tests/ jmapc/" }
-isort_lint = { cmd = "isort -- tests/ jmapc/" }
+black_lint = { cmd = "black -l 79 -- tests/ examples/ jmapc/" }
+isort_lint = { cmd = "isort -- tests/ examples/ jmapc/" }
 
 test = ["flake8", "isort", "black", "mypy", "pytest"]
-black = { cmd = "black -l 79 --check --diff --color -- tests/ jmapc/" }
-isort = { cmd = "isort --check-only -- tests/ jmapc/" }
+black = { cmd = "black -l 79 --check --diff --color -- tests/ examples/ jmapc/" }
+isort = { cmd = "isort --check-only -- tests/ examples/ jmapc/" }
 flake8 = { cmd = "flake8" }
 mypy = { cmd = "mypy" }
 pytest = { cmd = "pytest" }