pysimplegui之读写配置项操作

用户设置 API

在 4.30.0 版中，有一组新的 API 调用可用于帮助“用户设置”。将用户设置视为自动写入硬盘的字典。基本上就是这样。

在 4.50.0 版中，除了现有的 JSON 文件格式外，还添加了对 INI 文件的支持。

虽然使用 JSON 或配置文件来保存和加载设置字典并不是很困难，但如果要将设置保存为 GUI 的一部分，仍然需要编写代码。由于基于 GUI 的程序具有“设置”并不少见，因此将这种功能构建到 PySimpleGUI 中是有意义的。显然，您仍然可以使用自己的方法来保存设置，但如果您正在寻找一种简单易行的方法，那么这些调用可能会非常简单。

已经编写了一些使用 JSON 文件存储设置的演示程序。您可以预期此功能将在未来的更多演示中出现，因为它现在是 PySimpleGUI 的一部分。

用户设置存储在 Python 字典中，该字典保存到磁盘/从磁盘加载。因此，个人设置是字典的键。 您不需要显式读取或写入文件。更改任何条目都会导致文件被保存。如果尚未读取任何条目，则读取任何条目将导致读取该文件。

两个接口

有两种方法可以访问用户设置

1. 用户设置函数调用
2. UserSettings班级_

它们都提供相同的基本操作。类接口的另一个好处是能够使用与 Python 字典相同的语法访问各个设置。

如果要使用 INI 文件，则需要使用对象接口。

函数接口调用列表

功能	描述
用户设置	以字典形式返回设置
user_settings_delete_entry	删除设置
用户设置删除文件名	删除设置文件
user_settings_file_exists	如果指定的设置文件存在，则返回 True
用户设置文件名	返回当前设置文件的完整路径和文件名
user_settings_get_entry	返回设置的值。如果未找到设置，则返回指定的默认值
用户设置加载	从设置文件加载字典。这通常不需要
user_settings_save	将设置保存到当前或新指定的文件。通常不需要
user_settings_set_entry	将条目设置为特定值
user_settings_write_new_dictionary	将指定的字典写入设置文件

运营

呼叫可分为 2 类。

1. 文件操作
2. 设置操作

文件操作涉及使用 JSON 文件本身。它们包括： * 设置路径和/或文件名 * 加载/保存文件（这些是可选的，因为保存加载/保存是自动完成的） * 删除设置文件 * 检查设置文件是否存在

一般而言，使用通常是字符串的键来指定设置。设置操作用于处理单个设置，包括： * 获取设置的值（如果未找到则返回默认值） * 设置设置的值（也将设置保存到磁盘）

任何设置操作都可能导致文件被写入。这是因为如果未找到设置，“get”操作可以包括返回默认值。这意味着在您的设置字典中创建了一个新条目，该条目以前不存在。由于创建了一个新条目，这意味着它也需要写入磁盘。

文件名

设置文件名默认使用添加了扩展名“.json”的 Python 文件的文件名。如果您的 Python 程序被调用test.py，那么您的默认设置文件名将是test.json.

除了具有默认值的文件名之外，文件的路径也具有默认值。默认值取决于您的操作系统。

操作系统	默认路径
视窗	\user\user_name\AppData\Local\PySimpleGUI\settings
Linux	~/.config/PySimpleGUI/settings
苹果电脑	~/库/应用程序支持/PySimpleGUI/settings

调用用户设置 API 时，如果参数名为filename，您可以指定完整路径或仅指定文件名。这将为您省去在代码中拆分路径和文件名的麻烦。如果您仅指定路径，则文件名将添加到该路径并按照之前定义的方式命名。

与 PySimpleGUI 的其余部分一样，这个想法是让您编写尽可能少的代码。文件名和路径的默认值应该适合您使用。它们将存储在系统上用于存储用户设置的位置。

设置文件名

如果您想查看当前设置的文件名是什么，那么您可以user_settings_filename()不带参数调用，您将获得绝对路径和文件名。

为了使指定文件夹和文件名的代码尽可能简单，这两个部分在指定设置文件名称的调用中分开。但是，也可以提供完整且完整的文件夹 + 文件名。

设置文件的默认文件名是调用用户设置 API 的文件名，.py扩展名更改为.json扩展名。如果您的源文件被调用demo.py，那么您的设置文件名将是demo.json.

仅设置文件名

如果您想控制文件的名称和/或设置文件的路径，那么您将使用user_settings_filename调用。该函数有 2 个参数。

user_settings_filename(filename=None, path=None)

如果您仅设置路径，则文件名将默认为已描述的值。如果您只设置文件名，那么路径将是默认路径，具体取决于您的操作系统。有关每个操作系统的位置，请参见上表。

import PySimpleGUI as sg

sg.user_settings_filename(filename='my_settings.json')
print(sg.user_settings_filename())

