Proposal to format Django using black

classic Classic list List threaded Threaded
107 messages Options
123456
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Andrew Godwin-3
We've used Black for the Channels/ASGI projects for about the last year, and I have nothing but good opinions on it from that perspective. It's made pull requests much easier to get formatted, because fixing it is just a case of running a single command (and if you do the right pre-commit hook, you never even get that far).

As for Django, the single biggest problem I can see is the single reformat commit, but I think this is worth it. We've had a few of those in our history - and indeed at work - and while it is a bit of a pain, GitHub has a "see the blame before this commit" button to enable much easier browsing of files prior to it.

For that reason, I am +1 to using the Black code formatter.

Andrew


On Sun, Apr 14, 2019 at 10:22 AM Curtis Maloney <[hidden email]> wrote:
So to summarise the discussion so far:

1. automated code formatting will be a great boon - reduce work, lower
barrier for new committers, reduce work for the fellows, etc.

2. there are issues with git history in doing "the great commit".

3. there are issues with black's formatting choices.


So to address 1:

I am entirely +1 for automated code formatting to take the work out of
our hands.

Can such a tool be automated into, say, github in a way that doesn't
create extra commit noise?

To address 2:

I side with those who favour a progressive solution, whereby new code
only has the new tool applied.

That said, there might be cause to suggest a deadline [perhaps a N.0
release?] where all remaining code is "cleaned".

And finally 3:

My perspective on the goal of any code formatting tool is this:

When we as developers approach a piece of code, our goal is the
understand its intent and its implementation of that intent.

In the process of reaching that, we pass through the stages of (a)
identifying the relevant code, (b) understanding the action of the code,
and (c) understanding the intent of the code.

Good code formatting choices will remove or reduce the cognitive load in
(b) and (c).

In my experience with using black [we use it at work], there are
numerous choices (including those demonstrated in this list already)
where it can significantly _increase_ the cognitive load in simply
parsing the code.

As simple as black can make the job of code formatting, I feel I'd
rather see a different tool that retained the benefits of "trivial code
reformatting", but still allowed us to retain some of Django's existing
code formatting rules.

(An interesting [and defensible] choice, we had a module with a lot of
strings wrapped across lines. black opted to push them onto the same
line, but NOT to merge them.  This is because in Python prior to 3.7, it
would have altered the generated AST - one of the guides black uses)

--
Curtis

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/56392596-0246-b62b-4725-628a2b0801ae%40tinbrain.net.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAFwN1up9ZKUOLQH_N_M3wMB4ffhxcMWoFMtwemwuTUEXKKJucA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Florian Apolloner
In reply to this post by Curtis Maloney-2
Hi,

On Sunday, April 14, 2019 at 10:22:46 AM UTC+2, Curtis Maloney wrote:
Can such a tool be automated into, say, github in a way that doesn't
create extra commit noise?

Probably, but after blacking (is that even a word ;)) the codebase once there shouldn't be much commit noise.

I side with those who favour a progressive solution, whereby new code
only has the new tool applied.

I think that would make it hard on tools like git-hyper-blame which allow one to skip revisions. Also you cannot just run black over changes, the minimal unit is one file as far as I am aware. Which would make PR very very hard to review because you'd have a bunch of syntax changes next to real changes.

In my experience with using black [we use it at work], there are
numerous choices (including those demonstrated in this list already)
where it can significantly _increase_ the cognitive load in simply
parsing the code.

Generally I am okay with the way black formats code. But I have to admit that for some very tricky codepaths I tend to turn it off from time to time. That does not happen very often though.

As simple as black can make the job of code formatting, I feel I'd
rather see a different tool that retained the benefits of "trivial code
reformatting", but still allowed us to retain some of Django's existing
code formatting rules.

Open to suggestions, did you just offer to write one :)

(An interesting [and defensible] choice, we had a module with a lot of
strings wrapped across lines. black opted to push them onto the same
line, but NOT to merge them.  This is because in Python prior to 3.7, it
would have altered the generated AST - one of the guides black uses)

We can and should fix those occurrences in our codebase then I guess.
 
Cheers,
Florian

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/8a2e84f3-8b1f-45b7-9ae0-4d556e85133a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Josh Smeaton
Agree with Florian that the progressive rollout is more trouble than it's worth. Tangling up feature changes with whole file formatting will make it harder to review changes, but will also be more difficult to use tools like git blame.

As for disagreeing with some of Blacks choices - you learn very quickly to live with those choices, and forget those choices. Any set of configuration we could come up with for an existing tool would likely be bikeshedded to death and nothing would eventuate.

For line lengths, projects I work on set Black to 100 columns, but flake8 line length is capped to 120. This lets some long strings (black doesn't break long strings over multiple lines) get past flake8 without being over the top.

I'm in favour of using blacks double quotes for strings. I **hated** this decision when it was first made, but have seriously come around to it, and prefer it aesthetically too. Consistency with other projects (most big projects are adopting black) I feel is a good goal. The diff is already going to be huge, there's not much value in protecting a few strings.

Finally, there are some tricks you pick up if black fights you on some decisions. To use Berkers example:

TIME_INPUT_FORMATS = [ 
    '%H:%M:%S', # '14:30:59' 
    '%H:%M:%S.%f', # '14:30:59.000200' 
    '%H:%M', # '14:30' 


TIME_INPUT_FORMATS = ['%H:%M:%S', '%H:%M:%S.%f', '%H:%M'] # '14:30:59' 
# '14:30:59.000200' # '14:30' 

Break each individual format into its own variable, with appropriate comment, and add the variables to the list.

HMS = "%H:%M:%S"  # 14:30:59
HMSF = ".." 
HM = ".."
TIME_INPUT_FORMATS  = [HMS, HMSF, HM]

Obviously just an example, but something to keep in mind.


On Sunday, 14 April 2019 20:20:31 UTC+10, Florian Apolloner wrote:
Hi,

On Sunday, April 14, 2019 at 10:22:46 AM UTC+2, Curtis Maloney wrote:
Can such a tool be automated into, say, github in a way that doesn't
create extra commit noise?

Probably, but after blacking (is that even a word ;)) the codebase once there shouldn't be much commit noise.

I side with those who favour a progressive solution, whereby new code
only has the new tool applied.

I think that would make it hard on tools like git-hyper-blame which allow one to skip revisions. Also you cannot just run black over changes, the minimal unit is one file as far as I am aware. Which would make PR very very hard to review because you'd have a bunch of syntax changes next to real changes.

In my experience with using black [we use it at work], there are
numerous choices (including those demonstrated in this list already)
where it can significantly _increase_ the cognitive load in simply
parsing the code.

Generally I am okay with the way black formats code. But I have to admit that for some very tricky codepaths I tend to turn it off from time to time. That does not happen very often though.

As simple as black can make the job of code formatting, I feel I'd
rather see a different tool that retained the benefits of "trivial code
reformatting", but still allowed us to retain some of Django's existing
code formatting rules.

Open to suggestions, did you just offer to write one :)

