How do I use g_settings_schema_get_key from python?

Question

I'm following http://www.micahcarrick.com/gsettings-python-gnome-3.html to use GSettings from python, and I've succeeded to read a value:

from gi.repository import Gio
gso=Gio.Settings.new("org.gnome.desktop.wm.preferences")
gso.get_value("focus-mode")

This returns a "GLib.Variant", one of a set of enum values. To get valid enums I can set, I use:

gso.get_range("focus-mode")

However, the docs say

g_settings_get_range has been deprecated since version 2.40 and should not be used in newly-written code. Use g_settings_schema_key_get_range() instead.

So, how do I use g_settings_schema_key_get_range from python?

More generally, how can I introspect Gio to work out how to use it from python given the C docs?

Answer 1

You can use the regular python interpreter inspection:

>>> from gi.repository import Gio
>>> help (Gio)
>>> help (Gio.Settings)
>>> help (Gio.SettingsSchema)

...etc. It's not always very helpful but at least you can see whether a function exists in a namespace. Based on the docs, I would expect something like this to work:

schema = gso.get_property('settings-schema')
if schema.has_key('focus-mode'):
    key = schema.get_key('focus-mode')
    print (key.get_range())

Answer 2

You can also use the online documentation for PyGobject:

This function will return a GLib.Variant that fully describes the range of values that are valid for self.

The type of GLib.Variant returned is (sv). The string describes the type of range restriction in effect. The type and meaning of the value contained in the variant depends on the string.

If the string is 'type' then the variant contains an empty array. The element type of that empty array is the expected type of value and all values of that type are valid.

If the string is 'enum' then the variant contains an array enumerating the possible values. Each item in the array is a possible valid value and no other values are valid.

If the string is 'flags' then the variant contains an array. Each item in the array is a value that may appear zero or one times in an array to be used as the value for this key. For example, if the variant contained the array ['x', 'y'] then the valid values for the key would be [], ['x'], ['y'], ['x', 'y'] and ['y', 'x'].

Finally, if the string is 'range' then the variant contains a pair of like-typed values – the minimum and maximum permissible values for this key.

This information should not be used by normal programs. It is considered to be a hint for introspection purposes. Normal programs should already know what is permitted by their own schema. The format may change in any way in the future – but particularly, new forms may be added to the possibilities described above.

You should free the returned value with GLib.Variant.unref() when it is no longer needed.

That documentation is a gem. By the way, I believe you would also be interested in gso.get_enum(key):

Gets the value that is stored in self for key and converts it to the enum value that it represents.

In order to use this function the type of the value must be a string and it must be marked in the schema file as an enumerated type.

It is a programmer error to give a key that isn’t contained in the schema for self or is not marked as an enumerated type.

If the value stored in the configuration database is not a valid value for the enumerated type then this function will return the default value.

New in version 2.26.