mdformat crashes if it can't find .mdformat.toml

[outpaddling]

Describe the bug

context
When I try to run mdformat 0.7.22 after a fresh install, it crashes, stating that a specific pathname is missing:

[snip, see full output below]
OSError: [Errno 5] Input/output error: '/net/.mdformat.toml'

configuration_file.html does not indicate that this config file is required, only that it's "allowed".

expectation
Instead of this confusing traceback, it would be good to output a specific error message:

Error: Cannot find .mdformat.toml. You must create this file in the current working directory or one of its ancestors.

Better, yet, maybe don't require this file at all, and run with defaults if it cannot be found.

bug
Here's an error message I ran into...

$ mdformat Home.md
Traceback (most recent call last):
  File "/usr/local/bin/mdformat", line 8, in <module>
    sys.exit(run())
             ^^^^^
  File "/usr/local/lib/python3.11/site-packages/mdformat/__main__.py", line 8, in run
    exit_code = mdformat._cli.run(sys.argv[1:])
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mdformat/_cli.py", line 51, in run
    toml_opts, toml_path = read_toml(path.parent if path else Path.cwd())
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mdformat/_conf.py", line 42, in read_toml_opts
    return read_toml_opts(parent_dir)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mdformat/_conf.py", line 42, in read_toml_opts
    return read_toml_opts(parent_dir)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mdformat/_conf.py", line 42, in read_toml_opts
    return read_toml_opts(parent_dir)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  [Previous line repeated 3 more times]
  File "/usr/local/lib/python3.11/site-packages/mdformat/_conf.py", line 38, in read_toml_opts
    if not conf_path.is_file():
           ^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/pathlib.py", line 1267, in is_file
    return S_ISREG(self.stat().st_mode)
                   ^^^^^^^^^^^
  File "/usr/local/lib/python3.11/pathlib.py", line 1013, in stat
    return os.stat(self, follow_symlinks=follow_symlinks)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
OSError: [Errno 5] Input/output error: '/net/.mdformat.toml'

Reproduce the bug

1. Run mdformat file.md.
2. See traceback on terminal.

List your environment

mdformat --version 
mdformat 0.7.22

[KyleKing]

It looks like the file /net/.mdformat.toml appears to exist because the reported error is access denied ("Errno 5")

Could you confirm if that file exists and what permissions/content it has?

I wasn't able to replicate any issues with the configuration file not being configured

ls -a | grep mdformat
touch file.md
uvx 'mdformat==0.7.22' file.md

Could you please also try with the latest version:

uvx 'mdformat@latest' file.md

[outpaddling]

In your example above, you only checked CWD for the .mdformat.toml file. Does it maybe exist in an ancestor directory? The docs say mdformat searches backward from . to /.

# uv tool run 'mdformat@latest' Home.md 
Installed 3 packages in 6ms
Traceback (most recent call last):
  File "/home/bacon/.cache/uv/archive-v0/TVGvmxhpKrUmvL7w4Neow/bin/mdformat", line 12, in <module>
    sys.exit(run())
             ^^^^^
  File "/home/bacon/.cache/uv/archive-v0/TVGvmxhpKrUmvL7w4Neow/lib/python3.11/site-packages/mdformat/__main__.py", line 8, in run
    exit_code = mdformat._cli.run(sys.argv[1:])
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/bacon/.cache/uv/archive-v0/TVGvmxhpKrUmvL7w4Neow/lib/python3.11/site-packages/mdformat/_cli.py", line 51, in run
    toml_opts, toml_path = read_toml(path.parent if path else Path.cwd())
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/bacon/.cache/uv/archive-v0/TVGvmxhpKrUmvL7w4Neow/lib/python3.11/site-packages/mdformat/_conf.py", line 42, in read_toml_opts
    return read_toml_opts(parent_dir)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/bacon/.cache/uv/archive-v0/TVGvmxhpKrUmvL7w4Neow/lib/python3.11/site-packages/mdformat/_conf.py", line 42, in read_toml_opts
    return read_toml_opts(parent_dir)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/bacon/.cache/uv/archive-v0/TVGvmxhpKrUmvL7w4Neow/lib/python3.11/site-packages/mdformat/_conf.py", line 42, in read_toml_opts
    return read_toml_opts(parent_dir)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  [Previous line repeated 3 more times]
  File "/home/bacon/.cache/uv/archive-v0/TVGvmxhpKrUmvL7w4Neow/lib/python3.11/site-packages/mdformat/_conf.py", line 38, in read_toml_opts
    if not conf_path.is_file():
           ^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/pathlib.py", line 1267, in is_file
    return S_ISREG(self.stat().st_mode)
                   ^^^^^^^^^^^
  File "/usr/local/lib/python3.11/pathlib.py", line 1013, in stat
    return os.stat(self, follow_symlinks=follow_symlinks)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
OSError: [Errno 5] Input/output error: '/net/.mdformat.toml'

[KyleKing]

I was running my example from my home directory and don’t have mdformat configuration files in parent directories (I’m also using MacOS and can try Linux later)

[outpaddling]

I'm not much of a pythonista, but the code is not hard to read, so I kinda figured out what's happening. The /net directory on FreeBSD has attributes that forbid the existence of regular files. Only autofs is allowed to create directories there, one for each NFS host. I just confirmed that behavior on macOS is similar. conf_path.is_file() seems to choke on this. Converting the Path object to a string and using os.path.isfile() leads to a successful file test and averts the exception:

def read_toml_opts(conf_dir: Path) -> tuple[Mapping, Path | None]:
    conf_path = conf_dir / ".mdformat.toml"
    print("conf_path = {}".format(conf_path))
    # if not conf_path.is_file():
    if not os.path.isfile(str(conf_path)):
        parent_dir = conf_dir.parent
        print("parent_dir = {}".format(parent_dir))
        if conf_dir == parent_dir:
            return {}, None
        return read_toml_opts(parent_dir)

[KyleKing]

Makes sense! I pushed a possible fix and test here: #566

This change will only be fixed forward off of v1 of mdformat though. Do you need the patch backported to 0.7.22 for a specific reason?

[outpaddling]

No, thanks, I already submitted a patch that can reside in the FreeBSD port until it catches up with upstream.

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=292021

I would suggest documenting the reason for your fix, so someone in the future doesn't back it out to simplify what they might see is needlessly convoluted code.

The fix does seem to work.

[KyleKing]

Great and good point!