Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-11 Thread Wes Turner 
On Monday, December 11, 2017, Dustin Ingram  wrote:

> After working a bit on an implementation of the "JSON-compatible
> Metadata" section in this PEP, I'm noticing that it might be more
> useful if it had the following step instead for canonicalizing the
> field names:
>
> > #. All transformed keys should be reduced to lower case. Hyphens should
> be
> >replaced with underscores, but otherwise should retain all other
> characters;
>
> Thus a field like `Description-Content-Type` would become
> `description_content_type` and the resulting data structure would be
> slightly more useful (as it could be passed as `**kwargs` to a
> function with PEP 8 style parameter names)


Good idea.


>
> If no one has any objections to this, I'll update the draft accordingly.
>
> Also, if there is no other feedback on the current draft, I'l be
> formally submitting it for Daniel's review this week.


(Copied and pasted this from above)

>From "[distutils] Multiple package authors" [1]

- How should multiple author-email and maintainer-email addresses be
specified?

- Should we add security-email and/or security-disclosure-instructions?


[1] http://markmail.org/thread/xmwfktnsbmpakv6b


>
> Thanks,
> D.
>
> On Sat, Dec 9, 2017 at 8:27 AM, Daniel Holth  wrote:
> > I don't know why the parentheses were included in the older pep. They are
> > widely deployed. We probably can get rid of them or make them optional
> in a
> > practical parser.
> >
> >
> > On Sat, Dec 9, 2017, 02:03 Nick Coghlan  wrote:
> >>
> >> On 9 December 2017 at 02:42, Thomas Kluyver 
> wrote:
> >> > Dustin asked me to bring this issue to this thread:
> >> >
> >> > Metadata version 1.2 (PEP 345) says that version specifiers within a
> >> > Requires-Dist field should go in parentheses: "zope.interface
> (>3.5.0)".
> >> > The metadata spec on PyPUG repeats this.
> >> >
> >> > However, PEP 508 says that the parentheses are not needed, and tools
> >> > writing dependency specifications should not create them. Its
> >> > recommended format is therefore "zope.interface >3.5.0".
> >> >
> >> > Should the metadata 1.3 PEP note that this has changed? Or do we only
> >> > need to update the metadata spec on PyPUG?
> >>
> >> The new PEP already delegates to PEP 508 for the version specifier
> >> format, so I think that can just be updated in PyPUG.
> >>
> >> Cheers,
> >> Nick.
> >>
> >> --
> >> Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
> >> ___
> >> Distutils-SIG maillist  -  Distutils-SIG@python.org
> >> https://mail.python.org/mailman/listinfo/distutils-sig
> >
> >
> > ___
> > Distutils-SIG maillist  -  Distutils-SIG@python.org
> > https://mail.python.org/mailman/listinfo/distutils-sig
> >
> ___
> Distutils-SIG maillist  -  Distutils-SIG@python.org
> https://mail.python.org/mailman/listinfo/distutils-sig
>
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-11 Thread Dustin Ingram 
After working a bit on an implementation of the "JSON-compatible
Metadata" section in this PEP, I'm noticing that it might be more
useful if it had the following step instead for canonicalizing the
field names:

> #. All transformed keys should be reduced to lower case. Hyphens should be
>replaced with underscores, but otherwise should retain all other 
> characters;

Thus a field like `Description-Content-Type` would become
`description_content_type` and the resulting data structure would be
slightly more useful (as it could be passed as `**kwargs` to a
function with PEP 8 style parameter names)

If no one has any objections to this, I'll update the draft accordingly.

Also, if there is no other feedback on the current draft, I'l be
formally submitting it for Daniel's review this week.

Thanks,
D.