(An interesting [and defensible] choice, we had a module with a lot of
strings wrapped across lines. black opted to push them onto the same
line, but NOT to merge them.  This is because in Python prior to 3.7, it
would have altered the generated AST - one of the guides black uses)

We can and should fix those occurrences in our codebase then I guess.
 
Cheers,
Florian

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/8b81a047-babe-42d0-97f5-3af5f6b264fa%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Jon Dufresne
In reply to this post by Curtis Maloney-2
> 2. there are issues with git history in doing "the great commit".

Tools make a real difference here. I know everyone has their preferred tools and workflows, but there are tools that let one move through iterations of git blame. This is something I do quite frequently. Just one example, in Emacs the vc-annotate command (bound to "C-x v g") shows a view of git blame. The user can hit "a" to go to the previous diff the line appeared on which might be more interesting. So one could use this feature to skip over the Black commit on to a more interesting one. This is just a single example. Florian's suggested tools may handle this even more elegantly, but I haven't used them. This only goes to show that the history and git blame concerns don't need to be a show stopper and can be solved. The feature people are asking for, "skipping over" git commits in blame, does exist for some tools. It even exists in GitHub's blame view. The button is labeled "View blame prior to this change".


On Sun, Apr 14, 2019 at 1:22 AM Curtis Maloney <[hidden email]> wrote:
So to summarise the discussion so far:

1. automated code formatting will be a great boon - reduce work, lower
barrier for new committers, reduce work for the fellows, etc.

2. there are issues with git history in doing "the great commit".

3. there are issues with black's formatting choices.


So to address 1:

I am entirely +1 for automated code formatting to take the work out of
our hands.

Can such a tool be automated into, say, github in a way that doesn't
create extra commit noise?

To address 2:

I side with those who favour a progressive solution, whereby new code
only has the new tool applied.

That said, there might be cause to suggest a deadline [perhaps a N.0
release?] where all remaining code is "cleaned".

And finally 3:

My perspective on the goal of any code formatting tool is this:

When we as developers approach a piece of code, our goal is the
understand its intent and its implementation of that intent.

In the process of reaching that, we pass through the stages of (a)
identifying the relevant code, (b) understanding the action of the code,
and (c) understanding the intent of the code.

Good code formatting choices will remove or reduce the cognitive load in
(b) and (c).

In my experience with using black [we use it at work], there are
numerous choices (including those demonstrated in this list already)
where it can significantly _increase_ the cognitive load in simply
parsing the code.

As simple as black can make the job of code formatting, I feel I'd
rather see a different tool that retained the benefits of "trivial code
reformatting", but still allowed us to retain some of Django's existing
code formatting rules.

(An interesting [and defensible] choice, we had a module with a lot of
strings wrapped across lines. black opted to push them onto the same
line, but NOT to merge them.  This is because in Python prior to 3.7, it
would have altered the generated AST - one of the guides black uses)

--
Curtis

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/56392596-0246-b62b-4725-628a2b0801ae%40tinbrain.net.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CADhq2b4Udk1ooc0zdagMPecx-ZGRk%2B01dGCGVr%2BjYOA8vFp8Ag%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Aymeric Augustin
In reply to this post by Herman Schistad
Hello,

I'm strongly in favor of adopting black with the default options.

In my opinion, it's the first Python code formatter that passes the bar of "on average, does better than any single programmer". Trying to enforce something else manually is a waste of energy that produces worse results.

I like nicely formatted code and I hate some of what black produces, typically on Django model definitions. However, I've seen the benefits of an automated code formatter, even on projects where I write almost all of the code.

I'm positive the benefits will be great on Django, where you can tell when a module was (re)written just by looking at the style. Yes, there are some downsides, but it's clearly a good tradeoff.

Regarding the migration strategy, converting one package at a time sounds good, because then we can proof-read the Big Diff and perhaps tweak the code where the result really hurts the eyes.

Most of Django's style guide will still applies, as it's mostly conventions about naming things, ordering declarations, etc.

Best regards,

-- 
Aymeric.



On 13 Apr 2019, at 13:52, Herman S <[hidden email]> wrote:

Hi.

I propose that Django starts using 'black' [0] to auto-format all Python code.
For those unfamiliar with 'black' I recommend reading the the projects README.
The short version: it aims to reduce bike-shedding and non value-adding
discussions; saving time reviewing code; and making the barrier to entry lower
by taking some uncompromissing choices with regards to formatting.  This is
similar to tools such as 'gofmt' for Go and 'prettier' for Javascript.

Personally I first got involved contributing to Django couple of weeks back,
and from anecdotal experience I can testify to how 'formatting of code' creates
a huge barrier for entry. My PR at the time went multiple times back and forth
tweaking formatting. Before this, I had to research the style used by exploring
the docs at length and reading at least 10-20 different source – and even those
were not always consistent. At the end of the day I felt like almost 50% of the
time I used on the patch was not used on actually solving the issue at hand.
Thinking about code formatting in 2019 is a mental energy better used for other
things, and it feels unnecessary that core developers on Django spend their time
"nit-picking" on these things.

I recently led the efforts to make this change where I work. We have a 200K+
LOC Django code-base with more than 30K commits. Some key take-aways: it has
drastically changed the way we work with code across teams, new engineers are
easier on-boarded, PR are more focused on architectural choices and "naming
things", existing PRs before migration had surprisingly few conflicts and were
easy to fix, hot code paths are already "blameable" and it's easy to blame a
line of code and go past the "black-commit", and lastly the migration went
without any issues or down-time.

I had some really fruitful discussions at DjangoCon Europe this week on this
very topic, and it seems we are not alone in these experiences. I would love to
hear from all of you and hope that we can land on something that will enable
*more* people to easier contribute back to this project.

I've set up how this _could_ look depending on some configurables in Black:

* Default config: https://github.com/hermansc/django/pull/1
* Line length kept at 119: https://github.com/hermansc/django/pull/3
* Line length kept at 119, no string normalization:
https://github.com/hermansc/django/pull/2

Please have a look at the Black documentation. It explains the benefits better
than I possibly could do here.

With kind regards,
Herman Schistad

[0]: https://github.com/ambv/black

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAN%3DnMTx0EE5WfXuccv_e3MBuCxp9u_pAV_ow5MxNST6MptTDBw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/DCD30C61-13DD-4EC2-B8B6-FC5243149158%40polytechnique.org.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Berker Peksağ
In reply to this post by Florian Apolloner
On Sun, Apr 14, 2019 at 1:06 PM Florian Apolloner <[hidden email]> wrote:
> This is imo not something that scales well. Also it is not something I want to pay our fellows for, I rather have them use their time on something else. It is true that it is probably easier and faster to just fix code instead of back & forth with the contributor, but the main argument for me here is that this is work that shouldn't be needed in the first place.

