Utility functions

Common utility functions including frappe.throw, frappe.msgprint, and data helpers

Frappe provides a comprehensive set of utility functions for common operations like messaging, error handling, data manipulation, and formatting.

Messaging and errors

throw

Raise an exception and show a message to the user.

msg · str · required

Error message to display

exc · Exception · default: "ValidationError"

Exception class to raise

title · str

Message title. Default: “Message”

is_minimizable · bool · default: "False"

Allow users to minimize the modal

wide · bool · default: "False"

Show wide modal

# Basic usage
frappe.throw("Customer name is required")

# With custom exception
frappe.throw("Access denied", frappe.PermissionError)

# With title
frappe.throw(
    "Invalid quantity: must be greater than 0",
    title="Validation Error"
)

# Custom exception class
class StockUnavailable(frappe.ValidationError):
    pass

frappe.throw(
    "Item out of stock",
    exc=StockUnavailable,
    title="Stock Error"
)

msgprint

Display a message to the user without raising an exception.

msg · str · required

Message to display

title · str

Message title

raise_exception · bool | Exception · default: "False"

Raise exception after showing message

indicator · str

Color indicator: “blue”, “green”, “orange”, “red”, “yellow”

alert · bool · default: "False"

Show as toast notification

primary_action · dict

Add a primary action button

# Simple message
frappe.msgprint("Customer updated successfully")

# With title and indicator
frappe.msgprint(
    "Customer saved",
    title="Success",
    indicator="green"
)

# As toast notification
frappe.msgprint(
    "Changes saved",
    indicator="green",
    alert=True
)

# With primary action
frappe.msgprint(
    "Record created. Do you want to continue?",
    primary_action={
        "label": "Continue",
        "action": "my_app.api.continue_process"
    }
)

toast

Show a toast notification (shorthand for msgprint with alert=True).

message · str · required

Message to display

indicator · str

Color indicator

frappe.toast("Record saved", indicator="green")
frappe.toast("Warning: Low stock", indicator="orange")

Data utilities

cint

Convert value to integer.

value · any · required

Value to convert

default · int · default: "0"

Default value if conversion fails

from frappe.utils import cint

qty = cint("10")  # 10
qty = cint("10.5")  # 10
qty = cint("")  # 0
qty = cint(None, default=1)  # 1

flt

Convert value to float.

value · any · required

Value to convert

precision · int

Decimal precision

from frappe.utils import flt

price = flt("99.99")  # 99.99
price = flt("99.999", precision=2)  # 100.0
price = flt("")  # 0.0

cstr

Convert value to string.

value · any · required

Value to convert

from frappe.utils import cstr

name = cstr(123)  # "123"
name = cstr(None)  # ""
name = cstr([1, 2, 3])  # "[1, 2, 3]"

sbool

Convert value to boolean (handles string “0” and “1”).

value · any · required

Value to convert

from frappe.utils import sbool

flag = sbool("1")  # True
flag = sbool("0")  # False
flag = sbool("true")  # True
flag = sbool("")  # False

Date and time utilities

now

Get current datetime as string.

from frappe.utils import now

current_time = now()  # "2024-01-15 14:30:00.123456"

today

Get current date as string.

from frappe.utils import today

current_date = today()  # "2024-01-15"

getdate

Convert string to date object.

value · str | date | datetime

Date string or object. Default: today

from frappe.utils import getdate

date_obj = getdate("2024-01-15")  # datetime.date(2024, 1, 15)
date_obj = getdate()  # today's date

get_datetime

Convert string to datetime object.

value · str | datetime

Datetime string or object

from frappe.utils import get_datetime

dt = get_datetime("2024-01-15 14:30:00")
dt = get_datetime("2024-01-15")  # Sets time to 00:00:00

add_days

Add days to a date.

date · str | date

Starting date. Default: today

days · int · required

Number of days to add (negative to subtract)

from frappe.utils import add_days, today

tomorrow = add_days(today(), 1)
last_week = add_days(today(), -7)

add_months

Add months to a date.

date · str | date

Starting date

months · int · required

Number of months to add

from frappe.utils import add_months, today