如果您在 Windows 上运行，则运行此代码的结果将在控制台上打印：

C:\Users\your_use_name\AppData\Local\PySimpleGUI\settings\my_settings.json

您不限于将设置文件命名为 .json 的扩展名。这只是 PySimpleGUI 使用的默认扩展。你可以使用任何你想要的扩展，包括没有扩展。

仅设置路径

也许您不关心设置文件名本身，但您确实关心设置的存储位置。假设您希望将设置存储在与 Python 源文件相同的文件夹中。指定path='.'将实现这一点。

设置完全限定的文件名

如果要指定设置文件的完整绝对路径和文件名，可以使用 filename 参数来完成。不要只传递文件名，而是传递完全限定的路径和文件名。如果您想命名您的设置文件a:\temp\my_settings，那么您的调用将如下所示：

sg.user_settings_filename(filename=r'a:\temp\my_settings')

您不需要将文件分解为 2 个参数。如果你愿意，你可以。等效于使用 2 个参数的上述调用将是：

sg.user_settings_filename(filename='my_settings' , path=r'a:\temp')

获取当前文件名

不带参数调用user_settings_filename将返回设置文件的完整路径和文件名作为单个字符串。

文件加载/保存

一般来说，您不需要加载或保存设置文件。每次更改后都会自动保存。

请注意，读取设置也可能导致文件被写入。如果您读取了一个设置并且该设置不存在，那么您的调用user_settings_get_entry将返回您指定的默认值。结果，字典用这个默认值更新，作为回报，文件也用这个值写入。

您可能想要显式读取/加载设置文件的一种情况是，如果您希望它被另一个程序修改。

像 PySimpleGUI 一样，尽可能多地自动为您完成。这包括保存和加载设置文件的要求。甚至命名您的设置文件也是可选的。

类UserSettings接口

该类UserSettings使使用设置看起来像 Python 字典。熟悉的 [ ] 语法用于读取、写入和删除条目。

创建UserSettings对象

第一步是创建您的设置对象。参数与调用user_settings_filename函数相同。如果要使用默认值，则保持参数不变。

settings = sg.UserSettings()

这与调用相同 sg.user_settings_filename()

使用 [ ] 语法读取、写入和删除单个设置

第一个操作是创建用户设置对象。

settings = sg.UserSettings()

要读取设置，使用字典式 [ ] 语法。如果项目的名称是'-item-'，那么读取值是通过写入来实现的

item_value = settings['-item-']

编写设置的语法相同，但表达式相反。

settings['-item-'] = new_value

要删除一个项目，再次使用字典样式语法。

del settings['-item-']

您也可以调用 delete_entry 方法来删​​除条目。

settings.delete_entry('-item-')

UserSettings 方法

您会UserSettings在调用参考文档中找到所有可用的方法的详细信息。

特别是使用 [ ] 表示法无法实现的一项操作是具有默认值的“get”操作。对于字典，这个方法是get，对于UserSettings类，这个方法也被调用get。如果在字典中找不到键，它们都有一个可选的第二个参数，表示“默认值”。

如果您希望使用 key 的设置'-item-'返回一个空字符串''，而不是None如果找不到他们的 key，那么您可以使用此代码来实现：

value = settings.get('-item-', '')

它与您习惯用于字典的语法相同。

默认值

通常默认值是None如果没有找到键并且您使用括号格式获取条目的值：

item_value = settings['-item-']

您可以通过调用更改默认值settings.set_default_value(new_default)。这将设置默认值以在未找到密钥的情况下返回。请注意，当出现关键错误时不会引发异常（请参阅下一节有关错误处理的内容）。而是返回默认值并显示警告。

显示设置字典

类接口可以轻松转储字典。如果您打印 UserSettings 对象，您将获得字典的打印输出。

请注意，如果您尚未对设置执行任何操作，则需要从磁盘“加载”设置。

settings = sg.UserSettings()
settings.load()
print(settings)

如果您要在创建对象后打印字典，则load不需要

settings = sg.UserSettings()
print(settings['-item-'])
print(settings)

使用函数调用接口打印字典：

print(sg.user_settings())

用户设置的错误处理

从 GUI 的角度来看，用户设置对 GUI 操作本身并不重要。没有任何设置会导致您的窗口无法运行。因此，用户设置中发生的错误是“软错误”。如果可能，将显示一条错误消息以及有关您如何调用该函数的信息，然后继续执行。

将这些视为软错误并因此不引发异常的一个原因是引发异常会使您的 GUI 崩溃。如果您已经重定向了您的输出（许多 GUI 都会这样做），那么您将看不到任何错误信息，并且您的窗口将简单地消失。如果你双击一个 .py 文件来启动你的 GUI，如果 GUI 崩溃，GUI 和控制台窗口都会立即消失，没有任何信息可以帮助你调试问题。

