kuvert 1.0.0__tar.gz

kuvert-1.0.0/.gitignore

@@ -0,0 +1,153 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+**/__pycache__
+*.py[cod]
+*$py.class
+*.pyc
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# static files generated from Django application using `collectstatic`
+media
+export
+static_collected
+data
+
+*.token.temp
+*.fakts.yaml
+fakts.yaml
+# Local-source override for the integration stack (see tests/conftest.py)
+tests/integration/docker-compose.local.yml

kuvert-1.0.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: kuvert
+Version: 1.0.0
+Summary: The python client for kuvert, the arkitekt mail service
+Author-email: jhnnsrs <jhnnsrs@gmail.com>
+Requires-Python: >=3.11
+Requires-Dist: aiohttp<4,>=3.9.5
+Requires-Dist: koil>=1.0.0
+Requires-Dist: rath>=4.1.1
+Requires-Dist: websockets>=15.0.1
+Description-Content-Type: text/markdown
+
+# kuvert
+
+The python client for [kuvert](https://github.com/arkitektio/kuvert-server), the
+[Arkitekt](https://arkitekt.live) mail service: the mailboxes you linked, their
+folders and conversations, tasks over those conversations, and sending mail.
+
+## Installation
+
+```sh
+pip install kuvert
+```
+
+## Usage
+
+Every kuvert operation is a method of the `Kuvert` client, in a blocking and an
+`a`-prefixed async flavour.
+
+### In an arkitekt app
+
+The client is injected by annotation. Add the service to your app and ask for
+`kuvert: Kuvert`:
+
+```python
+from arkitekt import App, run
+from kuvert import Kuvert, kuvert_service
+
+app = App("mail-digest", "0.1.0", services=[kuvert_service])
+
+
+@app.action
+async def unread_subjects(kuvert: Kuvert) -> list[str]:
+    """The subjects of the unread conversations in my inboxes."""
+    threads = await kuvert.alist_threads(filter={"unread": True, "folderRole": "INBOX"})
+    return [thread.subject for thread in threads]
+
+
+if __name__ == "__main__":
+    run(app)
+```
+
+Messages, threads, outgoing mail, mailboxes, tasks and task lists travel between
+actions by id (`@kuvert/message`, `@kuvert/thread`, `@kuvert/outgoingmessage`,
+`@kuvert/mailaccount`, `@kuvert/task`, `@kuvert/tasklist`), so an action can take
+and return them directly, and a trigger on a kuvert signal hands them over.
+
+### From a script
+
+```python
+from arkitekt import easy
+from kuvert import kuvert_service
+
+with easy("my-script", kuvert_service) as kuvert:
+    for account in kuvert.list_mail_accounts():
+        print(account.email_address, account.unread_count)
+```
+
+### Standalone
+
+Without arkitekt, build the client over a rath link of your own:
+
+```python
+from kuvert import Kuvert
+from kuvert.rath import KuvertRath
+
+kuvert = Kuvert(rath=KuvertRath(link=...))
+
+with kuvert:
+    for account in kuvert.list_mail_accounts():
+        print(account.email_address, account.unread_count)
+
+    kuvert.send_message(
+        account=account.id,
+        to=[{"address": "someone@example.org"}],
+        subject="Hello",
+        text="From kuvert.",
+    )
+```
+
+Arguments the server defaults (`cc`, `bcc`, `attachments` of `send_message`,
+`notes`/`pinned` of `create_task`, …) are optional: **leave them out** rather
+than passing `None`. An explicit `None` is sent as `null`, which the server
+rejects for those fields.
+
+Changes to mail (flags, moves, deletes, categories) are local-first: they apply
+at once and reach the mail server when the mailbox next pushes.
+`list_mail_changes` shows what is still pending and `undo_mail_changes` takes a
+change back while it is.
+
+## Development
+
+The generated API (`kuvert/api/schema.py`) comes from the checked-in
+`schema.graphql` and the documents in `graphql/`. The config comment in
+`graphql.config.yaml` has the command that refreshes the schema from a
+kuvert-server checkout. Then run turms to regenerate the API.
+
+```sh
+uv run pytest -m "not integration"   # no server needed
+uv run pytest -m integration          # a real kuvert + mail server via dokker
+```
+
+See [RELEASING.md](RELEASING.md) for how versions are cut.

kuvert-1.0.0/README.md

@@ -0,0 +1,101 @@
+# kuvert
+
+The python client for [kuvert](https://github.com/arkitektio/kuvert-server), the
+[Arkitekt](https://arkitekt.live) mail service: the mailboxes you linked, their
+folders and conversations, tasks over those conversations, and sending mail.
+
+## Installation
+
+```sh
+pip install kuvert
+```
+
+## Usage
+
+Every kuvert operation is a method of the `Kuvert` client, in a blocking and an
+`a`-prefixed async flavour.
+
+### In an arkitekt app
+
+The client is injected by annotation. Add the service to your app and ask for
+`kuvert: Kuvert`:
+
+```python
+from arkitekt import App, run
+from kuvert import Kuvert, kuvert_service
+
+app = App("mail-digest", "0.1.0", services=[kuvert_service])
+
+
+@app.action
+async def unread_subjects(kuvert: Kuvert) -> list[str]:
+    """The subjects of the unread conversations in my inboxes."""
+    threads = await kuvert.alist_threads(filter={"unread": True, "folderRole": "INBOX"})
+    return [thread.subject for thread in threads]
+
+
+if __name__ == "__main__":
+    run(app)
+```
+
+Messages, threads, outgoing mail, mailboxes, tasks and task lists travel between
+actions by id (`@kuvert/message`, `@kuvert/thread`, `@kuvert/outgoingmessage`,
+`@kuvert/mailaccount`, `@kuvert/task`, `@kuvert/tasklist`), so an action can take
+and return them directly, and a trigger on a kuvert signal hands them over.
+
+### From a script
+
+```python
+from arkitekt import easy
+from kuvert import kuvert_service
+
+with easy("my-script", kuvert_service) as kuvert:
+    for account in kuvert.list_mail_accounts():
+        print(account.email_address, account.unread_count)
+```
+
+### Standalone
+
+Without arkitekt, build the client over a rath link of your own:
+
+```python
+from kuvert import Kuvert
+from kuvert.rath import KuvertRath
+
+kuvert = Kuvert(rath=KuvertRath(link=...))
+
+with kuvert:
+    for account in kuvert.list_mail_accounts():
+        print(account.email_address, account.unread_count)
+
+    kuvert.send_message(
+        account=account.id,
+        to=[{"address": "someone@example.org"}],
+        subject="Hello",
+        text="From kuvert.",
+    )
+```
+
+Arguments the server defaults (`cc`, `bcc`, `attachments` of `send_message`,
+`notes`/`pinned` of `create_task`, …) are optional: **leave them out** rather
+than passing `None`. An explicit `None` is sent as `null`, which the server
+rejects for those fields.
+
+Changes to mail (flags, moves, deletes, categories) are local-first: they apply
+at once and reach the mail server when the mailbox next pushes.
+`list_mail_changes` shows what is still pending and `undo_mail_changes` takes a
+change back while it is.
+
+## Development
+
+The generated API (`kuvert/api/schema.py`) comes from the checked-in
+`schema.graphql` and the documents in `graphql/`. The config comment in
+`graphql.config.yaml` has the command that refreshes the schema from a
+kuvert-server checkout. Then run turms to regenerate the API.
+
+```sh
+uv run pytest -m "not integration"   # no server needed
+uv run pytest -m integration          # a real kuvert + mail server via dokker
+```
+
+See [RELEASING.md](RELEASING.md) for how versions are cut.

kuvert-1.0.0/kuvert/__init__.py

@@ -0,0 +1,20 @@
+from .kuvert import Kuvert
+
+try:
+    from .arkitekt import kuvert as kuvert_service
+except ImportError as e:
+    # Only "rekuest is not installed" may pass silently. Anything else that fails
+    # to import here (a renamed query, a rekuest too old for what the module
+    # needs) is a bug, and hiding it makes this package's service vanish
+    # without a word. Whether it is installed is asked the plain way.
+    try:
+        import rekuest  # noqa: F401 -- presence is the question
+    except ImportError:
+        pass
+    else:
+        raise e
+
+__all__ = [
+    "Kuvert",
+    "kuvert_service",
+]

kuvert-1.0.0/kuvert/api/project.json

@@ -0,0 +1,120 @@
+{
+    "schema": "schema.graphql",
+    "documents": "graphql/**/**.graphql",
+    "extensions": {
+        "turms": {
+            "domain": null,
+            "out_dir": "kuvert/api",
+            "dump_configuration": true,
+            "configuration_name": "project.json",
+            "dump_schema": true,
+            "schema_name": "schema.graphql",
+            "generated_name": "schema.py",
+            "documents": "graphql/**/**.graphql",
+            "verbose": false,
+            "exit_on_error": true,
+            "allow_introspection": true,
+            "object_bases": [
+                "pydantic.BaseModel"
+            ],
+            "interface_bases": null,
+            "always_resolve_interfaces": true,
+            "exclude_typenames": true,
+            "scalar_definitions": {
+                "uuid": "str",
+                "Callback": "str",
+                "Any": "typing.Any",
+                "JSON": "typing.Any",
+                "ID": "rath.scalars.ID",
+                "_Any": "typing.Any",
+                "ByteCount": "int"
+            },
+            "coercible_scalars": {},
+            "coercible_inputs": {},
+            "graphql_default_class": null,
+            "deprecated_class": null,
+            "document_field_metadata": true,
+            "unset_type_class": null,
+            "unset_instance": null,
+            "freeze": {
+                "enabled": true,
+                "types": [
+                    "input",
+                    "fragment",
+                    "object"
+                ],
+                "exclude": null,
+                "include": null,
+                "convert_list_to_tuple": true
+            },
+            "create_catchall": true,
+            "options": {
+                "enabled": true,
+                "extra": "forbid",
+                "populate_by_name": true,
+                "from_attributes": null,
+                "use_enum_values": true,
+                "validate_assignment": null,
+                "alias_mode": "split",
+                "types": [
+                    "input"
+                ],
+                "exclude": null,
+                "include": null
+            },
+            "skip_forwards": false,
+            "min_python_version": "3.10",
+            "type_annotation_style": "auto",
+            "external_modules": [],
+            "additional_bases": {},
+            "additional_config": {},
+            "force_plugin_order": true,
+            "omitted_document_rules": [],
+            "parsers": [],
+            "plugins": [
+                {
+                    "type": "turms.plugins.enums.EnumsPlugin"
+                },
+                {
+                    "type": "turms.plugins.inputs.InputsPlugin"
+                },
+                {
+                    "type": "turms.plugins.fragments.FragmentsPlugin"
+                },
+                {
+                    "type": "turms.plugins.operations.OperationsPlugin"
+                },
+                {
+                    "type": "turms.plugins.client.ClientPlugin",
+                    "client_class": "KuvertApi",
+                    "global_kwargs": [
+                        {
+                            "key": "task",
+                            "type": "rath.task.TaskLike",
+                            "description": "The task this call is made for; the ambient one by default."
+                        }
+                    ],
+                    "reserved_from": [
+                        "kuvert.kuvert.Kuvert"
+                    ],
+                    "coercible_scalars": {
+                        "ID": "rath.scalars.IDCoercible"
+                    },
+                    "expand_input_types": [
+                        "input"
+                    ]
+                }
+            ],
+            "processors": [],
+            "stylers": [
+                {
+                    "type": "turms.stylers.default.DefaultStyler"
+                },
+                {
+                    "type": "turms.stylers.appender.AppenderStyler",
+                    "append_fragment": ""
+                }
+            ]
+        }
+    }
+}