edit 30/09/2021: Thanks to karolus for pointing out a few mistakes and for suggesting improvements for this tutorial.

Here is the plan for this tutorial:

• Prepare your file
• Some useful functions
• How to increment a tuple
• Try in the console
• Increment tuple step by step
• Use built-in functions ‘tuple’ and ‘reversed’ together
• Full ReverseRange.py file
• Walk through the code
• Test the code

Prepare your file

We start with creating a new folder, I named mine ‘part 9’, in the python scripts folder for LibreOffice. Depending on your OS, it will be at a specific location in your user folder. Within that location you can organise your python scripts the way you want and each folder will be seen as a module within the LibreOffice Python Script manager.
This part 9 will re-use some of the code from part 8 (also available on my gitHub repository).

I named the file for this tutorial ‘ReverseRange.py’.

Check my tutorial hello world if you need help to get started with python scripts for LibreOffice.

I usually assign a button or a keyboard shortcut to the main() program of my new python file. This is explained in tutorial Annex 1.

If you are starting from part 8 code, I am not using a context() function anymore to define the global variable needed for pyUNO, but instead I declare them at the global scope straight away. This make things easier and avoid repeating calling context in every function that need the global variables.

So this code below:

def context():
    
    # set global variables for context
    
    global desktop
    global model
    global active_sheet
    
    # get the doc from the scripting context 
    # which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
    # access the active sheet
    active_sheet = model.CurrentController.ActiveSheet

Is replaced by:

# set global variables for context
    
# get the doc from the scripting context 
# which is made available to all scripts
desktop = XSCRIPTCONTEXT.getDesktop()
model = desktop.getCurrentComponent()

# access the active sheet
active_sheet = model.CurrentController.ActiveSheet

Some useful functions

I also replaced the section that is calculating Cell addresses from the current Range selection, by a simpler function returning a new range with horizontal and vertical offset as arguments. These two arguments having a default value of 0.

def getSelectionAddresses(horizontalOffset = 0 , verticalOffset = 0):
    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()
    return oArea.StartColumn + horizontalOffset, oArea.StartRow + verticalOffset, oArea.EndColumn + horizontalOffset, oArea.EndRow + verticalOffset

This function returns a tuple(a list you cannot change, also called immutable, see further for more details) with 4 elements. You can indeed create a tuple without using parenthesis.
If you are not convinced, try this in a python console:

>>> fruits = "oranges","bananas","apples"
>>> fruits
('oranges', 'bananas', 'apples')
>>> type(fruits)
<class 'tuple'>

(Don’t type the ‘>>>’, it’s python key prompt!)

The python built-in method type() tells you that you have defined the object ‘fruits‘ as an instance of class ‘tuple‘.

How to increment a tuple

A tuple in python is a special type of array of data to store any type of data. Once a tuple has been created you cannot change its elements individually. A common solution to build a tuple is to use a ‘for loop‘ and to recreate the entire tuple with the same name at each loop iteration. It will look exactly like incrementing a variable, with each loop’s iteration looking like this:

myTuple = myTuple + (newElement,)

The comma at the end within the parenthesis is important, if you don’t have it, the (newElement) is not a tuple but just a single element of whatever the type of newElement is.

Try in the console

So let’s open an APSO console (see part 1 if you need help), or if any other python console like the Python Idle, or even your terminal after starting python3.

Then in the python console of your choice just create two new tuples like this:

source = (1,2,3)
target = ()

You can do a quick print of your two tuple if you want to make sure your 2 tuples are good:

>>> source
(1, 2, 3)
>>> target = ()
>>> ()
()
>>> type(target)
<class 'tuple'>

Note: as you can see you can create an empty tuple simply with empty parenthesis.

Increment tuple step by step

To have our ‘target‘ tuple elements in the exact reverse order than the elements from the ‘source‘ tuple we need to do the following steps:

1. define target tuple equal to target tuple (which is empty at this step) + last element of source tuple (3)
2. define target tuple equal to target tuple(as it is) + second last element of source tuple (2)
3. define target tuple equal to target tuple(as it is) + first element of source tuple (1)

In the console, it looks like this:

>>> target = target + (source[-1],)
>>> target
(3,)
>>> target = target + (source[-2],)
>>> target
(3, 2)
>>> target = target + (source[-3],)
>>> target
(3, 2, 1)

Use the reversed() function

Using a for loop and the reversed() function, we can now define a new function that takes a a tuple as argument and returns the reversed tuple, I called mine reverseTuple():

