Add an examples folder

[zarch]

Hi all,

I was thinking that perhaps it would be nice to have a folder examples/ in the repository similar to what exists in the paho project.

I was interested in understanding how to set and use the encryption for the mqtt connections.
Therefore, I freely translate the examples/client_sub_opts into the following code:

#!/usr/bin/python3
from __future__ import annotations

import argparse
import asyncio
import logging
import ssl
from typing import Any

import aiomqtt

logger = logging.getLogger(__name__)

TLS_PROTOCOLS = {
    "tlsv1": ssl.PROTOCOL_TLSv1,
    "tlsv1.1": ssl.PROTOCOL_TLSv1_1,
    "tlsv1.2": ssl.PROTOCOL_TLSv1_2,
}


def get_parser() -> argparse.ArgumentParser:
    """Return an ArgumentParser instance that define CLI interface."""
    parser = argparse.ArgumentParser()

    parser.add_argument(
        "-H", "--host", required=False, default="mqtt.eclipseprojects.io",
    )
    parser.add_argument("-t", "--topic", required=False, default="$SYS/#")
    parser.add_argument("-q", "--qos", required=False, type=int, default=0)
    parser.add_argument("-c", "--clientid", required=False, default=None)
    parser.add_argument("-u", "--username", required=False, default=None)
    parser.add_argument(
        "-d",
        "--disable-clean-session",
        action="store_true",
        help="disable 'clean session' (sub + msgs not cleared when client disconnects)",
    )
    parser.add_argument("-p", "--password", required=False, default=None)
    parser.add_argument(
        "-P",
        "--port",
        required=False,
        type=int,
        default=None,
        help="Defaults to 8883 for TLS or 1883 for non-TLS",
    )
    parser.add_argument("-k", "--keepalive", required=False, type=int, default=60)
    parser.add_argument("-s", "--use-tls", action="store_true")
    parser.add_argument("--insecure", action="store_true", default=False)
    parser.add_argument("-A", "--ca-certs", required=False, default=None)
    parser.add_argument("-C", "--certfile", required=False, default=None)
    parser.add_argument("-K", "--keyfile", required=False, default=None)
    parser.add_argument(
        "--tls-version",
        required=False,
        default=None,
        help="TLS protocol version, can be one of tlsv1.2 tlsv1.1 or tlsv1\n",
    )
    parser.add_argument("-D", "--debug", action="store_true")
    return parser


def get_client_params(args: argparse.Namespace) -> dict[str, Any]:
    """Parse, validate and convert arguments to client parameters."""
    usetls = True if args.ca_certs else args.use_tls

    port = args.port
    if port is None:
        port = 8883 if usetls else 1883

    tls_params = None
    if usetls:
        tls_params = aiomqtt.client.TLSParameters(
            ca_certs=args.ca_certs,
            certfile=args.certfile,
            keyfile=args.keyfile,
            cert_reqs=ssl.CERT_REQUIRED if not args.insecure else ssl.CERT_NONE,
            tls_version=TLS_PROTOCOLS.get(args.tls_version, None),
            ciphers=None,
            keyfile_password=None,
        )

    return {
        "hostname": args.host,
        "port": port,
        "username": args.username,
        "password": args.password,
        "logger": logger,
        "identifier": "aiomqtt-tls-client-sub",
        # queue_type
        # protocol
        # will
        "clean_session": not args.disable_clean_session,
        # transport
        "timeout": 10,
        "keepalive": 60,
        # bind_address
        # bind_port
        # clean_start
        # max_queued_incoming_messages
        # max_queued_outgoing_messages
        # max_inflight_messages
        # max_concurrent_outgoing_calls
        # properties
        # tls_context
        "tls_params": tls_params,
        "tls_insecure": args.insecure,
        # proxy
        # socket_options
        # websocket_path
        # websocket_headers
    }


async def main() -> None:
    """Subscribe to a topic."""
    parser = get_parser()
    args, _ = parser.parse_known_args()
    logger.debug(f"Arguments: {args}")
    params = get_client_params(args)
    logger.debug(f"AioMqtt parameters: {params}")
    async with aiomqtt.Client(**params) as client:
        await client.subscribe(args.topic)
        async for msg in client.messages:
            print(f"{msg.topic} | {msg.payload}")


if __name__ == "__main__":
    """
    Example of use:

        python __aiomqtt.py \
            --host=$MQTT_HOST \
            --port=$MQTT_PORT \
            --username="$MQTT_VHOST:$MQTT_USER" \
            --clientid="aiomqtt-client" \
            --password=$MQTT_PASSWORD \
            --keepalive=60 \
            --use-tls \
            --ca-certs=$MQTT_CERTIFICATE_AUTHORITY \
            --certfile=$MQTT_CLIENT_CERTIFICATE \
            --keyfile=$MQTT_PRIVATE_KEY \
            --debug \
            --topic="$MQTT_TOPIC/#"
    """
    asyncio.run(main())

Do you think it might be useful for the project?
If yes, I'm available to open a PR and start contributing and discussing on the code structure, parameters that must be available, etc. If not, it is perfectly fine, but I think it would be nice to share a working example of an encrypted MQTT connection. :-D