On Sat, Dec 9, 2017 at 8:27 AM, Daniel Holth  wrote:
> I don't know why the parentheses were included in the older pep. They are
> widely deployed. We probably can get rid of them or make them optional in a
> practical parser.
>
>
> On Sat, Dec 9, 2017, 02:03 Nick Coghlan  wrote:
>>
>> On 9 December 2017 at 02:42, Thomas Kluyver  wrote:
>> > Dustin asked me to bring this issue to this thread:
>> >
>> > Metadata version 1.2 (PEP 345) says that version specifiers within a
>> > Requires-Dist field should go in parentheses: "zope.interface (>3.5.0)".
>> > The metadata spec on PyPUG repeats this.
>> >
>> > However, PEP 508 says that the parentheses are not needed, and tools
>> > writing dependency specifications should not create them. Its
>> > recommended format is therefore "zope.interface >3.5.0".
>> >
>> > Should the metadata 1.3 PEP note that this has changed? Or do we only
>> > need to update the metadata spec on PyPUG?
>>
>> The new PEP already delegates to PEP 508 for the version specifier
>> format, so I think that can just be updated in PyPUG.
>>
>> Cheers,
>> Nick.
>>
>> --
>> Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
>> ___
>> Distutils-SIG maillist  -  Distutils-SIG@python.org
>> https://mail.python.org/mailman/listinfo/distutils-sig
>
>
> ___
> Distutils-SIG maillist  -  Distutils-SIG@python.org
> https://mail.python.org/mailman/listinfo/distutils-sig
>
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-09 Thread Daniel Holth 
I don't know why the parentheses were included in the older pep. They are
widely deployed. We probably can get rid of them or make them optional in a
practical parser.

On Sat, Dec 9, 2017, 02:03 Nick Coghlan  wrote:

> On 9 December 2017 at 02:42, Thomas Kluyver  wrote:
> > Dustin asked me to bring this issue to this thread:
> >
> > Metadata version 1.2 (PEP 345) says that version specifiers within a
> > Requires-Dist field should go in parentheses: "zope.interface (>3.5.0)".
> > The metadata spec on PyPUG repeats this.
> >
> > However, PEP 508 says that the parentheses are not needed, and tools
> > writing dependency specifications should not create them. Its
> > recommended format is therefore "zope.interface >3.5.0".
> >
> > Should the metadata 1.3 PEP note that this has changed? Or do we only
> > need to update the metadata spec on PyPUG?
>
> The new PEP already delegates to PEP 508 for the version specifier
> format, so I think that can just be updated in PyPUG.
>
> Cheers,
> Nick.
>
> --
> Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
> ___
> Distutils-SIG maillist  -  Distutils-SIG@python.org
> https://mail.python.org/mailman/listinfo/distutils-sig
>
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-08 Thread Nick Coghlan 
On 9 December 2017 at 02:42, Thomas Kluyver  wrote:
> Dustin asked me to bring this issue to this thread:
>
> Metadata version 1.2 (PEP 345) says that version specifiers within a
> Requires-Dist field should go in parentheses: "zope.interface (>3.5.0)".
> The metadata spec on PyPUG repeats this.
>
> However, PEP 508 says that the parentheses are not needed, and tools
> writing dependency specifications should not create them. Its
> recommended format is therefore "zope.interface >3.5.0".
>
> Should the metadata 1.3 PEP note that this has changed? Or do we only
> need to update the metadata spec on PyPUG?

The new PEP already delegates to PEP 508 for the version specifier
format, so I think that can just be updated in PyPUG.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-08 Thread Thomas Kluyver 
Dustin asked me to bring this issue to this thread:

Metadata version 1.2 (PEP 345) says that version specifiers within a
Requires-Dist field should go in parentheses: "zope.interface (>3.5.0)".
The metadata spec on PyPUG repeats this.

However, PEP 508 says that the parentheses are not needed, and tools
writing dependency specifications should not create them. Its
recommended format is therefore "zope.interface >3.5.0".

Should the metadata 1.3 PEP note that this has changed? Or do we only
need to update the metadata spec on PyPUG?

(I'm writing some validation code for flit, and quickly seeing the value
in having the latest information in one place, rather than scattered
across several PEPs)

Thomas