True, having an automated code formatter would definitely help to save
reviewer a bit time. However, Django has already flake8 checker on
GitHub, which would already help a contributor to fix biggest
inconsistencies in their PR. Note that my point in my earlier email
was that there are more minor details than just cosmetic fixes and
unfortunately you can't automatically fix all of them :) So, a final
round of edits still needed.

I've used git-hyper-blame before. Most of the time you need to
manually collect all "mass cleanup" commits in a file (and you need to
maintain that file separately) It's also not easy to integrate it with
your workflow especially if you're using "git blame" from your IDE of
choice.

--Berker

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAF4280LX-m8PiKC1bEQz%3DX9nS32BZ9Wb0NR1-UUpRY6CLgxqng%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Tobias McNulty
In reply to this post by Nick Sarbicki
On Sun, Apr 14, 2019 at 3:11 AM Nick Sarbicki <[hidden email]> wrote:
Just going to say that one of the main frustration points I've had when making a contribution is having to fix small formatting errors (often minor things in docstrings which aren't _always_ consistent).

I constantly need to be reminded to shorten docstrings and comments (and sometimes remove "We" from the beginning of such strings). Unfortunately (though understandably), Black won't help with any of these issues, and we'll still be left with the same back and forth about grammar, wrapping, etc. in comments and docstrings. (Again, as of mid-2018 there is the max-doc-length option for flake8 that could help with this somewhat, but that change can be made independently.)

I'm not arguing against Black adoption, but I don't think it's going to eliminate from the review process what may sometimes feel like inertia...

Tobias

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAMGFDKSykRi_51ZonvETYX7whWnPmEAVKm76-MxZifeEuqMt-A%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Simon Charette
In reply to this post by Aymeric Augustin
I was and and I'm still bugged by how black decided to go for double quotes instead of single ones. Even if it's backed some valid arguments it left all the projects following PEP 8's recommendations over the years with this git blaming loss trade off. From past experimentation with large'ish projects following PEP8's guideline string quotes changes represented well over 50% of the diff and there's no way to turn off only this form of string normalization, it's all or nothing. At $WORK we even went as far as forking the project to switch to use single quotes instead[0]. I understand requiring the use of a fork is not a feasible solution for Django but I just wished there was an option to stick to single quotes to reduce the cost of adoption for such projects without loosing all the other nifty string formatting goodies[1] /rant

Even if I don't completely agree with black's formatting choices and the sometimes quite unnatural code it generates my past month's usage at work and the adoption of the project in the Python ecosystem that made it's way in most IDE makes me mostly share the same feeling as Aymeric; it's not always pretty but not having to think about it makes it worth it. I suggest we stick to disabling string normalization to reduce the noise generated by the migration though.

Cheers,
Simon

[0] https://github.com/zapier/black/pull/1
[1] https://github.com/ambv/black#strings

Le dimanche 14 avril 2019 09:40:10 UTC-4, Aymeric Augustin a écrit :
Hello,

I'm strongly in favor of adopting black with the default options.

In my opinion, it's the first Python code formatter that passes the bar of "on average, does better than any single programmer". Trying to enforce something else manually is a waste of energy that produces worse results.

I like nicely formatted code and I hate some of what black produces, typically on Django model definitions. However, I've seen the benefits of an automated code formatter, even on projects where I write almost all of the code.

I'm positive the benefits will be great on Django, where you can tell when a module was (re)written just by looking at the style. Yes, there are some downsides, but it's clearly a good tradeoff.

Regarding the migration strategy, converting one package at a time sounds good, because then we can proof-read the Big Diff and perhaps tweak the code where the result really hurts the eyes.

Most of Django's style guide will still applies, as it's mostly conventions about naming things, ordering declarations, etc.

Best regards,

-- 
Aymeric.



On 13 Apr 2019, at 13:52, Herman S <<a href="javascript:" target="_blank" gdf-obfuscated-mailto="_lQhpnpMBQAJ" rel="nofollow" onmousedown="this.href=&#39;javascript:&#39;;return true;" onclick="this.href=&#39;javascript:&#39;;return true;">herman....@...> wrote:

Hi.

I propose that Django starts using 'black' [0] to auto-format all Python code.
For those unfamiliar with 'black' I recommend reading the the projects README.
The short version: it aims to reduce bike-shedding and non value-adding
discussions; saving time reviewing code; and making the barrier to entry lower
by taking some uncompromissing choices with regards to formatting.  This is
similar to tools such as 'gofmt' for Go and 'prettier' for Javascript.

Personally I first got involved contributing to Django couple of weeks back,
and from anecdotal experience I can testify to how 'formatting of code' creates
a huge barrier for entry. My PR at the time went multiple times back and forth
tweaking formatting. Before this, I had to research the style used by exploring
the docs at length and reading at least 10-20 different source – and even those
were not always consistent. At the end of the day I felt like almost 50% of the
time I used on the patch was not used on actually solving the issue at hand.
Thinking about code formatting in 2019 is a mental energy better used for other
things, and it feels unnecessary that core developers on Django spend their time
"nit-picking" on these things.

I recently led the efforts to make this change where I work. We have a 200K+
LOC Django code-base with more than 30K commits. Some key take-aways: it has
drastically changed the way we work with code across teams, new engineers are
easier on-boarded, PR are more focused on architectural choices and "naming
things", existing PRs before migration had surprisingly few conflicts and were
easy to fix, hot code paths are already "blameable" and it's easy to blame a
line of code and go past the "black-commit", and lastly the migration went
without any issues or down-time.

I had some really fruitful discussions at DjangoCon Europe this week on this
very topic, and it seems we are not alone in these experiences. I would love to
hear from all of you and hope that we can land on something that will enable
*more* people to easier contribute back to this project.

I've set up how this _could_ look depending on some configurables in Black:

* Default config: <a href="https://www.google.com/url?q=https%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F1&amp;sa=D&amp;sntz=1&amp;usg=AFQjCNHg_ctdhGBSbdZK3W4NXBAYv5TtMw" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F1\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNHg_ctdhGBSbdZK3W4NXBAYv5TtMw&#39;;return true;" onclick="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F1\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNHg_ctdhGBSbdZK3W4NXBAYv5TtMw&#39;;return true;">https://github.com/hermansc/django/pull/1
* Line length kept at 119: <a href="https://github.com/hermansc/django/pull/3" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F3\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNGnhCGXsB5HJ8sSyIW9DS2rkVMraw&#39;;return true;" onclick="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F3\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNGnhCGXsB5HJ8sSyIW9DS2rkVMraw&#39;;return true;">https://github.com/hermansc/django/pull/3
* Line length kept at 119, no string normalization:
<a href="https://www.google.com/url?q=https%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F2&amp;sa=D&amp;sntz=1&amp;usg=AFQjCNFQNq-hc9geZY_3egU-27BkSAvBhQ" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F2\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNFQNq-hc9geZY_3egU-27BkSAvBhQ&#39;;return true;" onclick="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F2\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNFQNq-hc9geZY_3egU-27BkSAvBhQ&#39;;return true;">https://github.com/hermansc/django/pull/2

