adds @generated to header of lockfile (#2773)

Resolves: #2034 

It's useful to both developer tools and for users to recognize the
lock file is generated. This header should achieve both.

src/poetry/packages/locker.py

@@ -19,6 +19,7 @@ from poetry.core.toml.file import TOMLFile
 from poetry.core.version.markers import parse_marker
 from poetry.core.version.markers import parse_marker
 from poetry.core.version.requirements import InvalidRequirement
 from poetry.core.version.requirements import InvalidRequirement
 from tomlkit import array
 from tomlkit import array
+from tomlkit import comment
 from tomlkit import document
 from tomlkit import document
 from tomlkit import inline_table
 from tomlkit import inline_table
 from tomlkit import item
 from tomlkit import item
@@ -38,6 +39,11 @@ if TYPE_CHECKING:
     from poetry.repositories import Repository
     from poetry.repositories import Repository
 
 
 logger = logging.getLogger(__name__)
 logger = logging.getLogger(__name__)
+_GENERATED_IDENTIFIER = "@" + "generated"
+GENERATED_COMMENT = (
+    f"This file is automatically {_GENERATED_IDENTIFIER} by Poetry and should not be"
+    " changed by hand."
+)
 
 
 
 
 class Locker:
 class Locker:
@@ -229,6 +235,7 @@ class Locker:
             del package["files"]
             del package["files"]
 
 
         lock = document()
         lock = document()
+        lock.add(comment(GENERATED_COMMENT))
         lock["package"] = package_specs
         lock["package"] = package_specs
 
 
         if root.extras:
         if root.extras:

tests/packages/test_locker.py

@@ -19,6 +19,7 @@ from poetry.core.packages.project_package import ProjectPackage
 from poetry.core.semver.version import Version
 from poetry.core.semver.version import Version
 
 
 from poetry.factory import Factory
 from poetry.factory import Factory
+from poetry.packages.locker import GENERATED_COMMENT
 from poetry.packages.locker import Locker
 from poetry.packages.locker import Locker
 from tests.helpers import get_dependency
 from tests.helpers import get_dependency
 from tests.helpers import get_package
 from tests.helpers import get_package
@@ -93,7 +94,9 @@ def test_lock_file_data_is_ordered(locker: Locker, root: ProjectPackage):
     with locker.lock.open(encoding="utf-8") as f:
     with locker.lock.open(encoding="utf-8") as f:
         content = f.read()
         content = f.read()
 
 
-    expected = """\
+    expected = f"""\
+# {GENERATED_COMMENT}
+
 [[package]]
 [[package]]
 name = "A"
 name = "A"
 version = "1.0.0"
 version = "1.0.0"
@@ -183,21 +186,23 @@ content-hash = "115cf985d932e9bf5f540555bbdd75decbb62cac81e399375fc19f6277f8c1d8
 
 
 [metadata.files]
 [metadata.files]
 A = [
 A = [
-    {file = "bar", hash = "123"},
-    {file = "foo", hash = "456"},
-    {file = "baz", hash = "345"},
+    {{file = "bar", hash = "123"}},
+    {{file = "foo", hash = "456"}},
+    {{file = "baz", hash = "345"}},
 ]
 ]
 B = []
 B = []
 git-package = []
 git-package = []
 git-package-subdir = []
 git-package-subdir = []
 url-package = []
 url-package = []
-"""
+"""  # noqa: E800
 
 
     assert content == expected
     assert content == expected
 
 
 
 
 def test_locker_properly_loads_extras(locker: Locker):
 def test_locker_properly_loads_extras(locker: Locker):
-    content = """\
+    content = f"""\
+# {GENERATED_COMMENT}
+
 [[package]]
 [[package]]
 name = "cachecontrol"
 name = "cachecontrol"
 version = "0.12.5"
 version = "0.12.5"
@@ -225,7 +230,7 @@ content-hash = "c3d07fca33fba542ef2b2a4d75bf5b48d892d21a830e2ad9c952ba5123a52f77
 
 
 [metadata.files]
 [metadata.files]
 cachecontrol = []
 cachecontrol = []
-"""
+"""  # noqa: E800
 
 
     locker.lock.write(tomlkit.parse(content))
     locker.lock.write(tomlkit.parse(content))
 
 
@@ -242,7 +247,9 @@ cachecontrol = []
 
 
 
 
 def test_locker_properly_loads_nested_extras(locker: Locker):
 def test_locker_properly_loads_nested_extras(locker: Locker):
-    content = """\
+    content = f"""\
+# {GENERATED_COMMENT}
+
 [[package]]
 [[package]]
 name = "a"
 name = "a"
 version = "1.0"
 version = "1.0"
@@ -252,7 +259,7 @@ optional = false
 python-versions = "*"
 python-versions = "*"
 
 
 [package.dependencies]
 [package.dependencies]
-b = {version = "^1.0", optional = true, extras = "c"}
+b = {{version = "^1.0", optional = true, extras = "c"}}
 
 
 [package.extras]
 [package.extras]
 b = ["b[c] (>=1.0,<2.0)"]
 b = ["b[c] (>=1.0,<2.0)"]
@@ -266,7 +273,7 @@ optional = false
 python-versions = "*"
 python-versions = "*"
 
 
 [package.dependencies]
 [package.dependencies]
-c = {version = "^1.0", optional = true}
+c = {{version = "^1.0", optional = true}}
 
 
 [package.extras]
 [package.extras]
 c = ["c (>=1.0,<2.0)"]
 c = ["c (>=1.0,<2.0)"]
@@ -288,7 +295,7 @@ content-hash = "123456789"
 "a" = []
 "a" = []
 "b" = []
 "b" = []
 "c" = []
 "c" = []
-"""
+"""  # noqa: E800
 
 
     locker.lock.write(tomlkit.parse(content))
     locker.lock.write(tomlkit.parse(content))
 
 
@@ -322,7 +329,9 @@ content-hash = "123456789"
 
 
 
 
 def test_locker_properly_loads_extras_legacy(locker: Locker):
 def test_locker_properly_loads_extras_legacy(locker: Locker):
-    content = """\
+    content = f"""\
+# {GENERATED_COMMENT}
+
 [[package]]
 [[package]]
 name = "a"
 name = "a"
 version = "1.0"
 version = "1.0"
@@ -332,7 +341,7 @@ optional = false
 python-versions = "*"
 python-versions = "*"
 
 
 [package.dependencies]
 [package.dependencies]
-b = {version = "^1.0", optional = true}
+b = {{version = "^1.0", optional = true}}
 
 
 [package.extras]
 [package.extras]
 b = ["b (^1.0)"]
 b = ["b (^1.0)"]
@@ -353,7 +362,7 @@ content-hash = "123456789"
 [metadata.files]
 [metadata.files]
 "a" = []
 "a" = []
 "b" = []
 "b" = []
-"""
+"""  # noqa: E800
 
 
     locker.lock.write(tomlkit.parse(content))
     locker.lock.write(tomlkit.parse(content))
 
 
@@ -532,7 +541,10 @@ def test_lock_packages_with_null_description(locker: Locker, root: ProjectPackag
     with locker.lock.open(encoding="utf-8") as f:
     with locker.lock.open(encoding="utf-8") as f:
         content = f.read()
         content = f.read()
 
 
-    expected = """[[package]]
+    expected = f"""\
+# {GENERATED_COMMENT}
+
+[[package]]
 name = "A"
 name = "A"
 version = "1.0.0"
 version = "1.0.0"
 description = ""
 description = ""
@@ -547,7 +559,7 @@ content-hash = "115cf985d932e9bf5f540555bbdd75decbb62cac81e399375fc19f6277f8c1d8
 
 
 [metadata.files]
 [metadata.files]
 A = []
 A = []
-"""
+"""  # noqa: E800
 
 
     assert content == expected
     assert content == expected
 
 
@@ -563,7 +575,10 @@ def test_lock_file_should_not_have_mixed_types(locker: Locker, root: ProjectPack
 
 
     locker.set_lock_data(root, [package_a])
     locker.set_lock_data(root, [package_a])
 
 
-    expected = """[[package]]
+    expected = f"""\
+# {GENERATED_COMMENT}
+
+[[package]]
 name = "A"
 name = "A"
 version = "1.0.0"
 version = "1.0.0"
 description = ""
 description = ""
@@ -573,8 +588,8 @@ python-versions = "*"
 
 
 [package.dependencies]
 [package.dependencies]
 B = [
 B = [
-    {version = "^1.0.0"},
-    {version = ">=1.0.0", optional = true},
+    {{version = "^1.0.0"}},
+    {{version = ">=1.0.0", optional = true}},
 ]
 ]
 
 
 [package.extras]
 [package.extras]
@@ -587,7 +602,7 @@ content-hash = "115cf985d932e9bf5f540555bbdd75decbb62cac81e399375fc19f6277f8c1d8
 
 
 [metadata.files]
 [metadata.files]
 A = []
 A = []
-"""
+"""  # noqa: E800
 
 
     with locker.lock.open(encoding="utf-8") as f:
     with locker.lock.open(encoding="utf-8") as f:
         content = f.read()
         content = f.read()
@@ -596,7 +611,10 @@ A = []
 
 
 
 
 def test_reading_lock_file_should_raise_an_error_on_invalid_data(locker: Locker):
 def test_reading_lock_file_should_raise_an_error_on_invalid_data(locker: Locker):
-    content = """[[package]]
+    content = f"""\
+# {GENERATED_COMMENT}
+
+[[package]]
 name = "A"
 name = "A"
 version = "1.0.0"
 version = "1.0.0"
 description = ""
 description = ""
@@ -617,7 +635,7 @@ content-hash = "115cf985d932e9bf5f540555bbdd75decbb62cac81e399375fc19f6277f8c1d8
 
 
 [metadata.files]
 [metadata.files]
 A = []
 A = []
-"""
+"""  # noqa: E800
     with locker.lock.open("w", encoding="utf-8") as f:
     with locker.lock.open("w", encoding="utf-8") as f:
         f.write(content)
         f.write(content)
 
 
@@ -644,7 +662,10 @@ def test_locking_legacy_repository_package_should_include_source_section(
     with locker.lock.open(encoding="utf-8") as f:
     with locker.lock.open(encoding="utf-8") as f:
         content = f.read()
         content = f.read()
 
 
-    expected = """[[package]]
+    expected = f"""\
+# {GENERATED_COMMENT}
+
+[[package]]
 name = "A"
 name = "A"
 version = "1.0.0"
 version = "1.0.0"
 description = ""
 description = ""
@@ -664,7 +685,7 @@ content-hash = "115cf985d932e9bf5f540555bbdd75decbb62cac81e399375fc19f6277f8c1d8
 
 
 [metadata.files]
 [metadata.files]
 A = []
 A = []
-"""
+"""  # noqa: E800
 
 
     assert content == expected
     assert content == expected
 
 
@@ -703,14 +724,16 @@ regenerate the lock file with the `poetry lock` command.\
 def test_locker_should_raise_an_error_if_lock_version_is_newer_and_not_allowed(
 def test_locker_should_raise_an_error_if_lock_version_is_newer_and_not_allowed(
     locker: Locker, caplog: LogCaptureFixture
     locker: Locker, caplog: LogCaptureFixture
 ):
 ):
-    content = """\
+    content = f"""\
+# {GENERATED_COMMENT}
+
 [metadata]
 [metadata]
 lock-version = "2.0"
 lock-version = "2.0"
 python-versions = "~2.7 || ^3.4"
 python-versions = "~2.7 || ^3.4"
 content-hash = "c3d07fca33fba542ef2b2a4d75bf5b48d892d21a830e2ad9c952ba5123a52f77"
 content-hash = "c3d07fca33fba542ef2b2a4d75bf5b48d892d21a830e2ad9c952ba5123a52f77"
 
 
 [metadata.files]
 [metadata.files]
-"""
+"""  # noqa: E800
     caplog.set_level(logging.WARNING, logger="poetry.packages.locker")
     caplog.set_level(logging.WARNING, logger="poetry.packages.locker")
 
 
     locker.lock.write(tomlkit.parse(content))
     locker.lock.write(tomlkit.parse(content))
@@ -730,7 +753,10 @@ def test_extras_dependencies_are_ordered(locker: Locker, root: ProjectPackage):
 
 
     locker.set_lock_data(root, [package_a])
     locker.set_lock_data(root, [package_a])
 
 
-    expected = """[[package]]
+    expected = f"""\
+# {GENERATED_COMMENT}
+
+[[package]]
 name = "A"
 name = "A"
 version = "1.0.0"
 version = "1.0.0"
 description = ""
 description = ""
@@ -739,7 +765,7 @@ optional = false
 python-versions = "*"
 python-versions = "*"
 
 
 [package.dependencies]
 [package.dependencies]
-B = {version = "^1.0.0", extras = ["a", "b", "c"], optional = true}
+B = {{version = "^1.0.0", extras = ["a", "b", "c"], optional = true}}
 
 
 [metadata]
 [metadata]
 lock-version = "1.1"
 lock-version = "1.1"
@@ -748,7 +774,7 @@ content-hash = "115cf985d932e9bf5f540555bbdd75decbb62cac81e399375fc19f6277f8c1d8
 
 
 [metadata.files]
 [metadata.files]
 A = []
 A = []
-"""
+"""  # noqa: E800
 
 
     with locker.lock.open(encoding="utf-8") as f:
     with locker.lock.open(encoding="utf-8") as f:
         content = f.read()
         content = f.read()
@@ -820,7 +846,9 @@ def test_locker_dumps_dependency_information_correctly(
     with locker.lock.open(encoding="utf-8") as f:
     with locker.lock.open(encoding="utf-8") as f:
         content = f.read()
         content = f.read()
 
 
-    expected = """[[package]]
+    expected = f"""# {GENERATED_COMMENT}
+
+[[package]]
 name = "A"
 name = "A"
 version = "1.0.0"
 version = "1.0.0"
 description = ""
 description = ""
@@ -829,11 +857,11 @@ optional = false
 python-versions = "*"
 python-versions = "*"
 
 
 [package.dependencies]
 [package.dependencies]
-B = {path = "project_with_extras", develop = true}
-C = {path = "directory/project_with_transitive_directory_dependencies"}
-D = {path = "distributions/demo-0.1.0.tar.gz"}
-E = {url = "https://python-poetry.org/poetry-1.2.0.tar.gz"}
-F = {git = "https://github.com/python-poetry/poetry.git", branch = "foo"}
+B = {{path = "project_with_extras", develop = true}}
+C = {{path = "directory/project_with_transitive_directory_dependencies"}}
+D = {{path = "distributions/demo-0.1.0.tar.gz"}}
+E = {{url = "https://python-poetry.org/poetry-1.2.0.tar.gz"}}
+F = {{git = "https://github.com/python-poetry/poetry.git", branch = "foo"}}
 
 
 [metadata]
 [metadata]
 lock-version = "1.1"
 lock-version = "1.1"
@@ -940,7 +968,9 @@ A = []
 def test_locked_repository_uses_root_dir_of_package(
 def test_locked_repository_uses_root_dir_of_package(
     locker: Locker, mocker: MockerFixture
     locker: Locker, mocker: MockerFixture
 ):
 ):
-    content = """\
+    content = f"""\
+# {GENERATED_COMMENT}
+
 [[package]]
 [[package]]
 name = "lib-a"
 name = "lib-a"
 version = "0.1.0"
 version = "0.1.0"
@@ -951,7 +981,7 @@ python-versions = "^2.7.9"
 develop = true
 develop = true
 
 
 [package.dependencies]
 [package.dependencies]
-lib-b = {path = "../libB", develop = true}
+lib-b = {{path = "../libB", develop = true}}
 
 
 [package.source]
 [package.source]
 type = "directory"
 type = "directory"
@@ -965,7 +995,7 @@ content-hash = "115cf985d932e9bf5f540555bbdd75decbb62cac81e399375fc19f6277f8c1d8
 [metadata.files]
 [metadata.files]
 lib-a = []
 lib-a = []
 lib-b = []
 lib-b = []
-"""
+"""  # noqa: E800
 
 
     locker.lock.write(tomlkit.parse(content))
     locker.lock.write(tomlkit.parse(content))
     create_dependency_patch = mocker.patch(
     create_dependency_patch = mocker.patch(