On Tue, Dec 5, 2017, at 04:39 PM, Dustin Ingram wrote:
> Hi all,
> 
> I'd appreciate your feedback on the following Metadata 1.3 PEP.
> 
> The goal here is not to provide a full specification for all fields as
> in previous PEPs, but to:
> 
> * Motivate and describe the addition of the new fields or changes to
> existing fields;
> * Point to the Core Metadata Specifications reference document as the
> canonical source for the specification.
> 
> Previous discussions:
> *
> https://mail.python.org/pipermail/distutils-sig/2017-September/031465.html
> * https://github.com/python/peps/issues/388
> 
> Thanks,
> D.
> 
> 
> PEP: 566
> Title: Metadata for Python Software Packages 1.3
> Version: $Revision$
> Last-Modified: $Date$
> Author: Dustin Ingram 
> Discussions-To: distutils-sig 
> Status: Draft
> Type: Standards Track
> Content-Type: text/x-rst
> Created: 1-Dec-2017
> Python-Version: 3.x
> Post-History:
> Replaces: 345
> 
> 
> Abstract
> 
> 
> This PEP describes the changes between versions 1.2 and 1.3 of the core
> metadata specification for Python packages. Version 1.2 is specified in
> PEP
> 345.
> 
> It also changes to the canonical source for field specifications to the
> `Core
> Metadata Specification`_ reference document, which includes specifics of
> the
> field names, and their semantics and usage.
> 
> Fields
> ==
> 
> The canonical source for the names and semantics of each of the supported
> metadata fields is the `Core Metadata Specification`_ document.
> 
> Fields marked with "(Multiple use)" may be specified multiple times in a
> single
> PKG-INFO file.  Other fields may only occur once in a PKG-INFO file. 
> Fields
> marked with "(optional)" are not required to appear in a valid PKG-INFO
> file;
> all other fields must be present.
> 
> New in Version 1.3
> --
> 
> Description-Content-Type (optional)
> :::
> 
> A string stating the markup syntax (if any) used in the distribution's
> description, so that tools can intelligently render the description.
> 
> Historically, tools like PyPI assume that a package's description is
> formatted
> in `reStructuredText (reST)
> `_,
> and
> fall back on plain text if the description is not valid reST.
> 
> The introduction of this field allows PyPI to support additional types of
> markup syntax, and not need to make this assumption.
> 
> The full specification for this field is defined in the `Core Metadata
> Specification`_.
> 
> 
> Provides-Extra (optional, multiple use)
> :::
> 
> A string containing the name of an optional feature. Must be a valid
> Python
> identifier. May be used to make a dependency conditional on whether the
> optional feature has been requested.
> 
> This introduction of this field allows packge installation tools (such as
> ``pip``) to determine which extras are provided by a given package, and
> so that
> package publication tools (such as ``twine``) can check for issues with
> environment markers which use extras.
> 
> The full specification for this field is defined in the `Core Metadata
> Specification`_.
> 
> Changed in Version 1.3
> --
> 
> Name
> 
> 
> The specification for the format of this field is now identical to the
> distribution name specification defined in PEP 508.
> 
> Version Specifiers
> ==
> 
> Version numbering requirements and the semantics for specifying
> comparisons
> between versions are defined in PEP 440.
> 
> Environment markers
> ===
> 
> An **environment marker** is a marker that can be added at the end of a
> field after a semi-colon (";"), to add a condition about the execution
> environment.
> 
> The environment marker format used to declare such a condition is defined
> in
> the environment markers section of PEP 508.
> 
> JSON-compatible Metadata
> 
> 
> It may be necessary to store metadata in a data structure which does not
> allow for multiple repeated keys, such as JSON.
> 
> The canonical method to transform metadata fields into such a data
> structure is
> as follows:
> 
> #. The original key-value format should be read with
>

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-07 Thread Wes Turner 
>From "[distutils] Multiple package authors" [1]

- How should multiple author-email and maintainer-email addresses be
specified?

- Should we add security-email and/or security-disclosure-instructions?


[1] http://markmail.org/thread/xmwfktnsbmpakv6b

On Wednesday, December 6, 2017, Nick Coghlan  wrote:

