The topic for today is on data validation and settings management using Python type hinting. We are going to use a Python package called pydantic which enforces type hints at runtime. It provides user-friendly errors, allowing you to catch any invalid data. Based on the official documentation, Pydantic is

今天的主題是有關使用Python類型提示的數據驗證和設置管理。 我們將使用一個名為pydantic的Python程序包，該程序包在運行時會強制執行類型提示。 它提供了用戶友好的錯誤，使您可以捕獲任何無效數據。 根據官方文件，Pydantic是

“… primarily a parsing library, not a validation library. Validation is a means to an end: building a model which conforms to the types and constraints provided.

“…主要是解析庫，而不是驗證庫。 驗證是達到目的的一種手段：建立一個符合提供的類型和約束的模型。

In other words, pydantic guarantees the types and constraints of the output model, not the input data.”

換句話說，Pydantic保證了輸出模型的類型和約束，而不是輸入數據。”

There are three sections in this tutorial:

本教程分為三個部分：

1. Setup
   建立
2. Implementation
   實作
3. Conclusion
   結論

Let’s proceed to the next section and start installing the necessary modules.

讓我們繼續下一節并開始安裝必要的模塊。

1.設定 (1. Setup)

It is highly recommended to create a virtual environment before you proceed with the installation.

強烈建議您在繼續安裝之前創建一個虛擬環境。

基本安裝 (Basic installation)

Open up a terminal and run the following command to install pydantic

打開終端并運行以下命令以安裝pydantic

pip install pydantic

升級現有軟件包 (Upgrade existing package)

If you already have an existing package and would like to upgrade it, kindly run the following command:

如果您已經有一個現有軟件包并想對其進行升級，請運行以下命令：

pip install -U pydantic

水蟒 (Anaconda)

For Anaconda users, you can install it as follows:

對于Anaconda用戶，可以按以下方式安裝：

conda install pydantic -c conda-forge

可選依賴項 (Optional dependencies)

pydantic comes with the following optional dependencies based on your needs:

pydantic根據您的需求附帶以下可選依賴項：

• email-validator — Support for email validation.

  email-validator支持電子郵件驗證。

• typing-extensions — Support use of Literal prior to Python 3.8.

  typing-extensions —支持在Python 3.8之前使用Literal 。

• python-dotenv — Support for dotenv file with settings.

  python-dotenv —支持帶有設置的dotenv文件。

You can install them manually:

您可以手動安裝它們：

# install email-validator
pip install email-validator# install typing-extensions
pip install typing_extensions# install python-dotenv
pip install python-dotenv

or along with pydantic as follows:

或與pydantic一起使用，如下所示：

# install email-validator
pip install pydantic[email]# install typing-extensions
pip install pydantic[typing_extensions]# install python-dotenv
pip install pydantic[dotenv]# install all dependencies
pip install pydantic[email,typing_extensions,dotenv]

2.實施 (2. Implementation)

In this section, we are going to explore some of the useful functionalities available in pydantic.

在本節中，我們將探索pydantic可用的一些有用功能。

Defining an object in pydantic is as simple as creating a new class which inherits from theBaseModel. When you create a new object from the class, pydantic guarantees that the fields of the resultant model instance will conform to the field types defined on the model.

在pydantic定義對象就像創建一個繼承自BaseModel的新類一樣簡單。 當您從類中創建新對象時， pydantic確保生成的模型實例的字段將與模型上定義的字段類型一致。

進口 (Import)

Add the following import declaration at the top of your Python file.

在Python文件頂部添加以下導入聲明。

from datetime import datetime
from typing import List, Optional
from pydantic import BaseModel

用戶類別 (User class)

Declare a new class which inherits the BaseModel as follow:

聲明一個繼承了BaseModel的新類，如下所示：

class User(BaseModel):
    id: int
    username : str
    password : str
    confirm_password : str
    alias = 'anonymous'
    timestamp: Optional[datetime] = None
    friends: List[int] = []