def reverseTuple(aTuple):
    oReversedSource = ()
    for t in reversed(aTuple): 
        oReversedSource = oReversedSource + (t,)
    return oReversedSource

Use built-in functions ‘tuple()’ and ‘reversed()’ together.

A nicer and more ‘pythonic’ way of doing it, is to use the function tuple() and building the elements using what is called ‘tuple comprehension’ with a loop on the reversed source tuple. This is done in one line only. So in the console it would look like this:

>>> source = (1,2,3)
>>> target = tuple(reversed(source))
>>> target
(3, 2, 1)
>>> 

So let’s create a reverse function. Now we have two functions doing the same job, just to show you that most of the time there are many ways to do the same thing in python and in programming in general. What counts is how readable the code is for you and other people that will read your code.

def reverse(aTuple):
    return tuple(reversed(aTuple))

Note that you could do without this function and use the tuple comprehension directly where you need to reverse your tuple.

For our final code we’ll keep the reverse function instead of the ReverseTuple, it’ll make people reading your code thinking, “That person knows python!”.

Now that we know how to reverse a tuple with python, we can apply it to a selected range of data within LibreOffice Calc.

Full ReverseRange.py file

# Created by Gwenole Capp 05/05/2021
# For tutolibro.tech
# Public Domain, feel free to copy, modify, use in your own scripts
# 
# email: gwenole.capp@gmail.com
   
# set global variables for context
    
# get the doc from the scripting context 
# which is made available to all scripts
desktop = XSCRIPTCONTEXT.getDesktop()
model = desktop.getCurrentComponent()

# access the active sheet
active_sheet = model.CurrentController.ActiveSheet

# define useful functions

def getSelectionAddresses(horizontalOffset = 0 , verticalOffset = 0):
    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()
    return oArea.StartColumn + horizontalOffset, oArea.StartRow + verticalOffset, oArea.EndColumn + horizontalOffset, oArea.EndRow + verticalOffset
    
def reverse(aTuple):
    return tuple(reversed(aTuple))

# main function
def main():
       
    # get the Cell Range
    # use tuple unpacking of getSelectionAddresses returned tuple as parameter of getCellRangeByPosition
    oRangeSource = active_sheet.getCellRangeByPosition(*getSelectionAddresses())
    
    # get data from the Range of cells and store in a tuple
    oDataSource = oRangeSource.getDataArray()
    
    # print to console
    print(oDataSource)
    
    # create a new range of cells
    # from current selection using function getSelectionAddresses with offset
    # you can use the kwarg (keyword argument) horizontalOffset in parameter
    oRangeTarget = active_sheet.getCellRangeByPosition(*getSelectionAddresses(horizontalOffset = 3))
    
    # Reverse the data 
    oReversedSource = reverse(oDataSource)
    # Then set data for the target range using the 'reversed' data from the source range.
    oRangeTarget.setDataArray(oReversedSource)

Walk through the code

The global variables at the start are what allow us to manipulate LibreOffice Objects like the spreadsheet and its cells.
Then the function getSelectionAddresses(), as we have seen earlier is to get the addresses of the selected cells on LibreOffice.
The function reverse() is returning a reversed version of a tuple.

Let’s focus on the main() function.
In the main function, The function getCellRangeByPosition() to get the cells coordinates of the range of cells, takes 4 arguments, and not a tuple with 4 elements. But our function getSelectionAddresses() returns a tuple of 4 elements. So that is why the argument getSelectionAddresses() is preceded with a ‘*’ (asterisk). This mean that we are ‘unpacking‘ the tuple returned by the function getSelectionAddresses() into a sequence of for single elements.
When you create a tuple, you are ‘packing’ it with elements. You can ‘unpack’ it to access all its elements at once. And the asterisk can do it for you!

    # get the Cell Range
    # use tuple unpacking of getSelectionAddresses returned tuple as parameter of getCellRangeByPosition
    oRangeSource = active_sheet.getCellRangeByPosition(*getSelectionAddresses())

Then we are using getDataArray() to get the data within the selected range, we are printing the tuple to the console.

    # get data from the Range of cells and store in a tuple
    oDataSource = oRangeSource.getDataArray()
    
    # print to console
    print(oDataSource)

