Format Markdown and Python code in docs

README.md

@@ -8,7 +8,7 @@ this wrong.* Splitting on the "." and taking the 2nd-to-last element only works
 for simple domains, e.g. .com. Consider
 [http://forums.bbc.co.uk](http://forums.bbc.co.uk): the naive splitting method
 will give you "co" as the domain, instead of "bbc". Rather than juggle TLDs,
-gTLDs, or ccTLDs  yourself, `tldextract` extracts the currently living public
+gTLDs, or ccTLDs yourself, `tldextract` extracts the currently living public
 suffixes according to [the Public Suffix List](https://publicsuffix.org).
 
 > A "public suffix" is one under which Internet users can directly register
@@ -19,40 +19,40 @@ A public suffix is also sometimes called an effective TLD (eTLD).
 ## Usage
 
 ```python
->>> import tldextract
+import tldextract
 
->>> tldextract.extract('http://forums.news.cnn.com/')
-ExtractResult(subdomain='forums.news', domain='cnn', suffix='com', is_private=False)
+tldextract.extract("http://forums.news.cnn.com/")
+# ExtractResult(subdomain='forums.news', domain='cnn', suffix='com', is_private=False)
 
->>> tldextract.extract('http://forums.bbc.co.uk/') # United Kingdom
-ExtractResult(subdomain='forums', domain='bbc', suffix='co.uk', is_private=False)
+tldextract.extract("http://forums.bbc.co.uk/")  # United Kingdom
+# ExtractResult(subdomain='forums', domain='bbc', suffix='co.uk', is_private=False)
 
->>> tldextract.extract('http://www.worldbank.org.kg/') # Kyrgyzstan
-ExtractResult(subdomain='www', domain='worldbank', suffix='org.kg', is_private=False)
+tldextract.extract("http://www.worldbank.org.kg/")  # Kyrgyzstan
+# ExtractResult(subdomain='www', domain='worldbank', suffix='org.kg', is_private=False)
 ```
 
 Note subdomain and suffix are _optional_. Not all URL-like inputs have a
 subdomain or a valid suffix.
 
 ```python
->>> tldextract.extract('google.com')
-ExtractResult(subdomain='', domain='google', suffix='com', is_private=False)
+tldextract.extract("google.com")
+# ExtractResult(subdomain='', domain='google', suffix='com', is_private=False)
 
->>> tldextract.extract('google.notavalidsuffix')
-ExtractResult(subdomain='google', domain='notavalidsuffix', suffix='', is_private=False)
+tldextract.extract("google.notavalidsuffix")
+# ExtractResult(subdomain='google', domain='notavalidsuffix', suffix='', is_private=False)
 
->>> tldextract.extract('http://127.0.0.1:8080/deployed/')
-ExtractResult(subdomain='', domain='127.0.0.1', suffix='', is_private=False)
+tldextract.extract("http://127.0.0.1:8080/deployed/")
+# ExtractResult(subdomain='', domain='127.0.0.1', suffix='', is_private=False)
 ```
 
 To rejoin the original hostname, if it was indeed a valid, registered hostname:
 
 ```python
->>> ext = tldextract.extract('http://forums.bbc.co.uk')
->>> ext.registered_domain
-'bbc.co.uk'
->>> ext.fqdn
-'forums.bbc.co.uk'
+ext = tldextract.extract("http://forums.bbc.co.uk")
+ext.registered_domain
+# 'bbc.co.uk'
+ext.fqdn
+# 'forums.bbc.co.uk'
 ```
 
 In addition to the Python interface, there is a command-line interface. Split
@@ -98,19 +98,18 @@ To control the cache's location, set the `TLDEXTRACT_CACHE` environment variable
 like for production systems. But I want you to have the latest TLDs, especially
 when I haven't kept this code up to date.)
 
-
 ```python
 # extract callable that falls back to the included TLD snapshot, no live HTTP fetching
 no_fetch_extract = tldextract.TLDExtract(suffix_list_urls=())
-no_fetch_extract('http://www.google.com')
+no_fetch_extract("http://www.google.com")
 
 # extract callable that reads/writes the updated TLD set to a different path
-custom_cache_extract = tldextract.TLDExtract(cache_dir='/path/to/your/cache/')
-custom_cache_extract('http://www.google.com')
+custom_cache_extract = tldextract.TLDExtract(cache_dir="/path/to/your/cache/")
+custom_cache_extract("http://www.google.com")
 
 # extract callable that doesn't use caching
 no_cache_extract = tldextract.TLDExtract(cache_dir=None)
-no_cache_extract('http://www.google.com')
+no_cache_extract("http://www.google.com")
 ```
 
 If you want to stay fresh with the TLD definitions--though they don't change
@@ -144,23 +143,25 @@ domains](https://publicsuffix.org/list/).
 By default, `tldextract` treats public and private domains the same.
 
 ```python
->>> extract = tldextract.TLDExtract()
->>> extract('waiterrant.blogspot.com')
-ExtractResult(subdomain='waiterrant', domain='blogspot', suffix='com', is_private=False)
+extract = tldextract.TLDExtract()
+extract("waiterrant.blogspot.com")
+# ExtractResult(subdomain='waiterrant', domain='blogspot', suffix='com', is_private=False)
 ```
 
 The following overrides this.
+
 ```python
->>> extract = tldextract.TLDExtract()
->>> extract('waiterrant.blogspot.com', include_psl_private_domains=True)
-ExtractResult(subdomain='', domain='waiterrant', suffix='blogspot.com', is_private=True)
+extract = tldextract.TLDExtract()
+extract("waiterrant.blogspot.com", include_psl_private_domains=True)
+# ExtractResult(subdomain='', domain='waiterrant', suffix='blogspot.com', is_private=True)
 ```
 
 or to change the default for all extract calls,
+
 ```python
->>> extract = tldextract.TLDExtract( include_psl_private_domains=True)
->>> extract('waiterrant.blogspot.com')
-ExtractResult(subdomain='', domain='waiterrant', suffix='blogspot.com', is_private=True)
+extract = tldextract.TLDExtract(include_psl_private_domains=True)
+extract("waiterrant.blogspot.com")
+# ExtractResult(subdomain='', domain='waiterrant', suffix='blogspot.com', is_private=True)
 ```
 
 The thinking behind the default is, it's the more common case when people
@@ -177,8 +178,9 @@ extract = tldextract.TLDExtract(
     suffix_list_urls=["http://foo.bar.baz"],
     # Recommended: Specify your own cache file, to minimize ambiguities about where
     # tldextract is getting its data, or cached data, from.
-    cache_dir='/path/to/your/cache/',
-    fallback_to_snapshot=False)
+    cache_dir="/path/to/your/cache/",
+    fallback_to_snapshot=False,
+)
 ```
 
 If the cached version of public suffix definitions doesn't exist, such as on
@@ -191,8 +193,9 @@ protocol with an absolute path:
 ```python
 extract = tldextract.TLDExtract(
     suffix_list_urls=["file://" + "/absolute/path/to/your/local/suffix/list/file"],
-    cache_dir='/path/to/your/cache/',
-    fallback_to_snapshot=False)
+    cache_dir="/path/to/your/cache/",
+    fallback_to_snapshot=False,
+)
 ```
 
 This also works via command line update:
@@ -210,8 +213,7 @@ will be merged into whatever public suffix definitions are already in use by
 `tldextract`.
 
 ```python
