Agent Skills
› Impertio-Studio/Frappe_Claude_Skill_Package
› frappe-core-utils
frappe-core-utils
GitHub提供Frappe框架v14-v16工具函数参考，涵盖日期、数值、字符串、验证及文件路径操作。旨在避免重复造轮子，确保时区、多租户等场景下的正确性。
Trigger Scenarios
需要处理日期时间计算或格式化
进行安全类型转换或金额格式化
验证邮箱、URL或JSON格式
获取文件或站点路径
Install
npx skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-core-utils -g -y
SKILL.md
Frontmatter
{
"name": "frappe-core-utils",
"license": "MIT",
"metadata": {
"author": "OpenAEC-Foundation",
"version": "3.0"
},
"description": "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,, date calculation, format number, money format, validate email, how to calculate days between. add_days, date_diff, validate_email, pretty_date, get_files_path.\n",
"compatibility": "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16."
}
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: Usefrappe.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
Version History
- 36cfa80 Current 2026-08-20 10:16
