What format should per-file options take?

[cpennington]

In #3388, I'm implementing in-file overrides for mypy options. Thus far, two different formats have come up, and I was asked to open this to come to an agreement on the preferred format.

Option 1: CLI-style

# mypy-options: --disallow-untyped-defs --allow-untyped-calls

Option 2: Config-style

# [mypy]
#     disallow_untyped_defs = True
#     disallow_untyped_calls = False

In both cases, I'm proposing that these options should have to be part of the first contiguous comment block in the file (preceded at most by lines of whitespace).

[miedzinski]

I'd want something more like

# mypy: disallow-untyped-defs allow-untyped-calls

with an option to split options into multiple lines

# mypy: disallow-untyped-defs
# mypy: allow-untyped-calls

Can't be simpler than that.

[cpennington]

Personally, I think I'd lean towards Option 1. It keeps a consistent format with another way in which you configure mypy (namely, the commandline), and it's more concise than Option 2. I do see the benefit of @miedzinski's suggestion, but think that losing the -- makes the format a bit less obviously an analog to the commandline.

[gvanrossum]

We should definitely not invent a new format, but follow either the command line or the config file.

I personally prefer using the config file format here, because in a sense it is the "canonical" format. The rule could be: when you put options in a file, you use the canonical format.

The config file format also makes it clear(er) that you can only specify "per-file" flags here, e.g. the various "strict" flags, and not "global only" flags such as --incremental or --python-version.

The config file format is also naturally a multi-line format, so we won't have to make up rules for multiple lines of flags.

[miedzinski]

If you really want to go for configparser's syntax in source code (which seems really weird), we should invent an end-of-mypy-config marker so it won't mix with possibly unrelated comments (e.g. flake8).

[gvanrossum]

which seems really weird

Why do you find weird? Do you have examples of other tools that have in-file configuration?

end-of-mypy-config marker

A blank (non-comment) line should suffice.

(e.g. flake8).

What is the format of flake8 comments? (I only know of # noqa per-line comments.)

[miedzinski]

which seems really weird

Why do you find weird? Do you have examples of other tools that have in-file configuration?

I simply don't like it and prefer my suggestion or opt 1.

(e.g. flake8).

What is the format of flake8 comments? (I only know of # noqa per-line comments.)

You can put # noqa: E001 etc at the top to apply it to whole file. Another example is # vim: noai:ts=4:sw=4.

[JukkaL]

I'd prefer using the config file option syntax but without a section header. For example:

# mypy: disallow_untyped_defs=True
# mypy: disallow_untyped_calls=False

Alternatively, we could use something like # mypy-option: ....

Rationale:

• Each line defines a single option and doesn't depend on other lines. Therefore copying options to another file is not error-prone (no need to remember to copy the section header).
• Specifying a single option is compact (only 1 line), compared to at least 2 lines for the section-based syntax.
• Grepping options is easier: look for # mypy: and you find all per-file options.
• There is no/less confusion about how to terminate a section since there is no section as such. We'll still need some rules about where the per-file options can appear, but mypy should perhaps just give an error if a valid-looking option is located at an unsupported location within a file.
• Fewer corner cases to handle such as multiple section headers.

I agree with @gvanrossum that it's better to mimic the per-file config file options here, since the command line options are global. Also, it's plausible that we will eventually have some options only valid within the config file. Having a very large number of command-line options is a little awkward, since --help output becomes hard to read etc.

[cpennington]

@JukkaL, @gvanrossum, @ddfisher: Is that enough consensus on @JukkaL's proposal that I should go ahead and implement it? It wouldn't be a huge deviation from the code I already have, which is nice.

[gvanrossum]

Let's go with Jukka's proposal. Note that you can use hyphens or underscores in config variable names, internally it's all converted to hyphens.

[hauntsaninja]

This was done at some point https://mypy.readthedocs.io/en/stable/inline_config.html