> On 6 December 2017 at 02:39, Dustin Ingram 
> wrote:
> > Hi all,
> >
> > I'd appreciate your feedback on the following Metadata 1.3 PEP.
> >
> > The goal here is not to provide a full specification for all fields as
> > in previous PEPs, but to:
> >
> > * Motivate and describe the addition of the new fields or changes to
> > existing fields;
> > * Point to the Core Metadata Specifications reference document as the
> > canonical source for the specification.
>
> Hi folks,
>
> While I'd normally step up as BDFL-Delegate for an interoperability
> specification like this one, I'm actually going to be offline for most
> of the rest of the year, which I figure wouldn't be especially
> conducive to running an effective and timely review process :)
>
> So while I'll note that I'm personally happy with the PEP as it
> currently stands (based on my review of Dustin's earlier drafts), I've
> also asked Daniel Holth if he'd be willing to handle the task of final
> review and approval for this PEP as the original author of the wheel
> specification, and Daniel's graciously agreed to do so.
>
> Regards,
> Nick.
>
> --
> Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
> ___
> Distutils-SIG maillist  -  Distutils-SIG@python.org
> https://mail.python.org/mailman/listinfo/distutils-sig
>
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-06 Thread Nick Coghlan 
On 6 December 2017 at 02:39, Dustin Ingram  wrote:
> Hi all,
>
> I'd appreciate your feedback on the following Metadata 1.3 PEP.
>
> The goal here is not to provide a full specification for all fields as
> in previous PEPs, but to:
>
> * Motivate and describe the addition of the new fields or changes to
> existing fields;
> * Point to the Core Metadata Specifications reference document as the
> canonical source for the specification.

Hi folks,

While I'd normally step up as BDFL-Delegate for an interoperability
specification like this one, I'm actually going to be offline for most
of the rest of the year, which I figure wouldn't be especially
conducive to running an effective and timely review process :)

So while I'll note that I'm personally happy with the PEP as it
currently stands (based on my review of Dustin's earlier drafts), I've
also asked Daniel Holth if he'd be willing to handle the task of final
review and approval for this PEP as the original author of the wheel
specification, and Daniel's graciously agreed to do so.

Regards,
Nick.

-- 
Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-05 Thread Nick Coghlan 
On 6 December 2017 at 07:02, Nathaniel Smith  wrote:
> On Dec 5, 2017 08:42, "Dustin Ingram"  wrote:
>
>
> Provides-Extra (optional, multiple use)
> :::
>
> A string containing the name of an optional feature. Must be a valid Python
> identifier. May be used to make a dependency conditional on whether the
> optional feature has been requested.
>
> This introduction of this field allows packge installation tools (such as
> ``pip``) to determine which extras are provided by a given package, and so
> that
> package publication tools (such as ``twine``) can check for issues with
> environment markers which use extras.
>
>
> I haven't followed this so sorry if this is an annoying comment, but having
> read this description I still don't really understand what Provides-Extra is
> doing. Don't packages already include extra information? What problem
> motivated this?

The main problem it solves is a procedural one related to the fact
that I co-opted Daniel Holth's original metadata 1.3 PEP (i.e. PEP
426) as a more expansive "What if we were designing the metadata
system from scratch?" proposal, which then fell prey to second system
syndrome (https://en.wikipedia.org/wiki/Second-system_effect).

We'd subsequently mitigated that problem by allowing additional fields
to be defined directly in
https://packaging.python.org/specifications/core-metadata/ without
being defined in a PEP, but that turned out to create a new problem
with a lack of adequate transparency in and around the specification
update process.

So Dustin's PEP is aimed mainly at getting things back on track from a
procedural perspective, with
https://packaging.python.org/specifications/ becomes PyPA's equivalent
to the Python Language Reference at
https://docs.python.org/3/reference/, and we use Standards Track PEPs
to justify additions and changes to those specifications, rather than
using Informational PEPs directly as the reference documentation.

As such, PEP 566 doesn't actually *change* the current metadata
specification at the field level - it just takes the existing
post-PEP-345 changes, and formalises them as version 1.3 of the
metadata spec (which should then help with consistency of
implementation across various tools).

The one real change that PEP 566 does propose is a new approach to the
question of defining a JSON-compatible variant of the data format:
rather than designing that from scratch as I did in later versions of
PEP 426 (which would have required major changes for existing tools to
adopt), it instead defines it as a reversible algorithmic
transformation from the existing Key:Value based format, which will
allow new tools to adopt it as their preferred working format, while
still maintaining compatibility with existing tools at the level of
the on-disk file format. (Having that transformation defined in an
interoperability PEP will also allow both Warehouse and
https://packaging.pypa.io/ to implement it, which will be useful when
designing packaging related REST APIs and metadata caching formats).

Cheers,
Nick.

P.S. I'm seriously considering moving PEP 426 and 459 from Deferred to
Withdrawn - while there are still some worthwhile ideas in there, I
think we've learned through experience that the more practical path
forward is to identify specific problems that we can't solve with the
existing interoperability specifications, and then propose concrete
solutions to those problems. While entertaining to explore, "What
would we consider doing if we had unlimited development resources?"
flights of fancy aren't actually a practical approach to making
changes :)

