Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python 개선 제안 한국어 번역

PEP 739 – build-details.json 1.0 — 파이썬 빌드 세부 정보에 대한 정적 설명 파일

Author:
Filipe Laíns <lains at python.org>
PEP-Delegate:
Paul Moore <p.f.moore at gmail.com>
Discussions-To:
Discourse thread
Status:
Accepted
Type:
Standards Track
Topic:
Packaging
Created:
19-Dec-2023
Python-Version:
3.14
Resolution:
Discourse message
Table of Contents

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain or CC0-1.0, whichever is more permissive 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

초록

이 PEP는 파이썬 설치의 빌드 세부 정보를 포함하는 정적 설명 파일인 build-details.json을 소개합니다.

파일 형식 버전 1.0의 정의를 포함하며, 이 파일의 표준 위치를 정의합니다.

근거

파이썬 설치를 조사할 때 코드를 실행하는 것은 바람직하지 않거나 불가능한 경우가 많습니다. 정적 설명 파일을 사용하면 인터프리터를 실행하지 않고도 파이썬 설치의 다양한 빌드 세부 정보를 이용할 수 있습니다.

이는 크로스 컴파일, 파이썬 런처 등의 사용 사례에 유용합니다.

범위

build-details.json은 설치 전체에 적용되는 파일이므로, 파이썬 설치의 모든 환경에서 일정한 정보만 포함해야 합니다.

site-packages경로와 같이 파이썬 환경에 특정한 정보는 이 파일의 범위에 포함되지 않으며, PEP 작성자들은 향후 PEP를 통해 정적 환경 설명 파일이 도입될 것으로 예상합니다.

사양

Python 3.14부터 이 PEP에서 지정한 형식 또는 향후 버전을 따르는 build-details.json이라는 파일은 플랫폼 독립적인 표준 라이브러리 디렉터리(stdlib, 예: /usr/lib/python3.14/build-details.json)에 MUST 설치해야 합니다. 단, 기술적 제한으로 인해 불가능한 경우는 UNLESS 제외합니다.

Attention

이 PEP에서 지정한 표준 위치 외에도 build-details.json 파일을 추가 위치에, 그리고 다른 이름으로 설치해도 됩니다. 그럼에도 불구하고 이 파일은 표준 위치에서 여전히 이용 가능해야 합니다.

실제로 PEP 작성자들은 향후 PEP에서 검색 가능성이 더 높은 추가 설치 위치를 정의할 것으로 예상합니다.

형식

형식 사양은 아래에 제공된 JSON Schema 정의로 규정되며, 여기에서는 사람이 읽을 수 있는 형식으로 렌더링됩니다.

$schema https://json-schema.org/draft/2020-12/schema
$id https://github.com/python/peps/blob/main/peps/pep-0739/python-build-info-v1.0.schema.json
Title build-details.json — a static description file with build details of Python installations
Type object
Additional properties Not allowed

schema_version

Type string (constant — 1.0)
Description Schema version.

This is a string following the format <MAJOR>.<MINOR>, where <MAJOR> and <MINOR> are unpadded numbers and represent the major and minor components of the version. Versions may be arithmetically compared by interpreting the version string as a decimal number.

For this specification version, this value is constant and MUST be 1.0.

Future versions of this schema MUST use a higher version number. Future versions of this schema MUST NOT use the same major version component as other schema version unless its specification is deemed backwards-compatible with them — it can’t change, or extend, any parts of the current specification in such a way as the semantics of the interpreted data differ, or that data valid under the new specification is invalid under the older specification, with the exception of additional properties (errors caused by additionalProperties).
Required True

base_prefix

Type string
Description Base prefix of the Python installation.

Either an absolute path, or a path relative to directory where this file is contained.
Examples /usr, ../.., etc.
Required True

base_interpreter

Type string
Description The path to the Python interpreter of the base installation.

Either an absolute path, or a path relative to base_prefix.

This field MUST be present if the installation provides an interpreter executable.
Examples
  • /usr/bin/python
  • bin/python
  • etc.
Required False

platform

Type string
Description System platform string.

This field SHOULD be equivalent to sysconfig.get_platform().
Examples
  • linux-x86_64
  • etc.
Required True

language

Type object
Description Object containing details related to the Python language specification.
Required True
Additional properties Not allowed

language.version

Type string
Description String representation the Python language version — a version string consisting only of the major and minor components.

This field SHOULD be equivalent to sysconfig.get_python_version().
Examples 3.14, etc.
Required True

language.version_info

Type object
Description Object in the format of sys.version_info.

