[Python] Tortoise ORM 사용법 - 필드(Fields)

Tortoise ORM이란? https://scshim.tistory.com/576

Tortoise ORM 시작하기 https://scshim.tistory.com/577

Tortoise ORM 사용법 - 모델(Medel) https://scshim.tistory.com/578

 

목차

· 필드란? 필드 사용하기

· Base 필드

· Base 필드를 상속한 여러가지 데이터 필드

· 설명 작성하기

---

필드란? 필드 사용하기

---

· 필드는 모델 클래스 객체의 속성을 정의한다.

· 다음과 같이 모델을 상속한 클래스의 내부 속성으로 필드를 정의할 수 있다.

from tortoise.models import Model
from tortoise import fields


class Tournament(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=255)

- 위 코드에서는 Model의 속성으로 IntField와 CharField가 사용되었다.

 

Base 필드

---

class tortoise.fields.base. Field (

source_field = None ,

generated = False ,

pk = False ,

null = False ,

default = None ,

unique = False ,

index = False ,

description = None ,

model = None ,

validators = None ,

** kwargs )

 

· 필드 타입을 정의할 때 필요한 애트리뷰트다. 즉, 모든 필드들은 해당 애트리뷰트는 상속한다. 

· Base 필드의 각 매개변수의 의미는 다음과 같다.

- source_field (Optional [str]): DB 컬럼 이름이 필드 이름에서 생성되는 대신에 특정해야 한다면, 소스 파일의 이름을 제공한다.

- generated ( bool ): 해당 필드가 DB에 생성되는가?

- pk ( bool ) - 해당 필드가 Primary Key인가? 모델에는 이러한 필드가 하나만 있고, 아무 것도 지정하지 않으면 id라고 불리는 primary key가 자동으로 생성된다.

- null ( bool ): 해당 필드는 null일 될 수 있는가?

- default (Optional [ Any ]): 모델 생성 시 지정되지 않은 경우 사용되는 필드를 위한 기본 값이다. TODO: This can also be a callable for dynamic defaults in which case we will call it. The default value will not be part of the schema. -> 무슨 말이지...

- unique ( bool ): 해당 필드는 유니크한가?

-  description ( Optional [ str ] ): 필드 설명으로, Tortoise.describe_model()과 생성된 DDL에서 DB comments로 나타난다.

-  validators (Optional [ List [ Union [Validator, Callable ]]]): 해당 필드에 대한 유효성 검사기

 

 

 Base 필드를 상속한 여러가지 데이터 필드

---

· Tortoise에는 Base 필드를 상속하여 여러가지 데이터를 표현하기 위한 내장 클래스들이 존재한다. 

 

CharField

· 문자 필드

· Parameters:  ( max_length , ** kwargs )

- Pydantic/JSONSchema 포맷으로 제약된 dict를 반환한다.

 

· 사용예시

class Author(Model):
    name = fields.CharField(max_length=255)

class Tournament(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=255, description="Tournament name", index=True)

class Event(Model):
    id = fields.IntField(pk=True, description="Event ID")
    name = fields.CharField(max_length=255, unique=True)

 

 

CharEnumField 

· 문자 열거형를 나타내는 필드

· Parameters: ( enum_type , description = None , max_length = 0 , ** kwargs )

- 주의사항: max_length가 지정되지 않거나 0이면, 표시된 char 필드의 크기가 자동으로 감지된다. 따라서 추후 열거형을 업데이트하면 테이블 스키마도 업데이트해야한다.

· Return Type: Enum

 

· 사용예시

class Service(IntEnum):
    python_programming = 1
    database_design = 2
    system_administration = 3


class Currency(str, Enum):
    HUF = "HUF"
    EUR = "EUR"
    USD = "USD"


class EnumFields(Model):
    service: Service = fields.IntEnumField(Service)
    currency: Currency = fields.CharEnumField(Currency, default=Currency.HUF)​

 

IntEnumField 

· 정수 열거형를 나타내는 필드

