wizards/Package_scriptforge.mk | 1
wizards/source/scriptforge/python/scriptforge.py | 104
wizards/source/scriptforge/python/scriptforge.pyi | 7232 ++++++++++++++++++++++
3 files changed, 7317 insertions(+), 20 deletions(-)
New commits:
commit c5e0c65bd26664349fb7c80a792e2fe949fee0fe
Author: Jean-Pierre Ledure <j...@ledure.be>
AuthorDate: Fri Mar 15 15:55:45 2024 +0100
Commit: Jean-Pierre Ledure <j...@ledure.be>
CommitDate: Fri Mar 15 17:27:00 2024 +0100
ScriptForge - Python typing hints
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 <j...@ledure.be>
Tested-by: Jenkins
diff --git a/wizards/Package_scriptforge.mk b/wizards/Package_scriptforge.mk
index 4cd78e1f4982..96b5a907a321 100644
--- a/wizards/Package_scriptforge.mk
+++ b/wizards/Package_scriptforge.mk
@@ -57,5 +57,6 @@ $(eval $(call
gb_Package_add_files,wizards_basicsrvscriptforge,$(LIBO_SHARE_FOLD
$(eval $(call
gb_Package_add_files,wizards_basicsrvscriptforge,$(LIBO_LIB_PYUNO_FOLDER),\
python/scriptforge.py \
+ python/scriptforge.pyi \
))
# vim: set noet sw=4 ts=4:
diff --git a/wizards/source/scriptforge/python/scriptforge.py
b/wizards/source/scriptforge/python/scriptforge.py
index de590875c961..e339ada06d63 100644
--- a/wizards/source/scriptforge/python/scriptforge.py
+++ b/wizards/source/scriptforge/python/scriptforge.py
@@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
-# Copyright 2020-2024 Jean-Pierre LEDURE, Rafael LIMA, Alain ROMEDENNE
+# Copyright 2020-2024 Jean-Pierre LEDURE, Rafael LIMA, @AmourSpirit, Alain
ROMEDENNE
#
=====================================================================================================================
# === The ScriptForge library and its associated libraries are part
of the LibreOffice project. ===
@@ -38,6 +38,11 @@
- implements a protocol between those interfaces and, when
appropriate, the corresponding ScriptForge
Basic libraries implementing the requested services.
+ The scriptforge.pyi module
+ - provides the static type checking of all the visible interfaces of
the ScriptForge API.
+ - when the user uses an IDE like PyCharm or VSCode, (s)he might
benefit from the typing
+ hints provided by them thanks to the twin scriptforhe.pyi module.
+
Usage:
When Python and LibreOffice run in the same process (usual case):
@@ -45,10 +50,13 @@
When Python and LibreOffice are started in separate processes,
LibreOffice being started from console ... (example for Linux with
port = 2023)
- ./soffice --accept='socket,host=localhost,port=2023;urp;'
+ ./soffice --accept='socket,host=localhost,port=2024;urp;'
then use next statements:
from scriptforge import CreateScriptService, ScriptForge
- ScriptForge(hostname = 'localhost', port = 2023)
+ ScriptForge(hostname = 'localhost', port = 2024)
+
+ When the user uses an IDE like PyCharm or VSCode, (s)he might benefit
from the typing
+ hints provided by them thanks to the twin scriptforhe.pyi module.
Specific documentation about the use of ScriptForge from Python scripts:
https://help.libreoffice.org/latest/en-US/text/sbasic/shared/03/sf_intro.html?DbPAR=BASIC
@@ -59,6 +67,7 @@ import uno
import datetime
import time
import os
+from typing import TypeVar
class _Singleton(type):
@@ -446,10 +455,10 @@ class ScriptForge(object, metaclass = _Singleton):
class SFServices(object):
"""
- Generic implementation of a parent Service class
- Every service must subclass this class to be recognized as a valid
service
+ Generic implementation of a parent Service class.
+ Every service must subclass this class to be recognized as a valid
service.
A service instance is created by the CreateScriptService method
- It can have a mirror in the Basic world or be totally defined in Python
+ It can have a mirror in the Basic world or be totally defined in
Python.
Every subclass must initialize 3 class properties:
servicename (e.g. 'ScriptForge.FileSystem', 'ScriptForge.Basic')
@@ -659,7 +668,6 @@ class SFServices(object):
# SFScriptForge CLASS (alias of ScriptForge Basic
library) ###
#
#####################################################################################################################
class SFScriptForge:
- pass
# #########################################################################
# SF_Array CLASS
@@ -1227,12 +1235,12 @@ class SFScriptForge:
def MoveFile(self, source, destination):
return self.ExecMethod(self.vbMethod, 'MoveFile', source,
destination)
- def Normalize(self, filename):
- return self.ExecMethod(self.vbMethod, 'Normalize', filename)
-
def MoveFolder(self, source, destination):
return self.ExecMethod(self.vbMethod, 'MoveFolder', source,
destination)
+ def Normalize(self, filename):
+ return self.ExecMethod(self.vbMethod, 'Normalize', filename)
+
def OpenTextFile(self, filename, iomode = 1, create = False, encoding
= 'UTF-8'):
return self.ExecMethod(self.vbMethod, 'OpenTextFile', filename,
iomode, create, encoding)
@@ -1529,12 +1537,12 @@ class SFScriptForge:
def SetPDFExportOptions(self, pdfoptions):
return self.ExecMethod(self.vbMethod + self.flgDictArg,
'SetPDFExportOptions', pdfoptions)
- def UnoObjectType(self, unoobject):
- return self.ExecMethod(self.vbMethod, 'UnoObjectType', unoobject)
-
def UnoMethods(self, unoobject):
return self.ExecMethod(self.vbMethod + self.flgArrayRet,
'UnoMethods', unoobject)
+ def UnoObjectType(self, unoobject):
+ return self.ExecMethod(self.vbMethod, 'UnoObjectType', unoobject)
+
def UnoProperties(self, unoobject):
return self.ExecMethod(self.vbMethod + self.flgArrayRet,
'UnoProperties', unoobject)
@@ -2391,11 +2399,11 @@ class SFDocuments:
def OpenFormDocument(self, formdocument, designmode = False):
return self.ExecMethod(self.vbMethod, 'OpenFormDocument',
formdocument, designmode)
- def OpenQuery(self, queryname):
- return self.ExecMethod(self.vbMethod, 'OpenQuery', queryname)
+ def OpenQuery(self, queryname, designmode = False):
+ return self.ExecMethod(self.vbMethod, 'OpenQuery', queryname,
designmode)
- def OpenTable(self, tablename):
- return self.ExecMethod(self.vbMethod, 'OpenTable', tablename)
+ def OpenTable(self, tablename, designmode = False):
+ return self.ExecMethod(self.vbMethod, 'OpenTable', tablename,
designmode)
def PrintOut(self, formdocument, pages = '', copies = 1):
return self.ExecMethod(self.vbMethod, 'PrintOut', formdocument,
pages, copies)
@@ -2666,12 +2674,12 @@ class SFDocuments:
XChartObj = False, XDiagram = False, XShape =
False, XTableChart = False,
XTitle = True, YTitle = True)
- def Resize(self, xpos = -1, ypos = -1, width = -1, height = -1):
- return self.ExecMethod(self.vbMethod, 'Resize', xpos, ypos, width,
height)
-
def ExportToFile(self, filename, imagetype = 'png', overwrite = False):
return self.ExecMethod(self.vbMethod, 'ExportToFile', filename,
imagetype, overwrite)
+ def Resize(self, xpos = -1, ypos = -1, width = -1, height = -1):
+ return self.ExecMethod(self.vbMethod, 'Resize', xpos, ypos, width,
height)
+
# #########################################################################
# SF_Form CLASS
# #########################################################################
@@ -3032,6 +3040,62 @@ def CreateScriptService(service, *args, **kwargs):
createScriptService, createscriptservice = CreateScriptService,
CreateScriptService
+
+#
###############################################################################
+# FOR TYPING HINTS, NEXT VARIABLE TYPES MAY BE IMPORTED IN USER SCRIPTS
+# EXAMPLE:
+# from scriptforge import CALC, RANGE
+# def userfct(c: CALC, r: RANGE) -> RANGE:
+# r1: RANGE = "A1:K10"
+#
###############################################################################
+# List the available service types
+# SFScriptForge
+ARRAY = SFScriptForge.SF_Array
+BASIC = SFScriptForge.SF_Basic
+DICTIONARY = SFScriptForge.SF_Dictionary
+EXCEPTION = SFScriptForge.SF_Exception
+FILESYSTEM = SFScriptForge.SF_FileSystem
+L10N = SFScriptForge.SF_L10N
+PLATFORM = SFScriptForge.SF_Platform
+REGION = SFScriptForge.SF_Region
+SESSION = SFScriptForge.SF_Session
+STRING = SFScriptForge.SF_String
+TEXTSTREAM = SFScriptForge.SF_TextStream
+TIMER = SFScriptForge.SF_Timer
+UI = SFScriptForge.SF_UI
+# SFDatabases
+DATABASE = SFDatabases.SF_Database
+DATASET = SFDatabases.SF_Dataset
+DATASHEET = SFDatabases.SF_Datasheet
+# SFDialogs
+DIALOG = SFDialogs.SF_Dialog
+DIALOGCONTROL = SFDialogs.SF_DialogControl
+# SFDocuments
+DOCUMENT = SFDocuments.SF_Document
+BASE = SFDocuments.SF_Base
+CALC = SFDocuments.SF_Calc
+CALCREFERENCE = SFDocuments.SF_CalcReference
+CHART = SFDocuments.SF_Chart
+FORM = SFDocuments.SF_Form
+FORMCONTROL = SFDocuments.SF_FormControl
+FORMDOCUMENT = SFDocuments.SF_FormDocument
+WRITER = SFDocuments.SF_Writer
+# SFWidgets
+MENU = SFWidgets.SF_Menu
+POPUPMENU = SFWidgets.SF_PopupMenu
+TOOLBAR = SFWidgets.SF_Toolbar
+TOOLBARBUTTON = SFWidgets.SF_ToolbarButton
+# UNO
+UNO = TypeVar('UNO')
+# Other
+FILE = TypeVar('FILE', str, str)
+SHEETNAME = TypeVar('SHEETNAME', str, str)
+RANGE = TypeVar('RANGE', str, str)
+SCRIPT_URI = TypeVar('SCRIPT_URI', str, str)
+SQL_SELECT = TypeVar('SQL_SELECT', str, str)
+SQL_ACTION = TypeVar('SQL_ACTION', str, str)
+
+
# ######################################################################
# Lists the scripts, that shall be visible inside the Basic/Python IDE
# ######################################################################
diff --git a/wizards/source/scriptforge/python/scriptforge.pyi
b/wizards/source/scriptforge/python/scriptforge.pyi
new file mode 100644
index 000000000000..dc2569279786
--- /dev/null
+++ b/wizards/source/scriptforge/python/scriptforge.pyi
@@ -0,0 +1,7232 @@
+# -*- coding: utf-8 -*-
+
+# Copyright 2020-2024 Jean-Pierre LEDURE, Rafael LIMA, @AmourSpirit, Alain
ROMEDENNE
+
+#
=====================================================================================================================
+# === The ScriptForge library and its associated libraries are part
of the LibreOffice project. ===
+# === Full documentation is available on
https://help.libreoffice.org/ ===
+#
=====================================================================================================================
+
+# ScriptForge is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+# ScriptForge is free software; you can redistribute it and/or modify it under
the terms of either (at your option):
+
+# 1) The Mozilla Public License, v. 2.0. If a copy of the MPL was not
+# distributed with this file, you can obtain one at
http://mozilla.org/MPL/2.0/ .
+
+# 2) The GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version. If a copy of the LGPL was not
+# distributed with this file, see http://www.gnu.org/licenses/ .
+
+"""
+ ScriptForge libraries are an extensible and robust collection of macro
scripting resources for LibreOffice
+ to be invoked from user Basic or Python macros. Users familiar with other
BASIC macro variants often face hard
+ times to dig into the extensive LibreOffice Application Programming
Interface even for the simplest operations.
+ By collecting most-demanded document operations in a set of easy to use,
easy to read routines, users can now
+ program document macros with much less hassle and get quicker results.
+
+ The use of the ScriptForge interfaces in user scripts hides the complexity
of the usual UNO interfaces.
+ However, it does not replace them. At the opposite their coexistence is
ensured.
+ Indeed, ScriptForge provides a number of shortcuts to key UNO objects.
+
+ The scriptforge.py module
+ - describes the interfaces (classes and attributes) to be used in
Python user scripts
+ to run the services implemented in the standard modules shipped with
LibreOffice
+ - implements a protocol between those interfaces and, when
appropriate, the corresponding ScriptForge
+ Basic libraries implementing the requested services.
+
+ The scriptforge.pyi module
+ - provides the static type checking of all the visible interfaces of
the ScriptForge API.
+ - when the user uses an IDE like PyCharm or VSCode, (s)he might
benefit from the typing
+ hints provided by them thanks to the actual scriptforge.pyi module.
+
+ Specific documentation about the use of ScriptForge from Python scripts:
+
https://help.libreoffice.org/latest/en-US/text/sbasic/shared/03/sf_intro.html?DbPAR=BASIC
+ """
+# IMPORTS
+from __future__ import annotations
+import datetime
+import time
+from typing import Any, Dict, List, Literal, NewType, Optional, overload,
Sequence, Tuple, TypeVar, Union
+
+# List the available service types
+# SFScriptForge
+ARRAY = SFScriptForge.SF_Array
+BASIC = SFScriptForge.SF_Basic
+DICTIONARY = SFScriptForge.SF_Dictionary
+EXCEPTION = SFScriptForge.SF_Exception
+FILESYSTEM = SFScriptForge.SF_FileSystem
+L10N = SFScriptForge.SF_L10N
+PLATFORM = SFScriptForge.SF_Platform
+REGION = SFScriptForge.SF_Region
+SESSION = SFScriptForge.SF_Session
+STRING = SFScriptForge.SF_String
+TEXTSTREAM = SFScriptForge.SF_TextStream
+TIMER = SFScriptForge.SF_Timer
+UI = SFScriptForge.SF_UI
+# SFDatabases
+DATABASE = SFDatabases.SF_Database
+DATASET = SFDatabases.SF_Dataset
+DATASHEET = SFDatabases.SF_Datasheet
+# SFDialogs
+DIALOG = SFDialogs.SF_Dialog
+DIALOGCONTROL = SFDialogs.SF_DialogControl
+# SFDocuments
+DOCUMENT = SFDocuments.SF_Document
+BASE = SFDocuments.SF_Base
+CALC = SFDocuments.SF_Calc
+CALCREFERENCE = SFDocuments.SF_CalcReference
+CHART = SFDocuments.SF_Chart
+FORM = SFDocuments.SF_Form
+FORMCONTROL = SFDocuments.SF_FormControl
+FORMDOCUMENT = SFDocuments.SF_FormDocument
+WRITER = SFDocuments.SF_Writer
+# SFWidgets
+MENU = SFWidgets.SF_Menu
+POPUPMENU = SFWidgets.SF_PopupMenu
+TOOLBAR = SFWidgets.SF_Toolbar
+TOOLBARBUTTON = SFWidgets.SF_ToolbarButton
+# Aggregate
+SERVICE = Union[ARRAY, BASIC, DICTIONARY, EXCEPTION, FILESYSTEM, L10N,
PLATFORM, REGION, SESSION, STRING,
+ TEXTSTREAM, TIMER, UI,
+ DATABASE, DATASET, DATASHEET,
+ DIALOG, DIALOGCONTROL,
+ DOCUMENT, BASE, CALC, CALCREFERENCE, CHART, FORM, FORMCONTROL,
FORMDOCUMENT, WRITER,
+ MENU, POPUPMENU, TOOLBAR, TOOLBARBUTTON]
+# UNO
+UNO = TypeVar('UNO')
+# Other
+FILE = TypeVar('FILE', str, str)
+""" File or folder name expressed in accordance with the
``FileSystem.FileNaming`` notation. """
+
+SHEETNAME = TypeVar('SHEETNAME', str, str)
+""" A sheet in a Calc document, as a string. It must not contain next
characters: "[]*?:\\/". The apostrophe (')
+is forbidden in the first and last positions. The "~" (tilde) character
designates the active sheet. """
+RANGE = TypeVar('RANGE', str, str)
+""" A set of contiguous cells located in a sheet.
+
+The sheet name is optional. If no sheet name is provided, then the active
sheet is used.
+The use of single quotes to enclose the sheet name is required if the name
contains blank spaces " " or periods ".".
+Otherwise surrounding single quotes and $ signs are allowed but ignored.
+
+The shortcut "~" (tilde) represents the current selection or the first
selected range if multiple ranges are selected.
+The shortcut "*" represents all used cells.
+
+Examples
+ - ``$'SheetX'.D2``, ``$D$2`` - Single cells
+ - ``$'SheetX'.D2:F6``, ``D2:D10`` - Single ranges with multiple cells
+ - ``$'SheetX'.*`` - All used cells in the given sheet
+ - ``$'SheetX'.A:A``, ``3:5`` - All cells in contiguous columns or rows up
to the last used cell
+ - ``myRange`` - A range named "myRange" at spreadsheet level
+ - ``~.someRange``, ``SheetX.someRange`` - Range names at sheet level
+ - ``~.~`` or ``~`` - The current selection in the active sheet
+"""
+SCRIPT_URI = TypeVar('SCRIPT_URI', str, str)
+""" String reference to a Basic or Python macro as described in
+``https://wiki.documentfoundation.org/Documentation/DevGuide/Scripting_Framework#Scripting_Framework_URI_Specification``
+"""
+SQL_SELECT = TypeVar('SQL_SELECT', str, str)
+""" A SQL command containing a SELECT statement, a tablename or a queryname.
+In a SELECT statement, table-, qyery- and field names may be surrounded by
square brackets. """
+SQL_ACTION = TypeVar('SQL_ACTION', str, str)
+""" A SQL command containing an action statement (CREATE TABLE, INSERT,
DELETE, ...).
+Table- and field names may be surrounded by square brackets. """
+SCALAR = Union[int, float, str, datetime.datetime]
+VECTOR = Sequence[SCALAR]
+MATRIX = Sequence[VECTOR]
+
+# Define the used UNO types
+try:
+ # Next code can succeed only when types-unopy is installed
+ from com.sun.star.awt import XControl
+ from com.sun.star.awt import XControlModel
+ from com.sun.star.awt import XTabControllerModel
+ from com.sun.star.awt import XWindow
+ from com.sun.star.awt.tree import XMutableTreeDataModel
+ from com.sun.star.awt.tree import XMutableTreeNode
+ from com.sun.star.beans import PropertyValue
+ from com.sun.star.chart import XDiagram
+ from com.sun.star.document import XEmbeddedScripts
+ from com.sun.star.drawing import XShape
+ from com.sun.star.form import ListSourceType
+ from com.sun.star.form import XForm
+ from com.sun.star.frame import XDesktop
+ from com.sun.star.lang import XComponent
+ from com.sun.star.script import XLibraryContainer
+ from com.sun.star.script.provider import XScriptProvider
+ from com.sun.star.sdb import XOfficeDatabaseDocument
+ from com.sun.star.sdbc import XConnection as UNOXConnection
+ from com.sun.star.sdbc import XDatabaseMetaData
+ from com.sun.star.sheet import XSheetCellCursor
+ from com.sun.star.sheet import XSpreadsheet
+ from com.sun.star.table import XCellRange
+ from com.sun.star.table import XTableChart
+ from com.sun.star.uno import XComponentContext
+ from com.sun.star.uno import XInterface
+ from com.sun.star.util import Date as UNODate
+ from com.sun.star.util import DateTime as UNODateTime
+ from com.sun.star.util import Time as UNOTime
+except ImportError:
+ # types-unopy is not installed
+ XControl = NewType('XControl', UNO)
+ XControlModel = NewType('XControlModel', UNO)
+ XTabControllerModel = NewType('XTabControllerModel', UNO)
+ XWindow = NewType('XWindow', UNO)
+ XMutableTreeDataModel = NewType('XMutableTreeDataModel', UNO)
+ XMutableTreeNode = NewType('XMutableTreeNode', UNO)
+ PropertyValue = NewType('PropertyValue', UNO)
+ XDiagram = NewType('XDiagram', UNO)
+ XEmbeddedScripts = NewType('XEmbeddedScripts', UNO)
+ XShape = NewType('XShape', UNO)
+ ListSourceType = NewType('ListSourceType', UNO)
+ XForm = NewType('XForm', UNO)
+ XDesktop = NewType('XDesktop', UNO)
+ XComponent = NewType('XComponent', UNO)
+ XLibraryContainer = NewType('XLibraryContainer', UNO)
+ XScriptProvider = NewType('XScriptProvider', UNO)
+ XOfficeDatabaseDocument = NewType('XOfficeDatabaseDocument', UNO)
+ UNOXConnection = NewType('UNOXConnection', UNO)
+ XDatabaseMetaData = NewType('XDatabaseMetaData', UNO)
+ XSheetCellCursor = NewType('XSheetCellCursor', UNO)
+ XSpreadsheet = NewType('XSpreadsheet', UNO)
+ XCellRange = NewType('XCellRange', UNO)
+ XTableChart = NewType('XTableChart', UNO)
+ XComponentContext = NewType('XComponentContext', UNO)
+ XInterface = NewType('XInterface', UNO)
+ UNODate = NewType('UNODate', UNO)
+ UNODateTime = NewType('UNODateTime', UNO)
+ UNOTime = NewType('UNOTime', UNO)
+
+# Docstring rules to display readable text both in PyCharm and VS Code
+# Indentation and punctuation are required like in the example below.
+# def ImportFromCSVFile(self, filename: FILE, delimiter: str = ',',
+# dateformat: Literal['YYYY-MM-DD', 'DD-MM-YYYY',
'MM-DD-YYYY'] = ...) -> Tuple[str, ...]:
+# """
+# Import the data contained in a comma-separated values (CSV) file.
The comma may be replaced
+# by any character.
+# Difference with the Basic version: dates are returned in their iso
format,
+# not as any of the datetime objects.
+# Args <<<<< No colon (:)
+# ``filename``: The name of the text file containing the
data.
+# The name must be expressed according to the current
FileNaming property of the FileSystem
+# service.
+# <<<<< When multiple arguments, a linefeed is
required here
+# ``dateformat``: A special mechanism handles dates when
``dateformat`` is not the empty string.
+# The dash (-) may be replaced by a dot (.), a slash (/) or
a space. Other date formats
+# will be ignored.
+# Returns <<<<< No colon (:)
+# A ``list`` of ``lists``.
+# """
+# ...
+
+
+#
#####################################################################################################################
+# ScriptForge CLASS
###
+#
#####################################################################################################################
+
+class ScriptForge(object, metaclass = ...):
+ """
+ The ScriptForge class encapsulates the core of the ScriptForge run-time
+ - Bridge with the LibreOffice process
+ - Implementation of the interlanguage protocol with the Basic
libraries
+ - Identification of the available services interfaces
+ - Dispatching of services
+ - Coexistence with UNO
+
+ The class may be instantiated several times. Only the first instance
will be retained ("Singleton").
+ """
+
+ def __init__(self, hostname: str = ..., port: int = ...):
+ """
+ The ScriptForge class encapsulates the core of the ScriptForge
run-time
+ - Bridge with the LibreOffice process
+ - Implementation of the interlanguage protocol with the Basic
libraries
+ - Identification of the available services interfaces
+ - Dispatching of services
+ - Coexistence with UNO
+
+ The class may be instantiated several times. Only the first
instance will be retained ("Singleton").
+
+ Both arguments are mandatory when Python and LibreOffice run in
separate processes.
+ Otherwise, do not call this routine or leave both arguments out.
+ To execute at most once by LibreOffice session.
+ Args
+ ``hostname``: probably 'localhost'
+
+ ``port``: port number
+ """
+ ...
+
+
+#
#####################################################################################################################
+# SFServices CLASS (ScriptForge services
superclass) ###
+#
#####################################################################################################################
+
+class SFServices(object):
+ """
+ Generic implementation of a parent Service class.
+
+ Every service must subclass this class to be recognized as a valid
service.
+ A service instance is created by the ``CreateScriptService`` method.
+
+ It can have a mirror in the ``Basic`` world or be totally defined in
``Python``.
+ """
+
+ def Dispose(self) -> None:
+ """ Free up the object's resources after usage. """
+ ...
+
+ def GetProperty(self, propertyname: str, arg: Any = ...) -> Any:
+ """ Get the given property from the Basic world """
+ ...
+
+ def Properties(self) -> Tuple[str, ...]:
+ """ Properties list. """
+ ...
+
+
+#
#####################################################################################################################
+# SFScriptForge CLASS (alias of ScriptForge Basic
library) ###
+#
#####################################################################################################################
+class SFScriptForge:
+ """ SF_ScriptForge all-purpose services. """
+
+ # #########################################################################
+ # SF_Array CLASS
+ # #########################################################################
+ class SF_Array(SFServices, metaclass = ...):
+
+ def ImportFromCSVFile(self,
+ filename: FILE,
+ delimiter: str = ',',
+ dateformat: Literal['YYYY-MM-DD', 'DD-MM-YYYY',
'MM-DD-YYYY',
+ 'YYYY/MM/DD',
'DD/MM/YYYY', 'MM/DD/YYYY',
+ 'YYYY.MM.DD',
'DD.MM.YYYY', 'MM.DD.YYYY',
+ 'YYYY MM DD', 'DD MM
YYYY', 'MM DD YYYY'] = ...
+ ) -> MATRIX:
+ """
+ Import the data contained in a comma-separated values (CSV)
file. The comma may be replaced
+ by any character.
+ Difference with the Basic version: dates are returned in their
iso format,
+ not as any of the datetime objects.
+ Args
+ ``filename``: The name of the text file containing the
data.
+ The name must be expressed according to the current
FileNaming property of the FileSystem
+ service.
+
+ ``dateformat``: A special mechanism handles dates when
``dateformat`` is not the empty string.
+ The dash (-) may be replaced by a dot (.), a slash (/)
or a space. Other date formats
+ will be ignored.
+ Returns
+ A ``list`` of ``lists``.
+ """
+ ...
+
+ # #########################################################################
+ # SF_Basic CLASS
+ # #########################################################################
+ class SF_Basic(SFServices, metaclass = ...):
+ """
+ This service proposes a collection of Basic methods to be executed
in a Python context
+ simulating the exact syntax and behavior of the identical Basic
builtin method.
+ Typical example:
+ ``basic = CreateScriptService('basic')``
+ ``basic.MsgBox('This has to be displayed in a message box')``
+ """
+
+ MB_ABORTRETRYIGNORE: Literal[2]
+ MB_DEFBUTTON1: Literal[128]
+ MB_DEFBUTTON2: Literal[258]
+ MB_DEFBUTTON3: Literal[215]
+ MB_ICONEXCLAMATION: Literal[48]
+ MB_ICONINFORMATION: Literal[64]
+ MB_ICONQUESTION: Literal[32]
+ MB_ICONSTOP: Literal[16]
+ MB_OK: Literal[0]
+ MB_OKCANCEL: Literal[1]
+ MB_RETRYCANCEL: Literal[5]
+ MB_YESNO: Literal[4]
+ MB_YESNOCANCEL: Literal[3]
+ IDABORT: Literal[3]
+ IDCANCEL: Literal[2]
+ IDIGNORE: Literal[5]
+ IDNO: Literal[7]
+ IDOK: Literal[1]
+ IDRETRY: Literal[4]
+ IDYES: Literal[6]
+
+ @classmethod
+ def CDate(cls, datevalue: Union[int, float, str]) ->
Optional[datetime.datetime]:
+ """
+ Converts a numeric expression or a string to a
``datetime.datetime`` Python native object.
+ Args
+ ``datevalue``: A numeric expression or a ``string``
representing a date.
+ Returns
+ The equivalent ``datetime.datetime``.
+ """
+ ...
+
+ @staticmethod
+ def CDateFromUnoDateTime(unodate: Union[UNODateTime, UNODate,
UNOTime]) -> datetime.datetime:
+ """
+ Converts a ``UNO date/time`` representation to a
``datetime.datetime`` Python native object.
+ Args
+ ``unodate``: A ``UNO date`` object,
``com.sun.star.util.DateTime``, ``.Date`` or ``.Time``.
+ Returns
+ The equivalent ``datetime.datetime``.
+ """
+ ...
+
+ @staticmethod
+ def CDateToUnoDateTime(date: Union[float, time.struct_time,
datetime.datetime, datetime.date, datetime.time]
+ ) -> UNODateTime:
+ """
+ Converts a date representation into the
``com.sun.star.util.DateTime`` date format.
+ Args
+ ``date``: A ``datetime`` like object.
+ When ``date`` is a ``float`` it is considered a
``time.time`` value.
+ Returns
+ A ``com.sun.star.util.DateTime`` UNO object.
+ """
+ ...
+
+ @classmethod
+ def ConvertFromUrl(cls, url: str) -> str:
+ """
+ Convert from url.
+ Args
+ ``url``: A string representing a file in URL format.
+ Returns
+ The same file name in native operating system
notation._
+ """
+ ...
+
+ @classmethod
+ def ConvertToUrl(cls, systempath: str) -> str:
+ """
+ Convert to url.
+ Args
+ ``systempath``: A string representing a file in native
operating system notation.
+ Returns
+ The same file name in URL format.
+ """
+ ...
+
+ @classmethod
+ def CreateUnoService(cls, servicename: str) -> UNO:
+ """
+ Instantiates a UNO service
+ Args
+ ``servicename``: A string representing the service to
create.
+ Returns
+ A UNO object
+ """
+ ...
+
+ @classmethod
+ def CreateUnoStruct(cls, unostructure: str) -> UNO:
+ """
+ Returns an instance of a UNO structure of the specified type.
+ Args
+ ``unostructure``: A UNO Struct typename such as
``com.sun.star.awt.Size``.
+ Returns
+ A UNO Object
+ """
+ ...
+
+ @classmethod
+ def DateAdd(cls,
+ interval: Literal['yyyy', 'q', 'm','y', 'w', 'ww', 'd',
'h', 'n', 's'],
+ number: int,
+ date: Union[float, time.struct_time, datetime.datetime,
datetime.date, datetime.time]
+ ) -> datetime.datetime:
+ """
+ Adds a date or time interval to a given date/time a number of
times and returns the resulting date.
+ Args
+ ``interval``: A string expression specifying the date
or time interval.
+
+ ``number``: A numerical expression specifying how
often the interval value will be added when
+ positive or subtracted when negative.
+
+ ``date``: A given ``datetime.datetime`` value, the
interval value will be added ``number``
+ times to this ``date`` value.
+ Returns
+ A ``datetime.datetime`` value.
+ """
+ ...
+
+ @classmethod
+ def DateDiff(cls,
+ interval: Literal['yyyy', 'q', 'm','y', 'w', 'ww', 'd',
'h', 'n', 's'],
+ date1: Union[float, time.struct_time, datetime.datetime,
datetime.date, datetime.time],
+ date2: Union[float, time.struct_time, datetime.datetime,
datetime.date, datetime.time],
+ firstdayofweek: Literal[0, 1, 2, 3, 4, 5, 6, 7] = ...,
+ firstweekofyear: Literal[0, 1, 2, 3] = ...,
+ ) -> int:
+ """
+ Gets the number of date or time intervals between two given
date/time values.
+ Args
+ ``interval``: A string expression specifying the date
interval.
+
+ ``date1``: The first ``datetime.datetime`` values to
be compared.
+
+ ``firstdayofweek``: An optional parameter that
specifies the starting day of a week.
+
+ ``firstweekofyear``: An optional parameter that
specifies the starting week of a year.
+ Returns
+ A number.
+ """
+ ...
+
+ @classmethod
+ def DatePart(cls,
+ interval: Literal['yyyy', 'q', 'm','y', 'w', 'ww', 'd',
'h', 'n', 's'],
+ date: Union[float, time.struct_time, datetime.datetime,
datetime.date, datetime.time],
+ firstdayofweek: Literal[0, 1, 2, 3, 4, 5, 6, 7] = ...,
+ firstweekofyear: Literal[0, 1, 2, 3] = ...,
+ ) -> int:
+ """
+ Gets a specified part of a date.
+ Args
+ ``interval``: A string expression specifying the date
interval.
+
+ ``date``: The date from which to extract a part.
+
+ ``firstdayofweek``: the starting day of a week.
Defaults to 1.
+
+ ``firstweekofyear``: the starting week of a year.
Defaults to 1.
+ Returns
+ The specified part of the date.
+ """
+ ...
+
+ @classmethod
+ def DateValue(cls, string: str) -> datetime.datetime:
+ """
+ Computes a date value from a date string.
+ Args
+ ``string``: A string expression that contains the date
that you want to calculate.
+ The string passed to ``DateValue`` must be expressed
in one of the date formats defined
+ by your locale setting or using the ISO date format
"yyyy-mm-dd" (year, month and day
+ separated by hyphens).
+ Returns
+ The converted date.
+ """
+ ...
+
+ @classmethod
+ def Format(cls, expression: Union[datetime.datetime, float, int],
format: str = ...) -> str:
+ """
+ Converts a number to a string, and then formats it according
to the format that you specify.
+ Args
+ ``expression``: Numeric expression that you want to
convert to a formatted string.
+
+ ``format``: the format to apply. Defaults to "".
+ Returns
+ The formatted value.
+ """
+ ...
+
+ @classmethod
+ def GetDefaultContext(cls) -> XComponentContext:
+ """
+ Gets the default context of the process service factory, if
existent, else returns a None reference.
+ """
+ ...
+
+ @classmethod
+ def GetGuiType(cls) -> int:
+ """
+ Gets a numerical value that specifies the graphical user
interface.
+ Returns
+ The GetGuiType value, 1 for Windows, 4 for UNIX
+ """
+ ...
+
+ @classmethod
+ def GetPathSeparator(cls) -> str:
+ """
+ Gets the operating system-dependent directory separator used
to specify file paths.
+ Returns
+ The os path separator
+ """
+ ...
+
+ @classmethod
+ def GetSystemTicks(cls) -> int:
+ """
+ Gets the number of system ticks provided by the operating
system.
+ You can use this function to optimize certain processes.
+ Use this method to estimate time in milliseconds:
+ Returns
+ The actual number of system ticks.
+ """
+ ...
+
+ class GlobalScope(metaclass = ...):
+ """
+ Use cases:
+ - ``GlobalScope.BasicLibraries``
+ - ``GlobalScope.DialogLibraries``
+ """
+
+ @classmethod
+ def BasicLibraries(cls) -> XLibraryContainer:
+ """
+ ``GlobalScope.BasicLibraries`` gets the UNO object
containing all shared Basic libraries
+ and modules. This method is the Python equivalent to
``GlobalScope.BasicLibraries``
+ in Basic scripts.
+ Returns
+ A ``XLibraryContainer`` UNO object.
+ """
+ ...
+
+ @classmethod
+ def DialogLibraries(cls) -> XLibraryContainer:
+ """
+ ``GlobalScope.DialogLibraries`` gets the UNO object
containing all shared dialog libraries.
+ Returns
+ A ``DialogLibraryContainer`` UNO object.
+ """
+ ...
+
+ @classmethod
+ def InputBox(cls,
+ prompt: str,
+ title: str = ...,
+ default: str = ...,
+ xpostwips: int = ...,
+ ypostwips: int = ...,
+ ) -> str:
+ """
+ Displays an input box.
+ Args
+ ``prompt``: String expression displayed as the message
in the dialog box.
+
+ ``title``: String expression displayed in the title
bar of the dialog box.
+
+ ``default``: String expression displayed in the text
box as default ifno other input is given.
+
+ ``xpostwips``: Integer expression that specifies the
horizontal position of the dialog.
+ The position is an absolute coordinate and does not
refer to the window of LibreOffice.
+
+ ``ypostwips``: Integer expression that specifies the
vertical position of the dialog.
+ The position is an absolute coordinate and does not
refer to the window of LibreOffice.
+
+ If ``xpostwips`` and ``ypostwips`` are omitted, the
dialog is centered on the screen.
+ Returns
+ The input string.
+ """
+ ...
+
+ @classmethod
+ def MsgBox(cls, prompt: str, buttons: int = ..., title: str = ...) ->
int:
+ """
+ Displays a dialogue box containing a message and returns an
optional value.
+
+ MB_xx constants help specify the dialog type, the number and
type of buttons to display,
+ plus the icon type. By adding their respective values they
form bit patterns, that define the
+ MsgBox dialog appearance.
+ Args
+ ``prompt``: String expression displayed as a message
in the dialog box.
+
+ ``buttons``: Integer expression that specifies the
dialog type, as well as the number
+ and type of buttons to display, and the icon type.
``buttons`` represents a combination of bit
+ patterns, that is, a combination of elements can be
defined by adding their respective values.
+ Defaults to 0.
+
+ ``title``: String expression displayed in the title
bar of the dialog. Defaults to "".
+ Returns
+ The pressed button.
+ """
+ ...
+
+ @classmethod
+ def Now(cls) -> datetime.datetime:
+ """
+ Gets the current system date and time as a
``datetime.datetime`` Python native object.
+ """
+ ...
+
+ @classmethod
+ def RGB(cls, red: int, green: int, blue: int) -> int:
+ """
+ Gets an integer color value consisting of red, green, and blue
components.
+ Args
+ ``red``: An integer expression that represents the red
component (0-255) of the composite color.
+
+ ``green``: An integer expression that represents the
green component (0-255) of the
+ composite color.
+
+ ``blue``: An integer expression that represents the
blue component (0-255) of the composite
+ color.
+ Returns
+ An integer color value consisting of red, green, and
blue components.
+ """
+ ...
+
+
+ @classmethod
+ def Xray(cls, unoobject: UNO) -> None:
+ """
+ Inspect UNO objects or variables.
+ Args
+ ``unoobject``: A variable or UNO object.
+ """
+ ...
+
+ StarDesktop: XDesktop
+ """ Gets the desktop as a UNO object. """
+ ThisComponent: Optional[XComponent]
+ """
+ If the current component refers to a LibreOffice document, this
method
+ returns the UNO object representing the document.
+ When the current component is the Basic IDE, the ThisComponent
object returns in Basic the
+ component owning the currently run user script. This behaviour
cannot be reproduced in Python.
+ Returns
+ The current component or None when not a document.
+ """
+ ThisDatabaseDocument: Optional[XOfficeDatabaseDocument]
+ """
+ If the script is being executed from a Base document or any of its
subcomponents
+ this method returns the main component of the Base instance.
+ Returns
+ The current Base (main) component or None when not a Base
document or one of its subcomponents.
+ """
+
+ # #########################################################################
+ # SF_Dictionary CLASS
+ # #########################################################################
+ class SF_Dictionary(SFServices, dict):
+ """
+ The service adds to a Python dict instance the interfaces for
conversion to and from
+ a list of UNO PropertyValues
+ Usage
+ ``dico = dict(A = 1, B = 2, C = 3)``
+
+ ``myDict = CreateScriptService('Dictionary', dico) #
Initialize myDict with the content of dico``
+
+ ``myDict['D'] = 4``
+
+ ``print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}``
+
+ ``propval = myDict.ConvertToPropertyValues()``
+ or
+ ``dico = dict(A = 1, B = 2, C = 3)``
+
+ ``myDict = CreateScriptService('Dictionary') #
Initialize myDict as an empty dict object``
+
+ ``myDict.update(dico) # Load the values of dico into myDict``
+
+ ``myDict['D'] = 4``
+
+ ``print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}``
+
+ ``propval = myDict.ConvertToPropertyValues()``
+ """
+
+ def ConvertToPropertyValues(self) -> Tuple[PropertyValue]:
+ """
+ Store the content of the dictionary in an array of
PropertyValues.
+ Each entry in the list is a
``com.sun.star.beans.PropertyValue``.
+ The key is stored in Name, the value is stored in ``Value``.
+
+ If one of the items has a type ``datetime``, it is converted
to a ``com.sun.star.util.DateTime``
+ structure. If one of the items is an empty list, it is
converted to ``None``.
+ Returns
+ A list of property values. The resulting list is empty
when the dictionary is empty.
+ """
+ ...
+
+ def ImportFromPropertyValues(self, propertyvalues:
Sequence[PropertyValue], overwrite: bool = ...) -> bool:
+ """
+ Inserts the contents of an array of ``PropertyValue`` objects
into the current dictionary.
+ ``PropertyValue`` Names are used as keys in the dictionary,
whereas Values contain
+ the corresponding values. Date-type values are converted to
``datetime.datetime`` instances.
+ Args
+ ``propertyvalues``: tuple containing
``com.sun.star.beans.PropertyValue`` objects.
+
+ ``overwrite``: When True, entries with same name may
exist in the dictionary
+ and their values are overwritten. When ``False``
(default), repeated keys are not overwritten.
+ Defaults to ``False``.
+ Returns
+ True when successful.
+ """
+ ...
+
+ # #########################################################################
+ # SF_Exception CLASS
+ # #########################################################################
+ class SF_Exception(SFServices, metaclass = ...):
+ """
+ The Exception service is a collection of methods for code
debugging.
+
+ The ``Exception`` service console stores events, variable values
and information about errors.
+
+ Use the console when the Python shell is not available, for
example in ``Calc`` user defined functions (UDF)
+ or during events processing.
+
+ Use the ``DebugPrint()`` and ``DebuDisplay()`` methods to log any
relevant information, events and data
+ of any type to the console.
+
+ Console entries can be dumped to a text file or visualized in a
dialogue.
+ """
+
+ def Console(self, modal: bool = ...):
+ """
+ Displays the console messages in a modal or non-modal dialog.
In both modes, all the past messages
+ issued by a ``DebugPrint()`` method or resulting from an
exception are displayed. In non-modal mode,
+ subsequent entries are added automatically.
+
+ If the console is already open, when non-modal, it is brought
to the front.
+
+ A modal console can only be closed by the user. A non-modal
console can either be closed by the user
+ or upon script termination.
+ Args
+ ``modal``: determine if the console window is modal
(``True``) or non-modal (``False``).
+ Default value is ``True``.
+ """
+ ...
+
+ def ConsoleClear(self, keep: int = ...):
+ """
+ Clears the console keeping an optional number of recent
messages. If the console is activated in non-modal mode,
+ it is refreshed.
+ Args
+ ``keep``: the number of recent messages to be kept.
Default value is 0.
+ """
+ ...
+
+ def ConsoleToFile(self, filename: FILE) -> bool:
+ """
+ Exports the contents of the console to a text file. If the
file already exists and the console
+ is not empty, it will be overwritten without warning. Returns
True if successful.
+ Args
+ ``filename``: the name of the text file the console
should be dumped into.
+ The name is expressed according to the current
``FileNaming`` property of the ``SF_FileSystem``
+ service.
+ Returns
+ ``True`` when successful.
+ """
+ ...
+
+ def DebugDisplay(self, *args)-> int:
+ """
+ Concatenates all the arguments into a single human-readable
string and displays it in a MsgBox
+ with an Information icon and an OK button. The displayed
string is also added to the Console.
+ Args
+ ``*args``: any number of arguments of any type.
+ Returns
+ The result of the execution of the ``MsgBox()`` method.
+ """
+ ...
+
+ def DebugPrint(self, *args):
+ """
+ Assembles all the given arguments into a single human-readable
string and adds it as a new entry
+ in the console.
+ Args
+ ``*args``: any number of arguments of any type.
+ """
+ ...
+
+ @classmethod
+ def PythonShell(cls, variables: dict = ...) -> None:
+ """
+ Opens an APSO Python shell as a non-modal window.
+ The Python script keeps running after the shell is opened.
+ The output from ``print`` statements inside the script are
shown in the shell.
+ Args
+ ``variables``: a Python dictionary with variable names
and values that will be
+ passed on to the APSO Python shell. By default, all
local variables are passed using
+ Python's builtin ``locals()`` function.
+
+ Typical use: ``{**globals(), **locals()}``
+ """
+ ...
+
+ # #########################################################################
+ # SF_FileSystem CLASS
+ # #########################################################################
+ class SF_FileSystem(SFServices, metaclass = ...):
+ """
+ The "FileSystem" service includes common file and folder handling
routines.
+ """
+
+ FileNaming: str
+ """
+ Sets or returns the current files and folders notation, either
``'ANY', 'URL'`` or ``'SYS'``:
+
+ ``ANY``: (default) the methods of the ``FileSystem`` service
accept both URL and current operating
+ system's notation for input arguments but always return URL
strings.
+
+ ``URL``: the methods of the ``FileSystem`` service expect URL
notation for input arguments and
+ return URL strings.
+
+ ``SYS``: the methods of the ``FileSystem`` service expect
current operating system's notation
+ for both input arguments and return strings.
+
+ Once set, the ``FileNaming`` property remains unchanged either
until the end of the ``LibreOffice``
+ session or until it is set again.
+ """
+ ConfigFolder: FILE
+ """ Returns the configuration folder of ``LibreOffice``. """
+ ExtensionsFolder: FILE
+ """ Returns the folder where extensions are installed. """
+ HomeFolder: FILE
+ """ Returns the user home folder. """
+ InstallFolder: FILE
+ """ Returns the installation folder of ``LibreOffice``. """
+ TemplatesFolder: FILE
+ """ Returns the folder containing the system templates files. """
+ TemporaryFolder: FILE
+ """ Returns the temporary files folder defined in the ``LibreOffice``
path settings. """
+ UserTemplatesFolder: FILE
+ """ Returns the folder containing the user-defined template files. """
+
+ ForReading: Literal[1]
+ ForWriting: Literal[2]
+ ForAppending: Literal[8]
+
+ def BuildPath(self, foldername: FILE, name: str) -> str:
+ """
+ Joins a folder path and the name of a file and returns the
full file name with a
+ valid path separator. The path separator is added only if
necessary.
+
+ Args
+ ``foldername``: the path with which name will be combined.
+ The specified path does not need to be an existing folder.
+
+ ``name``: the name of the file to be appended to
foldername. This parameter uses
+ the notation of the current operating system.
+
+ Returns
+ The path concatenated with the file name after insertion
of a path separator, if necessary.
+ """
+ ...
+
+ def CompareFiles(self, filename1: FILE, filename2: FILE,
comparecontents: bool = ...) -> bool:
+ """
+ Compare 2 files and return ``True`` if they seem identical.
+ Depending on the value of the ``comparecontents`` argument,
+ the comparison between both files can be either based only on
+ file attributes (such as the last modified date), or based on
the file contents.
+ Args
+ ``filename1``: the 1st file to compare.
+
+ ``filename2``: the 2nd file to compare.
+
+ ``comparecontents``: when ``True``, the contents of
the files are compared.
+ Defaults to ``False``.
+ Returns
+ ``True`` when the files seem identical
+ """
+ ...
+
+ def CopyFile(self, source: FILE, destination: FILE, overwrite: bool =
...) -> bool:
+ """
+ Copies one or more files from one location to another.
+ Args
+ ``source``: ``FileName`` or ``NamePattern`` which can
include wildcard characters,
+ for one or more files to be copied.
+
+ ``destination``: ``FileName`` where the single
``source`` file is to be copied
+ or ``FolderName`` where the multiple files from
``source`` are to be copied.
+
+ ``overwrite``: if ``True`` (default), files may be
overwritten.
+ ``CopyFile`` will fail if Destination has the
read-only attribute set,
+ regardless of the value of Overwrite.
+ Returns
+ ``True`` if at least one file has been copied.
``False`` if an error occurred.
+ An error also occurs if a source using wildcard
characters doesn't match any files.
+ The method stops on the first error it encounters.
+ No attempt is made to roll back or undo any changes
made before an error occurs.
+ Notes
+ - If ``destination`` does not exist, it is created.
+ - Wildcard characters are not allowed in
``destination``.
+ """
+ ...
+
+ def CopyFolder(self, source: FILE, destination: FILE, overwrite: bool
= ...) -> bool:
+ """
+ Copies one or more folders from one location to another.
+ Args
+ ``source``: ``FolderName`` or ``NamePattern`` which
can include wildcard characters,
+ for one or more folders to be copied.
+
+ ``destination``: ``FolderName`` where the single
``source`` folder is to be copied
+ or ``FolderName`` where the multiple folders from
``source`` are to be copied.
+ If ``FolderName`` does not exist, it is created.
+
+ ``overwrite``: if ``True`` (default), folders and
their content may be overwritten.
+ Defaults to ``True``. ``CopyFile`` will fail if
``destination`` has the read-only
+ attribute set, regardless of the value of
``overwrite``.
+ Returns
+ ``True`` if at least one folder has been copied.
``False`` if an error occurred.
+ An error also occurs if a ``source`` using wildcard
characters doesn't match any folders.
+ The method stops on the first error it encounters.
+ No attempt is made to roll back or undo any changes
made before an error occurs.
+ Notes
+ - If ``destination`` does not exist, it is created.
+ - Wildcard characters are not allowed in
``destination``.
+ """
+ ...
+
+ def CreateFolder(self, foldername: FILE) -> bool:
+ """
+ Creates the specified ``olderame``.
+ If the specified folder has a parent folder that does not
exist, it is created.
+ Args
+ foldername: a string representing the folder to
create. It must not exist.
+ Returns
+ ``True`` if ``foldername`` is a valid folder name,
does not exist and creation was successful.
+ ``False`` otherwise, including when ``foldername`` is
a file.
+ """
+ ...
+
+ def CreateTextFile(
+ self, filename: FILE, overwrite: bool = ..., encoding: str = ...
+ ) -> TEXTSTREAM:
+ """
+ Creates a specified file and returns a ``TextStream`` service
instance that can be used
+ to write to the file.
+ The method returns ``None`` if an error occurred.
+ Args
+ ``filename``: the name of the file to be created.
+
+ ``overwrite``: determines if ``filename`` can be
overwritten (default = ``True``).
+
+ ``encoding``: the character set to be used. The
default encoding is "UTF-8".
+ """
+ ...
+
+ def DeleteFile(self, filename: FILE) -> bool:
+ """
+ Deletes one or more files.
+ The files to be deleted must not be readonly.
+ Args
+ ``filename``: ``FileName`` or ``NamePattern`` which
can include wildcard characters,
+ for one or more files to be deleted.
+ Returns
+ ``True`` if at least one file has been deleted.
``False`` if an error occurred.
+ An error also occurs if ``fileName`` using wildcard
characters doesn't match any files.
+ The method stops on the first error it encounters.
+ No attempt is made to roll back or undo any changes
made before an error occurs.
+ """
+ ...
+
+ def DeleteFolder(self, foldername: FILE) -> bool:
+ """
+ Deletes one or more folders.
+ The folders to be deleted must not be readonly.
+ Args
+ ``foldername``: ``FolderName`` or ``NamePattern``
which can include wildcard characters,
+ for one or more Folders to be deleted.
+ Returns
+ ``True`` if at least one folder has been deleted.
``False`` if an error occurred.
+ An error will also occur if the ``foldername``
parameter uses wildcard characters and
+ does not match any folders.
+ The method stops immediately after it encounters an
error.
+ The method does not roll back nor does it undo changes
made before the error occurred.
+ """
+ ...
+
+ def ExtensionFolder(self, extension: str) -> str:
+ """
+ Returns a string containing the folder where the specified
extension package is installed.
+ Args
+ ``extension``: a string value with the ID of the
extension.
+ If the extension is not installed, an exception is
raised.
+ """
+ ...
+
+ def FileExists(self, filename: FILE) -> bool:
+ """
+ Return ``True`` if the given file exists.
+ Args
+ ``filename``: a string representing the file to be
tested.
+ Returns
+ ``True`` if ``filename`` is a valid File name and it
exists.
+ ``False`` otherwise, including when ``filename`` is a
folder.
+ """
+ ...
+
+ def Files(self, foldername: FILE, filter: str = ...,
includesubfolders: bool = ...) -> Tuple[str, ...]:
+ """
+ Gets a tuple of the ``FileNames`` stored in the given folder.
+ If the argument ``foldername`` specifies a folder that does
not exist, an exception is raised.
+ The resulting tuple may be filtered with wildcards.
+ Args
+ ``foldername``: the folder to explore.
+
+ ``filter``: contains wildcards ("?" and "*") to limit
the list to the relevant files
+ (default = "").
+
+ ``includesubfolders``: set this argument to ``True``
to include the contents of
+ subfolders (Default = ``False``).
+ Returns
+ A tuple of strings, each entry is the ``FileName`` of
an existing file.
+ """
+ ...
+
+ def FolderExists(self, foldername: FILE) -> bool:
+ """
+ Returns ``True`` if the given folder name exists.
+ Args
+ ``foldername``: a string representing a folder.
+ Returns
+ ``True`` if ``folderName`` is a valid folder name and
it exists.
+ ``False`` otherwise, including when ``foldername`` is
a file.
+ """
+ ...
+
+ def GetBaseName(self, filename: FILE) -> str:
+ """
+ Returns the ``BaseName`` (equal to the last component) of a
file or folder name, without its extension.
+ The method does not check for the existence of the specified
file or folder.
+ Args
+ ``filename``: path and file name
+ Returns
+ The ``BaseName`` of the given file name. It may be the
empty string.
+ """
+ ...
+
+ def GetExtension(self, filename: FILE) -> str:
+ """
+ Returns the extension part of a ``File-`` or ``FolderName``,
without the dot (.).
+ The method does not check for the existence of the specified
file or folder.
+ Args
+ ``filename``: path and file name
+ Returns
+ The extension without a leading dot. May be empty.
+ """
+ ...
+
+ def GetFileLen(self, filename: FILE) -> int:
+ """
+ Returns the length of a file in bytes.
+ Args
+ ``filename``: a string representing an existing file.
+ Returns
+ File size if ``filename`` exists.
+ """
+ ...
+
+ def GetFileModified(self, filename: FILE) -> datetime.datetime:
+ """
+ Returns the last modified date for the given file.
+ Args
+ ``filename``: a string representing an existing file.
+ Returns
+ The modification date and time.
+ """
+ ...
+
+ def GetName(self, filename: FILE) -> str:
+ """
+ Returns the last component of a ``File-`` or ``FolderName``.
+ The method does not check for the existence of the specified
file or folder.
+ Args
+ ``filename``: path and file name
+ Returns
+ The last component of the full file name in native
operating system format.
+ """
+ ...
+
+ def GetParentFolderName(self, filename: FILE) -> FILE:
+ """
+ Returns a string containing the name of the parent folder of the
last component in a specified
+ ``File-`` or ``FolderName``.
+ The method does not check for the existence of the specified file
or folder.
+ Args
+ ``filename``: path and file name.
+ Returns
+ A folder name including its final path separator.
+ """
+ ...
+
+ def GetTempName(self, extension: str = ...) -> FILE:
+ """
+ Returns a randomly generated temporary file name that is
useful for performing
+ operations that require a temporary file : the method does not
create any file.
+ Args
+ ``extension``: the extension of the temporary file
name (Default = "").
+ Returns
+ A ``FileName`` as a string.
+ By default, the returned file name does not have an
extension (suffix).
+ Use the extension parameter to specify the extension
of the file name to be generated.
+ The folder part of the returned string is the system's
temporary folder.
+ """
+ ...
+
+ def HashFile(self,
+ filename: FILE,
+ algorithm: Literal['MD5', 'SHA1', 'SHA224', 'SHA256',
'SHA384', 'SHA512'],
+ ) -> str:
+ """
+ Gets a hexadecimal string representing a checksum of the given
file.
+ Args
+ ``filename``: a string representing a file.
+
+ ``algorithm``: the hashing algorithm to use.
+ Returns
+ The requested checksum as a string. Hexadecimal digits
are lower-cased.
+ A zero-length string when an error occurred.
+ Note
+ The supported hashing algorithms are:
+ - MD5
+ - SHA1
+ - SHA224
+ - SHA256
+ - SHA384
+ - SHA512
+ """
+ ...
+
+ def MoveFile(self, source: FILE, destination: FILE) -> bool:
+ """
+ Moves one or more files from one location to another.
+ Returns ``True`` if at least one file has been moved or
``False`` if an error occurred.
+ An error will also occur if the source parameter uses wildcard
characters anddoes not match any files.
+
+ The method stops immediately after it encounters an error. The
method does not
+ roll back nor does it undo changes made before the error
occurred.
+ Args
+ ``source``: ``FileName`` or ``NamePattern`` which can
include wildcard characters,
+ for one or more files to be moved.
+
+ ``destination``: if ``source`` is an existing file
name then ``destination`` indicates
+ the new path and file name of the moved file. If the
move operation involves multiple files,
+ then ``destination`` must be a folder name. If it does
not exist, it is created.
+ If ``source`` and ``destination`` have the same parent
folder, the method will rename
+ the ``source``.
+ Wildcard characters are not allowed in ``destination``.
+ Returns
+ ``True`` if at least one file has been moved.
``False`` if an error occurred.
+ """
+ ...
+
+ def MoveFolder(self, source: FILE, destination: FILE) -> bool:
+ """
+ Moves one or more folders from one location to another.
+ Returns ``True`` if at least one folder has been moved or
``False`` if an error occurred.
+ An error will also occur if the source parameter uses wildcard
characters and does
+ not match any folders.
+
+ The method stops immediately after it encounters an error. The
method does not roll
+ back nor does it undo changes made before the error occurred.
+ Args
+ ``source``: ``FolderName`` or ``NamePattern`` which
can include wildcard characters,
+ for one or more folders to be moved.
+
+ ``destination``: if the move operation involves a
single folder, then ``destination``
+ is the name and path of the moved folder. It must not
exist.
+ If multiple folders are being moved, then
``destination`` designates where the folders
+ in ``source`` will be moved into. If ``destination``
does not exist, it is created.
+ Wildcard characters are not allowed in ``destination``.
+ Returns
+ ``True`` if at least one folder has been moved.
``False`` if an error occurred.
+ """
+ ...
+
+ def Normalize(self, filename: FILE) -> FILE:
+ """
+ Returns a string containing the normalized path name by
collapsing redundant separators and up-level
+ references. For instance, the path names ``A//B``, ``A/B/``,
``A/./B`` and ``A/foo/../B`` are all
+ normalized to ``A/B``.
+
+ On Windows, forward slashes ``/`` are converted to backward
slashes \\.
+ Args
+ ``filename``: a string representing a valid path name.
+ The file or directory represented by this argument may
not exist.
+ Returns
+ The normalized file name.
+ """
+ ...
+
+ def OpenTextFile(self,
+ filename: FILE,
+ iomode: Literal[1, 2, 8] = ...,
+ create: bool = ...,
+ encoding: str = ...,
+ ) -> TEXTSTREAM:
+ """
+ Opens a specified file and returns a ``TextStream`` object
that can be used to read from,
+ write to, or append to the file.
+ Args
+ ``filename``: identifies the file to open.
+
+ ``iomode``: indicates input/output mode. It can be one
of three constants:
+ ``filesystem.ForReading`` (default),
``filesystem.ForWriting``, or ``filesystem.ForAppending``.
+
+ ``create``: boolean value that indicates whether a new
file can be created if the specified
+ filename doesn't exist. The value is ``True`` if a new
file and its parent folders
+ may be created. ``False`` if they aren't created.
Defaults to ``False``.
+
+ ``encoding``: the character set that should be used.
Defaults to "UTF-8".
+ Returns
+ A ``TEXTSTREAM`` instance representing the opened file
or ``None`` if an error occurred.
+ The method does not check if the file is really a text
file. It doesn't check either
+ if the given encoding is implemented in LibreOffice
nor if it is the right one.
+ """
+ ...
+
+ def PickFile(self,
+ defaultfile: FILE = ...,
+ mode: Literal['OPEN', 'SAVE'] = ...,
+ filter: str = ...,
+ ) -> FILE:
+ """
+ Opens a dialog box to open or save a file.
+
+ If the ``SAVE`` mode is set and the picked file exists, a
warning message will be displayed.
+ Args
+ ``defaultfile``: this argument is a string composed of
a folder and file name.
+ The folder part indicates the folder that will be
shown when the dialog opens
+ (default = the last selected folder). The file part
designates the default file to open or save.
+
+ ``mode``: a string value that can be either "OPEN"
(for input files) or
+ "SAVE" (for output files). The default value is "OPEN".
+
+ ``filter``: the extension of the files displayed when
the dialog is opened
+ (default = no filter).
+ Returns
+ The selected FileName in ``filesystem.FileNaming``
format or "" if the dialog was cancelled.
+ """
+ ...
+
+ def PickFolder(self, defaultfolder: FILE = ..., freetext: str = ...)
-> FILE:
+ """
+ Display a dialog box to select a folder.
+ Args
+ ``defaultfolder``: the folder from which to start.
Default = the last selected folder.
+
+ ``freetext``: text to display in the dialog. Defaults
to "".
+ Returns
+ The selected folder in ``filesystem.FileNaming``
notation.
+ A zero-length string if the dialog was cancelled.
+ """
+ ...
+ def SubFolders(self,
+ foldername: FILE,
+ filter: str = ...,
+ includesubfolders: bool = ...
+ ) -> Tuple[str, ...]:
+ """
+ Returns a tuple of strings corresponding to the folders stored
+ in the given ``foldername``.
+ The list may be filtered with wildcards.
+ Args
+ ``foldername``: a string representing a folder. The
folder must exist. ``foldername`` must not
+ designate a file.
+
+ ``filter``: a string containing wildcards ("?" and
"*") that will be applied to the resulting
+ list of folders (default = "").
+
+ ``includesubfolders``: set this argument to ``True``
to include the contents of
+ subfolders (Default = ``False``).
+ """
+ ...
+
+ # #########################################################################
+ # SF_L10N CLASS
+ # #########################################################################
+ class SF_L10N(SFServices):
+ """
+ This service provides a number of methods related to the
translation of strings
+ with minimal impact on the program's source code.
+
+ The methods provided by the L10N service can be used mainly to:
+ - Create POT files that can be used as templates for
translation of all strings in the program.
+ - Get translated strings at runtime for the language defined
in the Locale property.
+ """
+
+ Folder: FILE
+ """ The folder containing the ``PO`` files """
+ Languages: Tuple[str, ...]
+ """ A list of all the base names (without the ``.po`` extensions found
in the specified ``folder``. """
+ Locale: str
+ """ The currently active ``language-COUNTRY`` combination. """
+
+ def AddText(self, context: str = ..., msgid: str = ..., comment: str =
...) -> bool:
+ """
+ Adds a new entry in the list of localizable strings. It must
not exist yet.
+ Args
+ ``context``: the key to retrieve the translated string
with the GetText method.
+ This parameter has a default value of "".
+
+ ``msgid``: the untranslated string, which is the text
appearing in the program code. ``msgid``
+ must not be empty.
+
+ The ``msgid`` becomes the key to retrieve the
translated string via
+ the ``GetText()`` method when ``context`` is empty.
+ The ``msgid`` string may contain any number of
placeholders (%1 %2 %3 ...) for dynamically
+ modifying the string at runtime.
+
+ ``comment``: optional comment to be added alongside
the string to help translators.
+ Returns
+ ``True`` if successful.
+ """
+ ...
+
+ def AddTextsFromDialog(self, dialog: DIALOG) -> bool:
+ """
+ Add all fixed text strings of a dialog to the list of
localizable text strings.
+
+ Added texts are:
+ - The title of the dialog.
+ - The caption associated with next control types: Button,
CheckBox, FixedLine, FixedText, GroupBox and RadioButton.
+ - The content of list- and combo boxes.
+ - The tip- or help text displayed when the mouse is
hovering the control.
+
+ The current method has method
``SFDialogs.SF_Dialog.GetTextsFromL10N()`` as counterpart.
+ The targeted dialog must not be open when the current method
is run.
+ Args
+ ``dialog``: a SFDialogs.Dialog service instance
+ Returns
+ ``True`` when successful.
+ """
+ ...
+
+ def ExportToPOTFile(self, filename: FILE, header: str = ..., encoding:
str = ...) -> bool:
+ """
+ Export a set of untranslated strings as a POT file.
+ The set of strings has been built either by a succession of
AddText() methods
+ or by a successful invocation of the L10N service with the
``FolderName`` argument.
+ The generated file should pass successfully the ``"msgfmt
--check 'the pofile'"`` GNU command.
+ Args
+ ``filename``: the complete file name (in
``filesstem.FileNaming`` notation)
+ to export to. If it exists, it is overwritten without
warning.
+
+ ``header``: comments that will appear on top of the
generated file. Do not include
+ any leading "#". If the string spans multiple lines,
insert escape sequences (``\n``) where
+ relevant. A standard header will be added anyway.
Defaults to "".
+
+ ``encoding``: the character set that should be used.
Defaults to "UTF-8".
+ Returns
+ ``True`` if successful.
+ """
+ ...
+
+ def GetText(self, msgid: str, *args: Any) -> str:
+ """
+ Gets the translated string corresponding to the given
``msgid`` argument.
+ A list of arguments may be specified to replace the
placeholders (%1, %2, ...) in the string.
+ Args
+ ``msgid``: the untranslated string, which is the text
appearing in the program code.
+ It must not be empty. It may contain any number of
placeholders (%1 %2 %3 ...) that can be used
+ to dynamically insert text at runtime.
+
+ Besides using a single ``msgid`` string, this method
also accepts the following formats:
+ - the untranslated text (``msgid``)
+ - the reference to the untranslated text
(``context``)
+ - both (``context|msgId``), use the pipe character
as delimiter.
+
+ ``args``: values to be inserted into the placeholders.
+ Any variable type is allowed, however only strings,
numbers and dates will be considered.
+ Returns
+ The translated string. If no translated string is
found, the method returns the untranslated
+ string after replacing the placeholders with the
specified arguments.
+ """
+ ...
+
+ # #########################################################################
+ # SF_Platform CLASS
+ # #########################################################################
+ class SF_Platform(SFServices, metaclass = ...):
+ """
+ The ``Platform`` service implements a collection of properties
about the actual execution environment
+ and context, such as :
+ - the hardware platform
+ - the operating system
+ - the LibreOffice version
+ - the current user
+ All its properties are read-only.
+ """
+
+ Architecture: str
+ """ The hardware bit architecture. Example: '32bit' or '64bit'. """
+ ComputerName: str
+ """ The computer's network name. """
+ CPUCount: int
+ """ The number of central processing units. """
+ CurrentUser: str
+ """ The name of the currently logged user. """
+ Extensions: Tuple[str, ...]
+ """ An array of strings containing the internal IDs of all installed
extensions. """
+ FilterNames: Tuple[str, ...]
+ """ An array of strings containing the available document import and
export filter names. """
+ Fonts: Tuple[str, ...]
+ """ An array of strings containing the names of all available fonts.
"""
+ FormatLocale: str
+ """ The locale used for numbers and dates as a string in the format
"la-CO" (language-COUNTRY). """
+ Locale: str
+ """ The locale of the operating system as a string in the format
"la-CO" (language-COUNTRY).
+ This is equivalent to the ``SystemLocale`` property. """
+ Machine: str
+ """ The machine type. Examples are: 'i386' or 'x86_64'. """
+ OfficeLocale: str
+ """ The locale of the user interface as a string in the format "la-CO"
(language-COUNTRY). """
+ OfficeVersion: str
+ """ The actual LibreOffice version expressed as ``LibreOffice w.x.y.z
(The Document Foundation)``. """
+ OSName: str
+ """ The operating system type. Example: 'Darwin, Linux' or 'Windows'.
"""
+ OSPlatform: str
+ """ A single string identifying the underlying platform with as much
useful and human-readable information
+ as possible. Example:
``Linux-5.8.0-44-generic-x86_64-with-glibc2.32``. """
+ OSRelease: str
+ """ The operating system's release. Example: ``5.8.0-44-generic``.
"""
+ OSVersion: str
+ """ The operating system's build or version. Example: ``#50-Ubuntu
SMP Tue Feb 9 06:29:41 UTC 2021 `` """
+ Printers: Tuple[str, ...]
+ """ The list of available printers. The default printer is put in the
first position of the list
+ (index = [0]). """
+ Processor: str
+ """ The real processor name. Example: ``amdk6``. This property may
return the same value as the ``Machine``
+ property. """
+ PythonVersion: str
+ """ The version of the Python interpreter being used as a string in
the format ``Python major.minor.patchlevel``
+ (ex: ``Python 3.9.7``). """
+ SystemLocale: str
+ """ The locale of the operating system as a string in the format
"la-CO" (language-COUNTRY).
+ This is equivalent to the ``Locale`` property. """
+ UserData: DICTIONARY
+ """ Returns a ``Dictionary`` instance containing key-value pairs in
relation with the
+ ``Tools - Options - User Data`` dialog. """
+
+ # #########################################################################
+ # SF_Region CLASS
+ # #########################################################################
+ class SF_Region(SFServices, metaclass = ...):
+ """
+ The "Region" service gathers a collection of functions about
languages, countries and timezones
+ - Locales
+ - Currencies
+ - Numbers and dates formatting
+ - Calendars
+ - Timezones conversions
+ - Numbers transformed to text in any supported language
+ """
+
+ def Country(self, region: str = ...) -> str:
+ """
+ Gets the country name in English corresponding to a given
region.
+ Args
+ ``region``: formatted as "la-CO" or "CO".
+ """
+ ...
+
+ def Currency(self, region: str = ...) -> str:
+ """
+ Gets the ISO 4217 currency code of the specified region.
+ Args:
+ ``region``: formatted as "la-CO" or "CO".
+ """
+ ...
+
+ def DatePatterns(self, region=...) -> Tuple[str, ...]:
+ """
+ Gets an array of strings containing the date acceptance patterns
for the specified region.
+ Args
+ ``region``: formatted as "la-CO".
+ """
+ ...
+
+ def DateSeparator(self, region: str = ...) -> str:
+ """
+ Returns the date separator used in the given region.
+ Args
+ ``region``: formatted as "la-CO".
+ """
+ ...
+
+ def DayAbbrevNames(self, region: str = ...) -> Tuple[str, ...]:
+ """
+ Gets an array of strings containing the list of abbreviated
weekday names in the specified language.
+ Args
+ ``region``: formatted as "la-CO" or "la".
+ """
+ ...
+
+ def DayNames(self, region: str = ...) -> Tuple[str, ...]:
+ """
+ Gets an array of strings containing the list of weekday names
in the specified language.
+ Args
+ ``region``: formatted as "la-CO" or "la".
+ """
+ ...
+
+ def DayNarrowNames(self, region: str = ...) -> Tuple[str, ...]:
+ """
+ Gets a zero-based array of strings containing the list of the
initials of weekday names
+ in the specified language.
+ Args
+ ``region``: formatted as "la-CO" or "la".
+ """
+ ...
+
+ def DecimalPoint(self, region: str = ...) -> str:
+ """
+ Gets the decimal separator used in numbers in the specified
region.
+ Args
+ ``region``: formatted as "la-CO".
+ """
+ ...
+
+ def Language(self, region: str = ...) -> str:
+ """
+ Gets tthe name of the language, in English, of the specified
region.
+ Args
+ ``region``: formatted as "la-CO" or "la".
+ """
+ ...
+
+ def ListSeparator(self, region: str = ...) -> str:
+ """
+ Gets the list separator used in the specified region.
+ Args
+ ``region``: formatted as "la-CO".
+ """
+ ...
+
+ def MonthAbbrevNames(self, region: str = ...) -> Tuple[str, ...]:
+ """
+ Gets a zero-based array of strings containing the list of
abbreviated month names
+ in the specified language.
+ Args
+ ``region``: formatted as "la-CO".
+ """
+ ...
+
+ def MonthNames(self, region: str = ...) -> Tuple[str, ...]:
+ """
+ Gets an array of strings containing the list of month names in
the specified language.
+ Args
+ ``region``: formatted as "la-CO" or "la".
+ """
+ ...
+
+ def MonthNarrowNames(self, region: str = ...) -> Tuple[str, ...]:
+ """
+ Gets an array of strings containing the list of the initials
of month names in the specified language.
+ Args
+ ``region``: formatted as "la-CO" or "la".
+ """
+ ...
+
+ def ThousandSeparator(self, region: str = ...) -> str:
+ """
+ Gets the thousands separator used in numbers in the specified
region.
+ Args
+ ``region``: formatted as "la-CO".
+ """
+ ...
+
+ def TimeSeparator(self, region: str = ...) -> str:
+ """
+ Gets the separator used to format times in the specified
region.
+ Args
+ ``region``: formatted as "la-CO".
+ """
+ ...
+
+ def DSTOffset(self, localdatetime: datetime.datetime, timezone: str,
locale: str = ...) -> int:
+ """
+ Computes the additional Daylight Saving Time (DST) offset, in
minutes, that is applicable
+ to a given region and timezone.
+ Args
+ ``localdatetime``: the local date and time to consider.
+
+ ``timezone``: the timezone for which the offset will
be calculated.
+
+ ``locale``: the locale specifying the country for
which the offset will be calculated,
+ given either in "la-CO" or "CO" formats. The default
value is the locale defined
+ in the ``OfficeLocale`` property of the ``Platform``
service.
+ """
+ ...
+
+ def LocalDateTime(self, utcdatetime: datetime.datetime, timezone: str,
locale: str = ...) -> datetime.datetime:
+ """
+ Computes the local date and time from a UTC date and time.
+ Args
+ ``utcdatetime``: the UTC date and time, expressed
using a date object.
+
+ ``timezone``: the timezone for which the local time
will be calculated.
+
+ ``locale``: the locale specifying the country for
which the offset will be calculated,
+ given either in "la-CO" or "CO" formats. The default
value is the locale defined
+ in the ``OfficeLocale`` property of the ``Platform``
service.
+ """
+ ...
+
+ def Number2Text(self, number: Union[int, float, str], locale: str =
...) -> str:
+ """
+ Converts numbers and monetary values into written text for any
of the currently supported languages.
+ Args
+ ``number``: the number to be converted into written
text.
+ It can be provided either as a numeric type or as a
string. When a string is provided,
+ it can be preceded by a prefix informing how the
numbers should be written.
+ It is also possible to include ISO 4217 currency codes.
+
+ ``locale``: the locale defining the language into
which the number will be converted to,
+ given either in "la-CO" or "la" formats.
+ The default value is the locale defined in the
``OfficeLocale`` property of the ``Platform``
+ service.
+ Returns
+ The converted number or monetary value in letters.
+ """
+ ...
+
+ def TimeZoneOffset(self, timezone: str, locale: str = ...) -> int:
+ """
+ Gets the offset between GMT and the given timezone and locale,
in minutes.
+ Args
+ ``imezone``: the timezone for which the offset to the
GMT will be calculated.
+
+ ``locale``: the locale specifying the country for
which the offset will be calculated,
+ given either in "la-CO" or "CO" formats.
+ The default value is the locale defined in the
``OfficeLocale`` property
+ of the ``Platform`` service.
+ """
+ ...
+
+ def UTCDateTime(self, localdatetime: datetime.datetime, timezone: str,
locale: str = ...) -> datetime.datetime:
+ """
+ Gets the UTC date and time considering a given local date and
time in a timezone.
+ Args
+ ``localdatetime``: the local date and time in a
specific timezone, expressed as a date.
+
+ ``timezone``: the timezone for which the
``localdatetime`` argument is given.
+
+ ``locale``: the locale specifying the country for
which the ``localdatetime`` argument is given,
+ expressed either in "la-CO" or "CO" formats. The
default value is the locale defined
+ in the ``OfficeLocale`` property of the ``Platform``
service.
+ """
+ ...
+
+ def UTCNow(self, timezone: str, locale: str = ...) ->
datetime.datetime:
+ """
+ Gets the current UTC date and time, given a timezone and a
locale.
+ Args
+ ``timezone``: the timezone for which the current UTC
time will be calculated.
+
+ ``locale``: the locale specifying the country for
which the current UTC time will be calculated,
+ expressed either in "la-CO" or "CO" formats. The
default value is the locale defined
+ in the ``OfficeLocale`` property of the ``Platform``
service.
+ """
+ ...
+
+ # #########################################################################
+ # SF_Session CLASS
+ # #########################################################################
+ class SF_Session(SFServices, metaclass = ...):
+ """
+ The Session service gathers various general-purpose methods about:
+ - UNO introspection
+ - the invocation of external scripts or programs
+ - send mails
+ - ...
+ """
+
+ # Class constants Where to find an invoked library ?
+ SCRIPTISEMBEDDED: Literal["document"]
+ """ The invoked library is in the document (Basic + Python). """
+ SCRIPTISAPPLICATION: Literal["application"]
+ """ The invoked library is in any shared library (Basic). """
+ SCRIPTISPERSONAL: Literal["user"]
+ """ The invoked library is in My Macros (Python). """
+ SCRIPTISPERSOXT: Literal["user:uno_packages"]
+ """ The invoked library is in an extension installed for the current
user (Python). """
+ SCRIPTISSHARED: Literal["share"]
+ """ The invoked library is in LibreOffice macros (Python). """
+ SCRIPTISSHAROXT: Literal["share:uno_packages"]
+ """ The invoked library is in an extension installed for all users
(Python). """
+ SCRIPTISOXT: Literal["uno_packages"]
+ """ The invoked library is in an extension but the installation
parameters are unknown (Python). """
+
+ @classmethod
+ def ExecuteBasicScript(
+ cls, scope: str = ..., script: str = ..., *args: Optional[Any]
+ ) -> Any:
+ """
+ Execute the Basic script given its name and location and fetch
its result if any.
+
+ If the script returns nothing, which is the case of procedures
defined with Sub,
+ the returned value is ``None``.
+ Args
+ ``scope``: string specifying where the script is
stored.
+
+ ``script``: string specifying the script to be called
in the format
+ "library.module.method" as a case-sensitive string.
+
+ ``args``: the arguments to be passed to the called
script.
+ Notes
+ Argument ``scope`` can be either:
+ - "document" (= ``session.SCRIPTISEMBEDDED``)
+ - "application" (=
``session.SCRIPTISAPPLICATION``).
+
+ About argument ``script``:
+ - The library is loaded in memory if necessary.
-e
... etc. - the rest is truncated
