Poetry.lock format , can i consider it as a right format for the poetry.lock file ?

[harshitbansal184507]

Is this the correct format for poetry.lock file , as i was trying to parse and have taken care of these fields , am i missing something , since there is no offical docs presenting the format of lockfile

# This file is automatically @generated by Poetry {version} and should not be changed by hand.

[[package]]
name = "example-pkg"                    # always present | package name
version = "1.2.3"                       # always present | exact resolved version
description = "Short description"       # always present | can be empty string ""
optional = false                        # always present | whether package is optional
python-versions = ">=3.9"              # always present | supported python range
groups = ["main"]                       # always present (2.1+) | which dependency groups: "main", "dev", "docs", etc.
markers = "python_version < \"3.11\""  # optional | environment markers, absent if no restrictions
develop = false                         # optional | only on git and directory source types
files = [                               # always present | empty [] for git/directory deps
    {file = "example-pkg-1.2.3-py3-none-any.whl", hash = "sha256:abc..."},
    {file = "example-pkg-1.2.3.tar.gz", hash = "sha256:def..."},
]

# markers can also be a per-group table when groups have different markers:
# markers = {main = "sys_platform == 'linux'", dev = "python_version >= '3.10'"}

[package.dependencies]
other-pkg = ">=1.0"                                                         # simple version
conditional-pkg = {version = ">=1.0", markers = "python_version < \"3.11\""}  # version with marker
optional-pkg = {version = ">=1.0", optional = true, markers = "extra == \"foo\""}  # optional dep
path-pkg = {path = "libs/mypkg"}                                            # path dep
path-pkg-dev = {path = "libs/mypkg", develop = true}                        # path dep editable
url-pkg = {url = "https://example.com/pkg-1.0.tar.gz"}                      # url dep
git-pkg = {git = "https://github.com/org/repo", branch = "main"}            # git with branch
git-pkg2 = {git = "https://github.com/org/repo", tag = "v1.0"}              # git with tag
git-pkg3 = {git = "https://github.com/org/repo", rev = "abc123"}            # git with rev
git-pkg4 = {git = "https://github.com/org/repo", rev = "abc123", subdirectory = "sub"}  # git with subdir
extras-pkg = {version = ">=1.0", extras = ["extra1", "extra2"]}             # dep with extras

# multiple constraints for same package (array form):
# multi-pkg = [
#     {version = ">=1.0", markers = "python_version >= '3.8'"},
#     {version = ">=2.0", markers = "python_version >= '3.10'"},
# ]


# --- Extras (optional, only if package defines extras) ---

[package.extras]
standard = ["httptools (>=0.5.0)", "uvloop (>=0.14.0)"]
trio = ["trio (>=0.31.0) ; python_version < \"3.10\""]


# --- Source (optional, ABSENT for default PyPI packages) ---

# TYPE: git
[package.source]
type = "git"
url = "https://github.com/org/repo.git"                         # repo URL
reference = "main"                                                # what user specified: branch/tag/rev
resolved_reference = "874ca2bc1c30d93a4ac6e36a15ed685eafe89097"  # actual commit hash
subdirectory = "packages/mypkg"                                   # optional, only if subdirectory specified

# TYPE: url
[package.source]
type = "url"
url = "https://example.com/package-1.0.tar.gz"                  # download URL

# TYPE: directory
[package.source]
type = "directory"
url = "mylib"                                                     # relative path from lockfile

# TYPE: file
[package.source]
type = "file"
url = "dist/my-package-0.1.0.tar.gz"                            # relative path from lockfile

# TYPE: legacy (private/custom registry)
[package.source]
type = "legacy"
url = "https://private.pypi.org/simple/"                         # registry URL
reference = "private-source-name"                                 # registry name from pyproject.toml

[metadata]
lock-version = "2.1"          # always present | format version (current: "2.1", Poetry reads ">=1,<3")
python-versions = "^3.9"      # always present | root package python constraint
content-hash = "sha256hex..."  # always present | hash of dependency sections in pyproject.toml

[radoering]

There is no official docs because the exact format is an internal detail and may change without notice. If you want to parse the file anyway, it is read/written in https://github.com/python-poetry/poetry/blob/main/src/poetry/packages/locker.py. In the corresponding test, you will find some examples.

[harshitbansal184507]

Thanks, I checked it out , I just wanted clarification , are core fields like "files" (wheel/sdist + hashes) expected to remain relatively stable across versions, or can their structure change in future ?

[Secrus]

Like Randy said, we treat lockfile structure as an internal implementation detail, so we are not giving any guarantees on anything regarding the structure of the file

[radoering]

The format was quite stable in the past except for some fields that were removed and some fields that were added but we cannot predict the future.

[harshitbansal184507]

Ok , got the the idea . Thanks