Property 클래스

참고: 새로운 애플리케이션을 빌드하는 개발자는 NDB 클라이언트 라이브러리를 사용하는 것이 좋습니다. NDB 클라이언트 라이브러리는 이 클라이언트 라이브러리와 비교할 때 Memcache API를 통한 자동 항목 캐싱과 같은 여러 이점이 있습니다. 현재 이전 DB 클라이언트 라이브러리를 사용 중인 경우 DB에서 NDB로의 마이그레이션 가이드를 참조하세요.

Property 클래스는 데이터 모델에 대한 속성 정의의 상위 클래스입니다. Property 클래스는 속성 값의 유형, 값의 유효성 검사 방법, Datastore에 값이 저장되는 방법을 정의합니다.

Property는 google.appengine.ext.db 모듈에서 제공됩니다.

소개

속성 클래스는 값 유형, 기본값, 유효성 검사 논리, 모델 속성의 기타 기능을 설명합니다. 각 속성 클래스는 Property 클래스의 하위 클래스입니다. Datastore API에는 각 Datastore 값 유형에 대한 속성 클래스와 Datastore 유형과 더불어 추가 기능을 제공하는 여러 속성 클래스를 포함합니다. 유형 및 속성 클래스를 참조하세요.

속성 클래스는 생성자에게 전달된 인수의 구성을 허용할 수 있습니다. 기본 클래스 생성자는 Datastore API에 제공된 모든 인수를 비롯해 일반적으로 모든 속성 클래스에서 지원되는 여러 인수를 지원합니다. 이러한 구성에는 기본값, 명시적 값의 필요 여부, 허용되는 값 목록, 커스텀 유효성 검사 로직이 포함됩니다. 속성 구성에 대한 자세한 내용은 특정 속성 유형 문서를 참조하세요.

속성 클래스는 데이터 저장소 속성의 모델을 정의하지만 모델 인스턴스의 속성 값은 포함하지 않습니다. Property 클래스의 인스턴스는 클래스의 인스턴스가 아니라 모델 클래스에 속합니다. Python 용어로 속성 클래스 인스턴스는 모델 인스턴스의 속성이 어떻게 동작하는지 정의하는 '설명자'입니다. 설명자에 대한 자세한 내용은 Python 문서를 참조하세요.

생성자

Property 기본 클래스의 생성자는 다음과 같이 정의됩니다.

class Property(verbose_name=None, name=None, default=None, required=False, validator=None, choices=None, indexed=True)

모델 속성 정의의 상위 클래스입니다.

인수

verbose_name

사용자 친화적인 속성 이름으로 항상 속성 생성자에 대한 첫 번째 인수여야 합니다. djangoforms 라이브러리는 이 이름을 사용하여 양식 필드 라벨을 만듭니다. 다른 곳에서도 비슷한 용도로 사용할 수 있습니다.

name

쿼리에 사용되는 속성의 저장소 이름입니다. 이 이름은 속성에 대한 특성(attribute) 이름의 기본값으로 사용됩니다. 모델 클래스는 속성(property) 외에 특성(attribute) 또한 가지기 때문에 속성은 이름을 사용하여 예약된 특성 이름을 Datastore의 속성 이름으로 사용하고, 속성의 특성(property attribute)에 대해서는 다른 이름을 사용할 수 있습니다. 자세한 내용은 허용되지 않는 속성 이름을 참조하세요.

default

속성의 기본값입니다. 속성에 값이 제공되지 않거나 None 값이 제공된 경우, 이 값이 기본값으로 간주됩니다.

참고: 모델 클래스 정의는 나머지 애플리케이션 코드와 함께 캐시됩니다. 여기에는 속성의 기본값 캐싱이 포함됩니다. users.get_current_user()와 같은 요청에 지정된 데이터를 사용하여 모델 정의의 기본값을 설정하지 마세요. 대신 속성 값을 초기화하는 Model 클래스의 __init__() 메서드를 정의하세요.

required

True인 경우 속성은 None 값을 가질 수 없습니다. 모델 인스턴스는 누락된 값으로 인스턴스가 작성되지 않도록 생성자의 모든 필수 속성을 초기화해야 합니다. 필수 속성을 초기화하지 않고 인스턴스 생성을 시도하거나 필수 속성에 None 값을 할당하려고 시도하면 BadValueError가 발생합니다.

필수이며 기본값이 있는 속성은 생성자에 속성이 지정되지 않은 경우 기본값을 사용합니다. 그러나 속성에는 None 값을 할당할 수 없으며 다른 값이 할당된 후에는 기본값을 자동으로 복구할 수 있는 방법이 없습니다. 항상 속성의 default에 액세스하여 이 값을 가져와서 명시적으로 할당할 수 있습니다.

validator