Please have a look at the Black documentation. It explains the benefits better
than I possibly could do here.

With kind regards,
Herman Schistad

[0]: <a href="https://github.com/ambv/black" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fambv%2Fblack\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNGrqVzKdISFdVR5lSsDnknmEceSew&#39;;return true;" onclick="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fambv%2Fblack\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNGrqVzKdISFdVR5lSsDnknmEceSew&#39;;return true;">https://github.com/ambv/black

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to <a href="javascript:" target="_blank" gdf-obfuscated-mailto="_lQhpnpMBQAJ" rel="nofollow" onmousedown="this.href=&#39;javascript:&#39;;return true;" onclick="this.href=&#39;javascript:&#39;;return true;">django-d...@googlegroups.com.
To post to this group, send email to <a href="javascript:" target="_blank" gdf-obfuscated-mailto="_lQhpnpMBQAJ" rel="nofollow" onmousedown="this.href=&#39;javascript:&#39;;return true;" onclick="this.href=&#39;javascript:&#39;;return true;">django-d...@googlegroups.com.
Visit this group at <a href="https://groups.google.com/group/django-developers" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://groups.google.com/group/django-developers&#39;;return true;" onclick="this.href=&#39;https://groups.google.com/group/django-developers&#39;;return true;">https://groups.google.com/group/django-developers.
To view this discussion on the web visit <a href="https://groups.google.com/d/msgid/django-developers/CAN%3DnMTx0EE5WfXuccv_e3MBuCxp9u_pAV_ow5MxNST6MptTDBw%40mail.gmail.com" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://groups.google.com/d/msgid/django-developers/CAN%3DnMTx0EE5WfXuccv_e3MBuCxp9u_pAV_ow5MxNST6MptTDBw%40mail.gmail.com&#39;;return true;" onclick="this.href=&#39;https://groups.google.com/d/msgid/django-developers/CAN%3DnMTx0EE5WfXuccv_e3MBuCxp9u_pAV_ow5MxNST6MptTDBw%40mail.gmail.com&#39;;return true;">https://groups.google.com/d/msgid/django-developers/CAN%3DnMTx0EE5WfXuccv_e3MBuCxp9u_pAV_ow5MxNST6MptTDBw%40mail.gmail.com.
For more options, visit <a href="https://groups.google.com/d/optout" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://groups.google.com/d/optout&#39;;return true;" onclick="this.href=&#39;https://groups.google.com/d/optout&#39;;return true;">https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/c02b4301-5b6f-4326-a9d0-efb4740f314a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Scot Hacker-2
In reply to this post by Herman Schistad
 Just bringing this up for the sake of thoroughness: 

NOTE: This is a beta product

Black is already successfully used by several projects, small and big. It also sports a decent test suite. However, it is still very new. Things will probably be wonky for a while. This is made explicit by the "Beta" trove classifier, as well as by the "b" in the version number. What this means for you is that until the formatter becomes stable, you should expect some formatting to change in the future. That being said, no drastic stylistic changes are planned, mostly responses to bug reports.

Many/most of us use it in production settings already, as the AST check guarantees it isn't going to break anything, but the beta status means you can't always do a simple `pip install black`, and it means that black's formatting choices could change. 

Does a project as significant as Django want to adopt a beta tool whose "contract" with its users has not yet stabilized?

I heart black and would be happy to see it in Django but wonder if we should wait a bit to hit 1.0.

./s

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/5d71f95a-1a8a-4db4-a2ac-8a59adde1fb5%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Adam Johnson-2
Lukasz Langa, the developer, said he will tag the first non-beta version in "Early April." https://twitter.com/llanga/status/1106247623802060802 There won't be any significant changes when it leaves beta afaiu.


On Mon, 15 Apr 2019 at 08:40, Scot Hacker <[hidden email]> wrote:
 Just bringing this up for the sake of thoroughness: 

NOTE: This is a beta product

Black is already successfully used by several projects, small and big. It also sports a decent test suite. However, it is still very new. Things will probably be wonky for a while. This is made explicit by the "Beta" trove classifier, as well as by the "b" in the version number. What this means for you is that until the formatter becomes stable, you should expect some formatting to change in the future. That being said, no drastic stylistic changes are planned, mostly responses to bug reports.

Many/most of us use it in production settings already, as the AST check guarantees it isn't going to break anything, but the beta status means you can't always do a simple `pip install black`, and it means that black's formatting choices could change. 

Does a project as significant as Django want to adopt a beta tool whose "contract" with its users has not yet stabilized?

I heart black and would be happy to see it in Django but wonder if we should wait a bit to hit 1.0.

./s

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/5d71f95a-1a8a-4db4-a2ac-8a59adde1fb5%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.


--
Adam

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAMyDDM2V_g95%3DKN-i9x8Wr6mc-DB%2BceJoqwfQVCfSMp48e06iQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Florian Apolloner
In reply to this post by Simon Charette
Hi Simon,

On Monday, April 15, 2019 at 1:02:49 AM UTC+2, charettes wrote:
 and there's no way to turn off only this form of string normalization, it's all or nothing.
 
So the black --help output lists:
-S, --skip-string-normalization Don't normalize string quotes or prefixes.
Or does that not what you wanted for your company?

Cheers,
Florian

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/47bc9b64-eab8-4405-979e-546d2ddf1a6c%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Florian Apolloner
In reply to this post by Adam Johnson-2
Hi, as Adam points out 1.0 is on it's way. My mails were written with that knowledge and assumption, sorry for not making this clear. I did actually had in mind to wait till it is out of beta -- which is most likely before we finished our discussions :D

Cheers,
Florian

On Monday, April 15, 2019 at 9:06:29 AM UTC+2, Adam Johnson wrote:
Lukasz Langa, the developer, said he will tag the first non-beta version in "Early April." <a href="https://twitter.com/llanga/status/1106247623802060802" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Ftwitter.com%2Fllanga%2Fstatus%2F1106247623802060802\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNFA5TDe7M3H-zHRI4j6ElBSPR3u4A&#39;;return true;" onclick="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Ftwitter.com%2Fllanga%2Fstatus%2F1106247623802060802\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNFA5TDe7M3H-zHRI4j6ElBSPR3u4A&#39;;return true;">https://twitter.com/llanga/status/1106247623802060802 There won't be any significant changes when it leaves beta afaiu.


On Mon, 15 Apr 2019 at 08:40, Scot Hacker <<a href="javascript:" target="_blank" gdf-obfuscated-mailto="Xx_cbJOFBQAJ" rel="nofollow" onmousedown="this.href=&#39;javascript:&#39;;return true;" onclick="this.href=&#39;javascript:&#39;;return true;">scot....@...> wrote:
 Just bringing this up for the sake of thoroughness: 

NOTE: This is a beta product