Next, we create a new range of cells, using again the ‘unpacked’ version of getSelectionAddresses() preceded with an asterix, but this time with the argument ‘horizontalOffset = 3‘, we don’t need to specify the verticalOffset if we want to use its default vaue set to 0 in the function definition. But we have to use the kwarg (the keyword argument) horizontalOffset to make sure we are passing the wanted value to the correct argument.
So in this case I have an offset of 3 cells horizontally, the reversed range of data will be displayed 3 cells on the right of the selected data.
If you wanted to reverse the range ‘in place’ and overwrite the source data, you just need to put no arguments in the code for function getSelectionAddresses().

    # create a new range of cells
    # from current selection using function getSelectionAddresses with offset
    # you can use the kwarg (keyword argument) horizontalOffset in parameter
    oRangeTarget = active_sheet.getCellRangeByPosition(*getSelectionAddresses(horizontalOffset = 3))

Note: there is no exception handling, no safeguard, to check if the offset your enter makes the range being 'out of range'. That could be a further improvement of this program. Another improvement could be to have the offset defined in a cell, or defined using a small control form with a text input.

Finally, we reverse the tuple of data and store it in our new range of Cell addresses in the LibreOffice Calc sheet.

    # Reverse the data 
    oReversedSource = reverse(oDataSource)
    # Then set data for the target range using the 'reversed' data from the source range.
    oRangeTarget.setDataArray(oReversedSource)

You can also find the file with the full code on this gitHub rep.

Test the code

Now it’s time to create a range of data, select that rage and run the python macro!

You can a look at tutorial Annex 1 to map a combination of key to this macro (I use CTRL + 0).
I hope this tutorial helped you understand a bit more about using python to control LibreOffice Calc. Please leave a comment to let me know!

Here is the plan for this tutorial:

• Start with code from the previous chapter
• Set the top-left and bottom-right Cells addresses
• Set the Target Range
• Create a new Array of data

Start with code from the previous chapter

Starting with the code from the previous episode of this series LibreOffice Calc & Python Programming from its corresponding gitHub rep, or a copy paste here:

def context():
    
    # set global variables for context
    
    global desktop
    global model
    global active_sheet
    
    # get the doc from the scripting context 
    # which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
    # access the active sheet
    active_sheet = model.CurrentController.ActiveSheet
    
def main():
    
    # call function context()
    context()
    
    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()

    # store the attribute of CellRangeAddress 
    nLeft = oArea.StartColumn
    nTop = oArea.StartRow
    nRight = oArea.EndColumn
    nBottom = oArea.EndRow
    #(note: could the attribute directly instead of using intermediary variable)
    
    # get the Cell Range 
    oRangeSource = active_sheet.getCellRangeByPosition(nLeft, nTop, nRight, nBottom)
    
    # example by name:
    # ~ oRangeSource = active_sheet.getCellRangeByName('A1:C10')
    
    # get data from the Range of cells and store in a tuple
    oDataSource = oRangeSource.getDataArray()
    
    # print to console
    print(oDataSource)

Set the top-left and bottom-right Cells addresses

This step is to calculate the addresses for our target range of cells, by defining the columns and rows for the top-left and bottom-right cells or our target range, the range where we are going to transfer the data from the selected area.
To avoid having python to throw an error, we need to make sure that our target area is exactly the same size than our source area.
We also don’t want to overlap our source area with our target area.
In this example, let’s define an area starting two columns to the right of our selected area. So the addresses of the cells in the new range will depend on the addresses of cells within the source range.
We can set an offset value that will define how many columns to the right of our selected range will our target range will be.

For example:
offset = 2

Then we set the leftmost column of our new range to be like this:
tLeft = nRight + offset
With nRight being the right column of our range of selected cells.
So here we are simply adding the offset (=2) to the end column of the source range.

Then we need to know the number of columns in the source area:
nbCol = nRight – nLeft + 1
This is the difference between the address of the right column of the source area and the address of the left column area, to which we add 1.
Check the illustration below to understand:

To remember that logic I always use a metaphor about number of holidays: if I start my holidays the 2nd of the month and my last day of holidays is the 4th of the month, I know I had 3 days of holidays, the 2nd, the 3rd and the 4th. And first day subtracted to last day makes 4 -2 = 2 , and I need to add 1 day to have the right count: 3 days from the 2nd to the 4th.
In the illustration above, the column 2 is the day 2 of the month, the column 4, the day 4…

