Katı Veri Sınıfları

huggingface_hub paketi, strict dataclass oluşturmak için bir yardımcı araç sağlar. Bunlar, ek doğrulama özelliklerine sahip, Python’un standart dataclass’larının geliştirilmiş versiyonlarıdır. Strict dataclass’lar, alanların hem başlatma hem de atama sırasında doğrulanmasını garanti ederek, veri bütünlüğünün kritik olduğu senaryolar için idealdir.

Genel Bakış

Strict dataclass'lar @strict dekoratörü kullanılarak oluşturulur. Düzenli dataclass'ların işlevselliğini şu şekilde genişletirler:

• Tip ipuçlarına dayalı alan türlerini doğrulama
• Ek kontroller için özel doğrulayıcıları destekleme
• Oluşturucuda isteğe bağlı olarak keyfi anahtar kelime argümanlarına izin verme
• Alanların hem başlatma sırasında hem de atama sırasında doğrulanması

Avantajlar

• Veri Bütünlüğü: Alanların her zaman geçerli veri içerdiğini sağlar
• Kullanım Kolaylığı: Python'un dataclass modülüyle kusursuz bir şekilde entegre olur
• Esneklik: Karmaşık doğrulama mantığı için özel doğrulayıcıları destekler
• Hafif: Pydantic, attrs veya benzeri kütüphaneler gibi ek bağımlılıklar gerektirmez

Kullanım

Temel Örnek

from dataclasses import dataclass
from huggingface_hub.dataclasses import strict, as_validated_field

# Custom validator to ensure a value is positive
@as_validated_field
def positive_int(value: int):
    if not value > 0:
        raise ValueError(f"Value must be positive, got {value}")

@strict
@dataclass
class Config:
    model_type: str
    hidden_size: int = positive_int(default=16)
    vocab_size: int = 32  # Default value

    # Methods named `validate_xxx` are treated as class-wise validators
    def validate_big_enough_vocab(self):
        if self.vocab_size < self.hidden_size:
            raise ValueError(f"vocab_size ({self.vocab_size}) must be greater than hidden_size ({self.hidden_size})")

Alanlar başlatma sırasında doğrulanır:

config = Config(model_type="bert", hidden_size=24)   # Valid
config = Config(model_type="bert", hidden_size=-1)   # Raises StrictDataclassFieldValidationError

Alanlar arasındaki tutarlılık, başlatma sırasında da doğrulanır (sınıf bazlı doğrulama):

# `vocab_size` too small compared to `hidden_size`
config = Config(model_type="bert", hidden_size=32, vocab_size=16)   # Raises StrictDataclassClassValidationError

Alanlar atama sırasında da doğrulanır:

config.hidden_size = 512  # Valid
config.hidden_size = -1   # Raises StrictDataclassFieldValidationError

Atama sonrasında sınıf genelindeki doğrulamayı yeniden çalıştırmak için .validate fonksiyonunu açıkça çağırmalısınız:

config.validate()  # Runs all class validators

Özel Doğrulayıcılar

validated_field kullanarak alanlara birden fazla özel doğrulayıcı ekleyebilirsiniz. Doğrulayıcı, tek bir argüman alır ve değer geçersizse bir istisna fırlatan çağrılabilir bir nesnedir.

from dataclasses import dataclass
from huggingface_hub.dataclasses import strict, validated_field

def multiple_of_64(value: int):
    if value % 64 != 0:
        raise ValueError(f"Value must be a multiple of 64, got {value}")

@strict
@dataclass
class Config:
    hidden_size: int = validated_field(validator=[positive_int, multiple_of_64])

Bu örnekte, her iki doğrulayıcı da hidden_size alanına uygulanır.

Ek Anahtar Sözcük Argümanları

Varsayılan olarak, strict dataclasses yalnızca sınıfta tanımlanmış alanları kabul eder. @strict dekoratöründe accept_kwargs=True ayarlayarak ek anahtar kelime argümanlarına izin verebilirsiniz.

from dataclasses import dataclass
from huggingface_hub.dataclasses import strict

@strict(accept_kwargs=True)
@dataclass
class ConfigWithKwargs:
    model_type: str
    vocab_size: int = 16

config = ConfigWithKwargs(model_type="bert", vocab_size=30000, extra_field="extra_value")
print(config)  # ConfigWithKwargs(model_type='bert', vocab_size=30000, *extra_field='extra_value')

Ek anahtar kelime argümanları, dataclass'ın string gösteriminde görünür ancak doğrulanmadıklarını vurgulamak için * önekiyle işaretlenir.

Type Hints ile Entegrasyon

Strict dataclasses, tip ipuçlarına uyar ve bunları otomatik olarak doğrular. Örneğin:

from typing import List
from dataclasses import dataclass
from huggingface_hub.dataclasses import strict

@strict
@dataclass
class Config:
    layers: List[int]

config = Config(layers=[64, 128])  # Valid
config = Config(layers="not_a_list")  # Raises StrictDataclassFieldValidationError

Desteklenen türler şunları içerir:

• Herhangi
• Birleşim
• İsteğe bağlı
• Literal
• Liste
• Dict
• Tuple
• Set

Ve bu türlerin herhangi bir kombinasyonu. Daha karmaşık tür doğrulaması gerekiyorsa, bunu özel bir doğrulayıcı (validator) aracılığıyla yapabilirsiniz.

Sınıf doğrulayıcıları

validate_xxx adlı yöntemler sınıf doğrulayıcıları olarak ele alınır. Bu yöntemler yalnızca self argümanını almalıdır. Sınıf doğrulayıcıları, başlatma sırasında bir kez, __post_init__ hemen ardından çalıştırılır. İhtiyaç duyduğunuz kadarını tanımlayabilirsiniz; sıralarıyla ardışık olarak yürütülürler.