Black is already successfully used by several projects, small and big. It also sports a decent test suite. However, it is still very new. Things will probably be wonky for a while. This is made explicit by the "Beta" trove classifier, as well as by the "b" in the version number. What this means for you is that until the formatter becomes stable, you should expect some formatting to change in the future. That being said, no drastic stylistic changes are planned, mostly responses to bug reports.

Many/most of us use it in production settings already, as the AST check guarantees it isn't going to break anything, but the beta status means you can't always do a simple `pip install black`, and it means that black's formatting choices could change. 

Does a project as significant as Django want to adopt a beta tool whose "contract" with its users has not yet stabilized?

I heart black and would be happy to see it in Django but wonder if we should wait a bit to hit 1.0.

./s

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to <a href="javascript:" target="_blank" gdf-obfuscated-mailto="Xx_cbJOFBQAJ" rel="nofollow" onmousedown="this.href=&#39;javascript:&#39;;return true;" onclick="this.href=&#39;javascript:&#39;;return true;">django-d...@googlegroups.com.
To post to this group, send email to <a href="javascript:" target="_blank" gdf-obfuscated-mailto="Xx_cbJOFBQAJ" rel="nofollow" onmousedown="this.href=&#39;javascript:&#39;;return true;" onclick="this.href=&#39;javascript:&#39;;return true;">django-d...@googlegroups.com.
Visit this group at <a href="https://groups.google.com/group/django-developers" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://groups.google.com/group/django-developers&#39;;return true;" onclick="this.href=&#39;https://groups.google.com/group/django-developers&#39;;return true;">https://groups.google.com/group/django-developers.
To view this discussion on the web visit <a href="https://groups.google.com/d/msgid/django-developers/5d71f95a-1a8a-4db4-a2ac-8a59adde1fb5%40googlegroups.com?utm_medium=email&amp;utm_source=footer" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://groups.google.com/d/msgid/django-developers/5d71f95a-1a8a-4db4-a2ac-8a59adde1fb5%40googlegroups.com?utm_medium\x3demail\x26utm_source\x3dfooter&#39;;return true;" onclick="this.href=&#39;https://groups.google.com/d/msgid/django-developers/5d71f95a-1a8a-4db4-a2ac-8a59adde1fb5%40googlegroups.com?utm_medium\x3demail\x26utm_source\x3dfooter&#39;;return true;">https://groups.google.com/d/msgid/django-developers/5d71f95a-1a8a-4db4-a2ac-8a59adde1fb5%40googlegroups.com.
For more options, visit <a href="https://groups.google.com/d/optout" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://groups.google.com/d/optout&#39;;return true;" onclick="this.href=&#39;https://groups.google.com/d/optout&#39;;return true;">https://groups.google.com/d/optout.


--
Adam

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/4d5ec068-b06a-4c68-9805-29b00eab7983%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Dmitriy Sintsov
In reply to this post by Simon Charette
Why can't it use mixed quotes, single quotes for all strings except the strings that contain single quote characters? I think mixed syntax of strings is made in various programming languages so both single and double quotes can be used inside strings not having to use ugly backslash escaping. Maybe you or someone can create such feature request in black repo? Why the people do not like mixed quotes strings and try to eliminate such great feature? Aesthetical issues are very much biased and enforcing these automatically is not always a good idea. Does the switching to double quote string makes the code error prone and safer? Probably not. Just some voluntary personal choice.

On Monday, April 15, 2019 at 2:02:49 AM UTC+3, charettes wrote:
I was and and I'm still bugged by how black decided to go for double quotes instead of single ones. Even if it's backed some valid arguments it left all the projects following PEP 8's recommendations over the years with this git blaming loss trade off. From past experimentation with large'ish projects following PEP8's guideline string quotes changes represented well over 50% of the diff and there's no way to turn off only this form of string normalization, it's all or nothing. At $WORK we even went as far as forking the project to switch to use single quotes instead[0]. I understand requiring the use of a fork is not a feasible solution for Django but I just wished there was an option to stick to single quotes to reduce the cost of adoption for such projects without loosing all the other nifty string formatting goodies[1] /rant

Even if I don't completely agree with black's formatting choices and the sometimes quite unnatural code it generates my past month's usage at work and the adoption of the project in the Python ecosystem that made it's way in most IDE makes me mostly share the same feeling as Aymeric; it's not always pretty but not having to think about it makes it worth it. I suggest we stick to disabling string normalization to reduce the noise generated by the migration though.

Cheers,
Simon

[0] <a href="https://github.com/zapier/black/pull/1" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fzapier%2Fblack%2Fpull%2F1\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNF-IQbzZTF2OweXTK2WfVP1havOTQ&#39;;return true;" onclick="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fzapier%2Fblack%2Fpull%2F1\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNF-IQbzZTF2OweXTK2WfVP1havOTQ&#39;;return true;">https://github.com/zapier/black/pull/1
[1] <a href="https://github.com/ambv/black#strings" target="_blank" rel="nofollow" onmousedown="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fambv%2Fblack%23strings\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNEt5aRyzCpnyxys67m-GBHViYBsQg&#39;;return true;" onclick="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fambv%2Fblack%23strings\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNEt5aRyzCpnyxys67m-GBHViYBsQg&#39;;return true;">https://github.com/ambv/black#strings

Le dimanche 14 avril 2019 09:40:10 UTC-4, Aymeric Augustin a écrit :
Hello,

I'm strongly in favor of adopting black with the default options.

In my opinion, it's the first Python code formatter that passes the bar of "on average, does better than any single programmer". Trying to enforce something else manually is a waste of energy that produces worse results.

I like nicely formatted code and I hate some of what black produces, typically on Django model definitions. However, I've seen the benefits of an automated code formatter, even on projects where I write almost all of the code.

I'm positive the benefits will be great on Django, where you can tell when a module was (re)written just by looking at the style. Yes, there are some downsides, but it's clearly a good tradeoff.

Regarding the migration strategy, converting one package at a time sounds good, because then we can proof-read the Big Diff and perhaps tweak the code where the result really hurts the eyes.

Most of Django's style guide will still applies, as it's mostly conventions about naming things, ordering declarations, etc.

Best regards,

-- 
Aymeric.



On 13 Apr 2019, at 13:52, Herman S <[hidden email]> wrote:

Hi.

I propose that Django starts using 'black' [0] to auto-format all Python code.
For those unfamiliar with 'black' I recommend reading the the projects README.
The short version: it aims to reduce bike-shedding and non value-adding
discussions; saving time reviewing code; and making the barrier to entry lower
by taking some uncompromissing choices with regards to formatting.  This is
similar to tools such as 'gofmt' for Go and 'prettier' for Javascript.

