myl-discovery 0.5.2__py3-none-any.whl → 0.5.4__py3-none-any.whl

{myl_discovery-0.5.2.dist-info → myl_discovery-0.5.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: myl-discovery
-Version: 0.5.2
+Version: 0.5.4
 Summary: email autodiscovery
 Author-email: Philipp Schmitt <philipp@schmitt.co>
 License: GNU GENERAL PUBLIC LICENSE
@@ -689,130 +689,92 @@ Requires-Dist: requests (==2.31.0)
 Requires-Dist: rich (==13.4.2)
 Requires-Dist: xmltodict (==0.13.0)
 
-# myl-discovery
+# 📩 myl-discovery
 
-Email autoconfig library
+myl-discovery is a Python library designed to detect email settings of a given 
+email address or domain.
 
-## Installation
+## 📥 Installation
 
-```shell
+To install myl-discovery, run the following command:
+
+```bash
 pip install myl-discovery
 ```
 
-## Usage
+## 📖 Usage
+
+After installing the package, you can use the `autodiscover` function to 
+discover the email settings for a domain. Here's an example:
 
 ```python
 from myldiscovery import autodiscover
-autodiscover("me@example.com")
-# {'imap': {'server': 'mail.example.com', 'port': 993, 'starttls': False},
-#  'smtp': {'server': 'mail.example.com', 'port': 587, 'starttls': False}}
-```
-
 
-## Development
+settings = autodiscover("yourdomain.com")  # or me@yourdomain.com
+print(settings)
 
-### Autodiscovery
-
-#### autoconfig
-
-```shell
-curl -L https://mail.example.com/mail/config-v1.1.xml
+# For Exchange autodiscovery you need to provide credentials
+settings = autodiscover(
+    'me@yourdomain.com', 
+    username='WORKGROUP\me', 
+    password='mypassword1234'
+)
 ```
 
-Response:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<clientConfig version="1.1">
-	<emailProvider id="example.com">
-	    <domain>example.com</domain>
+## 📄 Output
 
-	    <displayName>example.com Email</displayName>
-	    <displayShortName>%EMAILLOCALPART%</displayShortName>
-	    <incomingServer type="imap">
-			<hostname>mail.example.com</hostname>
-			<port>143</port>
-			<socketType>STARTTLS</socketType>
-			<authentication>password-cleartext</authentication>
-			<username>%EMAILADDRESS%</username>
-		</incomingServer>
-	    <outgoingServer type="smtp">
-			<hostname>mail.example.com</hostname>
-			<port>587</port>
-			<socketType>STARTTLS</socketType>
-			<authentication>password-cleartext</authentication>
-			<username>%EMAILADDRESS%</username>
-	    </outgoingServer>
-		<documentation url="https://autodiscover.example.com">
-			<descr lang="en">Generic settings page</descr>
-			<descr lang="fr">Paramètres généraux</descr>
-			<descr lang="es">Configuraciones genéricas</descr>
-			<descr lang="de">Allgemeine Beschreibung der Einstellungen</descr>
-			<descr lang="ru">Страница общих настроек</descr>
-		</documentation>
-	</emailProvider>
-</clientConfig>
-```
+The `autodiscover` function returns a dictionary with the detected settings. 
+The dictionary contains two keys, `imap` and `smtp`, each containing a 
+dictionary with the keys `server`, `port`, and `starttls`. 
 
-### autodiscover
+Here's an example:
 
-```shell
-curl -L mail.example.com/autodiscover/autodiscover.xml
+```json
+{
+  "imap": {
+    "server": "imap.yourdomain.com",
+    "port": 993,
+    "starttls": false
+  },
+  "smtp": {
+    "server": "smtp.yourdomain.com",
+    "port": 587,
+    "starttls": true
+  }
+}
 ```
 
-Response:
-
-```xml
-<?xml version="1.0" encoding="utf-8" ?>
-<Autodiscover xmlns="http://schemas.microsoft.com/exchange/autodiscover/responseschema/2006">
-        <Response xmlns="http://schemas.microsoft.com/exchange/autodiscover/responseschema/2006">
-                <User>
-                        <DisplayName>example.com Email</DisplayName>
-                </User>
-                <Account>
-                        <AccountType>email</AccountType>
-                        <Action>settings</Action>
-                        <ServiceHome>https://autodiscover.example.com</ServiceHome>
-
-                        <Protocol>
-                                <Type>IMAP</Type>
-                                <TTL>1</TTL>
-
-                                <Server>mail.example.com</Server>
-                                <Port>143</Port>
+## 🧩 Autodiscover Functions
 
-                                <LoginName></LoginName>
+myl-discovery exposes several functions to discover email settings:
 
-                                <DomainRequired>on</DomainRequired>
-                                <DomainName>example.com</DomainName>
+- `autodiscover`: This function wraps the below function do automatically detect
+the right settings. (See Autodiscover strategy for more information)
+- `autodiscover_srv`: This function attempts to resolve SRV records for 
+the domain to discover IMAP and SMTP servers.
+- `autodiscover_exchange`: This function attempts to use the Exchange 
+Autodiscover service to discover email settings. It requires a username and 
+password.
+- `autodiscover_autoconfig`: This function attempts to fetch and parse an 
+autoconfig XML file from a URL specified in the domain's TXT records.
+- `autodiscover_port_scan`: This function performs a port scan on the domain 
+to discover open IMAP and SMTP ports.
 
-                                <SPA>off</SPA>
-                                <Encryption>TLS</Encryption>
-                                <AuthRequired>on</AuthRequired>
-                        </Protocol>
-                </Account>
-                <Account>
-                        <AccountType>email</AccountType>
-                        <Action>settings</Action>
-                        <ServiceHome>https://autodiscover.example.com</ServiceHome>
+## 🧠 Autodiscover Strategy
 
-                        <Protocol>
-                                <Type>SMTP</Type>
-                                <TTL>1</TTL>
+The `autodiscover` function uses the following strategy to discover 
+email settings:
 
-                                <Server>mail.example.com</Server>
-                                <Port>587</Port>
+1. It first attempts to use `autodiscover_autoconfig` to discover settings 
+from an autoconfig/autodiscover URL specified in the domain's TXT records.
+2. If that fails, it attempts to use `autodiscover_srv` to discover settings 
+from the domain's SRV records.
+3. If that fails and a password is provided, it attempts to use 
+`autodiscover_exchange` to discover settings using the 
+Exchange Autodiscover service (only if credentials were provided)
+4. If all else fails, it uses `autodiscover_port_scan` to discover settings by 
+performing a port scan on the domain.
 
-                                <LoginName></LoginName>
-
-                                <DomainRequired>on</DomainRequired>
-                                <DomainName>example.com</DomainName>
-
-                                <SPA>off</SPA>
-                                <Encryption>TLS</Encryption>
-                                <AuthRequired>on</AuthRequired>
-                        </Protocol>
-                </Account></Response>
-</Autodiscover>
-```
+## 📜 License
 
+myl-discovery is licensed under the [GNU General Public License v3.0](LICENSE).

myl_discovery-0.5.4.dist-info/RECORD

@@ -0,0 +1,10 @@
+myldiscovery/__init__.py,sha256=L_XVC06ZVdjhnV5up1MBnywTuGUIyjt8PUoQDUOzfAk,381
+myldiscovery/__main__.py,sha256=5BjNuyet8AY-POwoF5rGt722rHQ7tJ0Vf0UFUfzzi-I,58
+myldiscovery/discovery.py,sha256=YnEJ54CdwaA6PluMSC0ba7uGhoM__-ejtPTCawa9cto,7358
+myldiscovery/main.py,sha256=dBvJULlnULiJOCtios2hF1A2lNu6EWMKpTSjC9fs2Ss,2016
+myl_discovery-0.5.4.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+myl_discovery-0.5.4.dist-info/METADATA,sha256=Bj7FHNAlBwBWSDj3JF6-enWBXe-dpzbszClTWe9n7tk,43775
+myl_discovery-0.5.4.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
+myl_discovery-0.5.4.dist-info/entry_points.txt,sha256=nyyAyvgvu6iO9mPEA6uVrPfd0lIrUyo9AQWeH2asEY0,52
+myl_discovery-0.5.4.dist-info/top_level.txt,sha256=v_h72JexaacqBNY6iOMD9PpGg8lnGoL-pkmUIzxdiVU,13
+myl_discovery-0.5.4.dist-info/RECORD,,

myldiscovery/__init__.py

@@ -1,4 +1,19 @@
-from .discovery import autodiscover, autodiscover_exchange
+from .discovery import (
+    autodiscover,
+    autodiscover_autoconfig,
+    autodiscover_exchange,
+    autodiscover_port_scan,
+    autodiscover_srv,
+    autodiscover_txt,
+)
 from .main import main
 
-__all__ = ["main", "autodiscover", "autodiscover_exchange"]
+__all__ = [
+    "main",
+    "autodiscover",
+    "autodiscover_autoconfig",
+    "autodiscover_exchange",
+    "autodiscover_port_scan",
+    "autodiscover_srv",
+    "autodiscover_txt",
+]

myldiscovery/discovery.py

@@ -66,10 +66,13 @@ def resolve_srv(domain):
 
 
 def autodiscover_txt(domain):
-    res = resolve_txt(domain, criteria="^mailconf=")
-    if not res:
-        return
-    return res.split("=")[1]
+    try:
+        res = resolve_txt(domain, criteria="^mailconf=")
+        if not res:
+            return
+        return res.split("=")[1]
+    except Exception:
+        LOGGER.warning("Failed to resolve TXT record")
 
 
 def parse_autoconfig(content):
@@ -147,29 +150,35 @@ def parse_autodiscover(content):
 
 
 def autodiscover_srv(domain):
-    imap = resolve_srv(f"_imaps._tcp.{domain}")
-    smtp = resolve_srv(f"_submission._tcp.{domain}")
-
-    return {
-        "imap": {
-            "server": imap[0].get("hostname"),
-            "port": int(imap[0].get("port")),
-            # FIXME We might want to "smartly" guess if starttls should be
-            # enabled or not, depending on the port:
-            # 143 -> starttls
-            # 993 -> no
-            "starttls": False,
-        },
-        "smtp": {
-            "server": smtp[0].get("hostname"),
-            "port": int(smtp[0].get("port")),
-            # FIXME We might want to "smartly" guess if starttls should be
-            # enabled or not, depending on the port:
-            # 465 -> starttls
-            # 587 -> no
-            "starttls": False,
-        },
-    }
+    try:
+        imap = resolve_srv(f"_imaps._tcp.{domain}")
+        smtp = resolve_srv(f"_submission._tcp.{domain}")
+
+        assert imap is not None
+        assert smtp is not None
+
+        return {
+            "imap": {
+                "server": imap[0].get("hostname"),
+                "port": int(imap[0].get("port")),
+                # FIXME We might want to "smartly" guess if starttls should be
+                # enabled or not, depending on the port:
+                # 143 -> starttls
+                # 993 -> no
+                "starttls": False,
+            },
+            "smtp": {
+                "server": smtp[0].get("hostname"),
+                "port": int(smtp[0].get("port")),
+                # FIXME We might want to "smartly" guess if starttls should be
+                # enabled or not, depending on the port:
+                # 465 -> starttls
+                # 587 -> no
+                "starttls": False,
+            },
+        }
+    except Exception as e:
+        LOGGER.warning(f"Failed to resolve SRV records: {e}")
 
 
 def port_check(host, port):
@@ -187,14 +196,19 @@ def check_email_ports(host):
 
 
 def autodiscover_exchange(email, password, username=None):
-    if not username:
-        username = email
-    creds = Credentials(username=username, password=password)
-    account = Account(
-        primary_smtp_address=email, credentials=creds, autodiscover=True
-    )
-    server = account.protocol.server
-
+    try:
+        if not username:
+            username = email
+        creds = Credentials(username=username, password=password)
+        account = Account(
+            primary_smtp_address=email, credentials=creds, autodiscover=True
+        )
+        return autodiscover_port_scan(account.protocol.server)
+    except Exception as e:
+        LOGGER.warning(f"Failed to autodiscover Exchange: {e}")
+
+
+def autodiscover_port_scan(server):
     portscan = check_email_ports(server)
     LOGGER.info(f"Port scan results: {portscan}")
 
@@ -228,27 +242,12 @@ def autodiscover_exchange(email, password, username=None):
     }
 
 
-def autodiscover(email_addr, srv_only=False, username=None, password=None):
-    domain = email_addr.split("@")[-1]
-    if not domain:
-        raise ValueError(f"Invalid email address {email_addr}")
-
-    if srv_only:
-        return autodiscover_srv(domain)
-
+def autodiscover_autoconfig(domain):
     autoconfig = autodiscover_txt(domain)
 
     if not autoconfig:
-        try:
-            return autodiscover_srv(domain)
-        except Exception:
-            LOGGER.warning("Failed to autodiscover using SRV records")
-            if password:
-                LOGGER.info("Trying autodiscover using Exchange credentials")
-                return autodiscover_exchange(
-                    email=email_addr, username=username, password=password
-                )
-            return
+        LOGGER.warning("Failed to autodiscover using TXT records")
+        return
 
     res = requests.get(autoconfig)
     res.raise_for_status()
@@ -258,3 +257,25 @@ def autodiscover(email_addr, srv_only=False, username=None, password=None):
     except Exception:
         LOGGER.warning("Failed to parse autoconfig, trying autodiscover")
         return parse_autodiscover(res.text)
+
+
+def autodiscover(email_addr, username=None, password=None):
+    domain = email_addr.split("@")[-1]
+    if not domain:
+        raise ValueError(f"Invalid email address {email_addr}")
+
+    res = autodiscover_autoconfig(domain)
+
+    if not res:
+        res = autodiscover_srv(domain)
+
+    if not res and password:
+        res = autodiscover_srv(domain)
+        autodiscover_exchange(
+            email=email_addr, username=username, password=password
+        )
+
+    if not res:
+        res = autodiscover_port_scan(domain)
+
+    return res

myl_discovery-0.5.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-myldiscovery/__init__.py,sha256=uYjN41LLdBJtkSU1JOn_Ryi6jxiN0D99WPVrhIvQt-Q,143
-myldiscovery/__main__.py,sha256=5BjNuyet8AY-POwoF5rGt722rHQ7tJ0Vf0UFUfzzi-I,58
-myldiscovery/discovery.py,sha256=wuV_9-Hmomt-g_iIJ2mqecR1gYXsbabgklcZSdNO820,6833
-myldiscovery/main.py,sha256=dBvJULlnULiJOCtios2hF1A2lNu6EWMKpTSjC9fs2Ss,2016
-myl_discovery-0.5.2.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-myl_discovery-0.5.2.dist-info/METADATA,sha256=LlbCj0P2mWvjqUx73LtYl9o-k5aHtEROeU6bhyMKDSk,44965
-myl_discovery-0.5.2.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
-myl_discovery-0.5.2.dist-info/entry_points.txt,sha256=nyyAyvgvu6iO9mPEA6uVrPfd0lIrUyo9AQWeH2asEY0,52
-myl_discovery-0.5.2.dist-info/top_level.txt,sha256=v_h72JexaacqBNY6iOMD9PpGg8lnGoL-pkmUIzxdiVU,13
-myl_discovery-0.5.2.dist-info/RECORD,,