More private utilities that need to be marked and public api deprecated

[Rowlando13]

In types.py

• convert_type - rename to _convert_type - currently has no top level import
• FuncParamType - maybe typing thing? - currently has no top level import

In _ ?,

• consider deprecating 'open_file'

[sirosen]

Should open_file and safecall be made private as well?

I'm looking at adapting pip-tools to handle v8.5.0 this morning, and we have (this all looks weird to me)...

my_file = click.open_file(filename, "w+b", atomic=True, lazy=True)
assert my_file is not None
if isinstance(my_file, click.utils.LazyFile):
    ctx.call_on_close(click.utils.safecall(my_file.close_intelligently))

I don't see any reason that anyone outside of click should ever use safecall: it's trivial to write it yourself. open_file doesn't seem good to expose if its return type won't be exposed. It's hard to figure out how to use it correctly in this case.

(We do want close_intelligently() since the target filename could be "-".)

[Rowlando13]

safe call is deprecated. It should issue a deprecation warning. I will have to check on the other.

[Rowlando13]

We will have to look at open_file. It is public on purpose but may need better type annotation or docs.

[sirosen]

I didn't want to suggest too much at first, but maybe we can spec it out with a typing.Protocol? I'm happy to help out if you want to go that route.

And yeah, I didn't notice that safecall was also warning, since I fixed this "all at once" on my end.

[Rowlando13]

Feel free to open an issue and propose a PR for what you think is best. I am always interested in type hints or docs that make usage clearer.

[davidism]

I feel like open_file should be private, but I haven't looked enough. atomic should be deprecated, if I remember correctly it's not actually atomic and there are better libraries out there for atomic access. lazy is only useful for the File param type when opening a file for writing, and should be invisible to the public API. It shouldn't matter if it's lazy, it should just close silently.