Personally I first got involved contributing to Django couple of weeks back,
and from anecdotal experience I can testify to how 'formatting of code' creates
a huge barrier for entry. My PR at the time went multiple times back and forth
tweaking formatting. Before this, I had to research the style used by exploring
the docs at length and reading at least 10-20 different source – and even those
were not always consistent. At the end of the day I felt like almost 50% of the
time I used on the patch was not used on actually solving the issue at hand.
Thinking about code formatting in 2019 is a mental energy better used for other
things, and it feels unnecessary that core developers on Django spend their time
"nit-picking" on these things.

I recently led the efforts to make this change where I work. We have a 200K+
LOC Django code-base with more than 30K commits. Some key take-aways: it has
drastically changed the way we work with code across teams, new engineers are
easier on-boarded, PR are more focused on architectural choices and "naming
things", existing PRs before migration had surprisingly few conflicts and were
easy to fix, hot code paths are already "blameable" and it's easy to blame a
line of code and go past the "black-commit", and lastly the migration went
without any issues or down-time.

I had some really fruitful discussions at DjangoCon Europe this week on this
very topic, and it seems we are not alone in these experiences. I would love to
hear from all of you and hope that we can land on something that will enable
*more* people to easier contribute back to this project.

I've set up how this _could_ look depending on some configurables in Black:

* Default config: <a href="https://www.google.com/url?q=https%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F1&amp;sa=D&amp;sntz=1&amp;usg=AFQjCNHg_ctdhGBSbdZK3W4NXBAYv5TtMw" rel="nofollow" target="_blank" onmousedown="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F1\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNHg_ctdhGBSbdZK3W4NXBAYv5TtMw&#39;;return true;" onclick="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F1\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNHg_ctdhGBSbdZK3W4NXBAYv5TtMw&#39;;return true;">https://github.com/hermansc/django/pull/1
* Line length kept at 119: <a href="https://github.com/hermansc/django/pull/3" rel="nofollow" target="_blank" onmousedown="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F3\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNGnhCGXsB5HJ8sSyIW9DS2rkVMraw&#39;;return true;" onclick="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F3\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNGnhCGXsB5HJ8sSyIW9DS2rkVMraw&#39;;return true;">https://github.com/hermansc/django/pull/3
* Line length kept at 119, no string normalization:
<a href="https://www.google.com/url?q=https%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F2&amp;sa=D&amp;sntz=1&amp;usg=AFQjCNFQNq-hc9geZY_3egU-27BkSAvBhQ" rel="nofollow" target="_blank" onmousedown="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F2\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNFQNq-hc9geZY_3egU-27BkSAvBhQ&#39;;return true;" onclick="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fhermansc%2Fdjango%2Fpull%2F2\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNFQNq-hc9geZY_3egU-27BkSAvBhQ&#39;;return true;">https://github.com/hermansc/django/pull/2

Please have a look at the Black documentation. It explains the benefits better
than I possibly could do here.

With kind regards,
Herman Schistad

[0]: <a href="https://github.com/ambv/black" rel="nofollow" target="_blank" onmousedown="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fambv%2Fblack\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNGrqVzKdISFdVR5lSsDnknmEceSew&#39;;return true;" onclick="this.href=&#39;https://www.google.com/url?q\x3dhttps%3A%2F%2Fgithub.com%2Fambv%2Fblack\x26sa\x3dD\x26sntz\x3d1\x26usg\x3dAFQjCNGrqVzKdISFdVR5lSsDnknmEceSew&#39;;return true;">https://github.com/ambv/black

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at <a href="https://groups.google.com/group/django-developers" rel="nofollow" target="_blank" onmousedown="this.href=&#39;https://groups.google.com/group/django-developers&#39;;return true;" onclick="this.href=&#39;https://groups.google.com/group/django-developers&#39;;return true;">https://groups.google.com/group/django-developers.
To view this discussion on the web visit <a href="https://groups.google.com/d/msgid/django-developers/CAN%3DnMTx0EE5WfXuccv_e3MBuCxp9u_pAV_ow5MxNST6MptTDBw%40mail.gmail.com" rel="nofollow" target="_blank" onmousedown="this.href=&#39;https://groups.google.com/d/msgid/django-developers/CAN%3DnMTx0EE5WfXuccv_e3MBuCxp9u_pAV_ow5MxNST6MptTDBw%40mail.gmail.com&#39;;return true;" onclick="this.href=&#39;https://groups.google.com/d/msgid/django-developers/CAN%3DnMTx0EE5WfXuccv_e3MBuCxp9u_pAV_ow5MxNST6MptTDBw%40mail.gmail.com&#39;;return true;">https://groups.google.com/d/msgid/django-developers/CAN%3DnMTx0EE5WfXuccv_e3MBuCxp9u_pAV_ow5MxNST6MptTDBw%40mail.gmail.com.
For more options, visit <a href="https://groups.google.com/d/optout" rel="nofollow" target="_blank" onmousedown="this.href=&#39;https://groups.google.com/d/optout&#39;;return true;" onclick="this.href=&#39;https://groups.google.com/d/optout&#39;;return true;">https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/21ef3344-673b-49af-9cbb-c17bb928ab0b%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Kye Russell
This is something discussed af length on the black issue tracker and not something the author wishes to change. 

On Mon, 15 Apr 2019 at 4:47 pm, Dmitriy Sintsov <[hidden email]> wrote:
Why can't it use mixed quotes, single quotes for all strings except the strings that contain single quote characters? I think mixed syntax of strings is made in various programming languages so both single and double quotes can be used inside strings not having to use ugly backslash escaping. Maybe you or someone can create such feature request in black repo? Why the people do not like mixed quotes strings and try to eliminate such great feature? Aesthetical issues are very much biased and enforcing these automatically is not always a good idea. Does the switching to double quote string makes the code error prone and safer? Probably not. Just some voluntary personal choice.


On Monday, April 15, 2019 at 2:02:49 AM UTC+3, charettes wrote:
I was and and I'm still bugged by how black decided to go for double quotes instead of single ones. Even if it's backed some valid arguments it left all the projects following PEP 8's recommendations over the years with this git blaming loss trade off. From past experimentation with large'ish projects following PEP8's guideline string quotes changes represented well over 50% of the diff and there's no way to turn off only this form of string normalization, it's all or nothing. At $WORK we even went as far as forking the project to switch to use single quotes instead[0]. I understand requiring the use of a fork is not a feasible solution for Django but I just wished there was an option to stick to single quotes to reduce the cost of adoption for such projects without loosing all the other nifty string formatting goodies[1] /rant

Even if I don't completely agree with black's formatting choices and the sometimes quite unnatural code it generates my past month's usage at work and the adoption of the project in the Python ecosystem that made it's way in most IDE makes me mostly share the same feeling as Aymeric; it's not always pretty but not having to think about it makes it worth it. I suggest we stick to disabling string normalization to reduce the noise generated by the migration though.

Cheers,
Simon


Le dimanche 14 avril 2019 09:40:10 UTC-4, Aymeric Augustin a écrit :
Hello,

I'm strongly in favor of adopting black with the default options.