-- 
Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-05 Thread Donald Stufft 


> On Dec 5, 2017, at 4:02 PM, Nathaniel Smith  wrote:
> 
> I haven't followed this so sorry if this is an annoying comment, but having 
> read this description I still don't really understand what Provides-Extra is 
> doing. Don't packages already include extra information? What problem 
> motivated this?


I’m pretty sure this field is literally what wheel already does. 
https://packaging.python.org/specifications/core-metadata/#provides-extra-optional-multiple-use
 
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-05 Thread Paul Moore 
On 5 December 2017 at 20:34, Dustin Ingram  wrote:
> Ah, I see, by "other two" I thought you meant the other two new fields.
>
> Looking at https://www.python.org/dev/peps/pep-0566/ might make it
> more clear that I originally intended the "New in Version 1.3" and
> "Changed in Version 1.3" headings to only be under the "Fields"
> heading, so the outline would be:
>
> * Abstract
> * Fields
>   - New in Version 1.3
> * Description-Content-Type (optional)
> * Provides-Extra (optional, multiple use)
>   - Changed in Version 1.3
> * Name
> * Version Specifiers
> * Environment markers
> * JSON-compatible Metadata
> * Summary of Differences From PEP 345
> * References
> * Copyright
> * Acknowledgements
>
> However I could see the value in inverting this a bit to be:
>
> * Abstract
> * New in Version 1.3
>   - Fields
> * Description-Content-Type (optional)
> * Provides-Extra (optional, multiple use)
> * Changed in Version 1.3
>   - Fields
> * Name
>   - Version Specifiers
>   - Environment markers
>   - JSON-compatible Metadata
> * Summary of Differences From PEP 345
> * References
> * Copyright
> * Acknowledgements
>
> If this is preferable.

Oh! Sorry, I follow now. I'd misunderstood the structure completely -
my mistake. I was thinking of "Version Specifiers" and "Environment
Markers" as fields, when they aren't - they are *part* of certain
fields. The table of contents is completely clear, though, it's just
that I wasn't concentrating so much when I read that.

I'd say it's fine as it stands. Thanks for clarifying.

Paul
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-05 Thread Nathaniel Smith 
On Dec 5, 2017 08:42, "Dustin Ingram"  wrote:


Provides-Extra (optional, multiple use)
:::

A string containing the name of an optional feature. Must be a valid Python
identifier. May be used to make a dependency conditional on whether the
optional feature has been requested.

This introduction of this field allows packge installation tools (such as
``pip``) to determine which extras are provided by a given package, and so
that
package publication tools (such as ``twine``) can check for issues with
environment markers which use extras.


I haven't followed this so sorry if this is an annoying comment, but having
read this description I still don't really understand what Provides-Extra
is doing. Don't packages already include extra information? What problem
motivated this?

-n
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-05 Thread Dustin Ingram 
Ah, I see, by "other two" I thought you meant the other two new fields.

Looking at https://www.python.org/dev/peps/pep-0566/ might make it
more clear that I originally intended the "New in Version 1.3" and
"Changed in Version 1.3" headings to only be under the "Fields"
heading, so the outline would be:

