Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor peps.json logic into PEP class #2585

Merged
merged 1 commit into from
Jun 8, 2022
Merged

Refactor peps.json logic into PEP class #2585

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions pep_sphinx_extensions/pep_zero_generator/parser.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,25 @@ def details(self, *, title_length) -> dict[str, str | int]:
"authors": ", ".join(author.nick for author in self.authors),
}

@property
def full_details(self) -> dict[str, str]:
Comment on lines +130 to +131
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
@property
def full_details(self) -> dict[str, str]:
def to_dict(self) -> dict[str, str]:

Instead of making this a property (especially when the otherwise similar details, despite its name being a noun, is not), it would be clearer, more descriptive and conventional to have it be a to_dict() method, no?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer the internal consistency of details / full_details, but not a big issue.

PEP.details will become a property under the refactoring work needed for subindices, I'm pretty sure, although again minor.

A

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, I'm not sure why it needs to be a property, but that's really just bikeshedding. What confused me more was the "consistency" with details , as it doesn't seem obvious without careful inspection how full_details differs from it, nor what callers should expect it to do.

However, that got me thinking: It would seem to me that there should only be one attribute (whether a metadata property, with the existing one made private or renamed to headers, or a to_dict() method) that contains the PEP's metadata as a dict, and selecting specific attributes the caller wants to use and any specialized output-specific reformatting it needs it should be the callers concern, rather than the PEP class.

This shouldn't be that much to unify them; as it stands now, details is only used by pep_zero_generator.writer.column_format, which just passes it to format(), and so the items it doesn't use are simply discarded. Otherwise, the only differences are:

  • number is missing from full_details, which should just be added
  • title is truncated in details, which can be done by the caller or better yet just dropped (since many non-truncated titles and those with many authors already extend to two lines anyway, so the space may as well be used to just show the full title, since only one PEP title is longer than 79 characters which still fits easily on two lines)
  • type and status are truncated to one letter in details, which can easily be done in the caller's format string, and is uppercased, which it already is for all valid types
  • status additionally has the April Fool status normalized, which should be done for both

So the only changes needed to replace details with full_details should be adding number, normalizing the April Fool status, and adding :.1 after type and status in the pep_zero_generator.writer.column_format format string.

"""Returns all headers of the PEP as a dict."""
return {
"title": self.title,
"authors": ", ".join(author.nick for author in self.authors),
"discussions_to": self.discussions_to,
"status": self.status,
"type": self.pep_type,
"created": self.created,
"python_version": self.python_version,
"post_history": self.post_history,
"resolution": self.resolution,
"requires": self.requires,
"replaces": self.replaces,
"superseded_by": self.superseded_by,
"url": f"https://peps.python.org/pep-{self.number:0>4}/",
}


def _raise_pep_error(pep: PEP, msg: str, pep_num: bool = False) -> None:
if pep_num:
Expand Down
31 changes: 7 additions & 24 deletions pep_sphinx_extensions/pep_zero_generator/pep_index_generator.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,25 +32,7 @@


def create_pep_json(peps: list[parser.PEP]) -> str:
pep_dict = {
pep.number: {
"title": pep.title,
"authors": ", ".join(pep.authors.nick for pep.authors in pep.authors),
"discussions_to": pep.discussions_to,
"status": pep.status,
"type": pep.pep_type,
"created": pep.created,
"python_version": pep.python_version,
"post_history": pep.post_history,
"resolution": pep.resolution,
"requires": pep.requires,
"replaces": pep.replaces,
"superseded_by": pep.superseded_by,
"url": f"https://peps.python.org/pep-{pep.number:0>4}/",
}
for pep in sorted(peps)
}
return json.dumps(pep_dict, indent=1)
return json.dumps({pep.number: pep.full_details for pep in peps}, indent=1)


def create_pep_zero(app: Sphinx, env: BuildEnvironment, docnames: list[str]) -> None:
Expand All @@ -77,7 +59,9 @@ def create_pep_zero(app: Sphinx, env: BuildEnvironment, docnames: list[str]) ->
pep = parser.PEP(path.joinpath(file_path).absolute(), authors_overrides)
peps.append(pep)

pep0_text = writer.PEPZeroWriter().write_pep0(sorted(peps))
peps = sorted(peps)

pep0_text = writer.PEPZeroWriter().write_pep0(peps)
pep0_path = Path(f"{pep_zero_filename}.rst")
pep0_path.write_text(pep0_text, encoding="utf-8")

Expand All @@ -89,7 +73,6 @@ def create_pep_zero(app: Sphinx, env: BuildEnvironment, docnames: list[str]) ->
env.found_docs.add(pep_zero_filename)

# Create peps.json
pep0_json = create_pep_json(peps)
out_dir = Path(app.outdir) / "api"
out_dir.mkdir(exist_ok=True)
Path(out_dir, "peps.json").write_text(pep0_json, encoding="utf-8")
json_path = Path(app.outdir, "api", "peps.json").resolve()
json_path.parent.mkdir(exist_ok=True)
json_path.write_text(create_pep_json(peps), encoding="utf-8")
Comment on lines +76 to +78
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I really understand the pressing need to rewrite all this when there were no functional changes in or near this line, and the previous form was perfectly valid and does exactly the same thing...it just seems like churn to me, but maybe I'm missing something important here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A (small) speed up as we only sort the large list of PEPs once.

A

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't follow, sorry. Maybe I'm missing something, but I don't see how any of the changes here have anything to do with that, as no sorting is performed within this block and create_pep_json is called once both times in the same way

(Pedantic note: Other than create_pep_json() is not bound to a name first before using it, which saves a few hundred kB of memory for the few ≈milliseconds it is alive while the path is checked, and perhaps on the order of microseconds on the fast local name lookup.)