Make unimported utilities explicitely private

[Rowlando13]

This utilities are not imported in init:

• LazyFile
• KeepOpenFile
• make_short_help
• PacifyFlushWrapper
• safecall

Is that intentional?

[Rowlando13]

@davidism

[davidism]

Yes, and in the future I'd lean towards not exposing anything new to the top level (or public) without very deliberate consideration.

[Rowlando13]

I will also add private to the doc strings since they have no leading _.

[kdeldycke]

Maybe we can even move them to the _utils.py file.

[Rowlando13]

I think we should rename them with leading _ and move into _utils if there is not a better spot for them.

[kdeldycke]

Another proposal: if we have a lot of file-related private utilities, we can move them all to an _io.py file. Which can also anticipate a future public facing io.py file.

[benblank]

Apologies for butting in, but if LazyFile is being made private, is there a more appropriate type hint for parameters receiving lazily-opened files? In my own CLIs, I'm currently using it in that fashion, e.g.:

from typing import TYPE_CHECKING

import click

from . import cook_the_data


if TYPE_CHECKING:
    from io import BufferedReader

    from click.utils import LazyFile


@click.command()
@click.argument("in_file", type=click.File("r"))
@click.argument("out_file", type=click.File("w"))  # Implicitly lazy.
def do_stuff(*, in_file: BufferedReader, out_file: LazyFile) -> None:
    raw_data = in_file.read()
    cooked_data = cook_the_data(raw_data)

    with out_file.open() as out_file_writer:
        out_file_writer.write(cooked_data)

It would suck to lose the ability to correctly type-hint out_file, here. 🙂

[davidism]

It should not matter if the file is lazy or not, it has the same interface as a regular file.

[benblank]

Okay, I see where my misunderstanding was; I had missed LazyFile.__getattr__ and thought lazy files needed to be explicitly .open()ed before use. Thanks for helping clear that up!