Metadata-Version: 2.2
Name: sympasoap
Version: 1.1.3
Summary: A simple Python Sympa API
Home-page: https://gitlab.com/animath/si/py-sympa-soap
Author: Emmy D'Anello
Author-email: emmy.danello@animath.fr
License: GPLv3
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: zeep<5.0,>=3.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

=========================
Python Sympa SOAP Wrapper
=========================

Small wrapper that uses `ZEEP <https://pypi.org/project/zeep/>`_ to communicate with a SOAP endpoint linked to a Sympa
server, to let automation in lists creation.

Example
=======

Start by creating a new client, and log in.
Then, you can use some pre-constructed methods.

.. code-block:: python

    from sympasoap import Client

    client = Client("https://lists.example.com/sympa")
    client.login("admin@example.com", "MY_STRONG_PASSWORD")     # Get from env

    # Create a list of type hotline that is named automatically-created@lists.example.com with basic description
    client.create_list(list_name="automatically-created", subject="Automatically created list", template="hotline",
            description="This mailing list was created from a Python shell.", topic="computers/software")

    # Subscribe the email address toto@example.com with name "Toto TOTO" to the list automatically-created@lists.example.com
    # in non-quiet mode: the user will receive a notification that they got subscribed
    client.subscribe(email="toto@example.com", list_address="automatically-created", quiet=False, name="Toto TOTO")

    # Unsubscribe the email in quiet mode
    client.subscribe(email="toto@example.com", list_address="automatically-created", quiet=True)


Available functions
===================

.. code-block:: python

    def login(self, email: str, password: str) -> None:
        """
        Login into the API. Set a cookie for future connexions.
        """

    def check_cookie(self) -> str:
        """
        From the current stored cookie, retrieve the email address.
        """

    def is_subscriber(self, email: str, mailing_list: str, function: str = "subscriber") -> bool:
        """
        Check if the given `email` is a member of type `function` in the `mailing_list`.
        The function parameter is one between subscriber, editor or owner.
        """

    def get_subscribers(self, mailing_list: str, emails_only: bool = True) -> list:
        """
        Get the list of all subscribers of a list, including the administrators and the editors.
        If emails_only == True, retrieve the list of email addresses only.
        Else, retrieve MLUser object, with the name of the user and the role.
        """

    def lists(self, topic: str, subtopic: str) -> list:
        """
        Get all the (visible) lists that match the given topic and the given subtopic.
        See TOPICS and SUBTOPICS for valid topics and subtopics.
        """

    def all_lists(self) -> list:
        """
        Retrieve all lists.
        """

    def create_list(self, list_name: str, subject: str, template: str, description: str, topic: str,
                    use_custom_template: bool = False, raise_error: bool = True) -> bool:
        """
        Create a new mailing-list.
        """

    def delete_list(self, list_name: str, raise_error: bool = False) -> bool:
        """
        Close a mailing list.
        Warning: the list is not deleted in order to keep the history. Please use the web interface to fully
        delete the list.
        Well, the main reason is that the API does not provide a delete method.
        """

    def subscribe(self, email: str, list_address: str, quiet: bool, name: str = "", raise_error: bool = False) -> bool:
        """
        Subscribe the user with the given email to the given mailing list.
        If the quiet mode is enabled, the user won't receive a notification that they got subscribed.
        """

    def unsubscribe(self, email: str, list_address: str, quiet: bool, raise_error: bool = False) -> bool:
        """
        Subscribe the user with the given email to the given mailing list.
        If the quiet mode is enabled, the user won't receive a notification that they got subscribed.
        """