next_month = add_months(today(), 1)
last_year = add_months(today(), -12)

date_diff

Get difference between two dates in days.

date1 · str | date · required

First date

date2 · str | date · required

Second date

from frappe.utils import date_diff

days = date_diff("2024-01-15", "2024-01-10")  # 5

time_diff

Get time difference between two datetimes.

time1 · str | datetime · required

First datetime

time2 · str | datetime · required

Second datetime

from frappe.utils import time_diff

td = time_diff("2024-01-15 15:00:00", "2024-01-15 14:00:00")
print(td.total_seconds() / 3600)  # 1.0 hour

format_date

Format date according to user’s locale.

date · str | date · required

Date to format

format_string · str

Custom format string

from frappe.utils import format_date

formatted = format_date("2024-01-15")  # Based on user format
formatted = format_date("2024-01-15", "dd-mm-yyyy")  # "15-01-2024"

String utilities

scrub

Convert string to lowercase with underscores.

text · str · required

Text to convert

frappe.scrub("Sales Order")  # "sales_order"
frappe.scrub("Customer Name")  # "customer_name"

unscrub

Convert underscore string to title case.

text · str · required

Text to convert

frappe.unscrub("sales_order")  # "Sales Order"
frappe.unscrub("customer_name")  # "Customer Name"

bold

Wrap text in bold HTML tag.

text · str · required

Text to make bold

from frappe.utils import bold

message = f"Customer {bold('CUST-001')} was updated"
# "Customer <b>CUST-001</b> was updated"

JSON utilities

as_json

Convert object to JSON string.

obj · dict | list · required

Object to convert

indent · int · default: "1"

Indentation level

data = {"name": "John", "age": 30}
json_str = frappe.as_json(data)
# '{\n "name": "John",\n "age": 30\n}'

parse_json

Parse JSON string to object.

text · str · required

JSON string

from frappe.utils import parse_json

obj = parse_json('{"name": "John"}')
print(obj["name"])  # "John"

Formatting utilities

format_value

Format a value based on field type.

value · any · required

Value to format

df · dict

Field definition dict with fieldtype, options, etc.

doc · Document

Document for context

from frappe.utils import format_value

# Format currency
formatted = format_value(
    1000,
    {"fieldtype": "Currency", "options": "INR"},
)
# "₹ 1,000.00"

# Format date
formatted = format_value(
    "2024-01-15",
    {"fieldtype": "Date"},
)

comma_and

Join list items with commas and ‘and’.

items · list · required

List of items

from frappe.utils import comma_and

result = comma_and(["Apple", "Orange", "Banana"])
# "Apple, Orange and Banana"

result = comma_and(["Item 1", "Item 2"])
# "Item 1 and Item 2"

Translation

_

Translate a string to the user’s language.

text · str · required

Text to translate

context · str

Translation context

from frappe import _

message = _("Customer saved successfully")
error = _("This field is required")

# With context for disambiguation
label = _("Close", context="Button label")

File utilities

get_files_path

Get the files directory path.

from frappe.utils import get_files_path

files_path = get_files_path()
# "/path/to/site/private/files" or "/path/to/site/public/files"

create_folder

Create a folder if it doesn’t exist.

path · str · required

Folder path to create

from frappe.utils import create_folder

create_folder("/path/to/new/folder")

Validation utilities

validate_email_address

Validate if string is a valid email address.

email · str · required

Email address to validate

throw · bool · default: "False"

Raise InvalidEmailAddressError if invalid

from frappe.utils import validate_email_address

validate_email_address("[e-mail]", throw=True)

validate_url

Validate if string is a valid URL.

url · str · required

URL to validate

throw · bool · default: "False"

Raise ValidationError if invalid

from frappe.utils import validate_url

validate_url("https://example.com", throw=True)

Miscellaneous

get_traceback

Get the current exception traceback as string.

try:
    # some code
    pass
except Exception:
    frappe.log_error(frappe.get_traceback())

generate_hash

Generate a random hash string.

length · int · default: "56"

Length of hash to generate

token = frappe.generate_hash(length=32)
# "a1b2c3d4e5f6..."