my_app/
└── my_module/
    └── doctype/
        └── my_doctype/
            └── my_doctype.py    # Python controller

undefined

def autoname(self):
    """Custom naming logic"""
    self.name = f"{self.prefix}-{frappe.generate_hash()[:8].upper()}"

def before_naming(self):
    """Called before autoname"""
    pass

# ===== VALIDATION =====

def before_validate(self):
    """Called before validate"""
    self.set_defaults()

def validate(self):
    """Main validation - called on insert and update"""
    self.validate_dates()
    self.validate_amounts()
    self.calculate_totals()
    self.set_status()

def before_save(self):
    """Called after validate, before database write"""
    self.update_modified_info()

# ===== INSERT =====

def before_insert(self):
    """Called before new document is inserted"""
    self.set_initial_values()

def after_insert(self):
    """Called after new document is inserted"""
    self.create_related_documents()
    self.send_notification()

# ===== UPDATE =====

def on_update(self):
    """Called after document is saved (insert or update)"""
    self.update_related_documents()
    self.clear_cache()

def after_save(self):
    """Called after on_update, always runs"""
    pass

def on_change(self):
    """Called when document changes in database"""
    pass

# ===== SUBMISSION =====

def before_submit(self):
    """Called before document is submitted"""
    self.validate_for_submit()

def on_submit(self):
    """Called after document is submitted"""
    self.create_gl_entries()
    self.update_stock()

def on_update_after_submit(self):
    """Called when submitted doc is updated (limited fields)"""
    pass

# ===== CANCELLATION =====

def before_cancel(self):
    """Called before document is cancelled"""
    self.validate_cancellation()

def on_cancel(self):
    """Called after document is cancelled"""
    self.reverse_gl_entries()
    self.reverse_stock()

# ===== DELETION =====

def before_delete(self):
    """Called before document is deleted"""
    self.check_dependencies()

def after_delete(self):
    """Called after document is deleted"""
    self.cleanup_related()

def on_trash(self):
    """Called when document is trashed"""
    pass

def after_restore(self):
    """Called after document is restored from trash"""
    pass

# ===== CUSTOM METHODS =====

def set_defaults(self):
    """Set default values"""
    if not self.posting_date:
        self.posting_date = nowdate()
    if not self.company:
        self.company = frappe.defaults.get_user_default("Company")

def validate_dates(self):
    """Validate date fields"""
    if self.end_date and getdate(self.start_date) > getdate(self.end_date):
        frappe.throw(_("End Date cannot be before Start Date"))

    if getdate(self.posting_date) > getdate(nowdate()):
        frappe.throw(_("Posting Date cannot be in the future"))

def validate_amounts(self):
    """Validate amount fields"""
    for item in self.items:
        if flt(item.qty) <= 0:
            frappe.throw(_("Row {0}: Quantity must be greater than 0").format(item.idx))
        if flt(item.rate) < 0:
            frappe.throw(_("Row {0}: Rate cannot be negative").format(item.idx))

def calculate_totals(self):
    """Calculate document totals"""
    self.total = 0
    for item in self.items:
        item.amount = flt(item.qty) * flt(item.rate)
        self.total += item.amount

    self.tax_amount = flt(self.total) * flt(self.tax_rate) / 100
    self.grand_total = flt(self.total) + flt(self.tax_amount)

def set_status(self):
    """Set document status based on state"""
    if self.docstatus == 0:
        self.status = "Draft"
    elif self.docstatus == 1:
        if self.is_completed():
            self.status = "Completed"
        else:
            self.status = "Submitted"
    elif self.docstatus == 2:
        self.status = "Cancelled"

def is_completed(self):
    """Check if document is completed"""
    return all(item.delivered_qty >= item.qty for item in self.items)

undefined

@frappe.whitelist()
def get_customer_details(customer):
    """Get customer details

    Args:
        customer (str): Customer ID

    Returns:
        dict: Customer details with outstanding amount
    """
    if not customer:
        frappe.throw(_("Customer is required"))

    doc = frappe.get_doc("Customer", customer)

    return {
        "customer_name": doc.customer_name,
        "customer_type": doc.customer_type,
        "territory": doc.territory,
        "credit_limit": flt(doc.credit_limit),
        "outstanding": get_customer_outstanding(customer)
    }


@frappe.whitelist()
def create_invoice(customer, items):
    """Create sales invoice from data

    Args:
        customer (str): Customer ID
        items (str): JSON string of items

    Returns:
        str: Invoice name
    """
    items = frappe.parse_json(items)

    doc = frappe.get_doc({
        "doctype": "Sales Invoice",
        "customer": customer,
        "items": [{
            "item_code": item.get("item_code"),
            "qty": flt(item.get("qty")),
            "rate": flt(item.get("rate"))
        } for item in items]
    })

    doc.insert()
    doc.submit()

    return doc.name

@frappe.whitelist(allow_guest=True)
def get_public_data():
    """Public API - no login required"""
    return {
        "status": "ok",
        "message": "This is public data"
    }

@frappe.whitelist(methods=["POST"])
def create_record(data):
    """Only accepts POST requests"""
    data = frappe.parse_json(data)
    doc = frappe.get_doc(data)
    doc.insert()
    return {"name": doc.name}


@frappe.whitelist(methods=["GET", "POST"])
def flexible_endpoint(**kwargs):
    """Accepts GET and POST"""
    return kwargs

@frappe.whitelist()
def sensitive_operation(doctype, name):
    """API with permission check"""
    # Check permission
    if not frappe.has_permission(doctype, "write", name):
        frappe.throw(_("Not permitted"), frappe.PermissionError)

    # Proceed with operation
    doc = frappe.get_doc(doctype, name)
    # ... do something

    return {"status": "success"}

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

try:
    # Process logic
    doc = frappe.get_doc("Customer", customer)
    doc.last_processed = frappe.utils.now()
    doc.save()
    frappe.db.commit()
except Exception:
    frappe.log_error(title="Process Data Failed")
    raise
finally:
    frappe.destroy()

undefined

scheduler_events = {
    "all": [
        "my_app.tasks.every_minute"
    ],
    "daily": [
        "my_app.tasks.daily_report"
    ],
    "hourly": [
        "my_app.tasks.hourly_sync"
    ],
    "cron": {
        "0 9 * * 1": [
            "my_app.tasks.monday_morning"
        ],
        "*/15 * * * *": [
            "my_app.tasks.every_15_min"
        ]
    }
}

from frappe import _
from frappe.exceptions import ValidationError, PermissionError

def my_function():
    # Throw with message
    frappe.throw(_("Invalid data"))

    # Throw with title
    frappe.throw(_("Cannot proceed"), title=_("Error"))

    # Throw with exception type
    frappe.throw(_("Permission denied"), exc=PermissionError)

    # Message without stopping
    frappe.msgprint(_("Warning: Check your data"))

    # Log error
    frappe.log_error(
        title="My Error",
        message=frappe.get_traceback()
    )

    # Try-except
    try:
        risky_operation()
    except Exception:
        frappe.log_error("Operation failed")
        frappe.throw(_("Something went wrong"))

from frappe.utils import (
    nowdate, nowtime, now_datetime, today,
    getdate, get_datetime,
    add_days, add_months, add_years,
    date_diff, time_diff_in_seconds,
    flt, cint, cstr,
    fmt_money, rounded,
    strip_html, escape_html
)

undefined

undefined

undefined

undefined

```python

undefined