Python API documentation for Settings class is incorrect

[cschreib]

Description of the bug

The documentation for sublime.Settings does not appear to be correct. It currently lists the following member functions that don't exist in 4169:

• __setitem__
• __delitem__
• __contains__
• to_dict
• setdefault
• update

The get member function, which exists in 4169, is not documented.

The summary "A dict like object that a settings hierarchy." seems to be missing a word ("that represents a settings hierarchy"?).

Furthermore, I am experiencing multithreading issues when trying to use this class in a worker thread; essentially all member functions (and sublime.load_settings() that creates the object in the first place) seem to have some sort of lock on them which blocks my worker thread. It isn't documented what creates this lock, so I don't know how to prevent it or work around it.

Steps to reproduce

Browse the public docs.

Expected behavior

Documentation reflects what the class can do

Actual behavior

Documentation is incorrect

Sublime Text build number

4169

Operating system & version

Linux Mint 21.2

(Linux) Desktop environment and/or window manager

Cinnamon

Additional information

No response

OpenGL context information

No response

[jfcherng]

sounds like you are writing a plugin with py33 rather than py38?

[cschreib]

Indeed! I didn't know the classes were different for the two versions. Now the class actually matches the docs, thanks. It still remains that:

• the docs don't mention that the class is different when using Python 3.3
• the docs don't mention why calling member functions of this class can block

[deathaxe]

Python 3.3 exists for backward compatibility only and therefore does not receive features/changes, which might break existing plugins. New plugins should target python 3.8 so this is the only up-to-date API of interest. Docs are auto-generated from sublime.py and sublime_plugin.py and thus should always be in-line.

The Settings.get() method has no doc comment and is therefore missing in generated API documentation.

All API functions are implemented in threadsafe manner, which involves holding a lock/mutex while being called from worker threads in order to avoid race conditions when multiple threads attempt to access the same object.

Furthermore python's GIL (global interpreter lock) prevents real multithreading.

[jfcherng]

• the docs don't mention that the class is different when using Python 3.3

Those methods are annotated as 3.8 in the doc. maybe it's not obvious what 3.8 means.

[cschreib]

All API functions are implemented in threadsafe manner, which involves holding a lock/mutex while being called from worker threads in order to avoid race conditions when multiple threads attempt to access the same object.

This might need clarifying or expanding upon in the docs then, as this wasn't obvious to me. For example, it can be thread-safe to read the settings from multiple threads simultaneously, or when another API function (or a command? I don't know) is being executed in another thread. But the API doesn't seem to allow it.

Tose methods are annotated as 3.8 in the doc. maybe it's not obvious what 3.8 means.

Oh! I didn't realize the 3.8 tag was for "Python 3.8"; I thought it referred to some SublimeText version.