唯一可能发生错误的时间是在文件操作期间。通常发生这些错误是因为您指定了错误的路径，或者您没有指定路径的写入权限。

示例错误消息。如果您执行此代码：

def main():
    sg.user_settings_filename(path='...')
    sg.user_settings_set_entry('-test-',123)

然后在尝试设置“-test-”条目时会出现错误，因为'...'它不是有效路径。

*** Error saving settings to file:***
 ...\scratch_1065.json [Errno 2] No such file or directory: '...\\scratch_1065.json'
The PySimpleGUI internal reporting function is save
The error originated from:
  File "C:/Users/mike/.PyCharmCE2019.1/config/scratches/scratch_1065.py"
line 8
in main
    sg.user_settings_set_entry('-test-',123)

您应该能够轻松找出这些错误，因为它们是文件操作，并且错误消息清楚地详细说明了发生的事情以及调用的来源。

消除错误

如果您不希望在控制台上看到任何错误消息，那么您可以将错误输出静音。

使用类接口时，有一个参数silent_on_error可以设置为True。

对于函数接口，调用函数user_settings_silent_on_error()并将参数设置为True

配置 INI 文件支持

与 JSON 相比，使用 INI 文件有一些优势，尤其是当人们要直接修改设置文件时。

要指定使用 INI 文件而不是 JSON，请use_config_file=True在创建UserSetting对象时设置参数。

settings = sg.UserSettings('my_config.ini', use_config_file=True, convert_bools_and_none=True)

请注意特定于 .ini 文件的 2 个参数： * use_config_file- 设置True为表示您正在使用 INI 文件 * convert_bools_and_none- 默认为True. 通常 INI 文件中的所有设置都是字符串。此参数将 'True'、'False' 和 'None' 转换为 Python 值True, False,None

还添加了一种附加方法delete_section，该方法将从 INI 文件中删除整个部分。

示例文件

让我们使用它作为我们的示例 INI 文件：

[My Section]
filename = test1234
filename2 = number 2
filename3 = number 3

[Section 2]
var = 123

[Empty]

[last section]
bool = True

获取/设置条目

就像 JSON 文件一样，您可以使用 UserSettings 类通过使用[ ]符号或调用get和set方法来访问各个设置。

INI 文件支持的最大区别是添加了一个额外的查找/参数，即部分名称。

要访问varsection中的条目Section 2，您可以使用这些中的枯萎：

settings['Section 2']['var']
settings['Section 2'].get('var', 'Default Value')

使用该get方法的优点是，如果条目不存在，则将返回默认值。

要设置条目，您还有 2 个选择：

settings['Section 2']['var'] = 'New Value'
settings['Section 2'].set('var', 'New Value')

访问 INI 文件部分

创建UserSettings对象后，您将使用 2 个键而不是 JSON 使用的 1 个键来访问条目。

要访问整个部分，您将编写：

settings['section']

要获得所有“我的部分”，它将是：

settings['My Section'] 它返回一个行为很像字典的部分对象。

要访问某个部分中的值，请再添加一个查找。要获取该部分中filename设置的值，请My Section使用以下代码完成：

settings['My Section']['filename']

删除条目

要删除单个条目，您可以使用几种不同的技术。一是使用del

del settings['My Section1']['test']

这将删除该test部分中的设置My Section1

您也可以通过调用delete_entry方法来做到这一点

settings.delete_entry(section='My Section1', key='test')

删除部分

如果要删除整个部分，有两种方法可以做到这一点。一种是调用方法UserSettings.delete_section并传入要删除的部分的名称。

settings.delete_section(section='My Section1')

另一种是查找该部分，然后调用delete_section该部分。

settings['My Section1'].delete_section()

INI 文件的打印设置

如果您为 INI 文件打印（或转换为字符串）节或 UserSettings 对象，那么您将获得格式良好的输出，其中显示节以及每个节中的设置。

回到前面的示例 INI 文件。打印此文件的 UserSettings 对象会产生以下输出：

My Section:
          filename : test1234
          filename2 : number 2
          filename3 : number 3
Section 2:
          var : 123
Empty:
last section:
          bool : True

INI 文件注释（警告）

如果您使用测试编辑器创建了一个 INI 文件，或者它是由 Python 创建的输出，那么在编写文件时，您的注释将被删除。正在将代码添加到 PySimpleGUI 以合并您的评论，但代码尚未完成。你要么暂时忍受这个限制，要么编写自己的合并代码。

是的，我知道，这很糟糕，但计划是克服这个 Python 限制。

用户设置键的编码约定

