ngclient: reveal final form (finish API changes)

There’s a bunch of small API changes that I think would still make the API better (more consistent, simpler, safer). The implementations of the individual changes can probably be separate but I think it makes sense to discuss the design as a whole: it’ll be a lot easier to discuss when the final form of the API is visible.

• simplify the caching support: I’ve advocated for just dropping the “cache support” in updated_targets() before (since it’s not really a specification feature) but… it looks like it can be just simplified
• solve potential issues with target paths as local file paths
• download_target() should return the local file path, not force client to guess
• make the API more obvious and consistent: Updater.updated_targets() return value is not obvious, and using a list is weird
• Updater.get_one_valid_targetinfo(): name is long without adding value
• Updater.refresh(): there is no reason to force client to explicitly call this

Planned API usage

NOTE: these examples have been updated as the ideas have crystallized: earlier comments may refer to a slightly different example

    updater = Updater(
        metadata_dir,
        "https://example.com/metadata/",
        targets_cache_dir,
        "https://example.com/targets/",
    )
    # Update metadata for a target, then download target into cache if needed
    info = updater.get_targetinfo("file.txt")
    path = updater.find_cached_target(info)
    if path is None:
        path = updater.download_target(info)

    # Alternatively if client knows the local filename it wants to use
    info = updater.get_targetinfo("file.txt")
    if not updater.find_cached_target(info, "./file.txt"):
        updater.download_target(info, "./file.txt")

Things to note there:

• refresh() is available but not required: it will be done on first get_targetinfo() if not explicitly called before
• the functions for finding a local file and downloading a file work the same way: signatures are almost identical
• both functions return a file path: caller does not have to guess where the file is stored locally
• the local path argument to both functions can be a filename or a directory. If it is a directory, then Updater chooses a safe filename for target path (similar to current functionality). If the client knows the filename it wants, it can just use that as the argument. This allows using the Updater in a caching manner (using the same cache dir over time), or just to download a file without any cache
• no local directories are created by any of the calls: If download_target() chooses the filename, it will encode the target path before using it as a filename.
• find_cached_target() name is not great but I want it to be a counterpart to download_target (and I believe it’s much better than the ambiguous updated_targets())

See #1604 for more details.

Considered, but not included changes

I considered these as well, but am currently not planning to include them:

• Does #1556 make sense: should there be version of download_target() that returns the target file as bytes for the use case where writing to a real file is not necessary? As far as I can tell these would be entirely new functions though so this could be done at a later time without breaking API, so I’m planning to not do this now.
• Should we support pathlib Paths instead of / in addition to str file paths? I think pathlib is complete enough in the Python versions we support so that’s no longer a barrier… I’m leaning on “no we should not” as it feels more like a purity test that makes API more complicated to average developer and not a major practical benefit: Sure, filenames are not strings but I think I’m fine limiting Updater to the subset of filenames that are strings.

[sechkova]

can you explain which variant exactly you mean? I can’t quite follow the question

Sorry, I’ve misunderstood partially. Let’s go for variant 2 then.

[joshuagl]

My preference is variant 2, due to the concern I raised with the original proposal.