This section SHOULD be equivalent to sys.version_info.
Examples
  • {'major': 3, 'minor': 14, 'micro': 1, 'releaselevel': 'final', 'serial': 0}
  • etc.
Required False
Additional properties Not allowed
language.version_info.major
Type number
Required True
language.version_info.minor
Type number
Required True
language.version_info.micro
Type number
Required True
language.version_info.releaselevel
Type string (enum — alpha, beta, candidate, final)
Required True
language.version_info.serial
Type number
Required True

implementation

Type object
Description Object containing details related to the Python implementation.

This section SHOULD be equivalent to sys.implementation. It follows the specification defined in PEP 421, meaning that in addition to the required keys, implementation-specific keys can also exist, but must be prefixed with an underscore.
Required True
Additional properties Allowed

implementation.name

Type string
Description Lower-case name of the Python implementation.
Examples cpython, pypy, etc.
Required True

implementation.version

Type object
Description Object in the format of sys.version_info, containing the implementation version.
Examples
  • {'major': 3, 'minor': 14, 'micro': 1, 'releaselevel': 'final', 'serial': 0}
  • {'major': 7, 'minor': 3, 'micro': 16, 'releaselevel': 'final', 'serial': 0}
  • etc.
Required True
Additional properties Not allowed
implementation.version.major
Type number
Required True
implementation.version.minor
Type number
Required True
implementation.version.micro
Type number
Required True
implementation.version.releaselevel
Type string (enum — alpha, beta, candidate, final)
Required True
implementation.version.serial
Type number
Required True

abi

Type object
Description Object containing details related to ABI.
Required False
Additional properties Not allowed

abi.flags

Type array
Description Build configuration flags, used to calculate the extension suffix.

The flags MUST be defined in the order they appear on the extension suffix.
Examples ['t', 'd'], etc.
Required True

abi.extension_suffix

Type string
Description Suffix used for extensions built against the current implementation version.

This field MUST be present if the Python implementation supports extensions, otherwise this entry will be missing.
Examples
  • .cpython-314-x86_64-linux-gnu.so
  • etc.
Required False

abi.stable_abi_suffix

Type string
Description Suffix used for extensions built against the stable ABI.

This field MUST be present if the Python implementation has a stable ABI extension suffix, otherwise this entry will be missing.
Examples .abi3.so, etc.
Required False

suffixes

Type object
Description Valid module suffixes grouped by type.

This section MUST be present if the Python installation supports importing external files, and it SHOULD be equivalent to the importlib.machinery.*_SUFFIXES attributes.

Additionally, if a Python implementation provides extension kinds other than the ones listed on importlib.machinery module, they MAY add a sub-section for them.
Examples
  • {'source': ['.py'], 'bytecode': ['.pyc'], 'optimized_bytecode': ['.pyc'], 'debug_bytecode': ['.pyc'], 'extensions': ['.cpython-313-x86_64-linux-gnu.so', '.abi3.so', '.so']}
  • etc.
Required False
Additional properties Allowed

libpython

Type object
Description Object containing details related to the libpython library.

This section MUST by present if Python installation provides a libpython library, otherwise this section will be missing.
Required False
Additional properties Not allowed

libpython.dynamic

Type string
Description The path to the dynamic libpython library.

Either an absolute path, or a path relative to base_prefix.

This field MUST be present if the Python installation provides a dynamic libpython library, otherwise this entry will be missing.
Examples
  • /usr/lib/libpython3.14.so.1.0
  • lib/libpython3.14.so.1.0
  • etc.
Required False

libpython.dynamic_stableabi

Type string
Description The path to the dynamic libpython library for the stable ABI.

Either an absolute path, or a path relative to base_prefix.

This field MUST be present if the Python installation provides a dynamic libpython library targetting the Stable ABI, otherwise this entry will be missing.

If this key is present dynamic MUST also be set.
Examples
  • /usr/lib/libpython3.so
  • lib/libpython3.so
  • etc.
Required False

libpython.static

Type string
Description The path to the static libpython library.

Either an absolute path, or a path relative to base_prefix.

This field MUST be present if the Python installation provides a static libpython library, otherwise this entry will be missing.
Examples
  • /usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a
  • lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a
  • etc.
Required False

c_api

Type object
Description Object containing details related to the Python C API.

This section MUST be present if the Python implementation provides a C API, otherwise this section will be missing.
Required False
Additional properties Not allowed

c_api.headers

Type string
Description The path to the C API headers.

