Is --target-version the minimum or should all be explicitly listed?

[hugovk]

With old Black 18.9b0, I had this in pyproject.toml:

[tool.black]
py36 = true

The new Black 19.3b0 warns:

--py36 is deprecated and will be removed in a future version. Use --target-version py36 instead.

The docs say:

  -t, --target-version [py27|py33|py34|py35|py36|py37|py38]
                                  Python versions that should be supported by
                                  Black's output. [default: per-file auto-
                                  detection]
  --py36                          Allow using Python 3.6-only syntax on all
                                  input files.  This will put trailing commas
                                  in function signatures and calls also after
                                  *args and **kwargs. Deprecated; use
                                  --target-version instead. [default: per-file
                                  auto-detection]

I see Black's own pyproject.toml includes:

[tool.black]
target_version = ['py36', 'py37', 'py38']

If I target just py36, does it treat that as a minimum?

Is that the same as ['py36', 'py37', 'py38']?

It recommended to explicitly list all the targetted versions?

[JelleZijlstra]

You should include all Python versions that you want your code to run under. In practice, though, 3.6 through 3.8 are currently the same as far as Black is concerned, so either variant will do the same.

Let us know if you think the docs can be improved.

[ambv]

Jelle, I get that certain edge cases in the grammar are only available in the newer versions, so we need the lower bound. Why do we need the upper bound, too?

[hynek]

FWIW I just had to look into black's source cod too, to figure out how to set target-version.

From the docs it's unclear that it takes multiple versions and reusing --target-version=py36 as target-version=py36 fails with confusing errors.

I think it's fine to allow supplying a range (although I'd prefer something like py27...py38 or py37... that conveys the meaning better), but the docs don't reflect that currently.

[hugovk]

Another confusion.

Let's say I support Python 3.5-3.8 so have this in pyproject.toml:

[tool.black]
target_version = ['py35', 'py36', 'py37', 'py38']

If I don't have this config file and want to do the same thing directly on the command line, do I need to repeat each argument?

$ black --target-version py35 --target-version py36 --target-version py37 --target-version py38 .

And then would .pre-commit.yaml need to look like this?

repos:
  - repo: https://github.com/psf/black
    rev: 19.10b0
    hooks:
      - id: black
        args: ["--target-version", "py35", "--target-version", "py36", "--target-version", "py37", "--target-version", "py38"]

These are pretty long, and it'd be nice to have a shorter range argument (or just a single lower bound).

---

I'm also curious why we need the upper bound. In practice, 3.5-3.8 is currently the same as just 3.5. What sort of theoretical cases are there where it'd be different?

Thanks!

[JelleZijlstra]

I'm also curious why we need the upper bound. In practice, 3.5-3.8 is currently the same as just 3.5. What sort of theoretical cases are there where it'd be different?

In theory, a new version of Python could change the syntax such that a kind of formatting that Black thinks is ideal is no longer supported. As a hypothetical example, maybe Python 3.9 will decide that all string prefixes have to be uppercase, so f"{x}" will be SyntaxError and only F"{x}" will be legal. In that case, if you set target_version to 3.5-3.8, we'd still emit f"{x}" (because Black's style prefers lowercase string prefixes), but with 3.5-3.9 we'd have to emit F"{x}".

In practice that sort of scenario doesn't seem terribly likely, so I'd be OK with making target_version just a minimum requirement.

[Zac-HD]

In practice that sort of scenario doesn't seem terribly likely, so I'd be OK with making target_version just a minimum requirement.

I was very surprised to discover it wasn't already a minimum requirement, and that only happened when I stumbled across this issue!

FWIW I think making forward-compatibilty the easy option is also better for the ecosystem 😄

[ambv]

At the same time I agree that it should almost certainly be 3.6+, 3.7+, 3.8+, and so on. But Jelle's got a point about possible syntax breaking changes in the future. I'm not sure if we should make this change.

[Zac-HD]

I'd hope the answer is "Python 2 taught us not to make breaking changes to the syntax" - and if we do, adding an optional --maximum-version argument will be the least of the problems dumped on the library ecosystem.

[henryiii]

My suggestion would be to read project.requires-python from pyproject.toml; you can compare using packaging.specifiers to see what the allowed versions are. cibuildwheel 1.9 does this. Since PEP 621, that is the canonical place for this information, and powerful enough to provide a subset or limit if needed.

See https://github.com/joerick/cibuildwheel/blob/58c5e56e9f271e32020b687f62cc02003602edd2/cibuildwheel/__main__.py#L173 and https://github.com/joerick/cibuildwheel/blob/58c5e56e9f271e32020b687f62cc02003602edd2/cibuildwheel/util.py#L77

[deathaxe]

if you set target_version to 3.5-3.8, we'd still emit f"{x}" (because Black's style prefers lowercase string prefixes), but with 3.5-3.9 we'd have to emit F"{x}".

This doesn't apply for python 3.3 does it? Black still outputs f-strings even though they are not supported.

[JelleZijlstra]

This doesn't apply for python 3.3 does it

Black doesn't support Python 3.3. Also, note that you're quoting a hypothetical out of context.

[scottclowe]

@hugovk

And then would .pre-commit.yaml need to look like this?

repos:
  - repo: https://github.com/psf/black
    rev: 19.10b0
    hooks:
      - id: black
        args: ["--target-version", "py35", "--target-version", "py36", "--target-version", "py37", "--target-version", "py38"]

These are pretty long, and it'd be nice to have a shorter range argument (or just a single lower bound).

You can alternatively write the yaml with the arguments stacked in a vertical list instead, which I think is a lot easier to read when you're specifying more than three versions for black to target.

repos:
  - repo: https://github.com/psf/black
    rev: 19.10b0
    hooks:
      - id: black
        args:
            - "--target-version=py35"
            - "--target-version=py36"
            - "--target-version=py37"
            - "--target-version=py38"

[ichard26]

@JelleZijlstra and I have decided to make --target-version the minimum. It better fits user expectations and it's the only way to reasonably support #3124. We'll still need to decide how specifying a single vs multiple versions will work though.

[yilei]

While implementing #3489, I came up with another need: a project may want to set a minimum version but still allow auto detecting target version when it uses newer syntaxes from later versions.

A concrete example: a projects supports Python 3.9+, but it may still contain some files with pattern matching syntax (a common case is its test files, it wants to make sure it works with pattern matching, but the test only runs on Python 3.10+).

Without specifying a minimum version of 3.9, it can't use parenthesized context managers (when the file doesn't contain syntaxes from 3.9+). But setting --target-version=3.9 today would make it fail to parse 3.10+ syntaxes.

[itdependsnetworks]

@JelleZijlstra and I have decided to make --target-version the minimum. It better fits user expectations and it's the only way to reasonably support #3124. We'll still need to decide how specifying a single vs multiple versions will work though.

Is it safe to say that thought it has been decided and has not been implemented? My interpretation of this thread is that current commendation for py38-py311 support would be:

target-version = ['py38', 'py39', 'py310', 'py311']

In the future it would be equivalent of:

target-version = ['py38']

[adamjstewart]

Any updates on this thread? I would also prefer specifying only the minimum version as it doesn't require using a bleeding edge version of black just to have it recognize 'py312' as a valid target version.