Search code examples
pythonpython-poetry

What is the meaning of a `files` key in poetry.lock?

I just installed a newer version of a package in a poetry project. Now, for every package listed in the poetry.lock file, there's an added files key, like this:

[[package]]
name = "..."
version = "..."
files = [
    {...},
    {...}
]

This wasn't there before, only after I installed the new version of the package, and introduces a lot of changes to the poetry.lock.

What is this files key and why was it created now when it wasn't there before? Can I prevent its creation?

Solution

  • There is little documentation on Poetry's lock file format and its changes from version to version. Regarding your question, there is a discussion on Github that briefly describes what's going on:

    Before lock file format version 2.0

    The files entry was its own section in the lock file, so one could find, for example, the following structure:

    [[package]]
name = "matplotlib"
version = ...
description = ...
category = ...
optional = ...
python-versions = ...

...

[metadata.files]
matplotlib = [
    {file = "matplotlib-XXX.whl", hash = "sha256:XXX"},
    ...
]

    With lock file format version 2.0

    The files entry is now part of each package's section, so a corresponding entry looks, for example, as follows:

    [[package]]
name = "matplotlib"
version = ...
description = ...
category = ...
optional = ...
python-versions = ...
files = [
    {file = "matplotlib-XXX.whl", hash = "sha256:XXX"},
    ...
]

    Information-wise, both representations are equivalent, just the structure is different.

    Meaning of the files entries

    To my understanding, the entries are created to ensure that the content of a package that is about to be installed has not changed since the lock file creation. This is to ensure the full reproducibility of the project's environment at reinstallation. That's why the entries consist of file-hash pairs:

    • file is the wheel (.whl file) that represents the Python package: usually there are different wheels for different platforms and Python versions, which is why there is a list of entries for most packages;
    • hash is the sha256 checksum for the wheel.

    As to your last question: I don't think it is possible to prevent the creation of the files entries. Also, given that (a) the corresponding information serves a vital purpose of the lock file and (b) the same information has been stored before albeit in a different place, I don't think it would make much sense to do so.