Confusing description for dictionary indentation

[westlake-moonlight]

Hello there,

I'm seeing 2 issues in Python style guide:

1. Chapter 3.9 is missing.
2. In chapter 3.4 Indentation, the 2nd example is incorrect. The comment is "# Aligned with opening delimiter in a dictionary", but this example is not aligned with the delimiter, using "4-space hanging indent" instead.

https://google.github.io/styleguide/pyguide.html#34-indentation

[lokeswaran-aj]

Hi, I find the 2nd issue in google_python_style.vim file and I would like to change it. Can I take that issue and fix it?

[westlake-moonlight]

Hi, I find the 2nd issue in google_python_style.vim file and I would like to change it. Can I take that issue and fix it?

That would be great if you can fix it!
However, it seems only Google team have access to fix it. They may not even aware of this issue yet.

[lokeswaran-aj]

@westlake-moonlight Okk. I thought its a Open source project. What is the Github User name of Google's open source project??

[IsaacG]

The Googlers that maintain this repo are likely subscribed to issues and get emails when people open or comment on issues.

Many of the style guide docs are maintained internally and exported to GitHub using tools like copybara. That means that fixes need to happen internally and pushed from there. And pull request needs to be copied and applied internally and cannot be directly merged into this repo.

The missing 3.9 section is likely an "internal only" section which appears in the internal style guide and talks about internal style or tooling but gets removed by copybara on export. That makes the fix a bit more tricky than just changing the numbers.

The style guide maintenance is largely managed by loosely organized volunteers who have some degree of expertise in the area, which means they probably have a lot of other projects also pulling at their attention - projects that are part of their actual responsibilities, unlike dealing with messing around to get the section numbers on the external version of the guide to line up. Fiddly bits on unstaffed projects tend to not get prioritized, but someone will probably get around to it eventually.

[gpshead]

Regarding the missing 3.9, we intentionally do not re-number sections as various things link to stuff by number. A 3.9 must've existed in the past.

(1) For the

       # Aligned with opening delimiter in a dictionary
       foo = {
           'long_dictionary_key': value1 +
                                  value2,
           ...
       }

example, the alignment is for the continued value's implied continuation. The wording of that comment could indeed be better...

---

(2) If you have an issue with google_python_style.vim, can you please file and issue or make a PR for that one (and if it lets you, assign it to me)? we don't merge directly into this repository but when things make sense for Python style related things I'll pick changes up, make them internally, and push out updated versions.

[westlake-moonlight]

@gpshead
(1) For the indention comment, it makes more sense when you say "It was meant to make value2 align with value1 for continuation". Do you think you can update the comment to make it clearer for all users?
When I looked at it, it looks like it wanted to show another similar example as the one below, aliging with the opening delimiter:

(2) For the section 3.9, maybe it's better to put a comment before section 3.10: "Section 3.9 is obsoleted, skipped here intentionally." That way, it could save a lot of Python users' time all around the globe.
Sometimes we see blank pages in documents, and a comment "This page is left blank intentionally" do help people to stop paying attention on it.

I'm still trying to figure out how to assign this issue to you. I will let you know once I made it. Thanks!

[westlake-moonlight]

@IsaacG Thanks for your information!

[westlake-moonlight]

@gpshead
So I didn't find a way to assign this issue to you, even though I can see the "Assignees" at the top right column of this page. Is there other ways to do this?
Thanks!

[vapier]

refining summary because it's as @gpshead said -- there was a section 3.9, but there isn't one anymore. the internal Google style guide is the same way. it's confusing, but the alternative (breaking links) is worse. maybe this should be explained in the intro chapters.

as for the example, it is correct, but I can see how it's confusing. when it says "opening delimiter", it's referring to the :, not the {. if it were to use 4-space hanging indent, then the value would be on the next line (as seen in a later example in this text).