-extract = tldextract.TLDExtract(
-    extra_suffixes=["foo", "bar", "baz"])
+extract = tldextract.TLDExtract(extra_suffixes=["foo", "bar", "baz"])
 ```
 
 ## FAQ
@@ -257,8 +259,8 @@ receiving exceptions or error metadata on results.
 ### Setting up
 
 1. `git clone` this repository.
-2. Change into the new directory.
-3. `pip install --upgrade --editable '.[testing]'`
+1. Change into the new directory.
+1. `pip install --upgrade --editable '.[testing]'`
 
 ### Running the test suite
 
@@ -281,4 +283,5 @@ Automatically format all code:
 
 ```zsh
 ruff format .
+mdformat .
 ```

pyproject.toml

@@ -46,6 +46,8 @@ release = [
     "twine",
 ]
 testing = [
+    "mdformat",
+    "mdformat-ruff",
     "mypy",
     "pytest",
     "pytest-gitignore",
@@ -90,6 +92,9 @@ strict = true
 [tool.pytest.ini_options]
 addopts = "--doctest-modules"
 
+[tool.ruff.format]
+docstring-code-format = true
+
 [tool.ruff.lint]
 select = [
   "A",

tests/__snapshots__/test_release.ambr

@@ -67,10 +67,10 @@
           }),
           'json': dict({
             'body': '''
-              * Bugfixes
-                  * Indicate MD5 not used in a security context (FIPS compliance) ([#309](https://github.com/john-kurkowski/tldextract/issues/309))
-              * Misc.
-                  * Increase typecheck aggression
+              - Bugfixes
+                - Indicate MD5 not used in a security context (FIPS compliance) ([#309](https://github.com/john-kurkowski/tldextract/issues/309))
+              - Misc.
+                - Increase typecheck aggression
 
               ## New Contributors
               * @jdoe contributed

tldextract/tldextract.py

@@ -4,30 +4,30 @@
 
     >>> import tldextract
 
-    >>> tldextract.extract('http://forums.news.cnn.com/')
+    >>> tldextract.extract("http://forums.news.cnn.com/")
     ExtractResult(subdomain='forums.news', domain='cnn', suffix='com', is_private=False)
 
-    >>> tldextract.extract('http://forums.bbc.co.uk/') # United Kingdom
+    >>> tldextract.extract("http://forums.bbc.co.uk/")  # United Kingdom
     ExtractResult(subdomain='forums', domain='bbc', suffix='co.uk', is_private=False)
 
-    >>> tldextract.extract('http://www.worldbank.org.kg/') # Kyrgyzstan
+    >>> tldextract.extract("http://www.worldbank.org.kg/")  # Kyrgyzstan
     ExtractResult(subdomain='www', domain='worldbank', suffix='org.kg', is_private=False)
 
 Note subdomain and suffix are _optional_. Not all URL-like inputs have a
 subdomain or a valid suffix.
 
-    >>> tldextract.extract('google.com')
+    >>> tldextract.extract("google.com")
     ExtractResult(subdomain='', domain='google', suffix='com', is_private=False)
 
-    >>> tldextract.extract('google.notavalidsuffix')
+    >>> tldextract.extract("google.notavalidsuffix")
     ExtractResult(subdomain='google', domain='notavalidsuffix', suffix='', is_private=False)
 
-    >>> tldextract.extract('http://127.0.0.1:8080/deployed/')
+    >>> tldextract.extract("http://127.0.0.1:8080/deployed/")
     ExtractResult(subdomain='', domain='127.0.0.1', suffix='', is_private=False)
 
 To rejoin the original hostname, if it was indeed a valid, registered hostname:
 
-    >>> ext = tldextract.extract('http://forums.bbc.co.uk')
+    >>> ext = tldextract.extract("http://forums.bbc.co.uk")
     >>> ext.registered_domain
     'bbc.co.uk'
     >>> ext.fqdn
@@ -73,9 +73,9 @@ class ExtractResult:
     def registered_domain(self) -> str:
         """Joins the `domain` and `suffix` fields with a dot, if they're both set, or else the empty string.
 
-        >>> extract('http://forums.bbc.co.uk').registered_domain
+        >>> extract("http://forums.bbc.co.uk").registered_domain
         'bbc.co.uk'
-        >>> extract('http://localhost:8080').registered_domain
+        >>> extract("http://localhost:8080").registered_domain
         ''
         """
         if self.suffix and self.domain:
@@ -86,9 +86,9 @@ def registered_domain(self) -> str:
     def fqdn(self) -> str:
         """Returns a 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
+        >>> extract("http://forums.bbc.co.uk/path/to/file").fqdn
         'forums.bbc.co.uk'
-        >>> extract('http://localhost:8080').fqdn
+        >>> extract("http://localhost:8080").fqdn
         ''
         """
         if self.suffix and (self.domain or self.is_private):
@@ -99,11 +99,11 @@ def fqdn(self) -> str:
     def ipv4(self) -> str:
         """Returns the IPv4, if that is what the input domain/URL was, or else the empty string.
 
-        >>> extract('http://127.0.0.1/path/to/file').ipv4
+        >>> extract("http://127.0.0.1/path/to/file").ipv4
         '127.0.0.1'
-        >>> extract('http://127.0.0.1.1/path/to/file').ipv4
+        >>> extract("http://127.0.0.1.1/path/to/file").ipv4
         ''
-        >>> extract('http://256.1.1.1').ipv4
+        >>> extract("http://256.1.1.1").ipv4
         ''
         """
         if (
@@ -118,11 +118,15 @@ def ipv4(self) -> str:
     def ipv6(self) -> str:
         """Returns the IPv6, 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').ipv6
+        >>> extract(
+        ...     "http://[aBcD:ef01:2345:6789:aBcD:ef01:127.0.0.1]/path/to/file"
+        ... ).ipv6
         'aBcD:ef01:2345:6789:aBcD:ef01:127.0.0.1'
-        >>> extract('http://[aBcD:ef01:2345:6789:aBcD:ef01:127.0.0.1.1]/path/to/file').ipv6
+        >>> extract(
+        ...     "http://[aBcD:ef01:2345:6789:aBcD:ef01:127.0.0.1.1]/path/to/file"
+        ... ).ipv6
         ''
-        >>> extract('http://[aBcD:ef01:2345:6789:aBcD:ef01:256.0.0.1]').ipv6
+        >>> extract("http://[aBcD:ef01:2345:6789:aBcD:ef01:256.0.0.1]").ipv6
         ''
         """
         min_num_ipv6_chars = 4
@@ -236,9 +240,9 @@ def extract_str(
         I.e. its effective TLD, gTLD, ccTLD, etc. components.
 
         >>> extractor = TLDExtract()
-        >>> extractor.extract_str('http://forums.news.cnn.com/')
+        >>> extractor.extract_str("http://forums.news.cnn.com/")
         ExtractResult(subdomain='forums.news', domain='cnn', suffix='com', is_private=False)
-        >>> extractor.extract_str('http://forums.bbc.co.uk/')
+        >>> extractor.extract_str("http://forums.bbc.co.uk/")
         ExtractResult(subdomain='forums', domain='bbc', suffix='co.uk', is_private=False)
 
         Allows configuring the HTTP request via the optional `session`
@@ -271,9 +275,11 @@ def extract_urllib(
         name has already been parsed.
 
         >>> extractor = TLDExtract()
-        >>> extractor.extract_urllib(urllib.parse.urlsplit('http://forums.news.cnn.com/'))
+        >>> extractor.extract_urllib(
+        ...     urllib.parse.urlsplit("http://forums.news.cnn.com/")
+        ... )
         ExtractResult(subdomain='forums.news', domain='cnn', suffix='com', is_private=False)
-        >>> extractor.extract_urllib(urllib.parse.urlsplit('http://forums.bbc.co.uk/'))
+        >>> extractor.extract_urllib(urllib.parse.urlsplit("http://forums.bbc.co.uk/"))
         ExtractResult(subdomain='forums', domain='bbc', suffix='co.uk', is_private=False)
         """
         return self._extract_netloc(

tox.ini

@@ -9,6 +9,7 @@ extras = testing
 basepython = python3.9
 commands =
     ruff format --check {posargs:.}
+    mdformat --check CHANGELOG.md README.md
 extras = testing
 
 [testenv:lint]