Merge remote-tracking branch 'origin/master' into registered-domain-semantics

Author: john-kurkowski

tldextract/tldextract.py

@@ -109,7 +109,7 @@ class ExtractResult:
 
     @property
     def fqdn(self) -> str:
-        """Returns a Fully Qualified Domain Name (FQDN), if there is a proper `domain` and `suffix`, or else the empty string.
+        """The Fully Qualified Domain Name (FQDN), if there is a proper `domain` and `suffix`, or else the empty string.
 
         >>> extract("http://forums.bbc.co.uk/path/to/file").fqdn
         'forums.bbc.co.uk'
@@ -122,7 +122,7 @@ def fqdn(self) -> str:
 
     @property
     def ipv4(self) -> str:
-        """Returns the IPv4, if that is what the input domain/URL was, or else the empty string.
+        """The IPv4 address, if that is what the input domain/URL was, or else the empty string.
 
         >>> extract("http://127.0.0.1/path/to/file").ipv4
         '127.0.0.1'
@@ -141,7 +141,7 @@ def ipv4(self) -> str:
 
     @property
     def ipv6(self) -> str:
-        """Returns the IPv6, if that is what the input domain/URL was, or else the empty string.
+        """The IPv6 address, if that is what the input domain/URL was, or else the empty string.
 
         >>> extract(
         ...     "http://[aBcD:ef01:2345:6789:aBcD:ef01:127.0.0.1]/path/to/file"
@@ -168,7 +168,7 @@ def ipv6(self) -> str:
 
     @property
     def registered_domain(self) -> str:
-        """Joins the `domain` and `suffix` fields with a dot, if they're both set, or else the empty string.
+        """The `domain` and `suffix` fields joined with a dot, if they're both set, or else the empty string.
 
         >>> extract("http://forums.bbc.co.uk").registered_domain
         'bbc.co.uk'
@@ -207,11 +207,17 @@ def registered_domain(self) -> str:
 
     @property
     def reverse_domain_name(self) -> str:
-        """Return the Reverse Domain Name Notation.
+        """The domain name in Reverse Domain Name Notation.
 
-        Applies a reverse domain name notation to the submitted domain, in which the
-        registered domain is used as the leftmost component. Reverse Domain Name
-        Notation is typically used to organize namespaces for packages and plugins.
+        Joins extracted components of the input URL in reverse domain name
+        notation. The suffix is used as the leftmost component, followed by the
+        domain, then followed by the subdomain with its parts reversed.
+
+        Reverse Domain Name Notation is typically used to organize namespaces
+        for packages and plugins. Technically, a full reversal would reverse
+        the parts of the suffix, e.g. "co.uk" would become "uk.co", but this is
+        not done in practice when Reverse Domain Name Notation is called for.
+        So this property leaves the `suffix` part in its original order.
 
         >>> extract("login.example.com").reverse_domain_name
         'com.example.login'
@@ -226,7 +232,7 @@ def reverse_domain_name(self) -> str:
 
     @property
     def top_domain_under_registry_suffix(self) -> str:
-        """Joins the rightmost domain and `registry_suffix` with a dot, if such a domain is available and `registry_suffix` is set, or else the empty string.
+        """The rightmost domain and `registry_suffix` joined with a dot, if such a domain is available and `registry_suffix` is set, or else the empty string.
 
         If the input was not in the Public Suffix List's private domains, this
         is equivalent to `top_domain_under_public_suffix`.
@@ -251,7 +257,7 @@ def top_domain_under_registry_suffix(self) -> str:
 
     @property
     def top_domain_under_public_suffix(self) -> str:
-        """Joins the `domain` and `suffix` fields with a dot, if they're both set, or else the empty string.
+        """The `domain` and `suffix` fields joined with a dot, if they're both set, or else the empty string.
 
         >>> extract("http://forums.bbc.co.uk").top_domain_under_public_suffix
         'bbc.co.uk'
@@ -490,9 +496,9 @@ def update(
 
     @property
     def tlds(self, session: requests.Session | None = None) -> list[str]:
-        """Returns the list of tld's used by default.
+        """The list of TLDs used by default.
 
-        This will vary based on `include_psl_private_domains` and `extra_suffixes`
+        This will vary based on `include_psl_private_domains` and `extra_suffixes`.
         """
         return list(self._get_tld_extractor(session=session).tlds())