* Abstract
* Fields
  - New in Version 1.3
* Description-Content-Type (optional)
* Provides-Extra (optional, multiple use)
  - Changed in Version 1.3
* Name
* Version Specifiers
* Environment markers
* JSON-compatible Metadata
* Summary of Differences From PEP 345
* References
* Copyright
* Acknowledgements

However I could see the value in inverting this a bit to be:

* Abstract
* New in Version 1.3
  - Fields
* Description-Content-Type (optional)
* Provides-Extra (optional, multiple use)
* Changed in Version 1.3
  - Fields
* Name
  - Version Specifiers
  - Environment markers
  - JSON-compatible Metadata
* Summary of Differences From PEP 345
* References
* Copyright
* Acknowledgements

If this is preferable.

Thanks,
D.
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-05 Thread Paul Moore 
On 5 December 2017 at 18:11, Dustin Ingram  wrote:
>> I was a bit confused at first by the fact that you describe
>> environment markers but not where they are allowed. On checking, I
>> find that this is defined in version 1.2 (PEP 345). It might be worth
>> a small clarification that this (and name and version specifiers) are
>> still used in the same way as in PEP 345. Better to be explicit than
>> implicit and all that :-)
>
> Thanks Paul. I will add a note to to these sections indicating that
> their usage is otherwise unchanged from PEP 345.
>
>> Formatting nit - the "Name" section header is at a different level
>> than the other two. You probably want the other two with ""
>> underlines.
>
> Unless I'm misunderstanding your nit, I believe this is already the case?

Sorry, I was rushing and didn't take the time to fight with Gmail to
do inline comments. What I was trying to get at:

> Changed in Version 1.3
> --
>
> Name
> 
>
> The specification for the format of this field is now identical to the
> distribution name specification defined in PEP 508.
>
> Version Specifiers
> ==

This should be

  ::

so "Version Specifiers" is at the same level as "Name"

>
> Version numbering requirements and the semantics for specifying comparisons
> between versions are defined in PEP 440.
>
> Environment markers
> ===

Same here, should be

  :::

> An **environment marker** is a marker that can be added at the end of a
> field after a semi-colon (";"), to add a condition about the execution
> environment.
>
> The environment marker format used to declare such a condition is defined in
> the environment markers section of PEP 508.

Paul
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-05 Thread Dustin Ingram 
> I was a bit confused at first by the fact that you describe
> environment markers but not where they are allowed. On checking, I
> find that this is defined in version 1.2 (PEP 345). It might be worth
> a small clarification that this (and name and version specifiers) are
> still used in the same way as in PEP 345. Better to be explicit than
> implicit and all that :-)

Thanks Paul. I will add a note to to these sections indicating that
their usage is otherwise unchanged from PEP 345.

> Formatting nit - the "Name" section header is at a different level
> than the other two. You probably want the other two with ""
> underlines.

Unless I'm misunderstanding your nit, I believe this is already the case?

Thanks again,
D.
___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-05 Thread Paul Moore 
LGTM.

I was a bit confused at first by the fact that you describe
environment markers but not where they are allowed. On checking, I
find that this is defined in version 1.2 (PEP 345). It might be worth
a small clarification that this (and name and version specifiers) are
still used in the same way as in PEP 345. Better to be explicit than
implicit and all that :-)

Formatting nit - the "Name" section header is at a different level
than the other two. You probably want the other two with ""
underlines.

Paul