값이 할당되었을 때 속성의 값을 검사하기 위해 호출해야 하는 함수입니다. 이 함수는 값을 유일한 인수로 사용하고 값이 유효하지 않은 경우 예외를 발생시킵니다. 지정된 검사기는 다른 검사(예: 필수 속성이 값을 가지는지 확인하는 검사)가 끝난 후에 호출됩니다. 필수가 아닌 속성에 값이 지정되지 않은 경우, 검사기는 None 인수와 함께 호출됩니다.

choices

속성에 허용되는 값의 목록입니다. 옵션이 설정된 경우 속성에 목록에 없는 값을 할당할 수 없습니다. required 및 기타 유효성 검사와 마찬가지로 모델 인스턴스는 유효하지 않은 값으로 인스턴스가 작성되지 않도록 모든 속성과 옵션을 초기화해야 합니다. choices가 None이면 유효성 검사를 통과한 모든 값이 허용됩니다.

indexed

이 속성이 개발자가 정의한 내장 색인에 포함되어야 하는지를 나타냅니다. False이면 Blob 및 Text 속성과 유사하게, Datastore에 작성된 항목이 이 속성을 기준으로 정렬하거나 필터링하는 쿼리에 의해 반환되지 않습니다.

참고: 색인이 생성된 모든 속성은 put() 및 delete() 호출에 약간의 오버헤드, CPU 비용, 지연 시간이 추가됩니다. 속성을 필터링하거나 정렬할 필요가 없는 경우 오버헤드를 피하려면 indexed=False 사용을 고려해 보세요. 이 경우 주의해야 합니다. 나중에 속성 색인을 생성하기로 결정하고 indexed=True로 되돌리면, 되돌린 이후의 쓰기에만 영향을 주기 때문입니다. 원래 indexed=False로 작성된 항목의 색인은 다시 생성할 수 없습니다.

클래스 속성

Property 클래스의 하위 클래스는 다음과 같은 클래스 속성을 정의합니다.

data_type

Python 고유 값으로 허용되는 Python 데이터 유형 또는 클래스입니다.

인스턴스 메서드

Property 클래스의 인스턴스에는 다음과 같은 메서드가 있습니다.

default_value()

속성의 기본값을 반환합니다. 이 메서드의 기본 구현에서는 생성자에 전달된 기본 인수 값을 사용합니다. 속성 클래스는 이 값을 재정의하여 DateTimeProperty의 auto-now 기능과 같은 특별한 기본값 동작을 제공합니다.

validate(value)

속성에 대한 완전한 유효성 검사 루틴입니다. 값이 유효한 경우 변경되지 않은 값 또는 필수 유형에 맞는 값을 반환합니다. 유효하지 않은 경우에는 적절한 예외가 발생합니다.

기본 구현에서는 value가 필수인 경우 None이 아닌지 확인하고(기본 Property 생성자에 대한 required 인수), 속성이 옵션으로 구성된 경우 값이 유효한 옵션 중 하나인지를 확인하고(choices 인수), 값이 커스텀 검사기(있는 경우)를 전달하는지 확인합니다(validator 인수).

유효성 검사 루틴은 속성 유형을 사용하는 모델이 기본값 또는 초기화된 값으로 인스턴스화되고 유형의 속성에 값이 할당될 때 호출됩니다. 이 루틴은 부작용이 없습니다.

empty(value)

value가 속성 유형의 빈 값으로 간주되는 경우 True를 반환합니다. 기본 구현은 대부분 유형에 충분한 not value와 동일합니다. 부울 유형을 비롯한 다른 유형에서는 이 메서드를 적절한 테스트로 대체할 수 있습니다.

get_value_for_datastore(model_instance)

지정된 모델 인스턴스 내의 이 속성에 대해 Datastore에 저장해야 하는 값을 반환합니다. 이 메서드의 기본 구현은 모델 인스턴스 내의 Python 고유의 속성 값을 반환하는 것입니다. 속성 클래스는 모델 인스턴스 대신 Datastore에 대해 다른 데이터 유형을 사용하거나, 모델 인스턴스를 저장하기 직전에 다른 데이터 변환을 수행하도록 이 값을 재정의할 수 있습니다.

make_value_from_datastore(value)

Datastore에서 지정된 값의 Python 고유 표현을 반환합니다. 이 메서드의 기본 구현은 단순히 값을 반환하는 것입니다. 속성 클래스는 모델 인스턴스 대신 Datastore에 대해 다른 데이터 유형을 재정의할 수 있습니다.

make_value_from_datastore_index_value(value)

Datastore 색인에서 지정된 값의 Python 고유 표현을 반환합니다. 이 메서드의 기본 구현은 단순히 값을 반환하는 것입니다. 속성 클래스는 모델 인스턴스 대신 Datastore에 대해 다른 데이터 유형을 재정의할 수 있습니다.