Add open_parent_fs() method

[BrunoGrandePhD]

Type of changes

• New feature
• Documentation / docstrings
• Tests

Checklist

• I've run the latest black with default args on new code.
• I've updated CHANGELOG.md and CONTRIBUTORS.md where appropriate.
• I've added tests for new code.
• I accept that @PyFilesystem/maintainers may be pedantic in the code review.

Description

One of my use cases for PyFileSystem2 is that I want to perform operations (read/write) on file URLs. Unfortunately, you can only use open_fs() with a directory URL. So, open_parent_fs() addresses this gap. I noticed the open() method, which has a similar return tuple, but based on my tests, it doesn't seem to work the same way. Feel free to tell me otherwise.

Here's the docstring for the new open_parent_fs() method:

Open a filesystem for the top-most directory in a FS URL.

Compared to ~Registry.open_fs, this function is useful for
handling URLs that point to files instead of directories.

The top-most directory is used as the root of the file system
because it doesn't assume that the intermediate directories
exist at the time of creating the file system. The user can
opt to run ~FS.makedirs to "fill in" the directories prior
to performing operations on the file indicated by the URL.

After determining the top-most directory, the remainder of the
given FS URL is provided as the second return value as a path
to be used in downstream FS operations.

[lurch]

I'll wait to see what the other maintainers say, but my knee-jerk instinct would be that rather than "polluting" the API with a new open_parent_fs() method, it'd be better to just have utility methods to break apart a file-URL into separate "file" and "directory" parts (I believe that the very nature of URLs means that you can't tell definitively whether a URL points at a file or directory?), and then just use the existing open_fs() method?

Aha... https://docs.pyfilesystem.org/en/latest/reference/opener.html#fs.opener.parse.parse_fs_url

[BrunoGrandePhD]

@lurch: Thanks for the feedback! I was aware of the parse_fs_url() function, but after taking another look, I noticed that it has a path component. According to the regex, it's whatever comes after a ! character in the URL. I didn't realize this convention with FS URLs; it doesn't seem documented, nor standard. That said, I think that does help with my use case since I can then use the open() method instead of open_fs() (source).

Can you think of any drawbacks from using the !<path> URL component?

^(.*?):\/\/(?:(?:(.*?)@(.*?))|(.*?))(?:!(.*?)$)*$

[lurch]

I'm afraid I never use FS URLs myself - I prefer to just construct the underlying class objects directly. So one of the other pyfilesystem maintainers will have to answer your question! 😄

nor standard

From my understanding FS URLs are like internet URLs, but subtly different in some regards, and ISTR this confusing other people too previously. So it sounds like https://docs.pyfilesystem.org/en/latest/openers.html could definitely do with being fleshed out a bit more...

Looks like https://github.com/PyFilesystem/pyfilesystem2/blob/master/tests/test_opener.py might give you some clues too.