Odoo Helper Functions

In this tutorial we will be going through some of the useful functions that we can use when we are developing for Odoo. These functions include amount to text translation and floating point utils etc.

Some of these functions are defined for the smooth working of the Odoo application, because some time Odoo needs to do some operation on the list or comparison between float numbers in lots of modules. Because of this wide usage they have made it as an independent function definitions, we can call them as helper function if we want.

I will be explaining some of the functions that can be very help full when you are developing for Odoo. These functions are same in every versions from Odoo 8 to Odoo 10 and can be found in the tools folder in any Odoo installation. Below are the commonly used helper functions categories.

Amount To Text Translation

These category deals with translation of any numbers to text format in different languages including german, french and english. If you look in the tools folder in Odoo you can see two files amount_to_text and amount_to_text_en , which contain all the function for this category. i have listed some of the functions and it's usage below.

Parameters passes are numbers and currency name as string for all functions. Basic syntax is given below. When importing the function in odoo10, we have to use odoo instead of openerp

                            
                            
from openerp.tools.amount_to_text import amount_to_text_fr // function for french translation
from openerp.tools.amount_to_text import amount_to_text_nl // function for German Translation
from openerp.tools.amount_to_text_en import amount_to_text as amount_to_text_en // function for english translation
// calling the function with parameters
value1 = amount_to_text_fr(451485,'franc')
value2 = amount_to_text_nl(451485,'euro')
value3 = amount_to_text_en(451485,'dollar')

If we print out these values we will get text format of the number that we passed in the given language. As of now Odoo have these three language translations as build in, but we can add more language option by calling the function add_amount_to_text_function from first file and pass the lang and func as the parameters.

Float Utils

Float numbers are difficult to represent in any system. As it's values can be entirely different on how you round them, like how many precision and when to round (after or before operation). Decimal precisions are more accurate when representing these kind of numbers, because you are dealing with accounting information.

But unfortunately all Odoo ORM uses float representation. For this reasons Odoo had added some helper functions for us to handle these situations. The main reason for this to increase the speed of the application, as math functions are faster than the normal decimal operations.

These function can be found in the file float_utils. And some of the useful function and it's syntax are given below.

If you want to go deep into, how Odoo rounds float numbers you can check this discussion link.

float_round

This is used for rounding a float number. The parameters used in and its syntax and explanations are given below

                            
                            
// function for rounding numbers
from openerp.tools.float_utils import float_round // importing
// value - float number
// precision_digits - number of fractional digits to round to
// precision_rounding - decimal number representing the minimum non-zero value at the desired precision
// rounding_method - can be 'HALF-UP' or 'UP'
value1 = float_round(10.005, precision_digits=2, precision_rounding=None, rounding_method='HALF-UP')
value2 = float_round(10.005, precision_digits=None, precision_rounding=2, rounding_method='HALF-UP')
value3 = float_round(10.005, precision_digits=2, precision_rounding=None, rounding_method='UP')
value4 = float_round(10.005, precision_digits=None, precision_rounding=2, rounding_method='UP')

In the parameters only supply one of the precision_rounding or precision_digits as parameters not both.

And also rounding method can be either HALF-UP or UP. First one will round the number up to the closest number with the rule that number>=0.5 latter one will always round up.

In the above example values will be equal to value1=10.01, value2=10.0, value3=12.0 and value4=10.01.

float_is_zero

This function will return True or False based on whether the number can be treated as zero. Basic syntax and parameters are given below.

                            
                            
// function for float_is_zero
from openerp.tools.float_utils import float_is_zero // importing
// value - float number
// precision_digits - number of fractional digits to round to
// precision_rounding - decimal number representing the minimum non-zero value at the desired precision
value1 = float_is_zero(0.005, precision_digits=2, precision_rounding=None)
value2 = float_is_zero(0.005, precision_digits=None, precision_rounding=2)

There is also another function called float_compare, which is different from above function as it will round after computation but here it will round the number first.

In the above example values will be equal to value1=False, True.

float_compare

This is for comparing two float values and return 1 for greater and -1 for smaller and 0 for same. And comparison always related to the first value.

Syntax and parameters are given below.

                            
                            
// function for float_compare
from openerp.tools.float_utils import float_compare // importing
// value1 - float number
// value2 - float number
// precision_digits - number of fractional digits to round to
// precision_rounding - decimal number representing the minimum non-zero value at the desired precision
value1 = float_compare(0.001, 0.002, precision_digits=2, precision_rounding=None)
value2 = float_compare(0.001, 0.002, precision_digits=None, precision_rounding=2)

In the above example values will be equal to value1=-1, 0.

Image Manipulation

In this category we will look into some basic image related functions. Odoo uses the Image which is imported from the PIL python package. You can find more information about these functions in the file image.py .

image_resize_image

This is for resizing the given image to the given size and has following parameters. The source must be base64 encoded version of the image.

                            
                            
// function for image_resize_image
from openerp.tools.image import image_resize_image // importing
// size - tuple(width, height)
// encoding - 'base64'
// filetype - the output filetype
// avoid_if_small - do not resize image if small
image_base64 = image_resize_image(base64_source=image_base64, size=(width, height), encoding='base64', filetype='PNG')

For example you can check the company logo in Odoo. Odoo also apply transparent overlay to the thumbnail created by this function.

image_resize_and_sharpen

This function is used for creating a thumbnail by resizing the image while keeping the aspect ratio. A sharpen filter is applied for a better looking result. Syntax is given below.

                            
                            
// function for image_resize_and_sharpen
from openerp.tools.image import image_resize_and_sharpen // importing
// image - PIL.Image.Image()
// size - tuple(width, height)
// preserve_aspect_ratio - boolea
// factor - Sharpen factor (default: 2.0
img = image_resize_and_sharpen(image, size, preserve_aspect_ratio=True)

This is commonly used when images are saved for website, so used with another function image_save_for_web. You can check this sample for more information.

image_save_for_web

This will save any image attachment that is uploaded from the website part of the Odoo. Syntax is given below.

                            
                            
// function for image_save_for_web
from openerp.tools.image import image_save_for_web // importing
// image - PIL.Image.Image()
// fp - File name or file object. If not specified, a bytestring is returned.
// format - File format if could not be deduced from image
img = image_save_for_web(img, response.stream, format=image.format)

For the usage of the function please refer the above example.

image_colorize

This is more interesting function as it can be used to add color to the transparent overlay for an image thumbnail. Example of this can be seen in the partner Kanban view in Odoo as partner image has different color background.

                            
                            
// function for image_colorize
from openerp.tools.image import image_colorize // importing
// original - file object on the original image file
// randomize - randomize the background color
// color - background-color, if not randomize
img = image_colorize(image)

image_get_resized_images

This is a standard tool function that can be used to return a dictionary containing the big, medium and small versions of the source image. This function is meant to be used for the methods of functional fields for models using images.

Example of this function can be seen in the res.partner model of Odoo : example. Synatx can be found here.

Date & Datetime Operation

In this category, Odoo provides some helper functions to handle date and datetime conversions from string to object and vice versa. You can check the working of this functions in my previous post.

Like the above functions there are lots of other functions that can be used in our development process. For example for getting the ip address of the host machine you can use the function detect_ip_addr from misc file in tools folder.

For more information and function like this you can check the above mentioned folders and files. Each functions have detailed information of what they do and parameters used as docstring.