pydantic uses the built-in type hinting syntax to determine the data type of each variable. Let’s explore one by one what happens behind the scenes.

pydantic使用內置的類型提示語法來確定每個變量的數據類型。 讓我們一一探討幕后發生的事情。

• id — An integer variable represents an ID. Since the default value is not provided, this field is required and must be specified during object creation. Strings, bytes, or floats will be coerced to integer if possible; otherwise, an exception will be raised.

  id —一個整數變量代表一個ID。 由于未提供默認值，因此此字段是必需的，并且必須在對象創建期間指定。 如果可能，字符串，字節或浮點數將被強制為整數； 否則，將引發異常。

• username — A string variable represents a username and is required.

  username —一個字符串變量代表一個用戶名，是必需的。

• password — A string variable represents a password and is required.

  password —字符串變量代表密碼，是必需的。

• confirm_password — A string variable represents a confirmation password and is required. It will be used for data validation later on.

  confirm_password —字符串變量代表確認密碼，是必需的。 稍后將用于數據驗證。

• alias — A string variable represents an alias. It is not required and will be set to anonymous if it is not provided during object creation.

  alias —字符串變量表示別名。 它不是必需的，如果在對象創建期間未提供，它將設置為匿名。

• timestamp — A date/time field, which is not required. Default to None. pydantic will process either a unix timestamp int or a string representing the date/time.

  timestamp —日期/時間字段，不是必需的。 默認為無。 pydantic將處理unix時間戳int或代表日期/時間的字符串。

• friends — A list of integer inputs.

  friends —整數輸入的列表。

對象實例化 (Object instantiation)

The next step is to instantiate a new object from the User class.

下一步是從User類實例化一個新對象。

data = {'id': '1234', 'username': 'wai foong', 'password': 'Password123', 'confirm_password': 'Password123', 'timestamp': '2020-08-03 10:30', 'friends': [1, '2', b'3']}user = User(**data)

You should get the following output when you print out the user variable. You can notice that id has been automatically converted to an integer, even though the input is a string. Likewise, bytes are automatically converted to integers, as shown by the friends field.

打印出user變量時，應該獲得以下輸出。 您會注意到，即使輸入是字符串， id也已自動轉換為整數。 同樣，字節會自動轉換為整數，如friends字段所示。

id=1234 username='wai foong' password='Password123' confirm_password='Password123' timestamp=datetime.datetime(2020, 8, 3, 10, 30) friends=[1, 2, 3] alias='anonymous'

BaseModel下的方法和屬性 (Methods and attributes under BaseModel)

Classes that inherit the BaseModel will have the following methods and attributes:

繼承BaseModel類將具有以下方法和屬性：

• dict() — returns a dictionary of the model’s fields and values

  dict() —返回模型字段和值的字典

• json() — returns a JSON string representation dictionary

  json() —返回一個JSON字符串表示字典

• copy() — returns a deep copy of the model

  copy() —返回模型的深層副本

• parse_obj() — a utility for loading any object into a model with error handling if the object is not a dictionary

  parse_obj() —如果對象不是字典，則用于通過錯誤處理將任何對象加載到模型中的實用程序

• parse_raw() — a utility for loading strings of numerous formats

  parse_raw() —用于加載多種格式的字符串的實用程序

• parse_field() — similar to parse_raw() but meant for files

  parse_field() -類似于parse_raw()但意味著文件

• from_orm() — loads data into a model from an arbitrary class

  from_orm() —將數據從任意類加載到模型中

• schema() — returns a dictionary representing the model as JSON schema

  schema() —返回一個將模型表示為JSON模式的字典

• schema_json() — returns a JSON string representation of schema()

  schema_json() —返回schema()的JSON字符串表示形式

• construct() — a class method for creating models without running validation

  construct() —一種無需運行驗證即可創建模型的類方法

