click.types.File Class Reference

Inheritance diagram for click.types.File:

Collaboration diagram for click.types.File:

Public Member Functions
None	__init__ (self, str mode="r", str|None encoding=None, str|None errors="strict", bool|None lazy=None, bool atomic=False)
dict[str, t.Any]	to_info_dict (self)
bool	resolve_lazy_flag (self, str|os.PathLike[str] value)
t.IO[t.Any]	convert (self, str|os.PathLike[str]|t.IO[t.Any] value, Parameter|None param, Context|None ctx)
list[CompletionItem]	shell_complete (self, Context ctx, Parameter param, str incomplete)
Public Member Functions inherited from click.types.ParamType
t.Any	__call__ (self, t.Any value, Parameter|None param=None, Context|None ctx=None)
str|None	get_metavar (self, Parameter param, Context ctx)
str|None	get_missing_message (self, Parameter param, Context|None ctx)
cabc.Sequence[str]	split_envvar_value (self, str rv)
t.NoReturn	fail (self, str message, Parameter|None param=None, Context|None ctx=None)

Public Attributes
	mode
	encoding
	errors
	lazy
	atomic
Public Attributes inherited from click.types.ParamType
	envvar_list_splitter

Static Public Attributes
str	name = "filename"
t	envvar_list_splitter = os.path.pathsep
Static Public Attributes inherited from click.types.ParamType
t	is_composite = False
t	arity = 1
str	name
t	envvar_list_splitter = None

Detailed Description

Declares a parameter to be a file for reading or writing.  The file
is automatically closed once the context tears down (after the command
finished working).

Files can be opened for reading or writing.  The special value ``-``
indicates stdin or stdout depending on the mode.

By default, the file is opened for reading text data, but it can also be
opened in binary mode or for writing.  The encoding parameter can be used
to force a specific encoding.

The `lazy` flag controls if the file should be opened immediately or upon
first IO. The default is to be non-lazy for standard input and output
streams as well as files opened for reading, `lazy` otherwise. When opening a
file lazily for reading, it is still opened temporarily for validation, but
will not be held open until first IO. lazy is mainly useful when opening
for writing to avoid creating the file until it is needed.

Files can also be opened atomically in which case all writes go into a
separate file in the same folder and upon completion the file will
be moved over to the original location.  This is useful if a file
regularly read by other users is modified.

See :ref:`file-args` for more information.

.. versionchanged:: 2.0
    Added the ``atomic`` parameter.

Member Function Documentation

convert()

t.IO[t.Any] click.types.File.convert	(		self,
		str | os.PathLike[str] | t.IO[t.Any]	value,
		Parameter | None	param,
		Context | None	ctx
	)

Convert the value to the correct type. This is not called if
the value is ``None`` (the missing value).

This must accept string values from the command line, as well as
values that are already the correct type. It may also convert
other compatible types.

The ``param`` and ``ctx`` arguments may be ``None`` in certain
situations, such as when converting prompt input.

If the value cannot be converted, call :meth:`fail` with a
descriptive message.

:param value: The value to convert.
:param param: The parameter that is using this type to convert
    its value. May be ``None``.
:param ctx: The current context that arrived at this value. May
    be ``None``.

Reimplemented from click.types.ParamType.

shell_complete()

list[CompletionItem] click.types.File.shell_complete	(		self,
		Context	ctx,
		Parameter	param,
		str	incomplete
	)

Return a special completion marker that tells the completion
system to use the shell to provide file path completions.

:param ctx: Invocation context for this command.
:param param: The parameter that is requesting completion.
:param incomplete: Value being completed. May be empty.

.. versionadded:: 8.0

Reimplemented from click.types.ParamType.

to_info_dict()

dict[str, t.Any] click.types.File.to_info_dict

(

self

)

Gather information that could be useful for a tool generating
user-facing documentation.

Use :meth:`click.Context.to_info_dict` to traverse the entire
CLI structure.

.. versionadded:: 8.0

Reimplemented from click.types.ParamType.

---

The documentation for this class was generated from the following file:

• docs/help/help-venv/lib/python3.12/site-packages/click/types.py