Frappe Utility Functions

Quick Reference: Python

nowdate()

today()

datetime.date

now_datetime()

datetime.datetime

getdate(str)

datetime.date

get_datetime(str)

datetime.datetime

add_days(date, n)

datetime.date

add_months(date, n)

datetime.date

date_diff(end, start)

int

format_date(dt)

str

pretty_date(dt)

str

flt(val, precision)

float

cint(val)

int

cstr(val)

str

sbool(val)

bool

safe_div(a, b)

float

fmt_money(amt, currency)

str

money_in_words(amt, cur)

str

strip_html(text)

str

comma_and(items)

str

validate_email_address(e)

str

""

validate_url(url)

bool

parse_json(s)

Any

get_files_path(is_private)

str

get_site_path(*parts)

str

unique(seq)

list

generate_hash(s, length)

str

ALL imports:

from frappe.utils import nowdate, flt, ...

in controllers/whitelisted methods. In Server Scripts: Use

frappe.utils.nowdate()

directly — NO import statements allowed.

Decision Tree: "Which function do I use?"

Need a date/time value?
├─ Current date → nowdate() or today()
├─ Current datetime → now_datetime()
├─ Parse a string → getdate() or get_datetime()
├─ Add/subtract time → add_days(), add_months(), add_to_date()
├─ Difference → date_diff() (days), month_diff(), time_diff_in_seconds()
├─ Period boundary → get_first_day(), get_last_day(), get_quarter_start()
└─ Display to user → format_date(), format_datetime(), pretty_date()

Need a number?
├─ Convert safely → flt(), cint(), cstr(), sbool()
├─ Round → rounded() (banker's rounding)
├─ Safe divide → safe_div(a, b, default=0) [v15+]
├─ Format money → fmt_money(amount, currency)
└─ Money to words → money_in_words(amount, currency)

Need string processing?
├─ HTML → strip_html(), escape_html(), is_html()
├─ Join list → comma_and(), comma_or(), comma_sep()
├─ Markdown ↔ HTML → to_markdown(), md_to_html()
└─ Mask sensitive → mask_string(input, show_first=4) [v16+]

Need validation?
├─ Email → validate_email_address(email, throw=False)
├─ URL → validate_url(url, valid_schemes=["https"])
├─ Phone → validate_phone_number(phone, throw=False)
├─ JSON → validate_json_string(s)
└─ IBAN → validate_iban(iban) [v16+]

Need file/path?
├─ Public files → get_files_path()
├─ Private files → get_files_path(is_private=True)
├─ Site directory → get_site_path("private", "backups")
├─ Bench root → get_bench_path()
└─ File size → get_file_size(path, format=True)

Critical Anti-Patterns

NEVER use Python stdlib when frappe.utils exists

datetime.datetime.now()

now_datetime()

datetime.date.today()

nowdate()

float(val)

flt(val, precision)

int(val)

cint(val)

round(val, 2)

rounded(val, 2)

val1 / val2

safe_div(val1, val2)

json.loads(s)

parse_json(s)

json.dumps(obj)

frappe.as_json(obj)

"{:,.2f}".format(a)

fmt_money(a, currency)

os.path.join(...)

get_site_path(...)

", ".join(items)

comma_and(items)

dt.strftime(fmt)

format_date(dt)

re.sub(r'<.*?>', '', h)

strip_html(h)

Server Script Sandbox

# ❌ NEVER in Server Scripts
from frappe.utils import nowdate, flt
import json

# ✅ ALWAYS in Server Scripts (no imports allowed)
today = frappe.utils.nowdate()
amount = frappe.utils.flt(doc.amount, 2)
data = frappe.parse_json(doc.json_field)

JavaScript Quick Reference

frappe.utils.escape_html(txt)

frappe.utils.html2text(html)

frappe.utils.is_html(txt)

frappe.utils.parse_json(str)

frappe.utils.is_url(txt)

frappe.utils.to_title_case(str)

frappe.utils.comma_and(list)

frappe.utils.unique(list)

frappe.utils.copy_to_clipboard(txt)

frappe.utils.scroll_to(el)

frappe.utils.is_mobile()

frappe.utils.throttle(fn, delay)

frappe.utils.debounce(fn, delay)

frappe.format(value, df, options, doc)

frappe.utils.get_formatted_duration(secs)

Version Differences

safe_div()

duration_to_seconds()

guess_date_format()

validate_duration_format()

mask_string()

validate_iban()

validate_name()

safe_json_loads()

groupby_metric()

Reference Files

• Date/Time Functions — Complete date/time API with signatures
• Number & Money Functions — flt, fmt_money, rounding
• String & Validation Functions — HTML, join, validate
• JavaScript Utilities — Client-side frappe.utils.*
• Anti-patterns — stdlib vs frappe.utils comparison