python / python/peps

Decouple and unify PEP header processing for rendering, PEP 0, JSON, RSS and linting

未关闭
#2,587 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

infra
主要语言
reStructuredText
星标
5k
派生
1.8k
平均合并
2 天 4 小时
30 天内合并 PR
25

描述

As a followup to #2584 and #2585 and as I've already been thinking about lately and discussed with @JelleZijlstra and @warsaw at PyCon, right now we parse the headers three different places with three different sets of logic:

  • pep_zero_generator.parser for PEP 0, the JSON and the RSS with some additional sub-parsing in those callers
  • pep_processor.transforms.header_transform for the PEP rendering
  • The .pre-commit-config.yaml pygrep hooks for linting),

Instead, we should just use the structured format I suggest in #2584 (with the parsing presumably in the PEP class) for all of them (starting with PEP rendering initially), for several reasons:

  • Simpler, more DRY, reliable and maintainable in the long run
  • Easier to add new headers in one central place, as in #2572
  • Enables simplifying/loosening the allowed input syntax for authors without fear of breaking anything
  • Simplifies adding requested features in the various outputs (e.g. :abbr: from #2514 )
  • Decouples the header format from reST/Sphinx and ensures the format-independence @AA-Turner originally wanted in #2358
  • Avoids cryptic regexes for linting (as @hugovk requested on #2484)

Of course, we should decide on and implement the structured format proposed in #2584 first, as it is a perquisite for this (alongside the changes in #2585 and #2579 needing to be merged before work on this begins), but I've opened this to keep track of it.

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

首先查看 #2584、#2585 和 #2579,因为这项工作依赖于它们。然后比较 pep_zero_generator.parser、pep_processor.transforms.header_transform 以及 .pre-commit-config.yaml 中的 pygrep hooks;当 PEP 渲染、PEP 0、JSON、RSS 和 linting 始终使用一种结构化 header 格式时,即表示完成。

由索引模型根据 Issue 内容生成。

评估

领域
documentation, tooling
Issue 类型
重构
难度
5/5
预计耗时
一周以上
活跃度
停滞
描述清晰度
基本清楚
新手友好度
30/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。