Frappe provides a comprehensive set of utility functions for common operations like date manipulation, formatting, validation, and data conversion.
Import Utilities import frappe from frappe import _ # Translation function from frappe.utils import ( flt, cint, cstr, # Type conversion getdate, nowdate, now, now_datetime, # Date/time formatdate, get_datetime, # Formatting add_days, add_months, # Date arithmetic get_link_to_form # UI helpers )
Type Conversion flt() - Float Conversion Convert any value to float with precision handling.
Value to convert to float
Basic Float Conversion
With Field Precision
from frappe.utils import flt # Convert to float value = flt( "123.456" ) # 123.456 price = flt( "100.999" , 2 ) # 100.99 # Handle None/empty safe_value = flt( None ) # 0.0 empty_value = flt( "" ) # 0.0 # Currency calculations grand_total = flt(net_total) + flt(tax_amount) discount = flt(total * discount_percent / 100 , 2 )
cint() - Integer Conversion Convert any value to integer.
Value to convert to integer
from frappe.utils import cint # Convert to integer quantity = cint( "10" ) # 10 disabled = cint( None ) # 0 # Boolean to int is_enabled = cint( True ) # 1 is_disabled = cint( False ) # 0 # Use in comparisons if cint(frappe.db.get_value( "Item" , item_code, "disabled" )): frappe.throw( "Item is disabled" ) # Check settings if not cint(frappe.db.get_default( "hide_currency_symbol" )): show_currency_symbol()
cstr() - String Conversion Safely convert any value to string.
Value to convert to string
from frappe.utils import cstr # Convert to string name = cstr(customer_id) description = cstr( None ) # "" # Format values message = cstr(error_message) log_entry = cstr({ "status" : "success" , "count" : 10 })
Date and Time Functions nowdate() - Current Date Get current date as string.
from frappe.utils import nowdate # Get today's date today = nowdate() # "2024-03-06" # Use in queries invoices = frappe.get_all( "Sales Invoice" , filters = { "posting_date" : nowdate()} ) # Default value if not posting_date: posting_date = nowdate()
now() - Current Timestamp Get current timestamp as string.
from frappe.utils import now # Get current timestamp timestamp = now() # "2024-03-06 14:30:00.123456" # Log timestamp log = { "timestamp" : now(), "action" : "Document Created" }
now_datetime() - Current Datetime Object Get current datetime as Python datetime object.
from frappe.utils import now_datetime import datetime # Get datetime object current_time = now_datetime() # datetime.datetime object # Use in comparisons if document.modified > now_datetime() - datetime.timedelta( hours = 1 ): print ( "Recently modified" )
getdate() - Parse Date Convert string to date object.
date_string
string | datetime
required
Date string or datetime object to convert
from frappe.utils import getdate # Parse date string date_obj = getdate( "2024-03-06" ) # datetime.date object # Convert datetime to date from frappe.utils import get_datetime dt = get_datetime( "2024-03-06 14:30:00" ) date_only = getdate(dt) # Use in calculations fiscal_year_start = getdate( "2024-01-01" ) fiscal_year_end = getdate( "2024-12-31" ) if getdate(invoice.posting_date) >= fiscal_year_start: print ( "In current fiscal year" )
get_datetime() - Parse Datetime Convert string to datetime object.
from frappe.utils import get_datetime # Parse datetime string dt = get_datetime( "2024-03-06 14:30:00" ) # Use in filters from_datetime = get_datetime( "2024-01-01 00:00:00" ) to_datetime = get_datetime( "2024-12-31 23:59:59" ) events = frappe.get_all( "Event" , filters = [ [ "starts_on" , ">=" , from_datetime], [ "starts_on" , "<=" , to_datetime] ] )
Format date for display.
date
string | datetime
required
Date to format
Optional format string (uses user preference if not provided)
from frappe.utils import formatdate # Format with user's preference formatted = formatdate( "2024-03-06" ) # "06-03-2024" (based on user settings) # Custom format formatted = formatdate( "2024-03-06" , "dd-mm-yyyy" ) # "06-03-2024" formatted = formatdate( "2024-03-06" , "dd/mm/yyyy" ) # "06/03/2024" formatted = formatdate( "2024-03-06" , "yyyy-mm-dd" ) # "2024-03-06" # In reports for row in data: row[ "posting_date" ] = formatdate(row[ "posting_date" ])
Date Arithmetic Add or subtract days, months, years from dates.
Add Days
Add Months
Date Calculations
from frappe.utils import add_days, nowdate # Add days to date tomorrow = add_days(nowdate(), 1 ) next_week = add_days(nowdate(), 7 ) last_week = add_days(nowdate(), - 7 ) # Calculate due date invoice.due_date = add_days(invoice.posting_date, payment_terms.credit_days )
Validation Functions validate_email_address() Validate email format.
from frappe.utils import validate_email_address # Validate email try : validate_email_address( "[email protected] " , throw = True ) print ( "Valid email" ) except frappe.exceptions.InvalidEmailAddressError: print ( "Invalid email" ) # Without exception is_valid = validate_email_address( "[email protected] " , throw = False ) if is_valid: contact.add_email(email)
validate_phone_number() Validate phone number format.
from frappe.utils import validate_phone_number # Validate phone try : validate_phone_number( "+91 9876543210" , throw = True ) except frappe.exceptions.InvalidPhoneNumberError: frappe.throw( "Invalid phone number" )
fmt_money() Format currency amounts.
from frappe.utils import fmt_money # Format amount formatted = fmt_money( 1234.56 , currency = "USD" ) # "$1,234.56" formatted = fmt_money( 1234.56 , currency = "INR" ) # "₹1,234.56" # In reports for row in data: row[ "grand_total" ] = fmt_money( row[ "grand_total" ], currency = row[ "currency" ] )
Get number formatting information.
from frappe.utils import get_number_format_info # Get format info format_info = get_number_format_info() # {"decimal_str": ".", "group_sep": ",", "precision": 2}
UI Helper Functions Create clickable link to form.
Link label (defaults to name)
from frappe.utils import get_link_to_form # Create link link = get_link_to_form( "Customer" , "CUST-001" ) # <a href="/app/customer/CUST-001">CUST-001</a> # With custom label link = get_link_to_form( "Sales Invoice" , "SI-2024-001" , "View Invoice" ) # In notifications message = f "Please review { get_link_to_form( 'Purchase Order' , po.name) } " frappe.msgprint(message) # In error messages frappe.throw( f "Stock not available in { get_link_to_form( 'Warehouse' , warehouse) } " )
Translation Function _() - Translate String Translate strings based on user language.
from frappe import _ # Simple translation message = _( "Hello World" ) # With variables error = _( "Item {0} is not available" ).format(item_code) # In validation frappe.throw(_( "Quantity cannot be negative" )) # User messages frappe.msgprint(_( "Document saved successfully" ))
Common Patterns Safe Value Access from frappe.utils import flt, cint, cstr # Safely get and convert values quantity = flt(doc.get( "qty" ) or 0 ) price = flt(doc.get( "rate" ) or 0 ) total = quantity * price # Boolean flags is_disabled = cint(doc.get( "disabled" )) if is_disabled: frappe.throw( "Document is disabled" ) # String handling description = cstr(doc.get( "description" ) or "" )
Date Range Queries from frappe.utils import nowdate, add_days, getdate # Last 7 days start_date = add_days(nowdate(), - 7 ) end_date = nowdate() invoices = frappe.get_all( "Sales Invoice" , filters = [ [ "posting_date" , ">=" , start_date], [ "posting_date" , "<=" , end_date], [ "docstatus" , "=" , 1 ] ], fields = [ "name" , "customer" , "grand_total" ] )
Currency Calculations from frappe.utils import flt, fmt_money def calculate_totals ( items , tax_rate = 0.18 ): """Calculate totals with proper precision""" subtotal = sum (flt(item.get( "amount" )) for item in items) tax_amount = flt(subtotal * tax_rate, 2 ) grand_total = flt(subtotal + tax_amount, 2 ) return { "subtotal" : subtotal, "tax_amount" : tax_amount, "grand_total" : grand_total, "formatted_total" : fmt_money(grand_total, currency = "USD" ) }
Best Practices
Always Use Type Converters Use flt(), cint(), cstr() to safely handle None and empty values: # Good total = flt(qty) * flt(rate) # Bad (can cause TypeError) total = qty * rate # Fails if qty is None
Use getdate() for Comparisons Convert strings to date objects for reliable comparisons: from frappe.utils import getdate if getdate(invoice.due_date) < getdate(nowdate()): mark_invoice_overdue(invoice)
Format Dates for Display Use formatdate() for user-friendly date display: from frappe.utils import formatdate # Format for user's locale display_date = formatdate(invoice.posting_date)
Translate User Messages Always wrap user-facing strings in _() for i18n: from frappe import _ frappe.msgprint(_( "Operation completed successfully" )) frappe.throw(_( "Invalid input provided" ))