• __fields_set__ — Set of names of fields which were set when the model instance was initialized

  __fields_set__ —初始化模型實例時設置的字段名稱集

• __fields__ — a dictionary of the model’s fields

  __fields__ —模型字段的字典

• __config__ — the configuration class for the model

  __config__ —模型的配置類

Let’s change the input for id to a string as follows:

讓我們將id的輸入更改為字符串，如下所示：

data = {'id': 'a random string', 'username': 'wai foong', 'password': 'Password123', 'confirm_password': 'Password123', 'timestamp': '2020-08-03 10:30', 'friends': [1, '2', b'3']}user = User(**data)

You should get the following error when you run the code.

運行代碼時，您應該得到以下錯誤。

value is not a valid integer (type=type_error.integer)

驗證錯誤 (ValidationError)

In order to get better details on the error, it is highly recommended to wrap it inside a try-catch block, as follows:

為了獲得有關錯誤的更好的詳細信息，強烈建議將其包裝在try-catch塊中，如下所示：

from pydantic import BaseModel, ValidationError# ... codes for User classdata = {'id': 'a random string', 'username': 'wai foong', 'password': 'Password123', 'confirm_password': 'Password123', 'timestamp': '2020-08-03 10:30', 'friends': [1, '2', b'3']}try:
    user = User(**data)
except ValidationError as e:
    print(e.json())

It will print out the following JSON, which indicates that the input for id is not a valid integer.

它將輸出以下JSON，它表示id的輸入不是有效的整數。

[
  {
    "loc": [
      "id"
    ],
    "msg": "value is not a valid integer",
    "type": "type_error.integer"
  }
]

欄位類型 (Field types)

pydantic provides support for most of the common types from the Python standard library. The full list is as follows:

pydantic為Python標準庫中的大多數常見類型提供支持。 完整列表如下：

• bool
  布爾
• int
  整型
• float
  浮動
• str
  力量
• bytes
  個字節
• list
  清單
• tuple
  元組
• dict
  字典
• set
  組
• frozenset
  冰封
• datetime.date
  datetime.date
• datetime.time
  datetime.time
• datetime.datetime
  datetime.datetime
• datetime.timedelta
  datetime.timedelta
• typing.Any
  打字
• typing.TypeVar
  Type.TypeVar
• typing.Union
  打字聯盟
• typing.Optional
  鍵入。可選
• typing.List
  打字。清單
• typing.Tuple
  鍵入。元組
• typing.Dict
  打字。字典
• typing.Set
  打字
• typing.FrozenSet
  鍵入.FrozenSet
• typing.Sequence
  打字順序
• typing.Iterable
  打字
• typing.Type
  類型
• typing.Callable
  打字
• typing.Pattern
  打字模式
• ipaddress.IPv4Address
  ipaddress.IPv4地址
• ipaddress.IPv4Interface
  ipaddress.IPv4接口
• ipaddress.IPv4Network
  ipaddress.IPv4網絡
• ipaddress.IPv6Address
  ipaddress.IPv6地址
• ipaddress.IPv6Interface
  ipaddress.IPv6接口
• ipaddress.IPv6Network
  ipaddress.IPv6網絡
• enum.Enum
  枚舉
• enum.IntEnum
  枚舉
• decimal.Decimal
  十進制。十進制
• pathlib.Path
  路徑庫
• uuid.UUID
  uuid.UUID
• ByteSize
  字節大小

約束類型 (Constrained types)

You can enforce your own restriction via the Constrained Types. Let’s have a look at the following example:

您可以通過Constrained Types實施自己的限制。 讓我們看下面的例子：

