Skip to content

Commit

Permalink
Merge pull request #13 from smkent/dev
Browse files Browse the repository at this point in the history
Add usage examples and development status information
  • Loading branch information
smkent authored Feb 26, 2022
2 parents dc4afe9 + 56bc661 commit 14c937d
Show file tree
Hide file tree
Showing 6 changed files with 166 additions and 8 deletions.
44 changes: 42 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
26 changes: 26 additions & 0 deletions examples/echo.py
Original file line number Diff line number Diff line change
@@ -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'})
32 changes: 32 additions & 0 deletions examples/identity_get.py
Original file line number Diff line number Diff line change
@@ -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
57 changes: 57 additions & 0 deletions examples/mailbox.py
Original file line number Diff line number Diff line change
@@ -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
4 changes: 2 additions & 2 deletions jmapc/methods/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 7 additions & 4 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@ classifiers = [
"Topic :: Office/Business :: Groupware",
"Topic :: Software Development :: Libraries :: Python Modules",
]
include = [
"examples",
]

[tool.poetry.dependencies]
python = "^3.8"
Expand Down Expand Up @@ -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" }
Expand Down

0 comments on commit 14c937d

Please sign in to comment.