Web Analytics Made Easy - Statcounter
Skip to content

The User Settings API is used to store your settings information from one session to another or from one program to another. They are stored on disk in either JSON or INI file formats.

In addition to user settings files, there is also a global PySimpleGUI settings file that PySimpleGUI uses to store information about the default Python interpreter you want to use with the Exec APIs, the default theme. You can directly access the global settings through the UserSettings object: pysimplegui_user_settings

UserSettings

UserSettings(
    filename = None,
    path = None,
    silent_on_error = False,
    autosave = True,
    use_config_file = None,
    convert_bools_and_none = True
)

Parameter Descriptions

Name Type Default Description
autosave bool True If True the settings file is saved after every update
convert_bools_and_none bool True If True then "True", "False", "None" will be converted to the Python values True, False, None when using INI files. Default is TRUE
filename (str or None) None The name of the file to use. Can be a full path and filename or just filename
path (str or None) None The folder that the settings file will be stored in. Do not include the filename.
silent_on_error bool False If True errors will not be reported
use_config_file bool None If True then the file format will be a config.ini rather than json

Class Properties

This class has no public properties

Class Methods

 def delete_entry
 def delete_file
 def delete_section
 def exists
 def get
 def get_dict
 def get_filename
 def load
 def read
 def save
 def set
 def set_default_value
 def set_location
 def write_new_dictionary

delete_entry

Deletes an individual entry. If no filename has been specified up to this point, then a default filename will be used. After value has been deleted, the settings file is written to disk.

delete_entry(
    key,
    section = None,
    silent_on_error = None
)

Parameter Descriptions

Name Type Default Description
key Any Setting to be deleted. Can be any valid dictionary key type (i.e. must be hashable)
silent_on_error bool None Determines if error should be shown. This parameter overrides the silent on error setting for the object.

delete_file

Deltes the filename and path for your settings file. Either paramter can be optional. If you don't choose a path, one is provided for you that is OS specific Windows path default = users/name/AppData/Local/PySimpleGUI/settings. If you don't choose a filename, your application's filename + '.json' will be used Also sets your current dictionary to a blank one.

delete_file(
    filename = None,
    path = None,
    report_error = False
)

Parameter Descriptions

Name Type Default Description
filename (str or None) None The name of the file to use. Can be a full path and filename or just filename
path (str or None) None The folder that the settings file will be stored in. Do not include the filename.
report_error bool False Determines if an error should be shown if a delete error happen (i.e. file isn't present)

delete_section

Deletes a section with the name provided in the section parameter. Your INI file will be saved afterwards if auto-save enabled (default is ON)

delete_section(
    section
)

Parameter Descriptions

Name Type Default Description
section str Name of the section to delete

exists

Check if a particular settings file exists. Returns True if file exists

exists(
    filename = None,
    path = None
)

Parameter Descriptions

Name Type Default Description
filename (str or None) None The name of the file to use. Can be a full path and filename or just filename
path (str or None) None The folder that the settings file will be stored in. Do not include the filename.

get

Returns the value of a specified setting. If the setting is not found in the settings dictionary, then the user specified default value will be returned. It no default is specified and nothing is found, then the "default value" is returned. This default can be specified in this call, or previously defined by calling set_default. If nothing specified now or previously, then None is returned as default.

get(
    key,
    default = None
)

Parameter Descriptions

Name Type Default Description
default Any None Value to use should the key not be found in the dictionary
key Any Key used to lookup the setting in the settings dictionary
RETURN Any Value of specified settings

get_dict

Returns the current settings dictionary. If you've not setup the filename for the settings, a default one will be used and then read.

Note that you can display the dictionary in text format by printing the object itself.

get_dict()

Parameter Descriptions

Name Type Default Description
RETURN Dict The current settings dictionary

get_filename

Sets the filename and path for your settings file. Either paramter can be optional.

If you don't choose a path, one is provided for you that is OS specific Windows path default = users/name/AppData/Local/PySimpleGUI/settings.

If you don't choose a filename, your application's filename + '.json' will be used.

Normally the filename and path are split in the user_settings calls. However for this call they can be combined so that the filename contains both the path and filename.

get_filename(
    filename = None,
    path = None
)

Parameter Descriptions

Name Type Default Description
filename (str or None) None The name of the file to use. Can be a full path and filename or just filename
path (str or None) None The folder that the settings file will be stored in. Do not include the filename.
RETURN str The full pathname of the settings file that has both the path and filename combined.

load

Specifies the path and filename to use for the settings and reads the contents of the file. The filename can be a full filename including a path, or the path can be specified separately. If no filename is specified, then the caller's filename will be used with the extension ".json"

load(
    filename = None,
    path = None
)

Parameter Descriptions

Name Type Default Description
filename (str or None) None Filename to load settings from (and save to in the future)
path (str or None) None Path to the file. Defaults to a specific folder depending on the operating system
RETURN dict The settings dictionary (i.e. all settings)

read

Reads settings file and returns the dictionary. If you have anything changed in an existing settings dictionary, you will lose your changes.

read()

Parameter Descriptions

Name Type Default Description
RETURN dict settings dictionary

save

Saves the current settings dictionary. If a filename or path is specified in the call, then it will override any previously specitfied filename to create a new settings file. The settings dictionary is then saved to the newly defined file.

save(
    filename = None,
    path = None
)

Parameter Descriptions

Name Type Default Description
filename (str or None) None The fFilename to save to. Can specify a path or just the filename. If no filename specified, then the caller's filename will be used.
path (str or None) None The (optional) path to use to save the file.
RETURN str The full path and filename used to save the settings

set

Sets an individual setting to the specified value. If no filename has been specified up to this point, then a default filename will be used. After value has been modified, the settings file is written to disk. Note that this call is not value for a config file normally. If it is, then the key is assumed to be the Section key and the value written will be the default value.

set(
    key,
    value
)

Parameter Descriptions

Name Type Default Description
key Any Setting to be saved. Can be any valid dictionary key type
value Any Value to save as the setting's value. Can be anything
RETURN Any value that key was set to

set_default_value

Set the value that will be returned if a requested setting is not found

set_default_value(
    default
)

Parameter Descriptions

Name Type Default Description
default Any value to be returned if a setting is not found in the settings dictionary

set_location

Sets the location of the settings file

set_location(
    filename = None,
    path = None
)

Parameter Descriptions

Name Type Default Description
filename (str or None) None The name of the file to use. Can be a full path and filename or just filename
path (str or None) None The folder that the settings file will be stored in. Do not include the filename.

write_new_dictionary

Writes a specified dictionary to the currently defined settings filename.

write_new_dictionary(
    settings_dict
)

Parameter Descriptions

Name Type Default Description
settings_dict dict The dictionary to be written to the currently defined settings file