To set the address of the last column of our target range we do the following:
tRight = nRight + nbCol – 1 + offset
Starting from the last column of the source area, you add the number of columns in that source area, subtract 1, and then add the same offset that you used for the starting column of this new range.
To use the same number of holidays example, to know what are the starting date and ending date of my holidays knowing that I have 3 days off next week, I need to add the number of days off to the starting date and take away 1: 2+3=5, 5-1 = 4 -> the 4th.

We can keep the same rows than the source area for the target area:
tTop = nTop
tBottom = nBottom

Altogether the snippet for setting the columns and rows of our new range is:

    # set the target columns and rows
    # relative to the selected area
    offset = 2
    tLeft = nRight + offset
    nbCol = nRight - nLeft + 1
    tRight = nRight + nbCol - 1 + offset
    tTop = nTop
    tBottom = nBottom

    print(tLeft,tTop,tRight,tBottom)

A simplified version, of tRight, if you replace nbCol by its value, would be:
tRight = 2*nRight – nLeft + offset
In which case you don’t need the nbCol variable anymore, but to make the explanation easier I am keeping it.

As usual, to help with testing, I added a print statement. It will print the value you calculated in the console. You can read my tutorial about the APSO console if you haven’t yet. Also to make testing easier, I usually assign the program to a combination of key, like CTRL + 0. Check my post that explains how to do that easily.

Set the Target range

We are going to use getCellRangeByPosition again to create a range of cells, but this time we are not going to use the addresses of the area defined by the mouse selection. We are now going to use the variables that we created in the previous step tLeft, tTop, tRight, tBottom.

    # create target Range
    oRangeTarget = active_sheet.getCellRangeByPosition(tLeft, tTop, tRight, tBottom)

Now that we have define a cell range, we can assign data to it.

Create a new Array of data

In the last tutorial we used the function getDataArray() to create a python tuple that we named oDataSource from the data stored in the source range of cells. This time we are going to use the function setDataArray() with the existing tuple of data oDataSource as parameter.

This will store the data from the tuple oDataSource to the target Range of Cells that we defined earlier, and hopefully display the data in the cells on the LibreOffice current spreadsheet.

    # set data for the target range using datafrom the source range.
    oRangeTarget.setDataArray(oDataSource)

Here is what I get with a bit of data, including the APSO console:

This is the full code:

def context():
    
    # set global variables for context
    
    global desktop
    global model
    global active_sheet
    
    # get the doc from the scripting context 
    # which is made available to all scripts
    desktop = XSCRIPTCONTEXT.getDesktop()
    model = desktop.getCurrentComponent()
    
    # access the active sheet
    active_sheet = model.CurrentController.ActiveSheet
    
def main():
    
    # call function context()
    context()
    
    # get the range of addresses from selection
    oSelection = model.getCurrentSelection()
    oArea = oSelection.getRangeAddress()

    # store the attribute of CellRangeAddress 
    nLeft = oArea.StartColumn
    nTop = oArea.StartRow
    nRight = oArea.EndColumn
    nBottom = oArea.EndRow
    #(note: could the attribute directly instead of using intermediary variable)
    
    # get the Cell Range 
    oRangeSource = active_sheet.getCellRangeByPosition(nLeft, nTop, nRight, nBottom)
    
    # example by name:
    # ~ oRangeSource = active_sheet.getCellRangeByName('A1:C10')
    
    # get data from the Range of cells and store in a tuple
    oDataSource = oRangeSource.getDataArray()
    
    # print to console
    print(oDataSource)
    
    # set the target columns and rows
    # relative to the selected area
    offset = 2
    tLeft = nRight + offset
    nbCol = nRight - nLeft + 1
    tRight = nRight + nbCol - 1 + offset
    tTop = nTop
    tBottom = nBottom
    
    print(tLeft,tTop,tRight,tBottom)
    
    # create target Range
    oRangeTarget = active_sheet.getCellRangeByPosition(tLeft, tTop, tRight, tBottom)
    
    # set data for the target range using data from the source range.
    oRangeTarget.setDataArray(oDataSource)

You can also find this code on this gitHub rep.

The getDataArray() function creates a tuple of tuples. Tuples are immutable objects, so you cannot change them once you have created them.
So if you want to change the data that you stored from a range of cells, you will need to create a new tuple, while looping on the source tuple element by element.
In the next episode of this series of Tutorials about LibreOffice Calc and Python Programming, I will show you some examples on how to work with these tuples of tuples to work on the data.

If you like this tutorial, you could buy me a coffee to help me continue writing add-free tutorials.

Thank you!