phantom types

tipe hantu

Jenis hantu untuk python akan membantu Anda membuat negara ilegal tidak dapat diperbaiki dan menghindari penguraian senapan dengan memungkinkan Anda berlatih "parse, jangan validasi".

Periksa dokumentasi lengkap tentang baca dokumen →

Instalasi

$  python3 -m pip install phantom-types

Tambahan

Ada beberapa tambahan yang tersedia yang dapat digunakan untuk mengaktifkan fitur atau menginstal versi yang kompatibel dari perpustakaan pihak ketiga.

Nama tambahan	Fitur
[dateutil]	Menginstal Python-Dateutil. Diperlukan untuk string parsing dengan TZAware dan TZNaive .
[phonenumbers]	Menginstal fonenumbers. Diperlukan untuk menggunakan phantom.ext.phonenumbers .
[pydantic]	Instal Pydantic.
[hypothesis]	Memasang hipotesis.
[all]	Menginstal semua hal di atas.

$  python3 -m pip install phantom-types[all]

Contoh

Dengan memperkenalkan tipe hantu kita dapat menentukan prasyarat untuk argumen fungsi.

 from phantom import Phantom
from phantom . predicates . collection import contained


class Name ( str , Phantom , predicate = contained ({ "Jane" , "Joe" })): ...


def greet ( name : Name ):
    print ( f"Hello { name } !" )

Sekarang ini akan menjadi panggilan yang valid.

 greet ( Name . parse ( "Jane" ))

... dan begitu juga ini.

 joe = "Joe"
assert isinstance ( joe , Name )
greet ( joe )

Tapi ini akan menghasilkan kesalahan pemeriksaan jenis statis.

 greet ( "bird" )

Untuk lebih jelasnya, alasan contoh pertama berlalu bukan karena tipe pemeriksa entah bagaimana secara ajaib tahu tentang predikat kami, tetapi karena kami memberikan bukti tipe checker melalui assert . Semua tipe pemeriksa yang peduli adalah bahwa runtime tidak dapat terus mengeksekusi melewati pernyataan, kecuali jika variabelnya adalah Name . Jika kita memindahkan panggilan seperti pada contoh di bawah ini, tipe checker akan memberikan kesalahan untuk panggilan greet() .

 joe = "Joe"
greet ( joe )
assert isinstance ( joe , Name )

Pemeriksaan Jenis Runtime

Dengan menggabungkan tipe hantu dengan pemeriksa tipe runtime seperti BearType atau Typeguard, kami dapat mencapai tingkat keamanan yang sama dengan yang Anda dapatkan dari menggunakan kontrak.

 import datetime
from beartype import beartype
from phantom . datetime import TZAware


@ beartype
def soon ( dt : TZAware ) -> TZAware :
    return dt + datetime . timedelta ( seconds = 10 )

Fungsi soon sekarang akan memvalidasi bahwa baik argumen dan nilai pengembaliannya adalah waktu yang sadar, misalnya kondisi sebelum dan sesudah.

Dukungan Pydantic

Jenis hantu siap digunakan dengan Pydantic dan memiliki dukungan terintegrasi di luar kotak. Subclass of Phantom bekerja dengan validasi Pydantic dan generasi skema.

 class Name ( str , Phantom , predicate = contained ({ "Jane" , "Joe" })):
    @ classmethod
    def __schema__ ( cls ) -> Schema :
        return super (). __schema__ () | {
            "description" : "Either Jane or Joe" ,
            "format" : "custom-name" ,
        }


class Person ( BaseModel ):
    name : Name
    created : TZAware


print ( json . dumps ( Person . schema (), indent = 2 ))

Kode di atas mengeluarkan jsonschema berikut.

{
  "title" : " Person " ,
  "type" : " object " ,
  "properties" : {
    "name" : {
      "title" : " Name " ,
      "description" : " Either Jane or Joe " ,
      "format" : " custom-name " ,
      "type" : " string "
    },
    "created" : {
      "title" : " TZAware " ,
      "description" : " A date-time with timezone data. " ,
      "type" : " string " ,
      "format" : " date-time "
    }
  },
  "required" : [ " name " , " created " ]
}

Perkembangan

Instal Persyaratan Pengembangan, lebih disukai di VirtualEnv:

$ python3 -m pip install .[all,test,type-check]

Jalankan tes:

$ pytest
# or
$ make test

Jalankan tipe checker:

$ mypy

Linters dan formatters diatur dengan Goose, setelah menginstalnya, Anda dapat menjalankannya sebagai:

 # run all checks
$ goose run --select=all
# or just a single hook
$ goose run mypy --select=all

Selain pemeriksaan tipe statis, proyek ini diatur dengan Pytest-Mypy-Plugins untuk menguji bahwa tipe Mypy yang terpapar berfungsi seperti yang diharapkan, cek ini akan berjalan bersama dengan sisa suite tes, tetapi Anda dapat memilihnya dengan perintah berikut.

$ make test-typing