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!

感谢您阅读本文。 希望在下一篇文章中再见！