On 5 December 2017 at 16:39, Dustin Ingram  wrote:
> Hi all,
>
> I'd appreciate your feedback on the following Metadata 1.3 PEP.
>
> The goal here is not to provide a full specification for all fields as
> in previous PEPs, but to:
>
> * Motivate and describe the addition of the new fields or changes to
> existing fields;
> * Point to the Core Metadata Specifications reference document as the
> canonical source for the specification.
>
> Previous discussions:
> * https://mail.python.org/pipermail/distutils-sig/2017-September/031465.html
> * https://github.com/python/peps/issues/388
>
> Thanks,
> D.
>
>
> PEP: 566
> Title: Metadata for Python Software Packages 1.3
> Version: $Revision$
> Last-Modified: $Date$
> Author: Dustin Ingram 
> Discussions-To: distutils-sig 
> Status: Draft
> Type: Standards Track
> Content-Type: text/x-rst
> Created: 1-Dec-2017
> Python-Version: 3.x
> Post-History:
> Replaces: 345
>
>
> Abstract
> 
>
> This PEP describes the changes between versions 1.2 and 1.3 of the core
> metadata specification for Python packages. Version 1.2 is specified in PEP
> 345.
>
> It also changes to the canonical source for field specifications to the `Core
> Metadata Specification`_ reference document, which includes specifics of the
> field names, and their semantics and usage.
>
> Fields
> ==
>
> The canonical source for the names and semantics of each of the supported
> metadata fields is the `Core Metadata Specification`_ document.
>
> Fields marked with "(Multiple use)" may be specified multiple times in a 
> single
> PKG-INFO file.  Other fields may only occur once in a PKG-INFO file.  Fields
> marked with "(optional)" are not required to appear in a valid PKG-INFO file;
> all other fields must be present.
>
> New in Version 1.3
> --
>
> Description-Content-Type (optional)
> :::
>
> A string stating the markup syntax (if any) used in the distribution's
> description, so that tools can intelligently render the description.
>
> Historically, tools like PyPI assume that a package's description is formatted
> in `reStructuredText (reST)
> `_, and
> fall back on plain text if the description is not valid reST.
>
> The introduction of this field allows PyPI to support additional types of
> markup syntax, and not need to make this assumption.
>
> The full specification for this field is defined in the `Core Metadata
> Specification`_.
>
>
> Provides-Extra (optional, multiple use)
> :::
>
> A string containing the name of an optional feature. Must be a valid Python
> identifier. May be used to make a dependency conditional on whether the
> optional feature has been requested.
>
> This introduction of this field allows packge installation tools (such as
> ``pip``) to determine which extras are provided by a given package, and so 
> that
> package publication tools (such as ``twine``) can check for issues with
> environment markers which use extras.
>
> The full specification for this field is defined in the `Core Metadata
> Specification`_.
>
> Changed in Version 1.3
> --
>
> Name
> 
>
> The specification for the format of this field is now identical to the
> distribution name specification defined in PEP 508.
>
> Version Specifiers
> ==
>
> Version numbering requirements and the semantics for specifying comparisons
> between versions are defined in PEP 440.
>
> Environment markers
> ===
>
> An **environment marker** is a marker that can be added at the end of a
> field after a semi-colon (";"), to add a condition about the execution
> environment.
>
> The environment marker format used to declare such a condition is defined in
> the environment markers section of PEP 508.
>
> JSON-compatible Metadata
> 
>
> It may be necessary to store metadata in a data structure which does not
> allow for multiple repeated keys, such as JSON.
>
> The canonical method to transform metadata fields into such a data structure 
> is
> as follows:
>
> #. The original key-value format should be read with
>``email.parser.HeaderParser``;
> #. All transformed keys should be reduced to lower case, but otherwise should
>retain all other characters;
> #. The transformed value for any field marked with "(Multiple-use") should be 
> a
>