Either an absolute path, or a path relative to base_prefix.
Examples
  • /usr/include/python3.14
  • include/python3.14
  • etc.
Required True

c_api.pkgconfig_path

Type string
Description The path to the pkg-config definition files.

Either an absolute path, or a path relative to base_prefix.

This field MUST be present if the Python implementation provides pkg-config definition files, otherwise this section will be missing.
Examples
  • /usr/lib/pkgconfig
  • lib/pkgconfig
  • etc.
Required False

arbitrary_data

Type object
Description Object containing extra arbitrary data.

This is meant to be used as an escape-hatch, to include any relevant data that is not covered by this specification. Implementations may choose what data to provide in this section.
Required False
Additional properties Allowed

예제

 1{
 2  "schema_version": "1.0",
 3  "base_prefix": "/usr",
 4  "base_interpreter": "/usr/bin/python",
 5  "platform": "linux-x86_64",
 6  "language": {
 7    "version": "3.14",
 8    "version_info": {
 9      "major": 3,
10      "minor": 14,
11      "micro": 0,
12      "releaselevel": "alpha",
13      "serial": 0
14    }
15  },
16  "implementation": {
17    "name": "cpython",
18    "version": {
19      "major": 3,
20      "minor": 14,
21      "micro": 0,
22      "releaselevel": "alpha",
23      "serial": 0
24    },
25    "hexversion": 51249312,
26    "cache_tag": "cpython-314",
27    "_multiarch": "x86_64-linux-gnu"
28  },
29  "abi": {
30    "flags": ["t", "d"],
31    "extension_suffix": ".cpython-314-x86_64-linux-gnu.so",
32    "stable_abi_suffix": ".abi3.so"
33  },
34  "suffixes": {
35    "source": [".py"],
36    "bytecode": [".pyc"],
37    "optimized_bytecode": [".pyc"],
38    "debug_bytecode": [".pyc"],
39    "extensions": [".cpython-314-x86_64-linux-gnu.so", ".abi3.so", ".so"]
40  },
41  "libpython": {
42    "dynamic": "/usr/lib/libpython3.14.so.1.0",
43    "dynamic_stableabi": "/usr/lib/libpython3.so",
44    "static": "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a",
45    "link_extensions": true
46  },
47  "c_api": {
48    "headers": "/usr/include/python3.14",
49    "pkgconfig_path": "/usr/lib/pkgconfig"
50  }
51}

