Controllers

A Controller is a normal Python class which extends from frappe.model.Document base class. This base class is the core logic of a DocType. It handles how values are loaded from the database, how they are parsed and saved back to the database.

When you create a DocType named Person, a python file is created by the name person.py and the contents look like:

import frappe
from frappe.model.document import Document

class Person(Document):
    pass

All the fields are available to the class as attributes.

Controller Methods

You can add custom methods to your Controller and it will be callable using the doc object. For example,

# controller class
class Person(Document):
    def get_full_name(self):
        """Returns the person's full name"""
        return f"{self.first_name} {self.last_name}"

# somewhere in your code
>>> doc = frappe.get_doc("Person", "000001")
>>> doc.get_full_name()
John Doe

Controller Hooks

To add custom behaviour during the lifecycle of a document, we have controller hooks.

Apart from doc events for typical actions, you can also hook into other actions.

To use a controller hook, just define a class method with that name. For e.g

class Person(Document):
    def validate(self):
        if self.age <= 18:
            frappe.throw("Person's age must be at least 18")

    def after_insert(self):
        frappe.sendmail(recipients=[self.email], message="Thank you for registering!")

You can also override the pre-defined document methods to add your own behaviour if the hooks aren't enough for you. For e.g to override the save() method,

class Person(Document):
    def save(self, *args, **kwargs):
        super().save(*args, **kwargs) # call the base save method
        do_something() # eg: trigger an API call or a Rotating File Logger that "User X has tried updating this particular record"

There are a lot of methods provided by default on the doc object. You can find the complete list here.

1. Create a document

To create a new document and save it to the database,

doc = frappe.get_doc({
    'doctype': 'Person',
    'first_name': 'John',
    'last_name': 'Doe'
})
doc.insert()

doc.name # 000001

2. Load a document

To get an existing document from the database,

doc = frappe.get_doc('Person', '000001')

# doctype fields
doc.first_name # John
doc.last_name # Doe

# standard fields
doc.creation # datetime.datetime(2018, 9, 20, 12, 39, 34, 236801)
doc.owner # john.doe@frappeframework.com

Document

A Document is an instance of a DocType. It usually maps to a single row in the database table. We refer to it as doc in code.

Example

Let's say we have a DocType ToDo with the following fields:

• description

• status

• priority

Now, if we want to query a document from the database, we can use the ORM.

>>> doc = frappe.get_doc("ToDo", "0000001")
<todo: 0000001="">

>>> doc.as_dict()
{'name': '0000001',
 'owner': 'Administrator',
 'creation': datetime.datetime(2022, 3, 28, 18, 20, 23, 275229),
 'modified': datetime.datetime(2022, 3, 28, 18, 20, 23, 275229),
 'modified_by': 'Administrator',
 'docstatus': 0,
 'idx': 0,
 'status': 'Open',
 'priority': 'Medium',
 'color': None,
 'date': None,
 'allocated_to': None,
 'description': 'Test',
 'reference_type': None,
 'reference_name': None,
 'role': None,
 'assigned_by': 'Administrator',
 'assigned_by_full_name': 'Administrator',
 'sender': None,
 'assignment_rule': None,
 'doctype': 'ToDo'}

You get the values of description, status and priority, but you also get fields like creation, owner and modified_by which are fields added by default by the framework on all docs.

Type Annotations

Introduced in Version 15.

Frappe support automatically generating Python type annotations in controller files. These annotations can be used for auto-completion, reference and type-checking inside the controller file.

class Person(Document):
    # begin: auto-generated types
    # This code is auto-generated. Do not modify anything in this block.

    from typing import TYPE_CHECKING

    if TYPE_CHECKING:
        from frappe.types import DF

        first_name: DF.Data
        last_name: DF.Data 
        user: DF.Link
    # end: auto-generated types
    pass

Note: These annotations are generated when creating or updating doctypes. If you modify the code block, it will get overridden on the next update.

You can configure automatic exporting in your app by adding the following hook.

# hooks.py

export_python_type_annotations = True

Learn more about type annotations:

• https://docs.python.org/3/library/typing.html

• VS Code users can install Python extension for better auto-complete - https://code.visualstudio.com/docs/languages/python

• Most other editors have an equivalent plugin system using LSP.