-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
/
Copy pathpep-0426.txt
1607 lines (1169 loc) · 63 KB
/
pep-0426.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
PEP: 426
Title: Metadata for Python Software Packages 2.0
Version: $Revision$
Last-Modified: $Date$
Author: Nick Coghlan <[email protected]>,
Daniel Holth <[email protected]>,
Donald Stufft <[email protected]>
BDFL-Delegate: Donald Stufft <[email protected]>
Discussions-To: Distutils SIG <[email protected]>
Status: Draft
Type: Informational
Content-Type: text/x-rst
Requires: 440, 508, 518
Created: 30 Aug 2012
Post-History: 14 Nov 2012, 5 Feb 2013, 7 Feb 2013, 9 Feb 2013,
27 May 2013, 20 Jun 2013, 23 Jun 2013, 14 Jul 2013,
21 Dec 2013
Replaces: 345
Abstract
========
This PEP describes a mechanism for publishing and exchanging metadata
related to Python distributions. It includes specifics of the field names,
and their semantics and usage.
This document specifies version 2.0 of the metadata format.
Version 1.0 is specified in PEP 241.
Version 1.1 is specified in PEP 314.
Version 1.2 is specified in PEP 345.
Version 2.0 of the metadata format migrates from directly defining a
custom key-value file format to instead defining a JSON-compatible in-memory
representation that may be used to define metadata representation in other
contexts (such as API and archive format definitions).
This version also defines a formal extension mechanism, allowing new
fields to be added for particular purposes without requiring updates to
the core metadata format.
Note on PEP Deferral
====================
This PEP was deferred for an extended period, from December 2013 through to
March 2017, as distutils-sig worked through a number of other changes. These
changes included:
* defining a binary compatibility tagging format in PEP 425
* defining a binary archive format (``wheel``) in PEP 427
* explicitly defining versioning and version comparison in PEP 440
* explicitly defining the PyPI "simple" API in PEP 503
* explicitly defining dependency specifiers and the extras system in PEP 508
* declaring static build system dependencies (``pyproject.toml``) in PEP 518
* migrating PyPI hosting to Rackspace, and placing it behind the Fastly CDN
* shipping ``pip`` with CPython by default in PEP 453, and backporting that
addition to Python 2.7 in PEP 477
* establishing `packaging.python.org`_ as the common access point for Python
packaging ecosystem documentation
* migrating to using the `specifications`_ section of packaging.python.org
as the central location for tracking packaging related PEPs
The time spent pursuing these changes provided additional perspective on which
metadata format changes were genuinely desirable, and which could be omitted
from the revised specification as merely being "change for change's sake".
It is allowed a number of features that aren't critical to the core activity
of publishing and distributing software to be moved out to PEP 459, a separate
proposal for a number of standard metadata extensions that provide additional
optional information about a release.
.. _packaging.python.org: https://packaging.python.org/
.. _specifications: https://packaging.python.org/specifications/
Purpose
=======
The purpose of this PEP is to define a common metadata interchange format
for communication between software publication tools and software integration
tools in the Python ecosystem. One key aim is to support full dependency
analysis in that ecosystem without requiring the execution of arbitrary
Python code by those doing the analysis. Another aim is to encourage good
software distribution practices by default, while continuing to support the
current practices of almost all existing users of the Python Package Index
(both publishers and integrators). Finally, the aim is to support an upgrade
path from the currently in use metadata formats that is transparent to end
users.
The design draws on the Python community's nearly 20 years of experience with
distutils based software distribution, and incorporates ideas and concepts
from other distribution systems, including Python's setuptools, pip and
other projects, Ruby's gems, Perl's CPAN, Node.js's npm, PHP's composer
and Linux packaging systems such as RPM and APT.
While the specifics of this format are aimed at the Python ecosystem, some
of the ideas may also be useful in the future evolution of other dependency
management ecosystems.
Development, Distribution and Deployment of Python Software
===========================================================
The metadata design in this PEP is based on a particular conceptual model
of the software development and distribution process. This model consists of
the following phases:
* Software development: this phase involves working with a source checkout
for a particular application to add features and fix bugs. It is
expected that developers in this phase will need to be able to build the
software, run the software's automated test suite, run project specific
utility scripts and publish the software.
* Software publication: this phase involves taking the developed software
and making it available for use by software integrators. This includes
creating the descriptive metadata defined in this PEP, as well as making
the software available (typically by uploading it to an index server).
* Software integration: this phase involves taking published software
components and combining them into a coherent, integrated system. This
may be done directly using Python specific cross-platform tools, or it may
be handled through conversion to development language neutral platform
specific packaging systems.
* Software deployment: this phase involves taking integrated software
components and deploying them on to the target system where the software
will actually execute.
The publication and integration phases are collectively referred to as
the distribution phase, and the individual software components distributed
in that phase are formally referred to as "distribution packages", but are more
colloquially known as just "packages" (relying on context to disambiguate them
from the "module with submodules" kind of Python package).
The exact details of these phases will vary greatly for particular use cases.
Deploying a web application to a public Platform-as-a-Service provider,
publishing a new release of a web framework or scientific library,
creating an integrated Linux distribution, or upgrading a custom application
running in a secure enclave are all situations this metadata design should
be able to handle.
The complexity of the metadata described in this PEP thus arises directly
from the actual complexities associated with software development,
distribution and deployment in a wide range of scenarios.
Supporting definitions
----------------------
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119.
"Projects" are software components that are made available for integration.
Projects include Python libraries, frameworks, scripts, plugins,
applications, collections of data or other resources, and various
combinations thereof. Public Python projects are typically registered on
the `Python Package Index`_.
"Releases" are uniquely identified snapshots of a project.
"Distribution packages" are the packaged files which are used to publish
and distribute a release.
Depending on context, "package" may refer to either a distribution, or
to an importable Python module that has a ``__path__`` attribute and hence
may also have importable submodules.
"Source archive" and "VCS checkout" both refer to the raw source code for
a release, prior to creation of an sdist or binary archive.
An "sdist" is a publication format providing the distribution metadata and
any source files that are essential to creating a binary archive for
the distribution. Creating a binary archive from an sdist requires that
the appropriate build tools be available on the system.
"Binary archives" only require that prebuilt files be moved to the correct
location on the target system. As Python is a dynamically bound
cross-platform language, many so-called "binary" archives will contain only
pure Python source code.
"Contributors" are individuals and organizations that work together to
develop a software component.
"Publishers" are individuals and organizations that make software components
available for integration (typically by uploading distributions to an
index server)
"Integrators" are individuals and organizations that incorporate published
distributions as components of an application or larger system.
"Build tools" are automated tools intended to run on development systems,
producing source and binary distribution archives. Build tools may also be
invoked by integration tools in order to build software distributed as
sdists rather than prebuilt binary archives.
"Index servers" are active distribution registries which publish version and
dependency metadata and place constraints on the permitted metadata.
"Public index servers" are index servers which allow distribution uploads
from untrusted third parties. The `Python Package Index`_ is a public index
server.
"Publication tools" are automated tools intended to run on development
systems and upload source and binary distribution archives to index servers.
"Integration tools" are automated tools that consume the metadata and
distribution archives published by an index server or other designated
source, and make use of them in some fashion, such as installing them or
converting them to a platform specific packaging format.
"Installation tools" are integration tools specifically intended to run on
deployment targets, consuming source and binary distribution archives from
an index server or other designated location and deploying them to the target
system.
"Automated tools" is a collective term covering build tools, index servers,
publication tools, integration tools and any other software that produces
or consumes distribution version and dependency metadata.
"Legacy metadata" refers to earlier versions of this metadata specification,
along with the supporting metadata file formats defined by the
``setuptools`` project.
"Distro" is used as the preferred term for Linux distributions, to help
avoid confusion with the Python-specific use of the term "distribution
package".
"Qualified name" is a dotted Python identifier. For imported modules and
packages, the qualified name is available as the ``__name__`` attribute,
while for functions and classes it is available as the ``__qualname__``
attribute.
A "fully qualified name" uniquely locates an object in the Python module
namespace. For imported modules and packages, it is the same as the
qualified name. For other Python objects, the fully qualified name consists
of the qualified name of the containing module or package, a colon (``:``)
and the qualified name of the object relative to the containing module or
package.
A "prefixed name" starts with a qualified name, but is not necessarily a
qualified name - it may contain additional dot separated segments which are
not valid identifiers.
Integration and deployment of distributions
-------------------------------------------
The primary purpose of the distribution metadata is to support integration
and deployment of distributions as part of larger applications and systems.
Integration and deployment can in turn be broken down into further substeps.
* Build: the build step is the process of turning a VCS checkout, source
archive or sdist into a binary archive. Dependencies must be available
in order to build and create a binary archive of the distribution
(including any documentation that is installed on target systems).
* Installation: the installation step involves getting the distribution
and all of its runtime dependencies onto the target system. In this
step, the distribution may already be on the system (when upgrading or
reinstalling) or else it may be a completely new installation.
* Runtime: this is normal usage of a distribution after it has been
installed on the target system.
These three steps may all occur directly on the target system. Alternatively
the build step may be separated out by using binary archives provided by the
publisher of the distribution, or by creating the binary archives on a
separate system prior to deployment. The advantage of the latter approach
is that it minimizes the dependencies that need to be installed on
deployment targets (as the build dependencies will be needed only on the
build systems).
The published metadata for distribution packages SHOULD allow integrators, with
the aid of build and integration tools, to:
* obtain the original source code that was used to create a distribution
* identify and retrieve the dependencies (if any) required to use a
distribution
* identify and retrieve the dependencies (if any) required to build a
distribution from source
* identify and retrieve the dependencies (if any) required to run a
distribution's test suite
Development and publication of distributions
--------------------------------------------
The secondary purpose of the distribution metadata is to support effective
collaboration amongst software contributors and publishers during the
development phase.
The published metadata for distributions SHOULD allow contributors
and publishers, with the aid of build and publication tools, to:
* perform all the same activities needed to effectively integrate and
deploy the distribution
* identify and retrieve the additional dependencies needed to develop and
publish the distribution
* specify the dependencies (if any) required to use the distribution
* specify the dependencies (if any) required to build the distribution
from source
* specify the dependencies (if any) required to run the distribution's
test suite
* specify the additional dependencies (if any) required to develop and
publish the distribution
Metadata format
===============
The format defined in this PEP is an in-memory representation of Python
distribution metadata as a string-keyed dictionary. Permitted values for
individual entries are strings, lists of strings, and additional
nested string-keyed dictionaries.
Except where otherwise noted, dictionary keys in distribution metadata MUST
be valid Python identifiers in order to support attribute based metadata
access APIs.
The individual field descriptions show examples of the key name and value
as they would be serialised as part of a JSON mapping.
Unless otherwise indicated, the fields identified as core metadata are required.
Automated tools MUST NOT accept distributions with missing core metadata as
valid Python distributions.
All other fields are optional. Automated tools MUST operate correctly
if a distribution does not provide them, except for those operations
which specifically require the omitted fields.
Automated tools MUST NOT insert dummy data for missing fields. If a valid
value is not provided for a required field then the metadata and the
associated distribution MUST be rejected as invalid. If a valid value
is not provided for an optional field, that field MUST be omitted entirely.
Automated tools MAY automatically derive valid values from other
information sources (such as a version control system).
Automated tools, especially public index servers, MAY impose additional
length restrictions on metadata beyond those enumerated in this PEP. Such
limits SHOULD be imposed where necessary to protect the integrity of a
service, based on the available resources and the service provider's
judgment of reasonable metadata capacity requirements.
Metadata files
--------------
The information defined in this PEP is serialised to ``pydist.json``
files for some use cases. These are files containing UTF-8 encoded JSON
metadata.
Each metadata file consists of a single serialised mapping, with fields as
described in this PEP. When serialising metadata, automated tools SHOULD
lexically sort any keys and list elements in order to simplify reviews
of any changes.
There are expected to be three standard locations for these metadata files:
* as a ``{distribution}-{version}.dist-info/pydist.json`` file in an
``sdist`` source distribution archive
* as a ``{distribution}-{version}.dist-info/pydist.json`` file in a ``wheel``
binary distribution archive
* as a ``{distribution}-{version}.dist-info/pydist.json`` file in a local
Python installation database
.. note::
These locations are to be confirmed, since they depend on the definition
of sdist 2.0 and the revised installation database standard. There will
also be a wheel 1.1 format update after this PEP is approved that
mandates provision of 2.0+ metadata.
Note that these metadata files MAY be processed even if the version of the
containing location is too low to indicate that they are valid. Specifically,
unversioned ``sdist`` archives, unversioned installation database directories
and version 1.0 of the ``wheel`` specification may still provide ``pydist.json``
files.
.. note::
Until this specification is formally marked as Active, it is recommended
that tools following the draft format use an alternative filename like
``metadata.json`` or ``pep426-20131213.json`` to avoid colliding with
the eventually standardised files.
Other tools involved in Python distribution MAY also use this format.
As JSON files are generally awkward to edit by hand, it is RECOMMENDED
that these metadata files be generated by build tools based on other
input formats (such as ``setup.py`` and ``pyproject.toml``) rather than being
used directly as a data input format. Generating the metadata as part of the
publication process also helps to deal with version specific fields (including
the source URL and the version field itself).
For backwards compatibility with older installation tools, metadata 2.0
files MAY be distributed alongside legacy metadata.
Index servers MAY allow distributions to be uploaded and installation tools
MAY allow distributions to be installed with only legacy metadata.
Automated tools MAY attempt to automatically translate legacy metadata to
the format described in this PEP. Advice for doing so effectively is given
in Appendix A.
Metadata validation
-------------------
A `jsonschema <https://pypi.python.org/pypi/jsonschema>`__ description of
the distribution metadata is `available
<http://hg.python.org/peps/file/default/pep-0426/pydist-schema.json>`__.
This schema does NOT currently handle validation of some of the more complex
string fields (instead treating them as opaque strings).
Except where otherwise noted, all URL fields in the metadata MUST comply
with RFC 3986.
.. note::
The current version of the schema file covers the previous draft of the
PEP, and has not yet been updated for the split into the essential
dependency resolution metadata and multiple standard extensions, and nor
has it been updated for the replacement of the various "semantic dependency"
fields with particular conventional "extras" declarations.
Core metadata
=============
This section specifies the core metadata fields that are required for every
Python distribution.
Publication tools MUST ensure at least these fields are present when
publishing a distribution.
Index servers MUST ensure at least these fields are present in the metadata
when distributions are uploaded.
Installation tools MUST refuse to install distributions with one or more
of these fields missing by default, but MAY allow users to force such an
installation to occur.
Metadata version
----------------
Version of the file format; ``"2.0"`` is the only legal value.
Automated tools consuming metadata SHOULD warn if ``metadata_version`` is
greater than the highest version they support, and MUST fail if
``metadata_version`` has a greater major version than the highest
version they support (as described in PEP 440, the major version is the
value before the first dot).
For broader compatibility, build tools MAY choose to produce
distribution metadata using the lowest metadata version that includes
all of the needed fields.
Example::
"metadata_version": "2.0"
Generator
---------
Name (and optional version) of the program that generated the file,
if any. A manually produced file would omit this field.
Examples::
"generator": "flit"
"generator": "setuptools (34.3.1)"
Name
----
The name of the distribution, as defined in PEP 508.
As distribution names are used as part of URLs, filenames, command line
parameters and must also interoperate with other packaging systems, the
permitted characters are constrained to:
* ASCII letters (``[a-zA-Z]``)
* ASCII digits (``[0-9]``)
* underscores (``_``)
* hyphens (``-``)
* periods (``.``)
Distribution names MUST start and end with an ASCII letter or digit.
Automated tools MUST reject non-compliant names. A regular expression to
enforce these constraints (when run with ``re.IGNORECASE``) is::
^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$
All comparisons of distribution names MUST be case insensitive, and MUST
consider hyphens and underscores to be equivalent.
Index servers MAY consider "confusable" characters (as defined by the
Unicode Consortium in `TR39: Unicode Security Mechanisms <TR39>`_) to be
equivalent.
Index servers that permit arbitrary distribution name registrations from
untrusted sources SHOULD consider confusable characters to be equivalent
when registering new distributions (and hence reject them as duplicates).
Integration tools MUST NOT silently accept a confusable alternate
spelling as matching a requested distribution name.
At time of writing, the characters in the ASCII subset designated as
confusables by the Unicode Consortium are:
* ``1`` (DIGIT ONE), ``l`` (LATIN SMALL LETTER L), and ``I`` (LATIN CAPITAL
LETTER I)
* ``0`` (DIGIT ZERO), and ``O`` (LATIN CAPITAL LETTER O)
Example::
"name": "ComfyChair"
Version
-------
The distribution's public or local version identifier, as defined in PEP 440.
Version identifiers are designed for consumption by automated tools and
support a variety of flexible version specification mechanisms (see PEP 440
for details).
Version identifiers MUST comply with the format defined in PEP 440.
Version identifiers MUST be unique within each project.
Index servers MAY place restrictions on the use of local version identifiers
as described in PEP 440.
Example::
"version": "1.0a2"
Summary
-------
A short summary of what the distribution does.
This field SHOULD contain fewer than 512 characters and MUST contain fewer
than 2048.
This field SHOULD NOT contain any line breaks.
A more complete description SHOULD be included as a separate file in the
sdist for the distribution. Refer to the ``python-details`` extension in
:pep:`459` for more information.
Example::
"summary": "A module that is more fiendish than soft cushions."
Source code metadata
====================
This section specifies fields that provide identifying details for the
source code used to produce this distribution.
All of these fields are optional. Automated tools MUST operate correctly if
a distribution does not provide them, including failing cleanly when an
operation depending on one of these fields is requested.
Source labels
-------------
Source labels are text strings with minimal defined semantics. They are
intended to allow the original source code to be unambiguously identified,
even if an integrator has applied additional local modifications to a
particular distribution.
To ensure source labels can be readily incorporated as part of file names
and URLs, and to avoid formatting inconsistencies in hexadecimal hash
representations they MUST be limited to the following set of permitted
characters:
* Lowercase ASCII letters (``[a-z]``)
* ASCII digits (``[0-9]``)
* underscores (``_``)
* hyphens (``-``)
* periods (``.``)
* plus signs (``+``)
Source labels MUST start and end with an ASCII letter or digit.
A regular expression to rnforce these constraints (when run with
``re.IGNORECASE``) is::
^([A-Z0-9]|[A-Z0-9][A-Z0-9._-+]*[A-Z0-9])$
A source label for a project MUST NOT match any defined version for that
project. This restriction ensures that there is no ambiguity between version
identifiers and source labels.
Examples::
"source_label": "1.0.0-alpha.1"
"source_label": "1.3.7+build.11.e0f985a"
"source_label": "v1.8.1.301.ga0df26f"
"source_label": "2013.02.17.dev123"
Source URL
----------
A string containing a full URL where the source for this specific version of
the distribution can be downloaded.
Source URLs MUST be unique within each project. This means that the URL
can't be something like ``"https://github.com/pypa/pip/archive/master.zip"``,
but instead must be ``"https://github.com/pypa/pip/archive/1.3.1.zip"``.
The source URL MUST reference either a source archive or a tag or specific
commit in an online version control system that permits creation of a
suitable VCS checkout. It is intended primarily for integrators that
wish to recreate the distribution from the original source form.
All source URL references SHOULD specify a secure transport mechanism
(such as ``https``) AND include an expected hash value in the URL for
verification purposes. If a source URL is specified without any hash
information, with hash information that the tool doesn't understand, or
with a selected hash algorithm that the tool considers too weak to trust,
automated tools SHOULD at least emit a warning and MAY refuse to rely on
the URL. If such a source URL also uses an insecure transport, automated
tools SHOULD NOT rely on the URL.
For source archive references, an expected hash value may be specified by
including a ``<hash-algorithm>=<expected-hash>`` entry as part of the URL
fragment.
As of 2017, it is RECOMMENDED that ``'sha256'`` hashes be used for source
URLs, as this hash is not yet known to be vulnerable to generation of
malicious collisions, while also being widely available on client systems.
For version control references, the ``VCS+protocol`` scheme SHOULD be
used to identify both the version control system and the secure transport,
and a version control system with hash based commit identifiers SHOULD be
used. Automated tools MAY omit warnings about missing hashes for version
control systems that do not provide hash based commit identifiers.
To handle version control systems that do not support including commit or
tag references directly in the URL, that information may be appended to the
end of the URL using the ``@<commit-hash>`` or the ``@<tag>#<commit-hash>``
notation.
.. note::
This isn't *quite* the same as the existing VCS reference notation
supported by pip. Firstly, the distribution name is a separate field rather
than embedded as part of the URL. Secondly, the commit hash is included
even when retrieving based on a tag, in order to meet the requirement
above that *every* link should include a hash to make things harder to
forge (creating a malicious repo with a particular tag is easy, creating
one with a specific *hash*, less so).
Example::
"source_url": "https://github.com/pypa/pip/archive/1.3.1.zip#sha256=2dc6b5a470a1bde68946f263f1af1515a2574a150a30d6ce02c6ff742fcc0db8
"source_url": "git+https://github.com/pypa/[email protected]#7921be1537eac1e97bc40179a57f0349c2aee67d"
"source_url": "git+https://github.com/pypa/pip.git@7921be1537eac1e97bc40179a57f0349c2aee67d"
Semantic dependencies
=====================
Dependency metadata allows published projects to make use of functionality
provided by other published projects, without needing to bundle copies of
particular releases of those projects.
Semantic dependencies allow publishers to indicate not only which other
projects are needed, but also *why* they're needed. This additional
information allows integrators to install just the dependencies they need
for specific activities, making it easier to minimise installation
footprints in constrained environments (regardless of the reasons for
those constraints).
By default, dependency declarations are assumed to be for
"runtime dependencies": other releases that are needed to actually use the
published release.
There are also four different kinds of optional dependency that releases may
declare:
* ``test`` dependencies: other releases that are needed to run the
automated test suite for this release, but are not needed just to
use it (e.g. ``nose2`` or ``pytest``)
* ``build`` dependencies: other releases that are needed to build this
a deployable binary version of this release from source
(e.g. ``flit`` or ``setuptools``)
* ``doc`` dependencies: other releases that are needed to build the
documentation for this distribution (e.g. the ``sphinx`` build tool)
* ``dev`` dependencies: other releases that are needed when working on this
distribution, but do not fit into exactly one of the other optional
dependency categories (e.g. ``pylint``, ``flake8``). ``dev`` dependencies
are also effectively considered as combined ``test``, ``build``, and ``doc``
dependencies, without needing to be listed three times
These optional categories are known as
`Extras <Extras (optional dependencies)>`_. In addition to the four
standard categories, projects may also declare their own custom categories
in the `Extras`_ field.
Dependency management is heavily dependent on the version identification
and specification scheme defined in PEP 440 and the dependency specification,
extra, and environment marker schemes defined in PEP 508.
All of these fields are optional. Automated tools MUST operate correctly if
a distribution does not provide them, by assuming that a missing field
indicates "Not applicable for this distribution".
Mapping dependencies to development and distribution activities
---------------------------------------------------------------
The different categories of dependency are based on the various distribution
and development activities identified above, and govern which dependencies
should be installed for the specified activities:
* Required runtime dependencies:
* unconditional dependencies
* Required build dependencies:
* the ``build`` extra
* the ``dev`` extra
* If running the distribution's test suite as part of the build process,
also install the unconditional dependencies and ``test`` extra
* Required development and publication dependencies:
* unconditional dependencies
* the ``test`` extra
* the ``build`` extra
* the ``doc`` extra
* the ``dev`` extra
The notation described in `Extras (optional dependencies)`_ SHOULD be used
to determine exactly what gets installed for various operations.
Installation tools SHOULD report an error if dependencies cannot be
satisfied, MUST at least emit a warning, and MAY allow the user to force
the installation to proceed regardless.
See Appendix B for an overview of mapping these dependencies to an RPM
spec file.
Extras
------
A list of optional sets of dependencies that may be used to define
conditional dependencies in dependency fields. See
`Extras (optional dependencies)`_ for details.
The names of extras MUST abide by the same restrictions as those for
distribution names.
The following extra names are available by default and SHOULD NOT be
declared explicitly:
* ``test``
* ``build``
* ``doc``
* ``dev``
The following extra names are reserved, and MUST NOT be declared:
* ``self``
* ``runtime``
Example::
"extras": ["warmup"]
Dependencies
------------
A list of release requirements needed to actually run this release.
Public index servers MAY prohibit strict version matching clauses or direct
references in this field.
Example::
"dependencies":
{
"requires": ["SciPy", "PasteDeploy", "zope.interface > 3.5.0"]
},
{
"requires": ["pywin32 > 1.0"],
"environment": "sys_platform == 'win32'"
},
{
"requires": ["SoftCushions"],
"extra": "warmup"
}
]
While many dependencies will be needed to use a project release at all, others
are needed only on particular platforms or only when particular optional
features of the release are needed.
To handle this, release dependency specifiers are mappings with the following
subfields:
* ``requires``: a list of requirements needed to satisfy the dependency
* ``extra``: the name of a set of optional dependencies that are requested
and installed together. See `Extras (optional dependencies)`_ for details
* ``environment``: an environment marker defining the environment that
needs these dependencies. The syntax and capabilities of environment
markers are defined in PEP 508
Individual entries in the ``requires`` lists are strings using the dependency
declaration format defined in PEP 508, with the exception that environment
markers MUST NOT be included in the individual dependency declarations, and
are instead supplied in the separate ``environment`` field.
``requires`` is the only required subfield. When it is the only subfield, the
dependencies are said to be *unconditional*. If ``extra`` or ``environment``
is specified, then the dependencies are *conditional*.
All three fields may be supplied, indicating that the dependencies are
needed only when the named extra is requested in a particular environment.
Automated tools MUST combine related dependency specifiers (those with
common values for ``extra`` and ``environment``) into a single specifier
listing multiple requirements when serialising metadata.
Despite this required normalisation, the same extra name or environment
marker MAY appear in multiple conditional dependencies. This may happen,
for example, if an extra itself only needs some of its dependencies in
specific environments. It is only the combination of extras and environment
markers that is required to be unique in a list of dependency specifiers.
Aside from the four standard extra categories, any extras referenced from a
dependency specifier MUST be named in the `Extras`_ field for this distribution.
This helps avoid typographical errors and also makes it straightforward to
identify the available extras without scanning the full set of dependencies.
Provides
--------
A list of strings naming additional dependency requirements that are
satisfied by installing this distribution. These strings must be of the
form ``Name`` or ``Name (Version)``, as for the ``requires`` field.
While dependencies are usually resolved based on distribution names and
versions, a distribution may provide additional names explicitly in the
``provides`` field.
For example, this may be used to indicate that multiple projects have
been merged into and replaced by a single distribution or to indicate
that this project is a substitute for another.
To avoid malicious hijacking of names, when interpreting metadata retrieved
from a public index server, automated tools MUST NOT pay any attention to
``"provides"`` entries that do not correspond to a published distribution.
However, to appropriately handle project forks and mergers, automated tools
MUST accept ``"provides"`` entries that name other distributions when the
entry is retrieved from a local installation database or when there is a
corresponding ``"obsoleted_by"`` entry in the metadata for the named
distribution.
A distribution may wish to depend on a "virtual" project name, which does
not correspond to any separately distributed project: such a name
might be used to indicate an abstract capability which could be supplied
by one of multiple projects. For example, multiple projects might supply
PostgreSQL bindings for use with SQL Alchemy: each project might declare
that it provides ``sqlalchemy-postgresql-bindings``, allowing other
projects to depend only on having at least one of them installed.
To handle this case in a way that doesn't allow for name hijacking, the
authors of the distribution that first defines the virtual dependency should
create a project on the public index server with the corresponding name, and
depend on the specific distribution that should be used if no other provider
is already installed. This also has the benefit of publishing the default
provider in a way that automated tools will understand.
A version declaration may be supplied as part of an entry in the provides
field and must follow the rules described in PEP 440. The distribution's
version identifier will be implied if none is specified.
Example::
"provides": ["AnotherProject (3.4)", "virtual-package"]
Obsoleted by
------------
A string that indicates that this project is no longer being developed. The
named project provides a substitute or replacement.
A version declaration may be supplied and must follow the rules described
in PEP 440.
An inactive project may be explicitly indicated by setting this field to
``None`` (which is serialised as ``null`` in JSON as usual).
Automated tools SHOULD report a warning when installing an obsolete project.
Possible uses for this field include handling project name changes and
project mergers.
Note that without a corresponding ``provides``, there is no expectation
that the replacement project will be a "drop-in" replacement for the
obsolete project - at the very least, upgrading to the new distribution
is likely to require changes to import statements.
Examples::
"name": "BadName",
"obsoleted_by": "AcceptableName"
Metadata Extensions
===================
Extensions to the metadata MAY be present in a mapping under the
``extensions`` key. The keys MUST be valid prefixed names, while
the values MUST themselves be nested mappings.
Two key names are reserved and MUST NOT be used by extensions, except as
described below:
* ``extension_version``
* ``installer_must_handle``
The following example shows the ``python.details`` and ``python.commands``
standard extensions from :pep:`459`::
"extensions" : {
"python.details": {
"license": "GPL version 3, excluding DRM provisions",
"keywords": [
"comfy", "chair", "cushions", "too silly", "monty python"
],
"classifiers": [
"Development Status :: 4 - Beta",
"Environment :: Console (Text Based)",
"License :: OSI Approved :: GNU General Public License v3 (GPLv3)"
],
"document_names": {
"description": "README.rst",
"license": "LICENSE.rst",
"changelog": "NEWS"
}
},
"python.commands": {
"wrap_console": [{"chair": "chair:run_cli"}],
"wrap_gui": [{"chair-gui": "chair:run_gui"}],
"prebuilt": ["reduniforms"]
},
}
Extension names are defined by distributions that will then make use of
the additional published metadata in some way.
To reduce the chance of name conflicts, extension names SHOULD use a
prefix that corresponds to a module name in the distribution that defines
the meaning of the extension. This practice will also make it easier to
find authoritative documentation for metadata extensions.
Metadata extensions allow development tools to record information in the
metadata that may be useful during later phases of distribution, but is
not essential for dependency resolution or building the software.
Extension versioning
--------------------
Extensions MUST be versioned, using the ``extension_version`` key.
However, if this key is omitted, then the implied version is ``1.0``.
Automated tools consuming extension metadata SHOULD warn if
``extension_version`` is greater than the highest version they support,