用户设置提示了一个新的编码约定，该约定已添加到 PySimpleGUI 示例中。正如您可能知道的那样，布局中的键具有格式'-KEY-'. 对于 UserSettings，使用了类似的格式，但字符串不是全部大写，而是字符小写。在下面的示例中，“文件名”的用户设置有一个用户设置键'-filename-'。在您的项目中拥有编码约定是一件好事。当然，您不必遵循这一点，但我们敦促您为代码中有意义的位置创建自己的位置。你可以说 PEP8 是整个 Python 语言的一个巨大的编码约定。您不必遵循它，但大多数 Python 程序员都会这样做。我们“按照惯例”遵循它。

在 PySimpleGUI 中执行此操作的原因是可以立即识别键。也许您的应用程序有您使用的字典。如果您遵循元素键的格式'-KEY-'和用户设置键的格式的 PySimpleGUI 编码约定'-key-'，那么您将立即了解特定键的用途。您的公司可能有自己的编码约定，因此如果合适，请遵循这些约定，而不是您在 PySimpleGUI 示例中看到的。

示例用户设置用法

可能使用的主要位置设置之一是文件名/文件夹名称。您运行了多少次相同的程序并需要输入相同的文件名？即使文件名在您的剪贴板上，每次运行代码时将其粘贴到输入字段中仍然很麻烦。如果您的程序记住您输入的最后一个值，会不会简单得多？嗯，这正是开发这套 API 的原因......再次，这种能力获得了生命的懒惰。

如果您希望Input元素默认为设置中的条目，则只需将第一个参数 ( default_text) 设置为设置文件中的设置值。

假设您的布局有这个典型的文件输入行：

[sg.Input(key='-IN-'), sg.FileBrowse()]

要自动填写Input最后输入的值，请使用以下布局行：

[sg.Input(sg.user_settings_get_entry('-filename-', ''), key='-IN-'), sg.FileBrowse()]

当您的用户单击确定或以积极的方式（而不是取消）关闭窗口时，然后添加此语句以保存该值。

sg.user_settings_set_entry('-filename-', values['-IN-'])

这是一个完整的程序，演示了这种使用用户设置的方式

import PySimpleGUI as sg

layout = [[sg.Text('Enter a filename:')],
          [sg.Input(sg.user_settings_get_entry('-filename-', ''), key='-IN-'), sg.FileBrowse()],
          [sg.B('Save'), sg.B('Exit Without Saving', key='Exit')]]

window = sg.Window('Filename Example', layout)

while True:
    event, values = window.read()
    if event in (sg.WINDOW_CLOSED, 'Exit'):
        break
    elif event == 'Save':
        sg.user_settings_set_entry('-filename-', values['-IN-'])

window.close()

在 2 行代码中，您让用户的生活变得如此轻松。而且，通过不为您的文件指定位置和名称，这些设置会被存储在视线之外/脑海中。如果您希望将设置与您的程序文件一起存储以便更明显，请在布局之前添加以下语句：

sg.user_settings_filename(path='.')

使用带有 [ ] 语法的 UserSettings 类的示例

可以使用UserSettings类和 [ ] 查找语法编写相同的示例。

这是与上面相同的程序。

import PySimpleGUI as sg

settings = sg.UserSettings()

layout = [[sg.Text('Enter a filename:')],
          [sg.Input(settings.get('-filename-', ''), key='-IN-'), sg.FileBrowse()],
          [sg.B('Save'), sg.B('Exit Without Saving', key='Exit')]]

window = sg.Window('Filename Example', layout)

while True:
    event, values = window.read()
    if event in (sg.WINDOW_CLOSED, 'Exit'):
        break
    elif event == 'Save':
        settings['-filename-'] = values['-IN-']

window.close()

如果您将这两个示例放在同一个文件中，以便一个接一个地运行，您会发现使用了相同的设置文件，因此第一个示例中保存的值将被第二个示例读取。

增加了一行代码：

settings.set_default_value('')      # Set the default not-found value to ''

严格来说，不需要这一行，因为 Input Element 现在None与 的值相同''，但为了产生相同的结果，我添加了这行代码。

演示程序

有许多演示程序展示了如何使用 UserSettings 为用户创建更丰富的体验，方法是记住最后一次输入到输入元素中的值，或者添加一个包含先前输入值历史的组合框。这些升级使 GUI 更易于使用，尤其是当您发现自己输入相同的值或使用相同的文件/文件夹时。

简短的警告 - 用户设置一直存在

如果您使用的是默认路径，请记住，之前运行的文件可能具有仍在设置文件中的旧设置。如果您忘记了之前编写的设置，您可能会感到困惑。看不到文件名可能会有这样的缺点。

此外，由于每次更新后设置都会自动保存，因此很容易意外覆盖以前保存的设置。如果您想避免这种情况，那么最好在代码中使用字典，然后在准备好将其提交到磁盘时显式保存字典。

要将 Python 字典保存到设置文件中，只需调用user_settings_write_new_dictionary(dict)，将字典作为参数传递。

文档来来源https://pysimplegui.readthedocs.io/en/latest/