In my opinion, it's the first Python code formatter that passes the bar of "on average, does better than any single programmer". Trying to enforce something else manually is a waste of energy that produces worse results.

I like nicely formatted code and I hate some of what black produces, typically on Django model definitions. However, I've seen the benefits of an automated code formatter, even on projects where I write almost all of the code.

I'm positive the benefits will be great on Django, where you can tell when a module was (re)written just by looking at the style. Yes, there are some downsides, but it's clearly a good tradeoff.

Regarding the migration strategy, converting one package at a time sounds good, because then we can proof-read the Big Diff and perhaps tweak the code where the result really hurts the eyes.

Most of Django's style guide will still applies, as it's mostly conventions about naming things, ordering declarations, etc.

Best regards,

-- 
Aymeric.



On 13 Apr 2019, at 13:52, Herman S <[hidden email]> wrote:

Hi.

I propose that Django starts using 'black' [0] to auto-format all Python code.
For those unfamiliar with 'black' I recommend reading the the projects README.
The short version: it aims to reduce bike-shedding and non value-adding
discussions; saving time reviewing code; and making the barrier to entry lower
by taking some uncompromissing choices with regards to formatting.  This is
similar to tools such as 'gofmt' for Go and 'prettier' for Javascript.

Personally I first got involved contributing to Django couple of weeks back,
and from anecdotal experience I can testify to how 'formatting of code' creates
a huge barrier for entry. My PR at the time went multiple times back and forth
tweaking formatting. Before this, I had to research the style used by exploring
the docs at length and reading at least 10-20 different source – and even those
were not always consistent. At the end of the day I felt like almost 50% of the
time I used on the patch was not used on actually solving the issue at hand.
Thinking about code formatting in 2019 is a mental energy better used for other
things, and it feels unnecessary that core developers on Django spend their time
"nit-picking" on these things.

I recently led the efforts to make this change where I work. We have a 200K+
LOC Django code-base with more than 30K commits. Some key take-aways: it has
drastically changed the way we work with code across teams, new engineers are
easier on-boarded, PR are more focused on architectural choices and "naming
things", existing PRs before migration had surprisingly few conflicts and were
easy to fix, hot code paths are already "blameable" and it's easy to blame a
line of code and go past the "black-commit", and lastly the migration went
without any issues or down-time.

I had some really fruitful discussions at DjangoCon Europe this week on this
very topic, and it seems we are not alone in these experiences. I would love to
hear from all of you and hope that we can land on something that will enable
*more* people to easier contribute back to this project.

I've set up how this _could_ look depending on some configurables in Black:

* Default config: https://github.com/hermansc/django/pull/1
* Line length kept at 119: https://github.com/hermansc/django/pull/3
* Line length kept at 119, no string normalization:
https://github.com/hermansc/django/pull/2

Please have a look at the Black documentation. It explains the benefits better
than I possibly could do here.

With kind regards,
Herman Schistad

[0]: https://github.com/ambv/black

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAN%3DnMTx0EE5WfXuccv_e3MBuCxp9u_pAV_ow5MxNST6MptTDBw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/21ef3344-673b-49af-9cbb-c17bb928ab0b%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CANK-ykmWbnCdbnLcj%2B%2BEon5a9ny7W4-AyMAQMHOD%3DdFAMA%2BOoA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Josh Smeaton
Yes, let’s not discuss the tools choice in quotes, that’s for another place. To provide some information though, black will not convert single quote strings if the string itself contains a double quote. It won’t escape the character, it’ll use single quotes. 

On Mon, 15 Apr 2019 at 18:48, Kye Russell <[hidden email]> wrote:
This is something discussed af length on the black issue tracker and not something the author wishes to change. 

On Mon, 15 Apr 2019 at 4:47 pm, Dmitriy Sintsov <[hidden email]> wrote:
Why can't it use mixed quotes, single quotes for all strings except the strings that contain single quote characters? I think mixed syntax of strings is made in various programming languages so both single and double quotes can be used inside strings not having to use ugly backslash escaping. Maybe you or someone can create such feature request in black repo? Why the people do not like mixed quotes strings and try to eliminate such great feature? Aesthetical issues are very much biased and enforcing these automatically is not always a good idea. Does the switching to double quote string makes the code error prone and safer? Probably not. Just some voluntary personal choice.


On Monday, April 15, 2019 at 2:02:49 AM UTC+3, charettes wrote:
I was and and I'm still bugged by how black decided to go for double quotes instead of single ones. Even if it's backed some valid arguments it left all the projects following PEP 8's recommendations over the years with this git blaming loss trade off. From past experimentation with large'ish projects following PEP8's guideline string quotes changes represented well over 50% of the diff and there's no way to turn off only this form of string normalization, it's all or nothing. At $WORK we even went as far as forking the project to switch to use single quotes instead[0]. I understand requiring the use of a fork is not a feasible solution for Django but I just wished there was an option to stick to single quotes to reduce the cost of adoption for such projects without loosing all the other nifty string formatting goodies[1] /rant

Even if I don't completely agree with black's formatting choices and the sometimes quite unnatural code it generates my past month's usage at work and the adoption of the project in the Python ecosystem that made it's way in most IDE makes me mostly share the same feeling as Aymeric; it's not always pretty but not having to think about it makes it worth it. I suggest we stick to disabling string normalization to reduce the noise generated by the migration though.

Cheers,
Simon


Le dimanche 14 avril 2019 09:40:10 UTC-4, Aymeric Augustin a écrit :
Hello,

I'm strongly in favor of adopting black with the default options.

In my opinion, it's the first Python code formatter that passes the bar of "on average, does better than any single programmer". Trying to enforce something else manually is a waste of energy that produces worse results.

I like nicely formatted code and I hate some of what black produces, typically on Django model definitions. However, I've seen the benefits of an automated code formatter, even on projects where I write almost all of the code.

I'm positive the benefits will be great on Django, where you can tell when a module was (re)written just by looking at the style. Yes, there are some downsides, but it's clearly a good tradeoff.

Regarding the migration strategy, converting one package at a time sounds good, because then we can proof-read the Big Diff and perhaps tweak the code where the result really hurts the eyes.

Most of Django's style guide will still applies, as it's mostly conventions about naming things, ordering declarations, etc.

Best regards,

-- 
Aymeric.



On 13 Apr 2019, at 13:52, Herman S <[hidden email]> wrote:

Hi.

I propose that Django starts using 'black' [0] to auto-format all Python code.
For those unfamiliar with 'black' I recommend reading the the projects README.
The short version: it aims to reduce bike-shedding and non value-adding
discussions; saving time reviewing code; and making the barrier to entry lower
by taking some uncompromissing choices with regards to formatting.  This is
similar to tools such as 'gofmt' for Go and 'prettier' for Javascript.