Re: [Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-05 Thread Tres Seaver 
On 12/05/2017 11:39 AM, Dustin Ingram wrote:
> Hi all,
> 
> I'd appreciate your feedback on the following Metadata 1.3 PEP.
> 
> The goal here is not to provide a full specification for all fields as
> in previous PEPs, but to:
> 
> * Motivate and describe the addition of the new fields or changes to
> existing fields;
> * Point to the Core Metadata Specifications reference document as the
> canonical source for the specification.
> 
> Previous discussions:
> * https://mail.python.org/pipermail/distutils-sig/2017-September/031465.html
> * https://github.com/python/peps/issues/388

LGTM.


Tres.
-- 
===
Tres Seaver  +1 540-429-0999  tsea...@palladion.com
Palladion Software   "Excellence by Design"http://palladion.com

___
Distutils-SIG maillist  -  Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig

[Distutils] RFC: PEP 566 - Metadata for Python Software Packages 1.3

2017-12-05 Thread Dustin Ingram 
Hi all,

I'd appreciate your feedback on the following Metadata 1.3 PEP.

The goal here is not to provide a full specification for all fields as
in previous PEPs, but to:

* Motivate and describe the addition of the new fields or changes to
existing fields;
* Point to the Core Metadata Specifications reference document as the
canonical source for the specification.

Previous discussions:
* https://mail.python.org/pipermail/distutils-sig/2017-September/031465.html
* https://github.com/python/peps/issues/388

Thanks,
D.


PEP: 566
Title: Metadata for Python Software Packages 1.3
Version: $Revision$
Last-Modified: $Date$
Author: Dustin Ingram 
Discussions-To: distutils-sig 
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 1-Dec-2017
Python-Version: 3.x
Post-History:
Replaces: 345


Abstract


This PEP describes the changes between versions 1.2 and 1.3 of the core
metadata specification for Python packages. Version 1.2 is specified in PEP
345.

It also changes to the canonical source for field specifications to the `Core
Metadata Specification`_ reference document, which includes specifics of the
field names, and their semantics and usage.

Fields
==

The canonical source for the names and semantics of each of the supported
metadata fields is the `Core Metadata Specification`_ document.

Fields marked with "(Multiple use)" may be specified multiple times in a single
PKG-INFO file.  Other fields may only occur once in a PKG-INFO file.  Fields
marked with "(optional)" are not required to appear in a valid PKG-INFO file;
all other fields must be present.

New in Version 1.3
--

Description-Content-Type (optional)
:::

A string stating the markup syntax (if any) used in the distribution's
description, so that tools can intelligently render the description.

Historically, tools like PyPI assume that a package's description is formatted
in `reStructuredText (reST)
`_, and
fall back on plain text if the description is not valid reST.

The introduction of this field allows PyPI to support additional types of
markup syntax, and not need to make this assumption.

The full specification for this field is defined in the `Core Metadata
Specification`_.


Provides-Extra (optional, multiple use)
:::

A string containing the name of an optional feature. Must be a valid Python
identifier. May be used to make a dependency conditional on whether the
optional feature has been requested.

This introduction of this field allows packge installation tools (such as
``pip``) to determine which extras are provided by a given package, and so that
package publication tools (such as ``twine``) can check for issues with
environment markers which use extras.

The full specification for this field is defined in the `Core Metadata
Specification`_.

Changed in Version 1.3
--

Name


The specification for the format of this field is now identical to the
distribution name specification defined in PEP 508.

Version Specifiers
==

Version numbering requirements and the semantics for specifying comparisons
between versions are defined in PEP 440.

Environment markers
===

An **environment marker** is a marker that can be added at the end of a
field after a semi-colon (";"), to add a condition about the execution
environment.

The environment marker format used to declare such a condition is defined in
the environment markers section of PEP 508.

JSON-compatible Metadata


It may be necessary to store metadata in a data structure which does not
allow for multiple repeated keys, such as JSON.

The canonical method to transform metadata fields into such a data structure is
as follows:

#. The original key-value format should be read with
   ``email.parser.HeaderParser``;
#. All transformed keys should be reduced to lower case, but otherwise should
   retain all other characters;
#. The transformed value for any field marked with "(Multiple-use") should be a
   single list containing all the original values for the given key;
#. The ``Keywords`` field should be converted to a list by splitting the
   original value on whitespace characters;
#. The result should be stored as a string-keyed dictionary.

Summary of Differences From PEP 345
===

* Metadata-Version is now 1.3.

* Fields are now specified via the `Core Metadata Specification`_.

* Added two new fields: ``Description-Content-Type`` and ``Provides-Extra``

* Acceptable values for the ``Name`` field are now specified as per PEP 508.

* Added canonical method of transformation into JSON-compatible data structure.

References
==

This document specifies version 1.3 of the metadata format.
Version 1.0 is specified in PEP 241.
Version 1.1 is specified in PEP 314.
Version 1.2 is