from pydantic import (
    BaseModel,
    NegativeInt,
    PositiveInt,
    conint,
    conlist,
    constr
)class Model(BaseModel):
    # minimum length of 2 and maximum length of 10
    short_str: constr(min_length=2, max_length=10)    # regex
    regex_str: constr(regex=r'^apple (pie|tart|sandwich)$')    # remove whitespace from string
    strip_str: constr(strip_whitespace=True)
    # value must be greater than 1000 and less than 1024
    big_int: conint(gt=1000, lt=1024)
    
    # value is multiple of 5
    mod_int: conint(multiple_of=5)
    
    # must be a positive integer
    pos_int: PositiveInt
    
    # must be a negative integer
    neg_int: NegativeInt
    # list of integers that contains 1 to 4 items
    short_list: conlist(int, min_items=1, max_items=4)

嚴格類型 (Strict types)

If you are looking for rigid restrictions which pass validation if and only if the validated value is of the respective type or is a subtype of that type, you can use the following strict types:

如果您正在尋找僅在經過驗證的值屬于相應類型或該類型的子類型時才通過驗證的嚴格限制，則可以使用以下嚴格類型：

• StrictStr
  嚴格的
• StrictInt
  嚴格的
• StrictFloat
  嚴格浮動
• StrictBool
  嚴格布爾

The following example illustrates the proper way to enforce StrictBool in your inherited class.

以下示例說明了在繼承的類中強制執行StrictBool的正確方法。

from pydantic import BaseModel, StrictBool,class StrictBoolModel(BaseModel):
    strict_bool: StrictBool

The string ‘False’ will raise ValidationError as it will only accept either True or False as input.

字符串'False'將引發ValidationError，因為它僅接受True或False作為輸入。

驗證器 (Validator)

Furthermore, you can create your own custom validators using the validator decorator inside your inherited class. Let’s have a look at the following example which determine if the id is of four digits and whether the confirm_password matches the password field.

此外，您可以使用繼承的類中的validator裝飾器來創建自己的自定義驗證validator 。 讓我們看下面的示例，該示例確定id是否為四位數，以及confirm_password是否與password字段匹配。

from datetime import datetime
from typing import List, Optional
from pydantic import BaseModel, ValidationError, validatorclass User(BaseModel):
    id: int
    username : str
    password : str
    confirm_password : str
    alias = 'anonymous'
    timestamp: Optional[datetime] = None
    friends: List[int] = []    @validator('id')
    def id_must_be_4_digits(cls, v):
        if len(str(v)) != 4:
            raise ValueError('must be 4 digits')
        return v    @validator('confirm_password')
    def passwords_match(cls, v, values, **kwargs):
        if 'password' in values and v != values['password']:
            raise ValueError('passwords do not match')
        return v

3.結論 (3. Conclusion)

Let’s recap what we have learned today.

讓我們回顧一下我們今天學到的東西。

We started off with a detailed explanation on Pydantic which helps to parse and validate data.

我們從有關Pydantic的詳細說明開始，該說明有助于解析和驗證數據。

Next, we created a virtual environment and installed Pydantic via pip or conda. It also includes support for three additional dependencies based on our use cases.

接下來，我們創建了一個虛擬環境，并通過pip或conda安裝了Pydantic。 它還包括根據我們的用例支持的三個附加依賴項。

Once we were done with the installation, we explored in-depth the basic functionalities provided by the package. The basic building block is to create a new class which inherits from BaseModel.

完成安裝后，我們將深入探討該軟件包提供的基本功能。 基本構建塊是創建一個繼承自BaseModel的新類。

We learned that Pydantic provides support for most of the common data types under Python standard library. We tested out both the Constrained Types and Strict Types which helps to enforce our own custom restrictions.

我們了解到Pydantic在Python標準庫下提供了對大多數常見數據類型的支持。 我們測試了Constrained Types和Strict Types ，這有助于實施我們自己的自定義限制。

Lastly, you played around with the validator decorator to allow only four digits input for id, and the confirm_password must match the password field.

最后，您與validator修飾器一起使用，僅允許輸入4位數字作為id ， confirm_password必須與password字段匹配。

Thanks for reading this piece. Hope to see you again in the next article!

感謝您閱讀本文。 希望在下一篇文章中再見！