pyactivesync 0.2.0__py3-none-any.whl

pyactivesync/models.py

@@ -0,0 +1,112 @@
+"""Public data types returned by :class:`pyactivesync.client.Client`."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+
+
+class FolderType(IntEnum):
+    """MS-ASCMD ``FolderHierarchy:Type`` values."""
+
+    GENERIC = 1
+    INBOX = 2
+    DRAFTS = 3
+    DELETED_ITEMS = 4
+    SENT_ITEMS = 5
+    OUTBOX = 6
+    TASKS = 7
+    CALENDAR = 8
+    CONTACTS = 9
+    NOTES = 10
+    JOURNAL = 11
+    USER_GENERIC = 12
+    USER_MAIL = 13
+    USER_CALENDAR = 14
+    USER_CONTACTS = 15
+    USER_TASKS = 16
+    USER_JOURNAL = 17
+    USER_NOTES = 18
+    UNKNOWN = 19
+    RECIPIENT_CACHE = 20
+
+
+class BodyType(IntEnum):
+    """MS-ASAIRSYNCBASE ``BodyPreference:Type`` / ``Body:Type`` values."""
+
+    PLAIN_TEXT = 1
+    HTML = 2
+    RTF = 3
+    MIME = 4
+
+
+@dataclass(frozen=True, slots=True)
+class Folder:
+    id: str
+    parent_id: str
+    type: FolderType
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class SyncItem:
+    """One ``Add`` or ``Change`` entry from a ``Sync`` response.
+
+    ``fields`` is a flat ``{tag_name: text}`` dump of every leaf element
+    under ``ApplicationData`` (e.g. ``"Email.Subject"``), so it works
+    across Email/Contacts/Calendar item classes without a per-class field
+    table.
+    """
+
+    server_id: str
+    fields: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class SyncResult:
+    sync_key: str
+    added: list[SyncItem] = field(default_factory=list)
+    changed: list[SyncItem] = field(default_factory=list)
+    deleted: list[str] = field(default_factory=list)
+    more_available: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class AttachmentInfo:
+    """Attachment metadata as found in a fetched item's properties.
+
+    Use ``file_reference`` with ``Client.fetch_attachment()`` to download
+    the actual bytes.
+    """
+
+    display_name: str
+    file_reference: str
+    content_type: str | None = None
+    estimated_data_size: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class GalEntry:
+    display_name: str | None = None
+    email_address: str | None = None
+    phone: str | None = None
+    office: str | None = None
+    title: str | None = None
+    company: str | None = None
+    alias: str | None = None
+    first_name: str | None = None
+    last_name: str | None = None
+    home_phone: str | None = None
+    mobile_phone: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Recipient:
+    type: str | None
+    display_name: str | None
+    email_address: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class PingResult:
+    status: str
+    changed_folder_ids: list[str] = field(default_factory=list)

pyactivesync-0.2.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: pyactivesync
+Version: 0.2.0
+Summary: A Python client for Exchange ActiveSync (EAS / MS-ASCMD / MS-ASWBXML)
+Project-URL: Homepage, https://github.com/monperrus/pyactivesync
+Project-URL: Repository, https://github.com/monperrus/pyactivesync
+Project-URL: Issues, https://github.com/monperrus/pyactivesync/issues
+Author: Martin Monperrus
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyactivesync
+
+A Python client library for Exchange ActiveSync (EAS), implementing
+enough of [MS-ASCMD] (the command protocol) and [MS-ASWBXML] (the binary
+XML encoding) to talk to a real Exchange server: folder listing, mail
+sync, item/attachment fetch, sending mail, folder management, moving
+items, directory search, and push notifications via `Ping`.
+
+[MS-ASCMD]: https://learn.microsoft.com/en-us/openspecs/exchange_server_protocols/ms-ascmd/
+[MS-ASWBXML]: https://learn.microsoft.com/en-us/openspecs/exchange_server_protocols/ms-aswbxml/
+
+## Install
+
+```
+pip install pyactivesync
+```
+
+## Usage
+
+```python
+from email.message import EmailMessage
+from pyactivesync import Client, FolderType, BodyType
+
+with Client(
+    server="mail.example.com",
+    username=r"CORP\jdoe",       # NTLM-style domain\user, or a plain email -- both work
+    password="...",
+    device_id="MyApp01",          # caller-provided; persist it yourself for a stable
+                                    # device identity across runs -- pyactivesync doesn't
+                                    # persist anything to disk on its own
+) as client:
+    folders = client.list_folders()
+    inbox = next(f for f in folders if f.type == FolderType.INBOX)
+
+    result = client.sync_folder(inbox.id)                              # bootstrap
+    result = client.sync_folder(inbox.id, sync_key=result.sync_key)     # Add/Change/Delete
+
+    for item in result.added:
+        print(item.fields.get("Email.Subject"))
+        body = client.fetch_item(inbox.id, item.server_id, body_type=BodyType.HTML)
+
+    msg = EmailMessage()
+    msg["To"] = "someone@example.com"
+    msg["Subject"] = "hello from pyactivesync"
+    msg.set_content("plain text body")
+    client.send_mail(msg)
+```
+
+`Client` is a context manager wrapping one `requests.Session` -- EAS is
+stateless HTTP (an auth header plus a `PolicyKey` header), so unlike an
+IMAP connection there's no server-side session to tear down; `__exit__`
+just closes the HTTP session. `provision()` (the device policy handshake)
+is called lazily on first use if you don't call it explicitly.
+
+Folder and item ids are plain strings (`"9"`, `"9:1"`), matching EAS's
+own `ServerId` format exactly -- there's no synthetic id layer to keep in
+sync with a local cache.
+
+## Command coverage
+
+| Command | Client method |
+|---|---|
+| `Provision` | `Client.provision()` (also called lazily) |
+| `FolderSync` | `Client.list_folders()` |
+| `Sync` | `Client.sync_folder()` |
+| `GetItemEstimate` | `Client.get_item_estimate()` |
+| `ItemOperations` Fetch (body) | `Client.fetch_item()` |
+| `ItemOperations` Fetch (attachment) | `Client.fetch_attachment()` |
+| `SendMail` | `Client.send_mail()` |
+| `FolderCreate`/`FolderUpdate`/`FolderDelete` | `Client.create_folder()`/`update_folder()`/`delete_folder()` |
+| `MoveItems` | `Client.move_item()` |
+| `Ping` | `Client.ping()` |
+| `ResolveRecipients` | `Client.resolve_recipients()` |
+| `Search` (GAL) | `Client.search_gal()` |
+| `Search` (Mailbox, structured) | `Client.search_mailbox()` |
+
+**Not implemented**: `MeetingResponse`, `ValidateCert`, `SmartForward`/`SmartReply`.
+Documented as unimplemented, not silently missing.
+
+**Non-goals**: an EAS *server*; Autodiscover (pass a server hostname
+directly); Calendar/Contacts *write* operations (read via `Sync` is
+supported); NTLM auth (Basic auth only -- `requests` doesn't do NTLM
+without an extra dependency); credential storage of any kind (that's the
+caller's business).
+
+`search_mailbox()` deliberately has no `free_text=` parameter: full-text
+`Search` conditions are known to fail against real Exchange servers with
+`Store.Status=110`, a server-side bug in EAS's `Search` handling rather
+than a WBXML encoding issue (confirmed by cross-checking the same
+mailbox's content index through an unrelated protocol, which returns
+correct results for the same query). Shipping that parameter would just
+reproduce the failure for every caller.
+
+## Development
+
+```
+pip install -e '.[dev]'
+pytest
+ruff check .
+mypy pyactivesync tests
+```
+
+Unit tests (WBXML codec against golden byte fixtures, codepage table
+sanity checks) require no network and run in CI on every push. Live
+integration tests in `tests/test_client_live.py` are skipped unless
+`PYACTIVESYNC_TEST_SERVER`, `PYACTIVESYNC_TEST_USER`, and `PYACTIVESYNC_TEST_PASSWORD` are
+set, and only ever create/rename/delete objects they create themselves --
+pre-existing folders and items are never touched.
+
+## License
+
+MIT

pyactivesync-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+pyactivesync/__init__.py,sha256=4Hm02ufV_3KNeMvPJOs_MYMUDBYH-rr4-9WjqvL0ZuE,696
+pyactivesync/_codepages.py,sha256=vLlgi229vAi7NdMFVQ3AafiS3-lZmwmksImMlNZxc_U,6170
+pyactivesync/_http.py,sha256=X4HUb0xSM-b86KghebL-11p-a2Z8yG_X2dQsYgMikyA,2409
+pyactivesync/_mime.py,sha256=_580HlTMBe75Ndu2S7tvrLHkyMJzbBtWDrv2iv3No3w,757
+pyactivesync/_wbxml.py,sha256=ZBNjjGNlS_PjyCG92u2TW7H6L1DqNiaQ1l85Ftf0u64,6226
+pyactivesync/cli.py,sha256=_ddoSg0vq3iKz2cS2ouX2wSAjUWR6gP7ts_oLM9nWVQ,5219
+pyactivesync/client.py,sha256=R2CRy_CDfYo0dUihHtGhoZcJ5fnYE2agFmvBLuj5BPA,25803
+pyactivesync/exceptions.py,sha256=k8IZm4qRaTqQOOUXif7AO2ufdLO6t64e2vBHSMvjoIg,944
+pyactivesync/models.py,sha256=amQFJMo9Ij_Ipg2JbMfHAPtuXfU0CgnEXyWTD99EkLw,2656
+pyactivesync-0.2.0.dist-info/METADATA,sha256=vYSy4OBX4lNizcMZLbDyLweTyENxy9iZkX-bjwXnix8,5690
+pyactivesync-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pyactivesync-0.2.0.dist-info/entry_points.txt,sha256=TqWjGn_lGoXbNjRoflxW12KnUHVywFeSUy9r33_9mJg,55
+pyactivesync-0.2.0.dist-info/licenses/LICENSE,sha256=cZcVt0H9cnb7yEUhuaOjEY44tOenoE73-XlnbE3fTG8,1073
+pyactivesync-0.2.0.dist-info/RECORD,,

pyactivesync-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyactivesync-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyactivesync = pyactivesync.cli:main

pyactivesync-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Monperrus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.