Frappe Utility Functions
Quick Reference — Python
| Need |
Function |
Returns |
| Current date |
nowdate() / today() |
datetime.date |
| Current datetime |
now_datetime() |
datetime.datetime |
| Parse date string |
getdate(str) |
datetime.date |
| Parse datetime string |
get_datetime(str) |
datetime.datetime |
| Add days |
add_days(date, n) |
datetime.date |
| Add months |
add_months(date, n) |
datetime.date |
| Date difference |
date_diff(end, start) |
int (days) |
| Format for user |
format_date(dt) |
str (user locale) |
| Relative time |
pretty_date(dt) |
str ("2 hours ago") |
| Safe float |
flt(val, precision) |
float |
| Safe int |
cint(val) |
int |
| Safe string |
cstr(val) |
str |
| Safe bool |
sbool(val) |
bool |
| Safe division |
safe_div(a, b) |
float [v15+] |
| Money format |
fmt_money(amt, currency) |
str |
| Money in words |
money_in_words(amt, cur) |
str |
| Strip HTML |
strip_html(text) |
str |
| List to prose |
comma_and(items) |
str ("a, b, and c") |
| Validate email |
validate_email_address(e) |
str or "" |
| Validate URL |
validate_url(url) |
bool |
| Parse JSON |
parse_json(s) |
Any |
| Files path |
get_files_path(is_private) |
str |
| Site path |
get_site_path(*parts) |
str |
| Unique list |
unique(seq) |
list |
| Hash |
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
| NEVER (stdlib) |
ALWAYS (frappe.utils) |
Why |
datetime.datetime.now() |
now_datetime() |
Ignores system timezone |
datetime.date.today() |
nowdate() |
Ignores system timezone |
float(val) |
flt(val, precision) |
Crashes on None/empty |
int(val) |
cint(val) |
Crashes on None/empty |
round(val, 2) |
rounded(val, 2) |
Inconsistent rounding |
val1 / val2 |
safe_div(val1, val2) |
ZeroDivisionError [v15+] |
json.loads(s) |
parse_json(s) |
Crashes on None/empty |
json.dumps(obj) |
frappe.as_json(obj) |
Inconsistent serialization |
"{:,.2f}".format(a) |
fmt_money(a, currency) |
Ignores locale/currency |
os.path.join(...) |
get_site_path(...) |
Breaks multi-tenancy |
", ".join(items) |
comma_and(items) |
No localized "and" |
dt.strftime(fmt) |
format_date(dt) |
Ignores user preference |
re.sub(r'<.*?>', '', h) |
strip_html(h) |
Misses edge cases |
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
| Need |
Function |
| Escape HTML |
frappe.utils.escape_html(txt) |
| HTML to text |
frappe.utils.html2text(html) |
| Check if HTML |
frappe.utils.is_html(txt) |
| Parse JSON |
frappe.utils.parse_json(str) |
| Validate URL |
frappe.utils.is_url(txt) |
| Title case |
frappe.utils.to_title_case(str) |
| Join with "and" |
frappe.utils.comma_and(list) |
| Unique array |
frappe.utils.unique(list) |
| Copy clipboard |
frappe.utils.copy_to_clipboard(txt) |
| Scroll to element |
frappe.utils.scroll_to(el) |
| Is mobile |
frappe.utils.is_mobile() |
| Throttle |
frappe.utils.throttle(fn, delay) |
| Debounce |
frappe.utils.debounce(fn, delay) |
| Format value |
frappe.format(value, df, options, doc) |
| Duration display |
frappe.utils.get_formatted_duration(secs) |
Version Differences
| Function |
v14 |
v15 |
v16 |
safe_div() |
-- |
Added |
Yes |
duration_to_seconds() |
-- |
Added |
Yes |
guess_date_format() |
-- |
Added |
Yes |
validate_duration_format() |
-- |
Added |
Yes |
mask_string() |
-- |
-- |
Added |
validate_iban() |
-- |
-- |
Added |
validate_name() |
-- |
-- |
Added |
safe_json_loads() |
-- |
-- |
Added |
groupby_metric() |
-- |
-- |
Added |
| Core functions |
Yes |
Yes |
Yes |
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
1---2name: frappe-core-utils3description: Use when working with utility functions in Frappe v14-v16. Covers frappe.utils.* for date/time, number/money, string, validation, and file path operations. Prevents reinventing stdlib alternatives that break timezone awareness, locale formatting, or multi-tenancy. Keywords: frappe.utils, nowdate, flt, cint, fmt_money, getdate, add_days, date_diff, validate_email, pretty_date, get_files_path.4license: MIT5---6
7# Frappe Utility Functions
8
9## Quick Reference — Python
10
11| Need | Function | Returns |
12|------|----------|---------|
13| Current date | `nowdate()` / `today()` | `datetime.date` |
14| Current datetime | `now_datetime()` | `datetime.datetime` |
15| Parse date string | `getdate(str)` | `datetime.date` |
16| Parse datetime string | `get_datetime(str)` | `datetime.datetime` |
17| Add days | `add_days(date, n)` | `datetime.date` |
18| Add months | `add_months(date, n)` | `datetime.date` |
19| Date difference | `date_diff(end, start)` | `int` (days) |
20| Format for user | `format_date(dt)` | `str` (user locale) |
21| Relative time | `pretty_date(dt)` | `str` ("2 hours ago") |
22| Safe float | `flt(val, precision)` | `float` |
23| Safe int | `cint(val)` | `int` |
24| Safe string | `cstr(val)` | `str` |
25| Safe bool | `sbool(val)` | `bool` |
26| Safe division | `safe_div(a, b)` | `float` [v15+] |
27| Money format | `fmt_money(amt, currency)` | `str` |
28| Money in words | `money_in_words(amt, cur)` | `str` |
29| Strip HTML | `strip_html(text)` | `str` |
30| List to prose | `comma_and(items)` | `str` ("a, b, and c") |
31| Validate email | `validate_email_address(e)` | `str` or `""` |
32| Validate URL | `validate_url(url)` | `bool` |
33| Parse JSON | `parse_json(s)` | `Any` |
34| Files path | `get_files_path(is_private)` | `str` |
35| Site path | `get_site_path(*parts)` | `str` |
36| Unique list | `unique(seq)` | `list` |
37| Hash | `generate_hash(s, length)` | `str` |
38
39> **ALL imports**: `from frappe.utils import nowdate, flt, ...` in controllers/whitelisted methods.
40> In **Server Scripts**: Use `frappe.utils.nowdate()` directly — NO import statements allowed.
41
42---
43
44## Decision Tree — "Which function do I use?"
45
46```
47Need a date/time value?
48├─ Current date → nowdate() or today()
49├─ Current datetime → now_datetime()
50├─ Parse a string → getdate() or get_datetime()
51├─ Add/subtract time → add_days(), add_months(), add_to_date()
52├─ Difference → date_diff() (days), month_diff(), time_diff_in_seconds()
53├─ Period boundary → get_first_day(), get_last_day(), get_quarter_start()
54└─ Display to user → format_date(), format_datetime(), pretty_date()
55
56Need a number?
57├─ Convert safely → flt(), cint(), cstr(), sbool()
58├─ Round → rounded() (banker's rounding)
59├─ Safe divide → safe_div(a, b, default=0) [v15+]
60├─ Format money → fmt_money(amount, currency)
61└─ Money to words → money_in_words(amount, currency)
62
63Need string processing?
64├─ HTML → strip_html(), escape_html(), is_html()
65├─ Join list → comma_and(), comma_or(), comma_sep()
66├─ Markdown ↔ HTML → to_markdown(), md_to_html()
67└─ Mask sensitive → mask_string(input, show_first=4) [v16+]
68
69Need validation?
70├─ Email → validate_email_address(email, throw=False)
71├─ URL → validate_url(url, valid_schemes=["https"])
72├─ Phone → validate_phone_number(phone, throw=False)
73├─ JSON → validate_json_string(s)
74└─ IBAN → validate_iban(iban) [v16+]
75
76Need file/path?
77├─ Public files → get_files_path()
78├─ Private files → get_files_path(is_private=True)
79├─ Site directory → get_site_path("private", "backups")
80├─ Bench root → get_bench_path()
81└─ File size → get_file_size(path, format=True)
82```
83
84---
85
86## Critical Anti-Patterns
87
88### NEVER use Python stdlib when frappe.utils exists
89
90| NEVER (stdlib) | ALWAYS (frappe.utils) | Why |
91|----------------|----------------------|-----|
92| `datetime.datetime.now()` | `now_datetime()` | Ignores system timezone |
93| `datetime.date.today()` | `nowdate()` | Ignores system timezone |
94| `float(val)` | `flt(val, precision)` | Crashes on None/empty |
95| `int(val)` | `cint(val)` | Crashes on None/empty |
96| `round(val, 2)` | `rounded(val, 2)` | Inconsistent rounding |
97| `val1 / val2` | `safe_div(val1, val2)` | ZeroDivisionError [v15+] |
98| `json.loads(s)` | `parse_json(s)` | Crashes on None/empty |
99| `json.dumps(obj)` | `frappe.as_json(obj)` | Inconsistent serialization |
100| `"{:,.2f}".format(a)` | `fmt_money(a, currency)` | Ignores locale/currency |
101| `os.path.join(...)` | `get_site_path(...)` | Breaks multi-tenancy |
102| `", ".join(items)` | `comma_and(items)` | No localized "and" |
103| `dt.strftime(fmt)` | `format_date(dt)` | Ignores user preference |
104| `re.sub(r'<.*?>', '', h)` | `strip_html(h)` | Misses edge cases |
105
106### Server Script Sandbox
107
108```python
109# ❌ NEVER in Server Scripts
110from frappe.utils import nowdate, flt
111import json
112
113# ✅ ALWAYS in Server Scripts (no imports allowed)
114today = frappe.utils.nowdate()
115amount = frappe.utils.flt(doc.amount, 2)
116data = frappe.parse_json(doc.json_field)
117```
118
119---
120
121## JavaScript Quick Reference
122
123| Need | Function |
124|------|----------|
125| Escape HTML | `frappe.utils.escape_html(txt)` |
126| HTML to text | `frappe.utils.html2text(html)` |
127| Check if HTML | `frappe.utils.is_html(txt)` |
128| Parse JSON | `frappe.utils.parse_json(str)` |
129| Validate URL | `frappe.utils.is_url(txt)` |
130| Title case | `frappe.utils.to_title_case(str)` |
131| Join with "and" | `frappe.utils.comma_and(list)` |
132| Unique array | `frappe.utils.unique(list)` |
133| Copy clipboard | `frappe.utils.copy_to_clipboard(txt)` |
134| Scroll to element | `frappe.utils.scroll_to(el)` |
135| Is mobile | `frappe.utils.is_mobile()` |
136| Throttle | `frappe.utils.throttle(fn, delay)` |
137| Debounce | `frappe.utils.debounce(fn, delay)` |
138| Format value | `frappe.format(value, df, options, doc)` |
139| Duration display | `frappe.utils.get_formatted_duration(secs)` |
140
141---
142
143## Version Differences
144
145| Function | v14 | v15 | v16 |
146|----------|:---:|:---:|:---:|
147| `safe_div()` | -- | Added | Yes |
148| `duration_to_seconds()` | -- | Added | Yes |
149| `guess_date_format()` | -- | Added | Yes |
150| `validate_duration_format()` | -- | Added | Yes |
151| `mask_string()` | -- | -- | Added |
152| `validate_iban()` | -- | -- | Added |
153| `validate_name()` | -- | -- | Added |
154| `safe_json_loads()` | -- | -- | Added |
155| `groupby_metric()` | -- | -- | Added |
156| Core functions | Yes | Yes | Yes |
157
158---
159
160## Reference Files
161
162- [Date/Time Functions](references/date-time-functions.md) — Complete date/time API with signatures
163- [Number & Money Functions](references/number-money-functions.md) — flt, fmt_money, rounding
164- [String & Validation Functions](references/string-validation-functions.md) — HTML, join, validate
165- [JavaScript Utilities](references/javascript-utilities.md) — Client-side frappe.utils.*
166- [Anti-patterns](references/anti-patterns.md) — stdlib vs frappe.utils comparison
majiayu000