Django Model - Field types
Model field reference
Model field reference
이 문서는 Django가 제공하는 필드 옵션과 필드 유형을 포함한 모든 필드의 API reference를 포함하고 있다.
Field types
AutoField
class AutoField(**options)
ID로 사용 가능한 자동으로 증가하는 IntegerField다. 보통 직접 사용할 필요는 없다. 모델의 기본키 필드는 별도로 지정하지 않으면 자동으로 추가된다.
BigAutoField
class BigAutoField(**options)
1부터 9223372036854775807까지 숫자에 맞도록 보장한다는 점을 제외하고 AutoField와 매우 유사한 64비트 정수다.
BigIntegerField
class BigIntergerField(**options)
-9223372036854775808부터 9223372036854775807까지 숫자에 맞도록 보장한다는 점을 제외하면 IntergerField와 매우 유사한 64비트 정수다. 이 필드의 기본 위젯은 TextInput이다.
BinaryField
class BinaryField(**options)
raw binary 데이터를 저장하기 위한 필드. 바이트 할당만을 지원한다. 이 필드는 기능이 제한적임을 명심해라. 예를 들면, BinaryField 값에 queryset을 필터링할 수 없다. 또한 ModelForm에 BinaryField를 포함시킬 수 없다.
Abusing BinaryField
데이터베이스에 파일을 저장하는 것을 99퍼센트의 경우 나쁜 디자인이라고 생각해라. 이 필드는 정적 파일을 적절하게 대체하지 못한다.
BooleanField
class BooleanField(**options)
true/false 필드다.
이 필드의 기본 폼 위젯은 CheckboxInput이다.
null값 허용이 필요하면 대신 NullBooleanField를 사용해라.
Field.default가 정의되지 않았을 때 BooleanField의 기본 값은 None이다. default None을 사용하고 해당 필드에 값을 넣지 않을 경우, migration시 에러가 발생하지 않고 실제 모델 객체가 저장될 때 DBMS에서 제약 조건 에러가 발생한다.
CharField
class CharField(max_length=None, **options)
작은 문자열에서 큰 사이즈의 문자열을 위한 문자열 필드다.
많은 양의 텍스트일 경우 TextField를 사용해라.
이 필드의 기본 폼 위젯은 TextInput이다.
CharField는 필수 인수가 추가로 하나 있다.
CharField.max_length
필드의 최대길이(문자 수). max_length는 데이터베이스 수준과 Django의 유효성 검증에서 처리된다.
Note
여러 데이터베이스 백엔드에 이식되어야 하는 애플리케이션을 작성 중이라면, 일부 백엔드에는 max_length에 대한 제약이 있음을 알고 있어야 한다.
DateField
class DateField(auto_now=False, auto_now_add=False, **options)
Python에서 datetime.date 인스턴스에 의해 표현되는 날짜다. 몇 가지 추가 선택적 인수를 가지고 있다.
DateField.auto_now
객체가 저장될 때마다 매번 자동으로 필드를 현재시간이 설정한다. "last-modified"의 타임스탬프로써 유용하다. 항상 현재 날짜가 사용됨에 주의해라. 기본값을 재정의 할 수 없다.
해당 필드는 Model.save()가 호출될 때 자동으로 수정된다. QuerySet.update() 같은 다른 방법으로 다른 필드를 수정하면 해당 필드는 수정되지 않는다. 다만 이런 방법으로 사용자 값을 지정하여 필드를 수정할 수는 있다.
DateField.auto_now_add
객체가 처음 생성될 때 자동으로 현재시간이 설정된다. 생성의 타임스탬프로 유용하다. 항상 현재 날짜가 사용됨에 주의해라. 기본값을 재정의 할 수 없다. 그러므로 객체가 생성될 때 이 필드에 값을 설정하더라도 무시된다. 이 필드의 수정을 원한다면, auto_now_add=True대신에 다음과 같이 설정해라.
default=today (datetime.date.today()의 값이 사용된다.)
default=timezone.now (django.utils.timezone.now()의 값이 사용된다.)
이 필드의 기본 폼 위젯은 TextInput이다. 어드민에는 자바스크립트 캘린더와 "Today" 숏컷을 추가한다. 추가로 invalid_date 오류 메시지 키를 포함한다.
auto_now_add, auto_now, default는 같이 쓰일 수 없다. 이러한 옵션들을 섞어 쓴다면 오류가 발생한다.
Note
필드에 auto_now 또는 auto_now_add를 True로 설정하면 editable=False와 blank=True이 설정된다.
Note
auto_now와 auto_now_add 옵션은 생성 또는 수정하는 순간의 기본 타임존 날짜가 항상 사용된다. 다른 것을 원한다면, auto_now, auto_now_add 대신에 default로 callable을 사용하거나 save() 메서드를 재정의해라. 또는 DateField 대신에 DateTimeField를 사용하고 표시 시간을 datetime에서 date로의 변환 등의 방법을 결정해라.
DateTimeField
class DateTimeField(auto_now=False, auto_now_add=False, **options)
Python에서 datetime.datetime 인스턴스로 표현되는 날짜와 시간. DateField와 동일한 추가 인수를 가지고 있다.
이 필드의 기본 폼 위젯은 단일 TextInput이다. 어드민에서는 JavaScript 숏컷과 별도로 두 개의 TextInput 위젯을 사용한다.
DecimalField
class DecimalField(max_digit=None, decimal_places=None, **options)
고정 소수로 Python에서 Decimal 인스턴스로 나타낸다. 두 개의 필수 인수가 있다.
DecimalField.max_digits
숫자에 허용되는 최대 자릿수다. 이 숫자는 decimal_places보다 크거나 같아야 한다.
DecimalField.decimal_places
숫자와 함께 저장될 소수 자릿수다.
예를 들어, 최대 999를 소수점 2자리 이하로 저장하기 위해서 다음과 같이 사용한다.
대략 10억을 소수점 10자리 이하로 저장하기 위해서 다음과 같이 사용한다.
이 필드의 기본 폼 위젯은 localize 설정이 Fasle 일 때 NumberInput이고 아닐 때는 TextInput이다.
DurationField
class DurationField(**options)
시간주기를 위한 필드 - Python에서 timedelta로 모델링. PostgreSQL에서는 데이터 타입이 interval이고 Oracle에서는 INTERVAL DAY(9) TO SECOND(6)다. 다른 DBMS에서는 마이크로초의 bigint가 사용된다.
Note
DurationField의 산술 연산은 대부분의 경우에 잘 동작한다. 하지만 PostgreSQL을 제외한 모든 데이터베이스에서 DurationField의 값을 DateTimeField 산술 인스턴스에 비교하는 것은 기대한 것처럼 동작하지 않는다.
EmailField
class EmailField(max_length=254, **options)
유효한 이메일 주소인지 체크하는 CharField다. 입력값을 검증하는데 EmailValidator를 사용한다.
FileField
class FileField(upload_to=None, max_length=100, **options)
파일 업로드 필드.
Note
primary_key 인수를 지원하지 않고 사용할 경우 에러를 발생시킨다.
두 개의 선택 인수가 있다.
FileField.upload_to
이 속성은 업로드 디렉터리와 파일 이름을 설정하는 방법을 제공하고 두 가지 방법을 사용할 수 있다. 두 경우 모두 Storage.save() 메서드가 호출된다.
문자열 값을 지정하면 strftime() 형식을 포함할 수 있다. 주어진 디렉터리에 포맷 형식을 업로드 일시로 변경 후 파일이 업로드된다.
기본 FileSystemStorage를 사용하면, 업로드된 파일이 저장될 로컬 파일 시스템에 위치가 MEDIA_ROOT 경로에 추가된다.
또한 upload_to는 함수 같은 callable일 수 있다. 파일 이름을 포함하여 업로드 경로를 얻기 위해 불려진다. callable은 두 인수를 수용하고 스토리지 시스템으로 전달되는 Unix 스타일 경로 (슬래시를 포함)를 리턴해야 한다. 두 가지 인수는 다음과 같다.
instance
FileField가 정의된 모델의 인스턴스. 더 구체적으로, 현재 파일이 첨부되는 특별한 인스턴스다.
대부분의 경우, 이 객체는 아직 데이터베이스에 저장되지 않은 상태기 때문에, 기본 AutoField를 사용한다면, 아직 primary key 필드에 값이 없을 것이다.
filename
원본 파일에 주어진 이름. 최종 목적 경로를 결정할 때 사용될 수도 있고 아닐 수도 있다.
FileField.storage
파일의 저장과 검색을 다루는 storage 객체.
이 필드의 기본 폼 위젯은 ClearableFileInput이다.
모델에서 FileField 또는 ImageField를 사용하면 몇 가지 진행과정이 있다.
1. settings 파일에, Django가 업로드된 파일을 저장하기 위해 디렉터리의 전체 경로로 MEDIA_ROOT 정의가 필요하다. (성능을 위해, 파일을 데이터베이스에 저장되지 않는다.).
디렉터리의 base public URL로 MEDIA_URL을 정의해라.
2. 모델에 FileField나 ImageField를 추가하고 업로드된 파일에 사용될 MEDIA_ROOT의 서브 디렉터리를 upload_to 옵션으로 정의해라.
3. 데이터베이스에 저장되는 것은 모두 파일에 대한 경로다(MEDIA_ROOT의 상대적인). 대부분 Django가 제공하는 편리한 url 속성을 사용하길 원할 것이다. 예를 들어, mug_shot라고 불리는 ImageField가 있다면, template에서 {{ object.mug_shot.url }}를 사용하여 이미지의 절대 경로를 얻을 수 있다.
예를 들어, MEDIA_ROOT가 '/home/media'로 upload_to가 'photos/%Y/%m/%d'로 설정되었다고 하자. upload_to의 '%Y/%m/%d' 부분은 strftime()로 포매팅된다. '%Y'는 네 자리 연도, '%m'은 두 자리 월, '%d'는 두 자리 일자다. 만약 2007년 1월 15일에 파일을 업로드한다면, /home/media/photos/2007/01/15 디렉터리에 저장될 것이다.
업로드된 파일의 디스크 상의 이름이나 사이즈를 검색하려면, 각각 name과 size속성을 사용할 수 있다. 사용 가능한 속성과 메서드에 대한 추가 정보는 Managing files 토픽 가이드와 File 클래스 레퍼런스를 봐라.
Note
파일은 데이터베이스에 모델이 저장되는 과정의 일부로 저장되므로, 디스크에 사용된 실제 파일 이름은 모델이 저장되기 전까지는 신뢰할 수 없다.
업로드된 파일의 상대 URL은 url속성을 사용하여 얻을 수 있다. 내부적으로는, Storage 클래스에 있는 url() 메서드를 호출한다.
업로드된 파일을 다룰 때는 언제나 업로드되는 위치 그리고 파일의 타입이 무엇인지 세심하게 주의하여 보안 허점을 피해야 한다. 업로드된 모든 파일을 검증함으로써 당신이 생각한 파일임을 확신해야 한다. 예를 들어, 누군가가 검증과정 없이 웹서버의 도큐먼트 루트 디렉터리에 맹목적으로 파일을 업로드하도록 허용한다면, CGI나 PHP 스크립트를 업로드하고 사이트에서 해당 URL을 방문함으로써 실행되게 할 수 있다. 이런 행위를 허용하지 말아라.
또한 업로드된 HTML조차 브라우저에 의해 (서버를 통해서가 아닌) 실행될 수 있기 때문에, XSS나 CSRF 공격과 동등한 보안 위협이 될 수 있다.
FileField 인스턴스는 데이터베이스에서 기본 최대길이가 100자인 varchar 칼럼으로 생성된다. 다른 필드들과 같이 최대길이를 max_length 인수로 변경할 수 있다.
FileField and FieldFile
class FieldFile
모델의 FileField에 접근할 때, FieldFile의 인스턴스가 파일에 접근하기 위한 프락시로써 제공된다.
FieldFile의 API는 File의 API를 미러링 한다. 주요한 차이점이 하나 있다. 클래스에 의해 래핑 된 객체는 Python 빌트인 File 객체를 감싸는 래퍼일 필요는 없다. 대신에, Storage.open() 메서드의 결과를 감싸는 래퍼다. File 객체나 사용자 정의 저장소의 File API 구현체일 수 있다.
read()와 write() 같은 File로부터 상속된 API 외에도, FieldFile에는 파일과 상호작용하기 위해 사용할 수 있는 다수의 메서드를 포함한다.
Warning
이 클래스의 두 메서드 save()와 delete()는 기본적으로 연관된 FieldFile의 모델 객체를 데이터베이스에 저장한다.
FieldFile.name
연관된 FileField의 Storage의 루트로부터의 상대 경로를 포함하고 있는 파일의 이름
FieldFile.size
Storage.size() 메서드의 결과
FieldFile.url
Storage 클래스의 url() 메서드에 의해 호출되는 파일의 상대 URL에 접근하기 위한 읽기 전용 프로퍼티
FieldFile.open(mode='rb')
지정한 mode로 인스턴스와 연관된 파일을 열거나 다시 연다. 표준 Python의 open() 메서드와 다르게 파일 디스크립터를 리턴하지 않는다.
필드에 접근 시 암시적으로 파일이 열리므로, 파일의 포인터 재설정 또는 mode변경을 제외하면 메서드 호출은 불필요하다.
FieldFile.close()
동작이 표준 Python file.close() 메서드와 비슷하며 해당 인스턴스와 관련된 파일을 닫는다.
FieldFile.save(name, content, save=True)
이 메서드는 파일 이름과 파일내용을 필드의 저장소 클래스에 전달하고, 저장된 파일을 모델 필드와 연결한다. 수동으로 모델에 FileField 인스턴스와 파일 데이터를 연결하길 원한다면, save() 메서드를 사용하여 파일 데이터를 유지해라.
두 가지 필수 인수를 가진다. name은 파일의 이름이고 content는 파일의 내용을 포함하는 객체다. 선택적 인수인 save는 필드와 관련된 파일이 변경된 후에 모델 인스턴스가 저장되는지 여부를 제어한다. 기본값은 True다.
content 인수가 Python의 빌트인 파일 객체가 아닌 django.core.files.File의 인스턴스야야 되는 것에 주의해라. 아래처럼 기존의 Python 파일 객체로부터 File을 구성할 수 있다.
또는 아래와 같이 하나의 Python 문자열로 구성할 수 있다.
FieldFile.delete(save=True)
인스턴스와 관련된 파일을 삭제하고 필드에 모든 속성을 클리어한다. 이 메서드는 delete()가 호출될 때 파일이 열리면 파일을 닫는다.
선택적 인수인 save는 필드와 연관된 파일이 삭제된 후 모델 인스턴스를 저장할지 여부를 제어한다. 기본값은 True다.
모델을 삭제하면 관련된 파일들은 삭제되지 않는다. 분리된 파일들을 삭제해야 한다면, 직접 삭제해야 한다. (예, 수동으로 실행하거나 cron 등을 통해 주기적으로 실행 가능한 custom management command를 작성)
FilePathField
class FilePathField(path=None, match=None, recursive=False, max_length=100, **options)
FilePathField는 파일 시스템에서 특정한 디렉터리에 파일 이름으로 제한된다. 세 가지 특별한 인수가 있고 그중 첫 번째 인수는 필수다.
FilePathField.path
필수 인수다. FilePathField가 선택해야 하는 디렉터리를 위한 절대 파일 시스템 경로다.
예: "/home/images".
FilePathField.match
선택적 인수다. FilePathField가 파일 이름을 필터링할 때 사용할 문자열로 된 정규표현식이다. 정규표현식은 전체 경로가 아닌 기본 파일 이름에 적용된다. 예를 들어, "foo.*\.txt$", 정규표현식이면 foo23.txt은 일치하나 bar.txt나 foo23.png는 일치되지 않는다.
FilePathField.recursive
선택적 인수다. True나 False 값이다. 기본값은 False다. path의 모든 서브 디렉터리가 포함되야하는지 여부를 지정한다.
FilePathField.allow_files
선택적 인수다. True나 False 값이다. 기본값은 True다. 지정된 위치에 파일을 포함할지 여부를 지정한다. allow_files 또는 allows_folders 둘 중에 하나는 True 여야 한다.
FilePathField.allow_folders
선택적 인수다. True나 False 값이다. 기본값은 True다. 지정된 위치에 폴더를 포함할지 여부를 지정한다. allow_files 또는 allows_folders 둘 중에 하나는 True 여야 한다.
물론, 두 인수를 한 번에 사용될 수 있다.
전체 경로가 아닌 기본 파일 이름에 match가 적용된다는 하나의 잠재적인 문제가 있다. 다음 예를 보자.
/home/images/foo.png는 일치하지만 /home/images/foo/bar.png는 아니다. 폴더가 아닌 기본 파일 이름에만 적용되기 때문이다. (foo.png와 bar.png)
FilePathField 인스턴스는 데이터베이스에 최대길이 기본값이 100자인 varchar 칼럼으로 생성된다. 다른 필드들과 마찬가지로, 최대 길이를 max_length 인수를 사용하여 변경할 수 있다.
FloatField
class FloatField(**options)
Python에서 float 인스턴스로 표현된 부동 소수점 숫자다.
이 필드의 기본 폼 위젯은 localize가 False일 때 NumberInput이고 그 외는 TextInput이다.
FloatField vs. DecimalField
FloatField 클래스는 때로는 DecimalField 클래스와 섞여 쓰인다. 비록 둘 모두 실수를 뜻하지만 다르게 숫자를 표현한다. FloatField는 내부적으로 Python의 float 타입을 사용하지만 DecimalField는 Python의 Decimal 타입을 사용한다. 두 필드의 비교에 대한 추가 정보는 Python의 decimal 모듈 문서를 참고해라.
ImageField
class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)
FileField로부터 모든 속성과 메서드를 상속받지만, 업로드된 객체가 유효한 이미지인지 검증한다.
ImageField는 FileField에 사용 가능한 특별한 속성들 외 추가적으로 height와 width 속성이 있다.
ImageField는 이러한 속성의 쿼리를 유용하게 하기 위해 두 가지 선택적인 추가 인수를 가지고 있다.
ImageField.height_field
모델 인스턴스가 저장될 때 이미지의 높이가 자동으로 채워지는 모델 필드의 이름이다.
ImageField.width_field
모델 인스턴스가 저장될 때 이미지의 너비가 자동으로 채워지는 모델 필드의 이름이다.
Pillow 라이브러리를 요구한다.
ImageField 인스턴스는 데이터베이스에 기본 최대길이가 100자인 varchar 칼럼으로 생성된다. 다른 필드와 마찬가지로 최대 길이를 max_length 인수를 사용하여 변경할 수 있다.
IntegerField
class IntegerField(**options)
정수다. Django가 지원하는 모든 데이터베이스에서 -2147483648부터 214783647까지의 값은 안전하다. 이 필드의 기본 폼 위젯은 localize가 False일 때 NumberInput이고 그 외에는 TextInput이다.
GenericIPAddressField
class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)
문자열 형식에 IPv4나 IPv6 주소다 (예, 192.0.2.30 or 2a02:42f3::4). 이 필드의 기본 폼 위젯은 TextInput이다.
IPv6 주소 정규화는 RFC 4291의 section 2.2를 따르며, 해당 섹션의 단락 3에서 제안된 ::ffff:192.0.2.0 같은 IPv4 포맷 사용도 포함한다. 예를 들어, 2001:0::0:01은 2001::1으로 정규화되고 ::ffff:0a0a:0a0a는 ::ffff:10.10.10.10로 정규화된다. 모든 문자는 소문자로 변환된다.
GenericIPAddressField.protocol
지정된 프로토콜을 위해 입력을 검증하여 제한한다. 허용되는 값은 'both' (기본값), 'IPv4', 'IPv6'이다. 대소문자를 구분하지 않는다.
GenericIPAddressField.unpack_ipv4
::ffff:192.0.2.1과 같이 IPv4 매핑된 주소의 압축을 푼다. 이 옵션이 허용되면 앞 주소가 압축 해제되어 192.0.2.1이 된다. 기본값은 사용불가다. 오직 protocol이 'both'로 사용될 때만 사용 가능하다.
빈 값을 허용한다면, 빈 값이 null로 저장되므로 null을 허용해야 한다.
NullBoleanField
class NullBooleanField(**options)
BooleanField와 비슷하지만, 옵션 중 하나로 NULL을 허용한다. BooleanField에 null=True 대신에 사용한다. 이 필드의 기본 폼 위젯은 NullBoleanSelect다.
PositiveIntegerField
class PositiveIntergerFeild(**options)
IntegerField와 비슷하지만, 0 또는 양수이어야 한다. Django가 지원하는 모든 데이터베이스에서 0부터 214783647까지의 값은 안전하다. 전 버전과의 호환을 위해 0 값을 허용한다.
PositiveSmallIntegerField
class PositiveSmallIntegerField(**options)
PositiveIntergerField와 비슷하지만, 오직 특정(데이터베이스에 종속적인) 지점 이하만을 허용한다. Django가 지원하는 모든 데이터베이스에서 0부터 32767까지의 값은 안전하다.
SlugField
class SlugField(max_length=50, **options)
Slug는 신문에서 사용되는 용어다. 슬러그는 오직 문자, 숫자, 밑줄, 하이픈만을 포함하는 짧은 레이블이다. 일반적으로 URL에 사용된다.
CharField와 마찬가지로, max_length(이 섹션에서 데이터베이스 이식성과 max_length에 대한 내용을 참고해라)를 지정할 수 있다. max_length가 지정되지 않으면, Django는 기본값으로 50자를 사용한다.
묵시적으로 Field.db_index를 True로 설정한다.
다른 값들로 SlugField를 자동으로 미리 채우는 것이 유용하다. prepopulated_fields를 사용하여 관리자에서 자동으로 이 작업을 할 수 있다.
SlugField.allow_unicode
True면, 필드는 ASCII 문자 외에 Unicode 문자를 허용한다. 기본값은 False다.
SmallIntegerField
class SmallIntegerField(**options)
IntegerField와 비슷하지만, 오직 특정(데이터베이스에 종속적인) 지점 이하만을 허용한다. Django가 지원하는 모든 데이터베이스에서 -32768부터 32767까지의 값은 안전하다.
TextField
class TextField(**options)
큰 텍스트 필드다. 이 필드의 기본 폼 위젯은 Textarea다.
max_length 속성이 지정되면, 자동으로 생성된 폼 필드의 Textarea 위젯에서 반영된다. 하지만 모델이나 데이터베이스 레벨에서 강제 적용되지는 않는다. 저런 경우는 CharField를 사용해라.
TimeField
class TimeField(auto_now=False, auto_now_add=False, **options)
Python에서 datetime.time 인스턴스로 나타내는 시간이다. DateField와 동일한 자동 채우기 옵션을 허용한다.
이 필드의 기본 폼 위젯은 TextInput이다. 관리자에서는 자바스크립트 바로가기를 추가한다.
URLField
class URLField(max_length=200, **options)
URL을 위한 CharField다.
이 필드의 기본 폼 위젯은 TextInput이다.
모든 CharField의 서브클래스와 마찬가지로, URLField는 선택적 인수인 max_length를 가지고 있다. max_length를 지정하지 않는다면, 기본값인 200자가 사용된다.
UUIDField
class UUIDField(**options)
universally unique identifiers를 저장하기 위한 필드다. Python의 UUID클래스를 사용한다. PostgreSQL을 사용하면 uuid 데이터 타입으로 저장되고 이외에는 char(32)로 저장된다.
Universally unique identifiers는 기본키를 위한 AutoField를 대신하는 좋은 방법이다. 데이터베이스는 UUID를 생성하지 않으므로 기본값 사용을 추천한다.
기본값은 UUID의 인스턴스가 아닌 호출 가능한 객체(괄호는 생략된)가 전달된다는 점을 주의해라.
