A model corresponds to the table of your database. It contains relationships and behaviors of the data.
The basics:
This example model defines a Member, which has a first_name and last_name:
import macaron
class Member(macaron.Model): pass
The above Member model corresponds to a database table like this:
CREATE TABLE member (
id INTEGER PRIMARY KEY,
first_name TEXT DEFAULT 'unknown',
last_name TEXT,
joined TIMESTAMP
);
Macaron does not create a table for simplified implementation, so attributes of the model is defined according to the table definition. In generally use, you need not modify the class definition of the model when the database table is modified.
Note
Most simple case, you do not define your Model classes except class definition. But you should define fields on your Models, the fields have validation and conversion mechanism. Field definition example is below.
class Member(macaron.Model):
name = macaron.CharField(max_length=20)
joined = macaon.TimestampAtCreate()
modified = macaron.TimestampAtSave()
point = macaron.IntegerField(min=0, max=20)
In the code, the NowAtCreate, NowAtSave, IntegerField, and CharField. The former two classes differs from the latter two ones. Built-in classes are described below.
This sets time created when INSERT is conducted.
This sets time modified when UPDATE is conducted.
Parameters: |
|
---|
This is for number field. The minimum and maximum values can be specified.
This is for integer field.
Parameters: |
|
---|
This is for text field. If you want to check the text length, you can specified min_length and max_length.
If you use a single table which has no relationship is very simple, which is described above. However, it is not a thing you hope. Macaron supports “Many-to-One” relationships and needs the field information in the class definition. See below.
class Team(macaron.Model): pass
class Member(macaron.Model):
team = macaron.ManyToOne(Team, related_name="members", fkey="team_id", key="id")
These Team and Member are defined as database tables in SQL.
CREATE TABLE team (
id INTEGER PRIMARY KEY,
name TEXT
);
CREATE TABLE member (
id INTEGER PRIMARY KEY,
team_id INTEGER NOT NULL,
first_name TEXT,
last_name TEXT,
age INT
);
Note
In this example, a Many-to-One relationship which represents that a Member has a Team – means a Member belongs to a Team but each Member only belongs to one Team – is defined as above.
The attribute team of Member class relate the Member and Team. This definition also create recursive relationships (an object with a Many-to-One relationship to itself), automatically. If you want to call the field to another name, you can it.
class Member(macaron.Model):
belongs_to = macaron.ManyToOne(Team, fkey="team_id", key="id", related_name="members")
Macaron’s model class is designed flexible. You can customize field types and before and after INSERT and UPDATE.
Field definition section describes how to use field classes. This section describes how to customize fields. Field type classes are derived from base class Field or subclasses of Field. Now there are AtCreate and AtSave subclasses derived from Field. For example, NowAtCreate is a subclass of AtCreate (i.e. it is a subclass of Field, too).
For example, NowAtCreate is implemented as below.:
class NowAtCreate(AtCreate):
def set(self, obj, value):
return datetime.datetime.now()
The NowAtCreate.set() is called when object is inserted to database. In this way, implementing some callback methods and you can control behaviors of model objects.
These methods are called in below sequence.