Skip to content

API reference

The public API is two functions, both exported from the top-level package:

from pyfilechoose import file_choose, files_choose

Both take keyword-only arguments. The leading * in the signatures means you must pass title, filetypes, and initialdir by name, never positionally.

The filetypes argument

filetypes is shared by both functions and has the type:

Sequence[Tuple[str, str]]

Each tuple is (label, pattern):

  • label is the human-readable name shown in the dialog's type selector (for example "CSV files").
  • pattern is a glob the dialog uses to filter files (for example "*.csv"). Combine extensions with spaces: "*.png *.jpg".

If filetypes is None (the default), every file is shown.

pyfilechoose.file_choose(*, title='Select a file', filetypes=None, initialdir=None)

Open a dialog and return the absolute path of the chosen file.

A small replication of R's file.choose() for Python.

Parameters:

Name Type Description Default
title str

Title shown in the dialog window.

 'Select a file'
filetypes Optional[FileTypes]

Optional sequence of (label, pattern) pairs used to filter the files shown, e.g. [("CSV files", "*.csv"), ("All files", "*.*")].

 None
initialdir Optional[str]

Directory the dialog should open in. Defaults to the platform's last-used directory.

 None

Returns:

Type Description
str

The absolute path of the selected file.

Raises:

Type Description
FileNotFoundError

If the user cancels the dialog without selecting a file.

Examples:

>>> import pandas as pd
>>> df = pd.read_csv(file_choose(filetypes=[("CSV files", "*.csv")]))
Source code in src/pyfilechoose/core.py 
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def file_choose(
    *,
    title: str = "Select a file",
    filetypes: Optional[FileTypes] = None,
    initialdir: Optional[str] = None,
) -> str:
    """Open a dialog and return the absolute path of the chosen file.

    A small replication of R's ``file.choose()`` for Python.

    Parameters
    ----------
    title:
        Title shown in the dialog window.
    filetypes:
        Optional sequence of ``(label, pattern)`` pairs used to filter the
        files shown, e.g. ``[("CSV files", "*.csv"), ("All files", "*.*")]``.
    initialdir:
        Directory the dialog should open in. Defaults to the platform's
        last-used directory.

    Returns
    -------
    str
        The absolute path of the selected file.

    Raises
    ------
    FileNotFoundError
        If the user cancels the dialog without selecting a file.

    Examples
    --------
    >>> import pandas as pd
    >>> df = pd.read_csv(file_choose(filetypes=[("CSV files", "*.csv")]))
    """
    file_path = _open_dialog(
        multiple=False,
        title=title,
        filetypes=filetypes,
        initialdir=initialdir,
    )

    # askopenfilename returns an empty string when the user cancels.
    if not file_path:
        raise FileNotFoundError("No file was selected.")

    return os.path.abspath(file_path)

pyfilechoose.files_choose(*, title='Select one or more files', filetypes=None, initialdir=None)

Open a dialog allowing multiple selections and return absolute paths.

Parameters:

Name Type Description Default
title str

See :func:file_choose.

 'Select one or more files'
filetypes str

See :func:file_choose.

 'Select one or more files'
initialdir str

See :func:file_choose.

 'Select one or more files'

Returns:

Type Description
list of str

Absolute paths of every selected file, in selection order.

Raises:

Type Description
FileNotFoundError

If the user cancels the dialog without selecting any file.
Source code in src/pyfilechoose/core.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
def files_choose(
    *,
    title: str = "Select one or more files",
    filetypes: Optional[FileTypes] = None,
    initialdir: Optional[str] = None,
) -> list[str]:
    """Open a dialog allowing multiple selections and return absolute paths.

    Parameters
    ----------
    title, filetypes, initialdir:
        See :func:`file_choose`.

    Returns
    -------
    list of str
        Absolute paths of every selected file, in selection order.

    Raises
    ------
    FileNotFoundError
        If the user cancels the dialog without selecting any file.
    """
    selection: Iterable[str] = _open_dialog(
        multiple=True,
        title=title,
        filetypes=filetypes,
        initialdir=initialdir,
    )

    paths = [os.path.abspath(p) for p in selection]
    if not paths:
        raise FileNotFoundError("No file was selected.")

    return paths

Reference (without mkdocstrings)

If you read this page as plain Markdown rather than through the built docs site, the ::: directives above are placeholders that mkdocstrings expands into the rendered docstrings. The signatures are:

file_choose

file_choose(
    *,
    title: str = "Select a file",
    filetypes: Sequence[Tuple[str, str]] | None = None,
    initialdir: str | None = None,
) -> str

Opens a dialog and returns the absolute path of the chosen file.

Parameter Type Default Description
title str "Select a file" Title of the dialog window.
filetypes Sequence[Tuple[str, str]] \| None None (label, pattern) filters.
initialdir str \| None None Directory the dialog opens in.

Returns a str: the absolute path of the selected file.

Raises FileNotFoundError if the user cancels, and RuntimeError if tkinter is unavailable.

files_choose

files_choose(
    *,
    title: str = "Select one or more files",
    filetypes: Sequence[Tuple[str, str]] | None = None,
    initialdir: str | None = None,
) -> list[str]

Same as file_choose, but the dialog allows multiple selections and the return value is a list[str] of absolute paths in selection order.

Raises FileNotFoundError if nothing is selected, and RuntimeError if tkinter is unavailable.