Sınıf doğrulayıcılarının, başlatma sonrasında bir alan güncellendiğinde otomatik olarak yeniden çalıştırılmadığına dikkat edin. Nesneyi manuel olarak yeniden doğrulamak için obj.validate() çağrısını yapmanız gerekir.

from dataclasses import dataclass
from huggingface_hub.dataclasses import strict

@strict
@dataclass
class Config:
    foo: str
    foo_length: int
    upper_case: bool = False

    def validate_foo_length(self):
        if len(self.foo) != self.foo_length:
            raise ValueError(f"foo must be {self.foo_length} characters long, got {len(self.foo)}")

    def validate_foo_casing(self):
        if self.upper_case and self.foo.upper() != self.foo:
            raise ValueError(f"foo must be uppercase, got {self.foo}")

config = Config(foo="bar", foo_length=3) # ok

config.upper_case = True
config.validate() # Raises StrictDataclassClassValidationError

Config(foo="abcd", foo_length=3) # Raises StrictDataclassFieldValidationError
Config(foo="Bar", foo_length=3, upper_case=True) # Raises StrictDataclassFieldValidationError

.validate() yöntemi, strict dataclass'lerde ayrılmış bir isimdir. Beklenmeyen davranışları önlemek için, sınıfınız zaten böyle bir yöntem tanımlıyorsa StrictDataclassDefinitionError hatası oluşturulur.

API Referansı

@strict

@strict dekoratörü, bir dataclass'ı katı doğrulama ile güçlendirir.

>>> from dataclasses import dataclass
>>> from huggingface_hub.dataclasses import as_validated_field, strict, validated_field

>>> @as_validated_field
>>> def positive_int(value: int):
...     if not value >= 0:
...         raise ValueError(f"Value must be positive, got {value}")

>>> @strict(accept_kwargs=True)
... @dataclass
... class User:
...     name: str
...     age: int = positive_int(default=10)

# Initialize
>>> User(name="John")
User(name='John', age=10)

# Extra kwargs are accepted
>>> User(name="John", age=30, lastname="Doe")
User(name='John', age=30, *lastname='Doe')

# Invalid type => raises
>>> User(name="John", age="30")
huggingface_hub.errors.StrictDataclassFieldValidationError: Validation error for field 'age':
    TypeError: Field 'age' expected int, got str (value: '30')

# Invalid value => raises
>>> User(name="John", age=-1)
huggingface_hub.errors.StrictDataclassFieldValidationError: Validation error for field 'age':
    ValueError: Value must be positive, got -1

validate_typed_dict

Bir TypedDict sınıfında tanımlanan tiplere uygunluğu doğrulamak için kullanılan yöntem.

Bu, TypedDictler için dataclass doğrulamasının eşdeğeridir. Tip işaretli sözlükler asla örneklenmediğinden (yalnızca statik tip denetleyicileri tarafından kullanıldıklarından), doğrulama adımının manuel olarak çağrılması gerekir.

>>> from typing import Annotated, TypedDict
>>> from huggingface_hub.dataclasses import validate_typed_dict

>>> def positive_int(value: int):
...     if not value >= 0:
...         raise ValueError(f"Value must be positive, got {value}")

>>> class User(TypedDict):
...     name: str
...     age: Annotated[int, positive_int]

>>> # Valid data
>>> validate_typed_dict(User, {"name": "John", "age": 30})

>>> # Invalid type for age
>>> validate_typed_dict(User, {"name": "John", "age": "30"})
huggingface_hub.errors.StrictDataclassFieldValidationError: Validation error for field 'age':
    TypeError: Field 'age' expected int, got str (value: '30')

>>> # Invalid value for age
>>> validate_typed_dict(User, {"name": "John", "age": -1})
huggingface_hub.errors.StrictDataclassFieldValidationError: Validation error for field 'age':
    ValueError: Value must be positive, got -1

as_validated_field

Tek bir doğrulayıcıya sahip alanlarda gereksiz kodu önlemek için önerilen, validated_field oluşturmak için kullanılan dekoratör.

validated_field

Özel doğrulama ile bir dataclass alanı oluşturur.

Hatalar

Neden pydantic Kullanılmıyor? (veya attrs? veya marshmallow_dataclass?)

• Pydantic'in bir bağımlılık olarak eklenmesine ilişkin tartışma için https://github.com/huggingface/transformers/issues/36329 adresine bakın. Bu, ağır bir ekleme olacak ve hem v1 hem de v2 sürümlerini desteklemek için dikkatli bir mantık gerektirecektir.
• Pydantic'in çoğu özelliğine, özellikle otomatik dönüştürme, jsonschema, seri hale getirme, takma adlar (aliases) gibi özelliklere ihtiyacımız yok.
• Bir sözlükten sınıf örneği oluşturma yeteneğine ihtiyacımız yok.
• Verileri değiştirmek (mutate) istemiyoruz. @strict içinde “validation” (doğrulama), “bir değerin geçerli olup olmadığını kontrol etme” anlamına gelir. Pydantic’te ise “validation” (doğrulama), “bir değeri dönüştürme (cast), gerekirse değiştirmesi ve ardından geçerli olup olmadığını kontrol etme” anlamına gelir.
• Çok hızlı doğrulama yapmamıza gerek yok. @strict, performansın kritik olduğu ağır yükler için tasarlanmamıştır. Yaygın kullanım senaryoları, bir model yapılandırmasını doğrulamayı içerir (bu işlem yalnızca bir kez yapılır ve modelin çalıştırılmasına kıyasla ihmal edilebilir düzeydedir). Bu sayede kodu minimal tutabiliriz.