gweasysoap 0.1.0__tar.gz

gweasysoap-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.env

gweasysoap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raymond Hulha
+
+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.

gweasysoap-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: gweasysoap
+Version: 0.1.0
+Summary: A helper library for the GroupWise SOAP API (gwsoap).
+Project-URL: Homepage, https://github.com/rhulha/GWEasySoap
+Project-URL: Documentation, https://github.com/rhulha/GWEasySoap#readme
+Project-URL: Repository, https://github.com/rhulha/GWEasySoap
+Project-URL: Bug Reports, https://github.com/rhulha/GWEasySoap/issues
+License: MIT
+License-File: LICENSE
+Keywords: groupwise,gwsoap,micro focus,novell,soap
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.9
+Requires-Dist: gwsoap>=1.0.3
+Description-Content-Type: text/markdown
+
+# gweasysoap
+
+A small, pythonic helper library on top of the auto-generated
+[`gwsoap`](https://pypi.org/project/gwsoap/) GroupWise SOAP client. It hides the
+request/context boilerplate and gives you simple methods for logging in,
+reading folders and items, sending mail, and creating appointments.
+
+## Installation
+
+```bash
+pip install gweasysoap
+```
+
+This pulls in `gwsoap>=1.0.3`.
+
+## Quick start
+
+```python
+from gweasysoap import GWEasySoap
+
+# Use it as a context manager so the session is always logged out.
+with GWEasySoap.connect_trusted_app(
+    "https://gw.example.com:7191/soap", "jdoe", "MyApp", "trusted-key"
+) as gw:
+    print("Logged in as", gw.user_name, gw.user_email)
+
+    mailbox = gw.get_mailbox()
+    for item in gw.get_folder_items(mailbox.id, count=20):
+        print(item.subject)
+
+    gw.send_mail(
+        subject="Hello",
+        body_text="Sent from gweasysoap",
+        recipients=[{"display_name": "Jane", "email": "jane@example.com"}],
+    )
+```
+
+### Logging in
+
+```python
+# Username / password
+gw = GWEasySoap.connect(endpoint, "jdoe", "secret")
+
+# Trusted application key (impersonate a specific user)
+gw = GWEasySoap.connect_trusted_app(endpoint, "jdoe", "MyApp", "trusted-key")
+
+# Trusted application key, first usable mailbox on the post office
+gw = GWEasySoap.connect_any_user(endpoint, "MyApp", "trusted-key")
+```
+
+Each `connect*` factory raises `GWEasySoapError` on failure. The matching
+instance methods (`login`, `login_trusted_app`, `login_with_any_user`) return a
+boolean instead, if you prefer to manage the instance yourself.
+
+Constructor options: `application` (the name reported to GroupWise),
+`debug`, and `verify_ssl`.
+
+### What you can do
+
+- **Users / mailboxes** – `get_user_list`, `get_user_mailboxes`
+- **Address book** – `get_system_address_book`, `get_address_book_entries`
+- **Folders** – `get_mailbox`, `get_trash_folder`, `get_calendar`,
+  `get_system_folder`, `get_folder_list`, `get_shared_folder_by_name`
+- **Items** – `get_items`, `get_folder_items`, `get_calendar_items`,
+  `get_item`, `get_full_item`, `get_body`, `remove_item`
+- **Mail** – `send_mail`
+- **Appointments** – `create_appointment`, `create_appointment_in_folder`,
+  `add_category`
+- **Session** – `whoami`, `user_name`, `user_email`, `logout`
+
+## License
+
+MIT

gweasysoap-0.1.0/PYPI_UPLOAD.md

@@ -0,0 +1,76 @@
+# PyPI Upload Instructions
+
+## Prerequisites
+
+1. Install build tools:
+```bash
+pip install --upgrade build twine
+```
+
+2. Create accounts on:
+   - PyPI: https://pypi.org/account/register/
+   - TestPyPI: https://test.pypi.org/account/register/
+
+3. Create API tokens:
+   - PyPI: https://pypi.org/manage/account/token/
+   - TestPyPI: https://test.pypi.org/manage/account/token/
+
+## Build the Package
+
+```bash
+python -m build
+```
+
+This creates:
+- `dist/moonpie-X.Y.Z-py3-none-any.whl` (wheel)
+- `dist/moonpie-X.Y.Z.tar.gz` (source distribution)
+
+## Upload to TestPyPI (Recommended First)
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Test installation:
+```bash
+pip install --index-url https://test.pypi.org/simple/ moonpie
+```
+
+## Upload to PyPI (Production)
+
+```bash
+python -m twine upload dist/*
+```
+
+Or use API token:
+```bash
+python -m twine upload --username __token__ --password pypi-YOUR_TOKEN_HERE dist/*
+```
+
+## Test Installation
+
+```bash
+pip install moonpie
+```
+
+Test the CLI:
+```bash
+moonpie
+moonpie examples/examples.lua
+python -m moonpie
+```
+
+## Update Version
+
+Before uploading a new version:
+1. Update version in `moonpie/__init__.py`
+2. Clean old builds: `rm -rf build dist *.egg-info`
+3. Rebuild: `python -m build`
+4. Upload: `python -m twine upload dist/*`
+
+## Notes
+
+- Version numbers must be unique (can't overwrite)
+- Use semantic versioning (MAJOR.MINOR.PATCH)
+- TestPyPI is cleared regularly, use for testing only
+- Keep your API tokens secure

gweasysoap-0.1.0/README.md

@@ -0,0 +1,73 @@
+# gweasysoap
+
+A small, pythonic helper library on top of the auto-generated
+[`gwsoap`](https://pypi.org/project/gwsoap/) GroupWise SOAP client. It hides the
+request/context boilerplate and gives you simple methods for logging in,
+reading folders and items, sending mail, and creating appointments.
+
+## Installation
+
+```bash
+pip install gweasysoap
+```
+
+This pulls in `gwsoap>=1.0.3`.
+
+## Quick start
+
+```python
+from gweasysoap import GWEasySoap
+
+# Use it as a context manager so the session is always logged out.
+with GWEasySoap.connect_trusted_app(
+    "https://gw.example.com:7191/soap", "jdoe", "MyApp", "trusted-key"
+) as gw:
+    print("Logged in as", gw.user_name, gw.user_email)
+
+    mailbox = gw.get_mailbox()
+    for item in gw.get_folder_items(mailbox.id, count=20):
+        print(item.subject)
+
+    gw.send_mail(
+        subject="Hello",
+        body_text="Sent from gweasysoap",
+        recipients=[{"display_name": "Jane", "email": "jane@example.com"}],
+    )
+```
+
+### Logging in
+
+```python
+# Username / password
+gw = GWEasySoap.connect(endpoint, "jdoe", "secret")
+
+# Trusted application key (impersonate a specific user)
+gw = GWEasySoap.connect_trusted_app(endpoint, "jdoe", "MyApp", "trusted-key")
+
+# Trusted application key, first usable mailbox on the post office
+gw = GWEasySoap.connect_any_user(endpoint, "MyApp", "trusted-key")
+```
+
+Each `connect*` factory raises `GWEasySoapError` on failure. The matching
+instance methods (`login`, `login_trusted_app`, `login_with_any_user`) return a
+boolean instead, if you prefer to manage the instance yourself.
+
+Constructor options: `application` (the name reported to GroupWise),
+`debug`, and `verify_ssl`.
+
+### What you can do
+
+- **Users / mailboxes** – `get_user_list`, `get_user_mailboxes`
+- **Address book** – `get_system_address_book`, `get_address_book_entries`
+- **Folders** – `get_mailbox`, `get_trash_folder`, `get_calendar`,
+  `get_system_folder`, `get_folder_list`, `get_shared_folder_by_name`
+- **Items** – `get_items`, `get_folder_items`, `get_calendar_items`,
+  `get_item`, `get_full_item`, `get_body`, `remove_item`
+- **Mail** – `send_mail`
+- **Appointments** – `create_appointment`, `create_appointment_in_folder`,
+  `add_category`
+- **Session** – `whoami`, `user_name`, `user_email`, `logout`
+
+## License
+
+MIT

gweasysoap-0.1.0/gweasysoap/__init__.py

@@ -0,0 +1,8 @@
+"""gweasysoap - a pythonic helper library for the GroupWise SOAP API."""
+
+from .client import GWEasySoap, GW_SYSTEM_ADDRESS_BOOK_NAME
+from .exceptions import GWEasySoapError
+
+__version__ = "0.1.0"
+
+__all__ = ["GWEasySoap", "GWEasySoapError", "GW_SYSTEM_ADDRESS_BOOK_NAME"]

gweasysoap-0.1.0/gweasysoap/client.py

@@ -0,0 +1,460 @@
+"""A pythonic helper around the auto-generated ``gwsoap`` GroupWise SOAP client."""
+
+import logging
+from datetime import datetime
+from typing import Any, Mapping, Optional, Sequence, Union
+
+from gwsoap.service.groupwise_client import GroupWiseClient
+from gwsoap.soap.exceptions import SoapFaultException
+from gwsoap.soap.request_context import RequestContext
+
+from gwsoap.methods.LoginRequest import LoginRequest
+from gwsoap.methods.LogoutRequest import LogoutRequest
+from gwsoap.methods.GetUserListRequest import GetUserListRequest
+from gwsoap.methods.GetAddressBookListRequest import GetAddressBookListRequest
+from gwsoap.methods.GetItemsRequest import GetItemsRequest
+from gwsoap.methods.GetItemRequest import GetItemRequest
+from gwsoap.methods.RemoveItemRequest import RemoveItemRequest
+from gwsoap.methods.SendItemRequest import SendItemRequest
+from gwsoap.methods.CreateItemRequest import CreateItemRequest
+from gwsoap.methods.ModifyItemRequest import ModifyItemRequest
+from gwsoap.methods.GetFolderListRequest import GetFolderListRequest
+
+from gwsoap.types.AddressBookItem import AddressBookItem
+from gwsoap.types.Appointment import Appointment
+from gwsoap.types.CategoryRefList import CategoryRefList
+from gwsoap.types.ContainerRef import ContainerRef
+from gwsoap.types.Custom import Custom
+from gwsoap.types.CustomList import CustomList
+from gwsoap.types.Distribution import Distribution
+from gwsoap.types.DistributionType import DistributionType
+from gwsoap.types.FolderType import FolderType
+from gwsoap.types.From import From
+from gwsoap.types.ItemChanges import ItemChanges
+from gwsoap.types.Mail import Mail
+from gwsoap.types.MessageBody import MessageBody
+from gwsoap.types.MessagePart import MessagePart
+from gwsoap.types.PlainText import PlainText
+from gwsoap.types.Recipient import Recipient
+from gwsoap.types.RecipientList import RecipientList
+from gwsoap.types.RecipientType import RecipientType
+from gwsoap.types.SharedFolder import SharedFolder
+from gwsoap.types.SystemFolder import SystemFolder
+from gwsoap.types.TrustedApplication import TrustedApplication
+
+from .exceptions import GWEasySoapError
+
+logger = logging.getLogger(__name__)
+
+GW_SYSTEM_ADDRESS_BOOK_NAME = "GroupWiseSystemAddressBook"
+
+RecipientLike = Union[Mapping[str, Any], Any]
+
+
+class GWEasySoap:
+    """High-level, session-aware wrapper for the GroupWise SOAP API.
+
+    Create it directly and call one of the ``login*`` methods, use one of the
+    ``connect*`` classmethod factories, or use it as a context manager so the
+    session is always logged out::
+
+        with GWEasySoap.connect_trusted_app(endpoint, user, app, key) as gw:
+            mailbox = gw.get_mailbox()
+    """
+
+    def __init__(self, application: str = "GWEasySoap", debug: bool = False,
+                 verify_ssl: bool = True):
+        self.client: Optional[GroupWiseClient] = None
+        self.session: Optional[str] = None
+        self.login_resp = None
+        self.application = application
+        self.debug = debug
+        self.verify_ssl = verify_ssl
+
+    # -- factories ---------------------------------------------------------
+
+    @classmethod
+    def connect(cls, endpoint: str, username: str, password: str, **kwargs) -> "GWEasySoap":
+        """Log in with a username/password and return the connected instance."""
+        gw = cls(**kwargs)
+        if not gw.login(endpoint, username, password):
+            raise GWEasySoapError(f"Login failed for user {username!r}")
+        return gw
+
+    @classmethod
+    def connect_trusted_app(cls, endpoint: str, username: str, tapp_name: str,
+                            tapp_key: str, **kwargs) -> "GWEasySoap":
+        """Log in via a trusted application key and return the connected instance."""
+        gw = cls(**kwargs)
+        if not gw.login_trusted_app(endpoint, username, tapp_name, tapp_key):
+            raise GWEasySoapError(f"Trusted app login failed for user {username!r}")
+        return gw
+
+    @classmethod
+    def connect_any_user(cls, endpoint: str, tapp_name: str, tapp_key: str,
+                         **kwargs) -> "GWEasySoap":
+        """Log in as the first usable mailbox on the post office (trusted app)."""
+        gw = cls(**kwargs)
+        gw.login_with_any_user(endpoint, tapp_name, tapp_key)
+        return gw
+
+    # -- context manager ---------------------------------------------------
+
+    def __enter__(self) -> "GWEasySoap":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.logout()
+
+    # -- login -------------------------------------------------------------
+
+    def login(self, endpoint: str, username: str, password: str) -> bool:
+        """Log in with a plain username and password."""
+        auth = PlainText(username=username, password=password)
+        return self._login_with_redirect(endpoint, auth)
+
+    def login_trusted_app(self, endpoint: str, username: str, tapp_name: str,
+                          tapp_key: str) -> bool:
+        """Log in on behalf of ``username`` using a trusted application key."""
+        auth = TrustedApplication(username=username, name=tapp_name, key=tapp_key)
+        return self._login_with_redirect(endpoint, auth)
+
+    def login_with_any_user(self, endpoint: str, tapp_name: str, tapp_key: str) -> bool:
+        """Try the trusted-app login against post office users until one succeeds."""
+        last_fault = None
+        for tried, info in enumerate(self.get_user_list(endpoint, tapp_name, tapp_key)):
+            if info.recip_type != RecipientType.USER or not info.userid:
+                continue
+            if tried >= 10:
+                break
+            try:
+                if self.login_trusted_app(endpoint, info.userid, tapp_name, tapp_key):
+                    return True
+            except SoapFaultException as e:
+                last_fault = e
+        if last_fault is not None:
+            raise last_fault
+        raise GWEasySoapError(
+            "No usable GroupWise mailbox found - does this post office have any?"
+        )
+
+    def _login_with_redirect(self, endpoint: str, auth) -> bool:
+        login_resp = self._attempt_login(endpoint, auth)
+        if login_resp is not None and login_resp.redirect_to_host:
+            # The mailbox lives on another post office; its Host carries no
+            # scheme, so retry against that POA trying both http and https.
+            host = login_resp.redirect_to_host[0]
+            logger.info("Login redirected to host %s:%s", host.ip_address, host.port)
+            login_resp = self._attempt_redirect(endpoint, host, auth)
+
+        if login_resp is None or login_resp.status is None or login_resp.status.code != 0:
+            return False
+        self.login_resp = login_resp
+        self.session = login_resp.session
+        return True
+
+    def _attempt_login(self, endpoint: str, auth):
+        self.client = GroupWiseClient(endpoint, debug=self.debug, verify_ssl=self.verify_ssl)
+        login_req = LoginRequest(auth=auth, application=self.application, language="en")
+        return self.client.login(login_req)
+
+    def _attempt_redirect(self, endpoint: str, host, auth):
+        import http.client
+        from urllib.parse import urlsplit, urlunsplit
+
+        parts = urlsplit(endpoint)
+        netloc = f"{host.ip_address}:{host.port}"
+        schemes = [parts.scheme, "https" if parts.scheme == "http" else "http"]
+        last_err = None
+        for scheme in schemes:
+            target = urlunsplit((scheme, netloc, parts.path, parts.query, parts.fragment))
+            try:
+                return self._attempt_login(target, auth)
+            except (OSError, http.client.HTTPException) as e:
+                last_err = e
+        if last_err is not None:
+            raise last_err
+        return None
+
+    # -- connected user ----------------------------------------------------
+
+    def whoami(self):
+        """Return the ``userinfo`` of the logged-in user, or ``None``."""
+        return self.login_resp.userinfo if self.login_resp else None
+
+    @property
+    def user_name(self) -> str:
+        info = self.whoami()
+        return (info.name if info else "") or ""
+
+    @property
+    def user_email(self) -> str:
+        info = self.whoami()
+        return (getattr(info, "email", None) if info else "") or ""
+
+    # -- users (no session needed) ----------------------------------------
+
+    def get_user_list(self, endpoint: str, tapp_name: str, tapp_key: str) -> list:
+        """Return the raw user records for the post office at ``endpoint``."""
+        client = GroupWiseClient(endpoint, debug=self.debug, verify_ssl=self.verify_ssl)
+        response = client.get_user_list(GetUserListRequest(name=tapp_name, key=tapp_key))
+        self._raise_on_bad_status(response, "get_user_list")
+        if response and response.users and response.users.user:
+            return response.users.user
+        return []
+
+    def get_user_mailboxes(self, endpoint: str, tapp_name: str, tapp_key: str) -> list:
+        """Return the post office mailboxes as plain dicts."""
+        return [
+            {
+                "userid": u.userid,
+                "display_name": u.name or u.userid,
+                "email": u.email or u.userid,
+                "uuid": u.uuid,
+            }
+            for u in self.get_user_list(endpoint, tapp_name, tapp_key)
+            if u.recip_type == RecipientType.USER and u.userid
+        ]
+
+    # -- address book ------------------------------------------------------
+
+    def get_system_address_book(self):
+        """Return the GroupWise system address book, or ``None``."""
+        response = self.client.get_address_book_list(GetAddressBookListRequest(), self._ctx)
+        books = response.books
+        if not books or not books.book:
+            return None
+        for book in books.book:
+            if book and book.id and book.id.startswith(GW_SYSTEM_ADDRESS_BOOK_NAME + "@"):
+                return book
+        return None
+
+    def get_address_book_entries(self, book, count: Optional[int] = None) -> list:
+        """Return the :class:`AddressBookItem` entries inside ``book``."""
+        response = self.client.get_items(
+            GetItemsRequest(container=book.id, count=count), self._ctx
+        )
+        items = response.items
+        if not items or not items.item:
+            return []
+        return [item for item in items.item if isinstance(item, AddressBookItem)]
+
+    # -- folders -----------------------------------------------------------
+
+    def get_system_folder(self, folder_type):
+        """Return the system folder of the given :class:`FolderType`, or ``None``."""
+        request = GetFolderListRequest(parent="folders", recurse=False, imap=False, nntp=False)
+        response = self.client.get_folder_list(request, self._ctx)
+        folders = response.folders
+        if not folders or not folders.folder:
+            return None
+        for folder in folders.folder:
+            if isinstance(folder, SystemFolder) and folder.folder_type == folder_type:
+                return folder
+        return None
+
+    def get_mailbox(self):
+        return self.get_system_folder(FolderType.MAILBOX)
+
+    def get_trash_folder(self):
+        return self.get_system_folder(FolderType.TRASH)
+
+    def get_calendar(self):
+        return self.get_system_folder(FolderType.CALENDAR)
+
+    def get_folder_list(self) -> list:
+        """Return every folder in the mailbox (recursive)."""
+        request = GetFolderListRequest(parent="folders", recurse=True, imap=False, nntp=False)
+        response = self.client.get_folder_list(request, self._ctx)
+        folders = response.folders
+        if not folders or not folders.folder:
+            return []
+        return folders.folder
+
+    def get_shared_folder_by_name(self, name: str):
+        """Return the :class:`SharedFolder` with the given name, or ``None``."""
+        for folder in self.get_folder_list():
+            if isinstance(folder, SharedFolder) and folder.name == name:
+                return folder
+        return None
+
+    # -- items -------------------------------------------------------------
+
+    def get_items(self, container_id: str, filter: Optional[str] = None,
+                  count: Optional[int] = None) -> list:
+        """Return the items inside a container (folder or address book)."""
+        request = GetItemsRequest(container=container_id, filter=filter, count=count)
+        response = self.client.get_items(request, self._ctx)
+        items = response.items
+        if not items or not items.item:
+            return []
+        return items.item
+
+    def get_folder_items(self, folder_id: str, count: int = 200) -> list:
+        return self.get_items(folder_id, count=count)
+
+    def get_calendar_items(self, count: int = 200) -> list:
+        calendar = self.get_calendar()
+        return self.get_items(calendar.id, count=count) if calendar else []
+
+    def get_item(self, item_id: str):
+        """Return a single item by id."""
+        response = self.client.get_item(GetItemRequest(id=item_id), self._ctx)
+        return response.item if response and response.item else None
+
+    def get_full_item(self, item_id: str):
+        """Return a single item including its message body view."""
+        from gwsoap.types.View import View
+
+        request = GetItemRequest(id=item_id, view=View(value=["message"]))
+        response = self.client.get_item(request, self._ctx)
+        return response.item if response and response.item else None
+
+    def get_body(self, item) -> str:
+        """Return the decoded plain-text body of ``item``."""
+        full = self.get_full_item(item.id)
+        message = getattr(full, "message", None)
+        if not message or not message.part:
+            return ""
+        value = message.part[0].value
+        return value.decode("utf-8", errors="replace") if value is not None else ""
+
+    def remove_item(self, container: str, item_id: str) -> None:
+        """Remove an item from a container."""
+        response = self.client.remove_item(
+            RemoveItemRequest(container=container, id=item_id), self._ctx
+        )
+        self._raise_on_bad_status(response, "remove_item")
+
+    # -- mail --------------------------------------------------------------
+
+    def send_mail(self, subject: str, body_text: str,
+                  recipients: Sequence[RecipientLike],
+                  return_sent_items_id: bool = True) -> Optional[str]:
+        """Send a plain-text mail.
+
+        ``recipients`` may be dicts or objects carrying ``display_name``/``name``,
+        ``email``/``userid`` and an optional ``uuid``.
+        """
+        self._require_session()
+        recipient_list = RecipientList(
+            recipient=[
+                Recipient(
+                    display_name=self._recipient_value(r, "display_name")
+                    or self._recipient_value(r, "name")
+                    or self._recipient_value(r, "userid"),
+                    email=self._recipient_value(r, "email")
+                    or self._recipient_value(r, "userid"),
+                    uuid=self._recipient_value(r, "uuid"),
+                    dist_type=DistributionType.TO,
+                    recip_type=RecipientType.USER,
+                )
+                for r in recipients
+            ]
+        )
+        request = SendItemRequest(
+            item=Mail(
+                subject=subject,
+                distribution=Distribution(recipients=recipient_list),
+                message=MessageBody(part=[MessagePart(value=body_text.encode("utf-8"))]),
+                return_sent_items_id=return_sent_items_id,
+            )
+        )
+        response = self.client.send_item(request, self._ctx)
+        self._raise_on_bad_status(response, "send_mail")
+        return response.id
+
+    # -- appointments ------------------------------------------------------
+
+    def create_appointment(self, subject: str, body: str, from_display_name: str,
+                           from_email: str, start: datetime, end: datetime,
+                           custom_field: str = "") -> None:
+        """Create an appointment in the connected user's calendar."""
+        apt = Appointment(
+            subject=subject,
+            distribution=Distribution(
+                from_value=From(display_name=from_display_name, email=from_email),
+                recipients=RecipientList(recipient=[
+                    Recipient(
+                        display_name=self.user_name,
+                        email=self.user_email,
+                        dist_type=DistributionType.TO,
+                        recip_type=RecipientType.USER,
+                    )
+                ]),
+            ),
+            message=self._text_message(body),
+            start_date=start,
+            end_date=end,
+            customs=CustomList(custom=[Custom(field="etermin", value=custom_field)])
+            if custom_field else None,
+        )
+        self._raise_on_bad_status(
+            self.client.create_item(CreateItemRequest(item=apt), self._ctx), "create_appointment"
+        )
+
+    def create_appointment_in_folder(self, folder_id: str, subject: str, body: str,
+                                     start: datetime, end: datetime) -> None:
+        """Create an appointment inside a specific (e.g. shared) folder."""
+        apt = Appointment(
+            subject=subject,
+            container=[ContainerRef(value=folder_id)],
+            message=self._text_message(body),
+            start_date=start,
+            end_date=end,
+        )
+        self._raise_on_bad_status(
+            self.client.create_item(CreateItemRequest(item=apt), self._ctx),
+            "create_appointment_in_folder",
+        )
+
+    def add_category(self, item_id: str, category_name: str) -> None:
+        """Tag an existing item with a category."""
+        updates = ItemChanges(add=Appointment(categories=CategoryRefList(category=[category_name])))
+        self._raise_on_bad_status(
+            self.client.modify_item(ModifyItemRequest(id=item_id, updates=updates), self._ctx),
+            "add_category",
+        )
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def logout(self) -> None:
+        """Log out and clear the session (safe to call when not logged in)."""
+        if self.client and self.session:
+            try:
+                self.client.logout(LogoutRequest(), self._ctx)
+            except SoapFaultException as e:
+                logger.warning("Logout failed: %s", e.fault_string)
+            finally:
+                self.session = None
+                self.login_resp = None
+
+    # -- helpers -----------------------------------------------------------
+
+    @property
+    def _ctx(self) -> RequestContext:
+        self._require_session()
+        return RequestContext(session_id=self.session)
+
+    def _require_session(self) -> None:
+        if not self.client or not self.session:
+            raise GWEasySoapError("Not logged in")
+
+    @staticmethod
+    def _text_message(body: str):
+        return MessageBody(part=[MessagePart(value=body.encode("utf-8"))]) if body else None
+
+    @staticmethod
+    def _recipient_value(recipient: RecipientLike, name: str):
+        if isinstance(recipient, Mapping):
+            return recipient.get(name)
+        return getattr(recipient, name, None)
+
+    @staticmethod
+    def _raise_on_bad_status(response, action: str) -> None:
+        status = getattr(response, "status", None)
+        if status and status.code not in (None, 0):
+            raise GWEasySoapError(
+                f"{action} failed: {status.description} (code {status.code})",
+                code=status.code,
+            )

gweasysoap-0.1.0/gweasysoap/exceptions.py

@@ -0,0 +1,6 @@
+class GWEasySoapError(Exception):
+    """Raised when a GroupWise SOAP request fails or returns a bad status."""
+
+    def __init__(self, message, code=None):
+        super().__init__(message)
+        self.code = code

gweasysoap-0.1.0/issues.txt

@@ -0,0 +1,28 @@
+ISSUES
+======
+
+1. Non-ASCII strings print as garbage on the Windows console
+----------------------------------------------------------------
+Symptom:
+    Running tests/07_address_book.py prints an address book entry as:
+        Gyn�kologie
+    instead of:
+        Gynäkologie
+
+Cause:
+    This is NOT a library bug. The data returned by gweasysoap is a correct
+    UTF-8 Python str. The problem is the default Windows console code page
+    (cp1252) used by print(); it cannot represent the 'ä' character and
+    substitutes the replacement glyph.
+
+Workaround:
+    Force UTF-8 output before printing, e.g. at the top of a script:
+        import sys
+        sys.stdout.reconfigure(encoding="utf-8")
+    or run Python with:
+        set PYTHONUTF8=1
+    or switch the console code page:
+        chcp 65001
+
+Status:
+    Open. Cosmetic only - affects console display, not the library data.

gweasysoap-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gweasysoap"
+version = "0.1.0"
+description = "A helper library for the GroupWise SOAP API (gwsoap)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["groupwise", "soap", "gwsoap", "novell", "micro focus"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Communications :: Email",
+]
+dependencies = ["gwsoap>=1.0.3"]
+
+[project.urls]
+Homepage = "https://github.com/rhulha/GWEasySoap"
+Documentation = "https://github.com/rhulha/GWEasySoap#readme"
+Repository = "https://github.com/rhulha/GWEasySoap"
+"Bug Reports" = "https://github.com/rhulha/GWEasySoap/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["gweasysoap"]

gweasysoap-0.1.0/tests/01_login_password.py

@@ -0,0 +1,8 @@
+"""1 - The simplest case: log in with a password and print who we are."""
+
+from gweasysoap import GWEasySoap
+from config import GW_SOAP_URL, GW_USER, GW_PASSWORD
+
+
+with GWEasySoap.connect(GW_SOAP_URL, GW_USER, GW_PASSWORD) as gw:
+    print(f"Logged in as: {gw.user_name} <{gw.user_email}>")

gweasysoap-0.1.0/tests/02_login_trusted_app.py

@@ -0,0 +1,15 @@
+"""2 - Log in on behalf of a user with a trusted application key (no password)."""
+
+from gweasysoap import GWEasySoap
+from config import GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+
+
+with GWEasySoap.connect_trusted_app(
+    GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+) as gw:
+    info = gw.whoami()
+    print("User info:")
+    for attr in ("display_name", "name", "email"):
+        value = getattr(info, attr, None)
+        if value:
+            print(f"  {attr}: {value}")

gweasysoap-0.1.0/tests/03_user_list.py

@@ -0,0 +1,12 @@
+"""3 - List the post office mailboxes (uses the trusted-app key, no session)."""
+
+from gweasysoap import GWEasySoap
+from config import GW_SOAP_URL, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+
+
+gw = GWEasySoap()
+mailboxes = gw.get_user_mailboxes(GW_SOAP_URL, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY)
+
+print(f"Found {len(mailboxes)} mailbox(es):")
+for mb in mailboxes:
+    print(f"  {mb['display_name']} <{mb['email']}>  (userid={mb['userid']})")

gweasysoap-0.1.0/tests/04_login_any_user.py

@@ -0,0 +1,10 @@
+"""4 - Log in as the first usable mailbox on the post office."""
+
+from gweasysoap import GWEasySoap
+from config import GW_SOAP_URL, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+
+
+with GWEasySoap.connect_any_user(
+    GW_SOAP_URL, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+) as gw:
+    print(f"Logged in as: {gw.user_name} <{gw.user_email}>")

gweasysoap-0.1.0/tests/05_mailbox_items.py

@@ -0,0 +1,18 @@
+"""5 - Open the mailbox folder and list the items inside it."""
+
+from gweasysoap import GWEasySoap
+from config import GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+
+
+with GWEasySoap.connect_trusted_app(
+    GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+) as gw:
+    mailbox = gw.get_mailbox()
+    if mailbox is None:
+        raise SystemExit("Mailbox not found")
+
+    print(f"Mailbox: {mailbox.name} (id={mailbox.id})")
+    items = gw.get_folder_items(mailbox.id, count=20)
+    print(f"{len(items)} item(s):")
+    for item in items:
+        print(f"  {getattr(item, 'subject', None) or item.name}")

gweasysoap-0.1.0/tests/06_calendar.py

@@ -0,0 +1,14 @@
+"""6 - List the appointments in the calendar."""
+
+from gweasysoap import GWEasySoap
+from config import GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+
+
+with GWEasySoap.connect_trusted_app(
+    GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+) as gw:
+    items = gw.get_calendar_items(count=50)
+    print(f"{len(items)} calendar item(s):")
+    for item in items:
+        start = getattr(item, "start_date", None)
+        print(f"  {start}  {item.subject}")

gweasysoap-0.1.0/tests/07_address_book.py

@@ -0,0 +1,16 @@
+"""7 - Read the system address book and list its entries."""
+
+from gweasysoap import GWEasySoap
+from config import GW_SOAP_URL, GW_USER, GW_PASSWORD
+
+
+with GWEasySoap.connect(GW_SOAP_URL, GW_USER, GW_PASSWORD) as gw:
+    book = gw.get_system_address_book()
+    if book is None:
+        raise SystemExit("System address book not found")
+
+    print(f"Address book: {book.name}")
+    entries = gw.get_address_book_entries(book)
+    print(f"{len(entries)} entry/entries:")
+    for entry in entries:
+        print(f"  {entry.name}")

gweasysoap-0.1.0/tests/08_filter_items.py

@@ -0,0 +1,17 @@
+"""8 - Use a server-side filter: find items whose subject begins with "P"."""
+
+from gweasysoap import GWEasySoap
+from config import GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+from gwsoap.types.Filter import Filter
+from gwsoap.types.FilterEntry import FilterEntry
+from gwsoap.types.FilterOp import FilterOp
+
+
+with GWEasySoap.connect_trusted_app(
+    GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+) as gw:
+    f = Filter(element=FilterEntry(op=FilterOp.BEGINS, field="subject", value="P"))
+    items = gw.get_items(None, filter=f, count=10)
+    print(f"{len(items)} match(es):")
+    for item in items:
+        print(f"  {item.subject}")

gweasysoap-0.1.0/tests/09_read_body.py

@@ -0,0 +1,18 @@
+"""9 - Drill into a single mailbox item and fetch its decoded body text."""
+
+from gweasysoap import GWEasySoap
+from config import GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+
+
+with GWEasySoap.connect_trusted_app(
+    GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+) as gw:
+    mailbox = gw.get_mailbox()
+    items = gw.get_folder_items(mailbox.id, count=5) if mailbox else []
+    if not items:
+        raise SystemExit("Mailbox is empty - nothing to read")
+
+    first = items[0]
+    print(f"Subject: {getattr(first, 'subject', None)}")
+    print("Body:")
+    print(gw.get_body(first) or "  (no text body)")

gweasysoap-0.1.0/tests/10_send_mail.py

@@ -0,0 +1,16 @@
+"""10 - Send a plain-text mail to the connected user (a safe self-send)."""
+
+from gweasysoap import GWEasySoap
+from config import GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+
+
+with GWEasySoap.connect_trusted_app(
+    GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+) as gw:
+    recipient = {"display_name": gw.user_name, "email": gw.user_email}
+    ids = gw.send_mail(
+        subject="Hello from gweasysoap",
+        body_text="This message was sent by the gweasysoap test suite.",
+        recipients=[recipient],
+    )
+    print("Sent mail; sent-items id(s):", ids or "(none returned)")

gweasysoap-0.1.0/tests/11_create_appointment.py

@@ -0,0 +1,27 @@
+"""11 - The hardest case: create a one-hour appointment in the calendar."""
+
+from datetime import datetime, timedelta
+
+from gweasysoap import GWEasySoap
+from config import GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+
+
+with GWEasySoap.connect_trusted_app(
+    GW_SOAP_URL, GW_USER, GW_TRUSTED_APP_NAME, GW_TRUSTED_APP_KEY
+) as gw:
+    start = datetime.now().replace(minute=0, second=0, microsecond=0) + timedelta(days=1)
+    end = start + timedelta(hours=1)
+
+    gw.create_appointment(
+        subject="gweasysoap test appointment",
+        body="Created by the gweasysoap test suite.",
+        from_display_name=gw.user_name,
+        from_email=gw.user_email,
+        start=start,
+        end=end,
+    )
+    print(f"Created appointment {start:%Y-%m-%d %H:%M} - {end:%H:%M}")
+
+    print("Calendar now contains:")
+    for item in gw.get_calendar_items(count=50):
+        print(f"  {getattr(item, 'start_date', None)}  {item.subject}")

gweasysoap-0.1.0/tests/README.md

@@ -0,0 +1,40 @@
+# gweasysoap test scripts
+
+Manual, runnable scripts that exercise the library against a live GroupWise post
+office. They are ordered from the simplest task to the hardest.
+
+## Setup
+
+1. Install the package (from the project root):
+
+   ```bash
+   pip install -e .
+   ```
+
+2. Edit [config.py](config.py) so the URL, user and trusted-app key point at a
+   reachable POA.
+
+3. Run a script from inside this folder (so `config.py` is importable):
+
+   ```bash
+   cd tests
+   python 01_login_password.py
+   ```
+
+## The scripts
+
+| # | Script | What it shows |
+|---|--------|---------------|
+| 01 | `01_login_password.py` | Log in with a password, print the connected user |
+| 02 | `02_login_trusted_app.py` | Trusted-application login (no password) |
+| 03 | `03_user_list.py` | List the post office mailboxes (no session) |
+| 04 | `04_login_any_user.py` | Log in as the first usable mailbox |
+| 05 | `05_mailbox_items.py` | Open the mailbox folder and list its items |
+| 06 | `06_calendar.py` | List calendar appointments |
+| 07 | `07_address_book.py` | Read the system address book |
+| 08 | `08_filter_items.py` | Server-side filter (subject begins with "P") |
+| 09 | `09_read_body.py` | Fetch and decode a single item's body |
+| 10 | `10_send_mail.py` | **Sends** a mail (self-send) |
+| 11 | `11_create_appointment.py` | **Creates** a calendar appointment |
+
+Scripts 10 and 11 modify the mailbox; run them only against a test account.

gweasysoap-0.1.0/tests/config.py

@@ -0,0 +1,10 @@
+"""Connection settings for the test scripts.
+
+Point these at a reachable GroupWise post office agent (POA) before running.
+"""
+
+GW_SOAP_URL = "http://172.30.15.95:7191/soap"
+GW_USER = "testgw1"
+GW_PASSWORD = "novell"
+GW_TRUSTED_APP_NAME = "MyTapp"
+GW_TRUSTED_APP_KEY = "E879BF5111D1123486257DE8AD4B4FF9E879BF5211D10000AB9FA533175F62F2"