Do we need to expose the `Distribution` class? about importlib_metadata

[jaraco]

In GitLab by @jaraco on Sep 15, 2018, 11:47

I'm perfectly okay with those being private interfaces.

[jaraco]

In GitLab by @jaraco on Sep 16, 2018, 03:08

Related to this concern, I opened up #15, which addresses this concern from a different angle. I think the resolution to that issue will provide a clearer answer to this proposal.

[jaraco]

In GitLab by @jaraco on Sep 18, 2018, 12:54

I think we do. After removing the from_module functionality per #15, I explored removing the distribution function and its associated public functionality, but there was a test that made me reconsider. This test is demonstrating the value of being able to load arbitrary metadata from the package, perhaps even metadata that hasn't been defined today but will be subsequently.

I think it's fine not to advertise this functionality, and do primarily document the high-level interfaces, but I do think it's reasonable that an application would rely on this functionality. That leads me to believe we should document and support the interface.

[jaraco]

In GitLab by @jaraco on Sep 18, 2018, 12:56

mentioned in merge request !20

[jaraco]

In GitLab by @warsaw on Sep 18, 2018, 17:53

I think what's confusing is that we have conflicting definitions for "metadata". Is it the contents of the dist-info/METADATA file specifically, or any file within dist-info? E.g. is dist-info/top_level.txt "package metadata" or something else?

What are the official PyPA definitions? There are too many PEPs for me to follow :(

We should align on the same definitions, and expose those as the APIs for this package. I'm thinking that "metadata" should be the contents of dist-info/METADATA (or PKG-INFO, but let's not go there :) and other files should be the "distribution information". Maybe that means we need a metadata() function that returns the ConfigParser instance, and information() function that returns a named file in the dist-info directory with convenience functions for things like entry_points.txt.

I think that also means we should rename Distribution.load_metadata() to Distribution.load_information(). Once we expose information(filename) in the high level API, then I do think we can mostly hide the Distribution class. The one place we still won't be able to hide it is in the discussion about 3rd party extensions, since they have to implement the abstract method Distribution.load_metadata() (or in the future? Distribution.load_information()). That's okay though, we can mention the class in that section, tell authors to derived from it, and just implement that method. We don't need to go into tons of detail.

[jaraco]

In GitLab by @jaraco on Sep 18, 2018, 18:49

What is metadata?

I've been assuming it's everything in dist-info (not just METADATA). I don't know what the PEPs say.

I'm thinking that "metadata" should be the contents of dist-info/METADATA

Hmm. I'm okay with making that shift. And it does align the names, for clarity.

that means we need a ... information() function that returns a named file in the dist-info directory

I'm not fond of "information". It feels too general. I'm thinking since they're file names and we're returning the text of those files, something like load_file_text() or load_text_file() or load_text() or text(). That also helps if some future packager puts binary data there (imagine load_binary('logo.png') or load_binary('pubkey')).

Can we defer this change for 0.6 so we can cut a release with the merged/pending changes?

[jaraco]

In GitLab by @warsaw on Sep 19, 2018, 14:30

In importlib_resources we have read_text() and read_binary(). While the APIs are different, I think it makes sense to be consistent with naming.

I don't know if this is true, but are all the text files inside dist_info/ guaranteed to be UTF-8? If so, then we don't need as complex an API here, but we can still call the functions read_text() and if needed in the future, read_binary(). Let's call YAGNI for now on the open_*() alternatives.

[jaraco]

In GitLab by @jaraco on Sep 19, 2018, 16:56

are all the text files inside dist_info/ guaranteed to be UTF-8?

I don't know, but I'm happy to assume that's the case until we encounter a spec that indicates otherwise.

I like read_text().

[jaraco]

In GitLab by @jaraco on Sep 20, 2018, 03:05

mentioned in commit 10080a4969f468fa5f77f9a8b178e0c60e0aa9f7

[jaraco]

In GitLab by @jaraco on Sep 20, 2018, 03:08

mentioned in commit 3f211f033925023368357818532866e1976a7be4

[jaraco]

In GitLab by @jaraco on Sep 20, 2018, 03:08

mentioned in commit ffa8373ae37285249913eb75bb6c5fdd69a5d1b5

[jaraco]

In GitLab by @jaraco on Sep 20, 2018, 03:10

mentioned in merge request !23

[jaraco]

In GitLab by @jaraco on Oct 7, 2018, 13:48

mentioned in commit 7f4cda8

[jaraco]

In GitLab by @jaraco on Oct 7, 2018, 13:48

mentioned in commit 6f946ea

[jaraco]

In GitLab by @jaraco on Oct 7, 2018, 13:57

closed via commit 7f4cda8

[jaraco]

In GitLab by @jaraco on Oct 7, 2018, 13:57

closed via merge request !23