JSON 스키마

  1{
  2  "$schema": "https://json-schema.org/draft/2020-12/schema",
  3  "$id": "https://github.com/python/peps/blob/main/peps/pep-0739/python-build-info-v1.0.schema.json",
  4  "type": "object",
  5  "title": "build-details.json — a static description file with build details of Python installations",
  6  "required": [
  7    "schema_version",
  8    "base_prefix",
  9    "platform",
 10    "language",
 11    "implementation"
 12  ],
 13  "additionalProperties": false,
 14  "properties": {
 15    "schema_version": {
 16      "type": "string",
 17      "description": "Schema version.\n\nThis is a string following the format ``<MAJOR>.<MINOR>``, where ``<MAJOR>`` and ``<MINOR>`` are unpaded numbers and represent the **major** and **minor** components of the version. Versions may be arithmetically compared by intrepreting the version string as a decimal number.\n\nFor this specification version, this value is constant and **MUST** be ``1.0``.\n\nFuture versions of this schema **MUST** use a higher version number. Future versions of this schema **MUST NOT** use the same **major** version component as other schema version unless its specification is deemed backwards-compatible with them — it can't change, or extend, any parts of the current specification in such a way as the semantics of the interpreted data differ, or that data valid under the new specification is invalid under the older specification, with the exception of additional properties (errors caused by ``additionalProperties``).",
 18      "const": "1.0"
 19    },
 20    "base_prefix": {
 21      "type": "string",
 22      "description": "Base prefix of the Python installation.\n\nEither an absolute path, or a path relative to directory where this file is contained.",
 23      "examples": [
 24        "/usr",
 25        "../.."
 26      ]
 27    },
 28    "base_interpreter": {
 29        "type": "string",
 30        "description": "The path to the Python interprer of the base installation.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the installation provides an interpreter executable.",
 31        "examples": [
 32          "/usr/bin/python",
 33          "bin/python"
 34        ]
 35    },
 36    "platform": {
 37      "type": "string",
 38      "description": "System platform string.\n\nThis field **SHOULD** be equivalent to ``sysconfig.get_platform()``.",
 39      "examples": [
 40        "linux-x86_64"
 41      ]
 42    },
 43    "language": {
 44      "type": "object",
 45      "description": "Object containing details related to the Python language specification.",
 46      "required": [
 47        "version"
 48      ],
 49      "additionalProperties": false,
 50      "properties": {
 51        "version": {
 52          "type": "string",
 53          "description": "String representation the Python language version — a version string consisting only of the *major* and *minor* components.\n\nThis field **SHOULD** be equivalent to ``sysconfig.get_python_version()``.",
 54          "examples": ["3.14"]
 55        },
 56        "version_info": {
 57          "type": "object",
 58          "description": "Object in the format of :py:data:`sys.version_info`.\n\nThis section **SHOULD** be equivalent to :py:data:`sys.version_info`.",
 59          "required": ["major", "minor", "micro", "releaselevel", "serial"],
 60          "additionalProperties": false,
 61          "examples": [
 62            {
 63              "major": 3,
 64              "minor": 14,
 65              "micro": 1,
 66              "releaselevel": "final",
 67              "serial": 0
 68            }
 69          ],
 70          "properties": {
 71            "major": {
 72              "type": "number"
 73            },
 74            "minor": {
 75              "type": "number"
 76            },
 77            "micro": {
 78              "type": "number"
 79            },
 80            "releaselevel": {
 81              "type": "string",
 82              "enum": ["alpha", "beta", "candidate", "final"]
 83            },
 84            "serial": {
 85              "type": "number"
 86            }
 87          }
 88        }
 89      }
 90    },
 91    "implementation": {
 92      "type": "object",
 93      "description": "Object containing details related to Python implementation.\n\nThis section **SHOULD** be equivalent to :py:data:`sys.implementation`. It follows specification defined in PEP 421, meaning that on top of the required keys, implementation-specific keys can also exist, but must be prefixed with an underscore.",
 94      "required": [
 95        "name",
 96        "version",
 97        "hexversion",
 98        "cache_tag"
 99      ],
100      "additionalProperties": true,
101      "properties": {
102        "name": {
103          "type": "string",
104          "description": "Lower-case name of the Python implementation.",
105          "examples": ["cpython", "pypy"]
106        },
107        "version": {
108          "type": "object",
109          "description": "Object in the format of :py:data:`sys.version_info`, containing the implementation version.",
110          "required": ["major", "minor", "micro", "releaselevel", "serial"],
111          "additionalProperties": false,
112          "examples": [
113            {
114              "major": 3,
115              "minor": 14,
116              "micro": 1,
117              "releaselevel": "final",
118              "serial": 0
119            },
120            {
121              "major": 7,
122              "minor": 3,
123              "micro": 16,
124              "releaselevel": "final",
125              "serial": 0
126            }
127          ],
128          "properties": {
129            "major": {
130              "type": "number"
131            },
132            "minor": {
133              "type": "number"
134            },
135            "micro": {
136              "type": "number"
137            },
138            "releaselevel": {
139              "type": "string",
140              "enum": ["alpha", "beta", "candidate", "final"]
141            },
142            "serial": {
143              "type": "number"
144            }
145          }
146        }
147      }
148    },
149    "abi": {
150      "type": "object",
151      "description": "Object containing details related to ABI.",
152      "required": [
153        "flags"
154      ],
155      "additionalProperties": false,
156      "properties": {
157        "flags": {
158          "type": "array",
159          "description": "Build configuration flags, used to calculate the extension suffix.\n\nThe flags **MUST** be defined in the order they appear on the extension suffix.",
160          "additionalProperties": true,
161          "examples": [
162            ["t", "d"]
163          ]
164        },
165        "extension_suffix": {
166          "type": "string",
167          "description": "Suffix used for extensions built against the current implementation version.\n\nThis field **MUST** be present if the Python implementation supports extensions, otherwise this entry will be missing.",
168          "examples": [
169            ".cpython-314-x86_64-linux-gnu.so"
170          ]
171        },
172        "stable_abi_suffix": {
173          "type": "string",
174          "description": "Suffix used for extensions built against the stable ABI.\n\nThis field **MUST** be present if the Python implementation has a stable ABI extension suffix, otherwise this entry will be missing.",
175          "examples": [
176            ".abi3.so"
177          ]
178        }
179      }
180    },
181    "suffixes": {
182      "type": "object",
183      "description": "Valid module suffixes grouped by type.\n\nThis section **MUST** be present if the Python installation supports importing external files, and it **SHOULD** be equivalent to the ``importlib.machinery.*_SUFFIXES`` attributes.\n\nAdditionally, if a Python implementation provides extension kinds other than the ones listed on ``importlib.machinery`` module, they **MAY** add a sub-section for them.",
184      "examples": [
185        {
186          "source": [".py"],
187          "bytecode": [".pyc"],
188          "optimized_bytecode": [".pyc"],
189          "debug_bytecode": [".pyc"],
190          "extensions": [".cpython-313-x86_64-linux-gnu.so", ".abi3.so", ".so"]
191        }
192      ]
193    },
194    "libpython": {
195      "type": "object",
196      "description": "Object containing details related to the ``libpython`` library.\n\nThis section **MUST** by present if Python installation provides a ``libpython`` library, otherwise this section will be missing.",
197      "additionalProperties": false,
198      "properties": {
199        "dynamic": {
200          "type": "string",
201          "description": "The path to the dynamic ``libpython`` library.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing.",
202          "examples": [
203            "/usr/lib/libpython3.14.so.1.0",
204            "lib/libpython3.14.so.1.0"
205          ]
206        },
207        "dynamic_stableabi": {
208          "type": "string",
209          "description": "The path to the dynamic ``libpython`` library for the stable ABI.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python installation provides a dynamic ``libpython`` library targetting the Stable ABI, otherwise this entry will be missing.\n\nIf this key is present ``dynamic`` **MUST** also be set.",
210          "examples": [
211            "/usr/lib/libpython3.so",
212            "lib/libpython3.so"
213          ]
214        },
215        "static": {
216          "type": "string",
217          "description": "The path to the static ``libpython`` library.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python installation provides a static ``libpython`` library, otherwise this entry will be missing.",
218          "examples": [
219            "/usr/lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a",
220            "lib/python3.14/config-3.14-x86_64-linux-gnu/libpython3.14.a"
221          ]
222        },
223        "link_extensions": {
224          "type": "boolean",
225          "description": "Should extensions built against a dynamic ``libpython`` link to it?\n\nThis field **MUST** be present if the Python installation provides a dynamic ``libpython`` library, otherwise this entry will be missing."
226        }
227      }
228    },
229    "c_api": {
230      "type": "object",
231      "description": "Object containing details related to the Python C API.\n\nThis section **MUST** be present if the Python implementation provides a C API, otherwise this section will be missing.",
232      "required": [
233        "headers"
234      ],
235      "additionalProperties": false,
236      "properties": {
237        "headers": {
238          "type": "string",
239          "description": "The path to the C API headers.\n\nEither an absolute path, or a path relative to ``base_prefix``.",
240          "examples": [
241            "/usr/include/python3.14",
242            "include/python3.14"
243          ]
244        },
245        "pkgconfig_path": {
246          "type": "string",
247          "description": "The path to the pkg-config definition files.\n\nEither an absolute path, or a path relative to ``base_prefix``.\n\nThis field **MUST** be present if the Python implementation provides pkg-config definition files, otherwise this section will be missing.",
248          "examples": [
249            "/usr/lib/pkgconfig",
250            "lib/pkgconfig"
251          ]
252        }
253      }
254    },
255    "arbitrary_data": {
256      "type": "object",
257      "description": "Object containing extra arbitrary data.\n\nThis is meant to be used as an escape-hatch, to include any relevant data that is not covered by this specification. Implementations may choose what data to provide in this section.",
258      "additionalProperties": true
259    }
260  }
261}

거부된 아이디어

환경별 데이터 포함

이 PEP의 논의에서 주요 요청 중 하나는 site-packages 경로와 같은 다른 종류의 정보를 포함하는 것이었습니다. PEP 작성자들은 Python 환경에 관한 정보는 별도의 파일에서 제공해야 한다고 생각합니다.

환경별 데이터를 구성 파일에 포함하면 해당 파일도 환경별 파일이 되므로, 가상 환경마다 자체 구성 파일이 필요합니다. 이는 가상 환경이 기본 Python 설치의 업데이트 이후에도 유지되기 때문에 문제가 됩니다. 이로 인해 정적 구성 파일이 오래되어 데이터의 신뢰성이 떨어질 수 있으며, 이는 정적 구성 파일의 목적을 무력화합니다.

이 PEP에서 부분적으로 구현된 제안된 해결책은 기본 Python 설치를 참조하는 build-details.json 파일과 특정 환경을 참조하는 environment.json 파일을 두는 것입니다.

build-details.json이 Python 배포의 일부이므로 기본 Python 설치가 업데이트되면 build-details.json도 업데이트되며, 정적 설명 파일이 절대 오래되지 않도록 보장합니다.