Personally I first got involved contributing to Django couple of weeks back,
and from anecdotal experience I can testify to how 'formatting of code' creates
a huge barrier for entry. My PR at the time went multiple times back and forth
tweaking formatting. Before this, I had to research the style used by exploring
the docs at length and reading at least 10-20 different source – and even those
were not always consistent. At the end of the day I felt like almost 50% of the
time I used on the patch was not used on actually solving the issue at hand.
Thinking about code formatting in 2019 is a mental energy better used for other
things, and it feels unnecessary that core developers on Django spend their time
"nit-picking" on these things.

I recently led the efforts to make this change where I work. We have a 200K+
LOC Django code-base with more than 30K commits. Some key take-aways: it has
drastically changed the way we work with code across teams, new engineers are
easier on-boarded, PR are more focused on architectural choices and "naming
things", existing PRs before migration had surprisingly few conflicts and were
easy to fix, hot code paths are already "blameable" and it's easy to blame a
line of code and go past the "black-commit", and lastly the migration went
without any issues or down-time.

I had some really fruitful discussions at DjangoCon Europe this week on this
very topic, and it seems we are not alone in these experiences. I would love to
hear from all of you and hope that we can land on something that will enable
*more* people to easier contribute back to this project.

I've set up how this _could_ look depending on some configurables in Black:

* Default config: https://github.com/hermansc/django/pull/1
* Line length kept at 119: https://github.com/hermansc/django/pull/3
* Line length kept at 119, no string normalization:
https://github.com/hermansc/django/pull/2

Please have a look at the Black documentation. It explains the benefits better
than I possibly could do here.

With kind regards,
Herman Schistad

[0]: https://github.com/ambv/black

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAN%3DnMTx0EE5WfXuccv_e3MBuCxp9u_pAV_ow5MxNST6MptTDBw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/21ef3344-673b-49af-9cbb-c17bb928ab0b%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/django-developers/wK2PzdGNOpQ/unsubscribe.
To unsubscribe from this group and all its topics, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CANK-ykmWbnCdbnLcj%2B%2BEon5a9ny7W4-AyMAQMHOD%3DdFAMA%2BOoA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAPbDM0d5TmKs2%2Br4DcNeXMqnFkzCP%2B%3D7pF-0aJh_jANw2L5Sng%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

René Fleschenberg
In reply to this post by Josh Smeaton
Hi

> HMS = "%H:%M:%S"  # 14:30:59
> HMSF = ".." 
> HM = ".."
> TIME_INPUT_FORMATS  = [HMS, HMSF, HM]

Just my two cents: This particular rule is the main reason why I
personally have not adopted black yet. I really find the
one-item-per-line style *much* more readable in many cases.

In natural-language writing, there are occasions where you use "foo,
bar, baz" and other occasions where you use

- foo
- bar
- baz

IMO, both variants have their place in Python code, too. I'd like to see
a black variant which allows to leave this decision to a human.

--
René

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/1a9e62ac-8cdc-6660-2587-204230ec8dbf%40fleschenberg.net.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Ned Batchelder

On 4/15/19 7:13 AM, René Fleschenberg wrote:

> Hi
>
>> HMS = "%H:%M:%S"  # 14:30:59
>> HMSF = ".."
>> HM = ".."
>> TIME_INPUT_FORMATS  = [HMS, HMSF, HM]
> Just my two cents: This particular rule is the main reason why I
> personally have not adopted black yet. I really find the
> one-item-per-line style *much* more readable in many cases.
>
> In natural-language writing, there are occasions where you use "foo,
> bar, baz" and other occasions where you use
>
> - foo
> - bar
> - baz
>
> IMO, both variants have their place in Python code, too. I'd like to see
> a black variant which allows to leave this decision to a human.
>
Try the latest black.  A multi-line lists with comments on each line is
not converted to a one-line list.  The lined-up indentation of the
comments is lost :(, but it's still multi-line.

This is one of my concerns: Black is still beta, and is still adjusting
the way it formats in small ways.  So a boil-the-ocean formatting of the
code may not be the last time the code will change to suit black.

--Ned.

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/19e8938e-47be-d1f2-6349-bf4a9eb506de%40nedbatchelder.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

René Fleschenberg
Hi Ned.

> Try the latest black.  A multi-line lists with comments on each line is
> not converted to a one-line list.  The lined-up indentation of the
> comments is lost :(, but it's still multi-line.

Hmmm, I tried commit cea13f4 (current master at the time of this writing).

It turned

l = [
    1,  # one
    2,  # two
    3,  # three
]

into

l = [1, 2, 3]  # one  # two  # three

Maybe in your case the line limit kicked in and prevented the reformatting?

> This is one of my concerns: Black is still beta, and is still adjusting
> the way it formats in small ways.  So a boil-the-ocean formatting of the
> code may not be the last time the code will change to suit black.

I agree.

--
René

--
You received this message because you are subscribed to the Google Groups "Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/2137d5e8-80fd-eecc-9128-8e0f31d606d7%40fleschenberg.net.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Tim Allen
Another plus one for Black, without getting too into the weeds. I think the time is will save likely outweigh the valid concerns posted here. I've used Black extensively on several projects, and much like f-strings, the last Pink Floyd album, and broccoli, have found I really like something I didn't think I would.

I've gone through the churn of style edits each time I've made a PR to Django, despite using flake8. Having an automated tool to avoid that back-and-forth time would be a big help. It would also help reduce feelings of impostor syndrome; I know I've kicked myself for making basic formatting mistakes. Submitting to a project like Django can be intimidating, and this would remove some of the intimidation factor. I like to ask with every major change, "What does it mean for the newcomer?" Much like the new 2.0 URL routing syntax, I think this is  a slam-dunk.

While I prefer longer line lengths, I agree we should just stick with Black's defaults. Their commentary on the choice of 88 characters is compelling: it saves quite a bit of space over PEP-8's 79, but stays readable for the greater majority of people. Keeping the code base accessible to as many as possible is a big plus. I also find that with 88 character limits, I can keep three files open on a 16x9 screen in an editor, which is a nice editor workspace while working on Django (models file, views file, template). While Black may change in the future, I doubt the changes would be so large as to cause us to need another "huge commit and merge."

Regards,

Tim


--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/3b3f2605-f10e-4262-8547-c854c5cad644%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|

Re: Proposal to format Django using black

Simon Charette
In reply to this post by Florian Apolloner
Florian,

This option turns off *all* string normalization and not only quote normalization.

We wanted to still have prefixes stripping because of our usage of __future__.unicode_literals for example.

Cheers,
Simon

Le lundi 15 avril 2019 04:12:13 UTC-4, Florian Apolloner a écrit :
Hi Simon,

On Monday, April 15, 2019 at 1:02:49 AM UTC+2, charettes wrote:
 and there's no way to turn off only this form of string normalization, it's all or nothing.
 
So the black --help output lists:
-S, --skip-string-normalization Don't normalize string quotes or prefixes.
Or does that not what you wanted for your company?

Cheers,
Florian

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/0b01f92e-c17c-435d-abbf-9c0332ce3d2f%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
123456