· Parameters: ( enum_type , description = None , ** kwargs )

- 주의사항: max_length가 지정되지 않거나 0이면, 표시된 char 필드의 크기가 자동으로 감지된다. 따라서 추후 열거형을 업데이트하면 테이블 스키마도 업데이트해야한다.

 

· 사용예시:

- 위 CharEnumField 예시에 함께 표현

TextField 

· Large 텍스트 필드

· Parameters: ( pk = False , unique = False , index = False , ** kwargs ) 

· 사용예시:

class Tournament(Model):
    id = fields.IntField(pk=True)
    name = fields.TextField()

 

DateField 

· 날짜를 나타내는 필드

· Parameters: ( source_field = None , generated = False , pk = False , null = False , default = None , unique = False , index = False , description = None , model = None , validators = None , ** kwargs )

 

· 사용예시:

 

class Tournament(Model):
   id = fields.IntField(pk=True, description="토너먼트 아이디")
   name = fields.TextField(description="토너먼트 이름")
   host_date = fields.DateField(description="주최 날짜")

 

DatetimeField 

· 날짜와 시간을 나타내는 필드

· Parameters: ( auto_now = False , auto_now_add = False , ** kwargs )

· 사용예시:

class Tournament(Model):
   id = fields.IntField(pk=True, description="토너먼트 아이디")
   name = fields.TextField(description="토너먼트 이름")
   host_time = fields.DatetimeField(description="주최 시간")

 

 

DecimalField 

· 정확한 소수를 표현하는 필드

- decimal은 빠르고 정확하게 자리 올림 하는 십진 부동 소수 산술을 지원합니다. 

 

· Parameters: ( max_digits , decimal_places , ** kwargs )

- 필수요소:

▶ max_digits (int): 소수 필드의 최대 유효 자릿수  

▶ decimal_place (int): 소수점 이하의 유효 자릿수 

 

· 사용예시:

class Path(Model):
   place_a = fields.TextField()
   place_b = fields.TextField()
   distance = fields.DecimalField(max_digits=6, decimal_places=2)


async def run_create_with_path():
   await Path.create(place_a="서초", place_b="군자", distance=13.539999)

   paths = await Path.all()
   for path in paths:
       print(path.id, path.place_a, path.place_b, path.distance)

loop = asyncio.get_event_loop()
loop.run_until_complete(run_create_with_path())
loop.close()

 

결과

 

FloatField 

· Float(double) 필드

· Parameters: ( source_field = None , generated = False , pk = False , null = False , default = None , unique = False , index = False , description = None , model = None , validators = None , ** kwargs )

 

· 사용예시:

 

class Book(Model):
    name = fields.CharField(max_length=255)
    author = fields.ForeignKeyField("models.Author", related_name="books")
    rating = fields.FloatField()

 

SmallIntField 

· 작은 정수형 필드 (16-bit signed, 0 ~ 65,535)

· Parameters: ( pk = False , ** kwargs )

· 사용예시:

class Tournament(Model):
   id = fields.IntField(pk=True, description="토너먼트 아이디")
   name = fields.TextField(description="토너먼트 이름")
   host_time = fields.DatetimeField(description="주최 시간")
   participants = fields.SmallIntField(description="참가 인원")

 

설명 작성하기

---

· 테이블과 컬럼의 설명을 주석으로 작성할 수 있다.

· Field의 description 필드를 통해 컬럼의 설명을 작성할 수 있고, Model을 상속 받은 클래스의 내부 클래스토 Meta 클래스를 정의하고, 해당 Meta 클래스의 table_description 필드를 통해 테이블의 설명을 작성할 수 있다.

 

from tortoise.models import Model
from tortoise import fields

class Tournament(Model):
   id = fields.IntField(pk=True, description="토너먼트 아이디")
   name = fields.TextField(description="토너먼트 이름")
  
   class Meta:
       table = "tournament"
       table_description = "토너먼트 테이블"

TODO: BigIntField, BinaryField, JSONField