Python typing hints may be stored either
- inside the original .py source file
- in a separate .pyi source file (aka. STUB).
Choice is made to create a new scriptforge.pyi file
- to allow hiding the private functions
- to specialize each module: technical doc
vs. user doc
- to allow potential later translation
- to minimize the impact at run-time:
stubs are active only during code edition.
The new scriptforge.pyi module
- provides the static type checking of all the public
interfaces (methods/properties) of the ScriptForge API.
- when the user uses an IDE like PyCharm or VSCode,
(s)he might benefit from the typing hints provided
by the signatures and docstrings stored
in the module.
Visually, while editing a user script:
- hovering an object instance, a method or a property
displays its detailed description
- a "." after an object instance displays a drop-down
box listing all available interfaces
- brackets after a method-name start code-completion
by displaying its arguments.
Limitations: SF supports ProperCase, lowercase and
camelCase naming for methods and properties.
Only ProperCase is described in scriptforge.pyi.
Extending to the other 2 notations would be easy
but would also overload needlessly the drop-down lists.
The effective code (scriptforge.py) is completed
with a series of importable variable types,
corresponding roughly with the available service
instance names in uppercase. Example
from scriptforge import CALC, RANGE
def userfct(c: CALC, r: RANGE) -> RANGE:
r1: RANGE = "A1:K10"
Objective: enrich the signatures in user scripts
and benefit from the same hints when the variable
types cannot be derived from the context.
The help documentation should be complemented
with the actual additional feature.
Change-Id: I6c39939a3cdbed94828e9449cd691fe15c24c923
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/164867
Reviewed-by: Jean-Pierre Ledure <jp@ledure.be>
Tested-by: Jenkins
Andrea Gelmini