1 of 21

globality-black tech talk

2021-12-09

2 of 21

TABLE OF CONTENTS

01 | Context

02 | Black and the magic comma

02 | globality-black

03 | Usage

04 | How to adopt

2

3 of 21

Context

Developers spend most of their time reading code, ~10x vs writing

A good code style allows to improve code reviewing experience

Code is more readable
But overall, is consistent
Speed up reading the code
Avoid nits in PRs --> speed up PR approval

Most of the time

there’s a widely accepted way to style a piece of code
there are different ways and no strong arguments for either of them
Examples

3

4 of 21

Horizontal spacing

4

5 of 21

Comprehensions

5

6 of 21

More examples

6

7 of 21

Context

What people do to ensure good code style

Expect everyone in the team writes good code :) (and/or educate people who don’t)
Linters, e.g. Flake8
Auto-formatters

Why auto-formatting?

same as good code style pros

Improve code reviewing experience
Avoiding nits in PRs

Help junior coders / newcomers to write code with consistent style
Speed up code writing experience

Popular auto-formatters

prettier (not python): 40k ⭐️
autopep8: 4k ⭐️
yapf: 12k ⭐️
black: 22k ⭐️ used in

popular projects e.g. pytest, scikit-learn, pandas, django, SQLAlchemy
orgs e.g. Facebook, Dropbox, ...

7

8 of 21

Black

Black is an opinionated Python auto-formatter. In their words:

Black is the uncompromising Python code formatter. By using it, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.

But you still have some control:

Max line length: set in pyproject.toml. Default = 88
Magic comma
# fmt: off - # fmt: on

8

9 of 21

The magic comma

Always explode if there is a trailing comma. Otherwise explode depending on whether it fits the max line length (default for black = 88 characters).

9

10 of 21

fmt: off – fmt: on

An automated tool will never handle well 100% of the cases. We can explicitly �protect portions of code

but without protection ...

10

11 of 21

Black

Black is an opinionated Python auto-formatter. In their words:

Black is the uncompromising Python code formatter. By using it, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.

You still have some control:

Magic comma
Max line length: set in pyproject.toml
#fmt:off - #fmt:on

After a PoC last year, we found that Black is right most of the time

Turns single quotes to double quotes
Fixes horizontal spacing
Many other no-brainers

but:

Compresses ALL comprehensions that fit into one line
Removes blank lines intended for readability
Compresses dotted chains

11

12 of 21

Well done, black

12

13 of 21

Oh no, black: comprehensions

13

14 of 21

Oh no, black: blank lines

14

15 of 21

Oh no, black: dotted chains

15

16 of 21

globality-black

Intended to fix most of the issues by black not adapting to Globality conventions
Pipeline: preprocessing --> black --> postprocessing
Features

Max line length: default = 100 --> but you can still configure it
comprehensions: overwrite black output by exploding if

dictionary
”complex” list/set
otherwise leave black output

blank lines: protector, not formatter
dotted chains: protector, not formatter
length 1 tuples: protector, not formatter
# fmt: off as in black

16

¹ All info here explained in the README

17 of 21

globality-black

Intended to fix most of the issues by black not adapting to Globality conventions
Pipeline: preprocessing --> black --> postprocessing
Features

Max line length: default = 100 --> but you can still configure it
comprehensions: overwrite black output by exploding if

dictionary
”complex” list/set
otherwise leave black output

blank lines: protector, not formatter
dotted chains: protector, not formatter
length 1 tuples: protector, not formatter
# fmt: off as in black

What we don’t cover

Ternary operators
Some nested comprehensions
Probably some other edge cases
See docs for examples

17

¹ All info here explained in the README

² Only .py in package (excluding notebooks) and excluding __init__ files

Success stories	lines of code ²	files ²	# fmt: off
Project 1	10k	100	7
Project 2	5.6k	45	10
Project 3	7k	80	0
Project 4	10k	65	14
Project 5	2.4k	40	2
Project 6	23k	258	5

18 of 21

Usage

See section in README

CLI

file or directory
check
diff

Pycharm
VScode
Jupyter notebooks
CI/CD: turn lint stage into isort --> flake8 --> globality-black

18

19 of 21

FAQ

How to adopt in my repo? Integrated in globality-build (Globality users only)

for python-service, python-library and ai-model
add “use_globality_black”: true to your build.json
re-run globality-build --> lint stage will turn into flake8 + isort + globality-black
failing if globality-black needs to be applied and showing changes in a git diff² format

100 characters per line is too short / long for me --> Just change the pyproject.toml setting

19

¹ See FAQ section in the README

²To achieve this, git is installed if use_globality_black

20 of 21

FAQ

How to adopt in my repo? Integrated in globality-build (Globality users only)

for python-service, python-library and ai-model
add “use_globality_black”: true to your build.json
re-run globality-build --> lint stage will turn into flake8 + isort + globality-black
failing if globality-black needs to be applied and showing changes in a git diff² format

100 characters per line is too short / long for me --> Just change the pyproject.toml setting
I don’t want to destroy all my git history (e.g. git blame) with a bulk change

Just add a .git-blame-ignore-revs file to your repo, ignoring the bulk commit where gblack is applied for the first time. Source

I want to explode some lists and keep some in one line --> magic comma
I want to ignore specific blocks of code -->

talk to Marc, v1 covered only comprehensions and blank lines!
easier/faster: just wrap with # fmt: off – # fmt: on

20

¹ See FAQ section in the README

²To achieve this, git is installed if use_globality_black

21 of 21

21

THANK YOU

and some credit to @pokey who helped with

the first prototype of globality-black