orjson

orjson

orjson adalah perpustakaan JSON yang cepat dan benar untuk Python. Ini menjadi tolok ukur sebagai pustaka Python tercepat untuk JSON dan lebih tepat daripada pustaka json standar atau pustaka pihak ketiga lainnya. Ini membuat serial instance dataclass, datetime, numpy, dan UUID secara asli.

orjson.dumps() adalah sesuatu yang 10x lebih cepat dari json , membuat serial tipe dan subtipe umum, memiliki parameter default bagi pemanggil untuk menentukan cara membuat serial tipe arbitrer, dan memiliki sejumlah tanda yang mengontrol keluaran.

orjson.loads() kira-kira 2x lebih cepat dari json , dan sangat sesuai dengan UTF-8 dan RFC 8259 ("Format Pertukaran Data JavaScript Object Notation (JSON)").

Membaca dari dan menulis ke file, file JSON yang dibatasi baris, dan sebagainya tidak disediakan oleh perpustakaan.

orjson mendukung CPython 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, dan 3.14.

Ini mendistribusikan roda amd64/x86_64, i686/x86, aarch64/armv8, arm7, POWER/ppc64le, dan s390x untuk Linux, roda amd64 dan aarch64 untuk macOS, dan roda amd64 dan i686/x86 untuk Windows.

orjson tidak dan tidak akan mendukung PyPy, build Python tertanam untuk Android/iOS, atau subinterpreter PEP 554.

Rilis yang mengikuti pembuatan versi semantik dan membuat serial tipe objek baru tanpa tanda keikutsertaan dianggap sebagai perubahan yang dapat menyebabkan gangguan.

orjson dilisensikan di bawah lisensi Apache 2.0 dan MIT. Repositori dan pelacak masalah adalah github.com/ijl/orjson, dan patch dapat dikirimkan ke sana. Ada CHANGELOG yang tersedia di repositori.

1. Penggunaan
   1. Memasang
   2. Mulai cepat
   3. Bermigrasi
   4. Buat serial
      1. bawaan
      2. pilihan
      3. Fragmen
   5. Deserialisasi
2. Jenis
   1. kelas data
   2. tanggalwaktu
   3. enum
   4. mengambang
   5. ke dalam
   6. numpy
   7. str
   8. uuid
3. Pengujian
4. Pertunjukan
   1. Latensi
   2. Bereproduksi
5. Pertanyaan
6. Kemasan
7. Lisensi

Penggunaan

Memasang

Untuk memasang roda dari PyPI, instal paket orjson .

Dalam format requirements.in atau requirements.txt , tentukan:

orjson >= 3.10,<4

Dalam format pyproject.toml , tentukan:

 orjson = " ^3.10 "

Untuk membuat roda, lihat kemasannya.

Mulai cepat

Ini adalah contoh serialisasi, dengan opsi yang ditentukan, dan deserialisasi:

 > >> import orjson , datetime , numpy
> >> data = {
    "type" : "job" ,
    "created_at" : datetime . datetime ( 1970 , 1 , 1 ),
    "status" : "?" ,
    "payload" : numpy . array ([[ 1 , 2 ], [ 3 , 4 ]]),
}
> >> orjson . dumps ( data , option = orjson . OPT_NAIVE_UTC | orjson . OPT_SERIALIZE_NUMPY )
b'{"type":"job","created_at":"1970-01-01T00:00:00+00:00","status":" xf0 x9f x86 x97 ","payload":[[1,2],[3,4]]}'
> >> orjson . loads ( _ )
{ 'type' : 'job' , 'created_at' : '1970-01-01T00:00:00+00:00' , 'status' : '?' , 'payload' : [[ 1 , 2 ], [ 3 , 4 ]]}

Bermigrasi

orjson versi 3 membuat serial lebih banyak tipe daripada versi 2. Subkelas str , int , dict , dan list sekarang diserialkan. Ini lebih cepat dan lebih mirip dengan perpustakaan standar. Itu dapat dinonaktifkan dengan orjson.OPT_PASSTHROUGH_SUBCLASS . dataclasses.dataclass instance sekarang diserialisasikan secara default dan tidak dapat dikustomisasi dalam fungsi default kecuali option=orjson.OPT_PASSTHROUGH_DATACLASS ditentukan. Instans uuid.UUID diserialisasikan secara default. Untuk tipe apa pun yang sekarang berseri, implementasi dalam fungsi default dan opsi yang mengaktifkannya dapat dihapus tetapi tidak perlu dihapus. Tidak ada perubahan dalam deserialisasi.

Untuk bermigrasi dari perpustakaan standar, perbedaan terbesarnya adalah orjson.dumps mengembalikan bytes dan json.dumps mengembalikan str .

Pengguna dengan objek dict yang menggunakan kunci non- str harus menentukan option=orjson.OPT_NON_STR_KEYS .

sort_keys digantikan oleh option=orjson.OPT_SORT_KEYS .

indent diganti dengan option=orjson.OPT_INDENT_2 dan level indentasi lainnya tidak didukung.

ensure_ascii mungkin tidak relevan saat ini dan karakter UTF-8 tidak dapat di-escape ke ASCII.

Buat serial

 def dumps (
    __obj : Any ,
    default : Optional [ Callable [[ Any ], Any ]] = ...,
    option : Optional [ int ] = ...,
) -> bytes : ...

dumps() membuat serial objek Python ke JSON.

Ini secara asli membuat serial str , dict , list , tuple , int , float , bool , None , dataclasses.dataclass , typing.TypedDict , datetime.datetime , datetime.date , datetime.time , uuid.UUID , numpy.ndarray , dan orjson.Fragment Contoh orjson.Fragment . Ini mendukung tipe arbitrer melalui default . Ini membuat serial subkelas str , int , dict , list , dataclasses.dataclass , dan enum.Enum . Itu tidak membuat serialisasi subkelas tuple untuk menghindari serialisasi objek namedtuple sebagai array. Untuk menghindari serialisasi subkelas, tentukan opsi orjson.OPT_PASSTHROUGH_SUBCLASS .

Outputnya adalah objek bytes yang berisi UTF-8.

Kunci juru bahasa global (GIL) ditahan selama panggilan berlangsung.

Ini memunculkan JSONEncodeError pada tipe yang tidak didukung. Pesan pengecualian ini menjelaskan objek yang tidak valid dengan pesan kesalahan Type is not JSON serializable: ... . Untuk memperbaikinya, tentukan default.

Ini memunculkan JSONEncodeError pada str yang berisi UTF-8 yang tidak valid.

Ini memunculkan JSONEncodeError pada bilangan bulat yang melebihi 64 bit secara default atau, dengan OPT_STRICT_INTEGER , 53 bit.

Ini memunculkan JSONEncodeError jika dict memiliki tipe kunci selain str , kecuali OPT_NON_STR_KEYS ditentukan.

Ini memunculkan JSONEncodeError jika output default berulang ke penanganan secara default dengan kedalaman lebih dari 254 level.

Ini memunculkan JSONEncodeError pada referensi melingkar.

Ini memunculkan JSONEncodeError jika tzinfo pada objek datetime tidak didukung.

JSONEncodeError adalah subkelas dari TypeError . Ini untuk kompatibilitas dengan perpustakaan standar.

Jika kegagalan disebabkan oleh pengecualian secara default , maka JSONEncodeError merangkai pengecualian asli sebagai __cause__ .

bawaan

Untuk membuat serial subkelas atau tipe arbitrer, tentukan default sebagai callable yang mengembalikan tipe yang didukung. default mungkin berupa fungsi, lambda, atau instance kelas yang dapat dipanggil. Untuk menentukan bahwa suatu tipe tidak ditangani secara default , berikan pengecualian seperti TypeError .

 > >> import orjson , decimal
> >>
def default ( obj ):
    if isinstance ( obj , decimal . Decimal ):
        return str ( obj )
    raise TypeError

> >> orjson . dumps ( decimal . Decimal ( "0.0842389659712649442845" ))
JSONEncodeError : Type is not JSON serializable : decimal . Decimal
> >> orjson . dumps ( decimal . Decimal ( "0.0842389659712649442845" ), default = default )
b'"0.0842389659712649442845"'
> >> orjson . dumps ({ 1 , 2 }, default = default )
orjson . JSONEncodeError : Type is not JSON serializable : set

Callable default dapat mengembalikan objek yang harus ditangani secara default hingga 254 kali sebelum pengecualian dimunculkan.

Penting agar default memunculkan pengecualian jika suatu tipe tidak dapat ditangani. Python sebaliknya secara implisit mengembalikan None , yang tampak bagi pemanggil seperti nilai yang sah dan diserialkan:

 > >> import orjson , json
> >>
def default ( obj ):
    if isinstance ( obj , decimal . Decimal ):
        return str ( obj )

> >> orjson . dumps ({ "set" :{ 1 , 2 }}, default = default )
b'{"set":null}'
> >> json . dumps ({ "set" :{ 1 , 2 }}, default = default )
'{"set":null}' 

pilihan

Untuk mengubah cara data diserialkan, tentukan option . Setiap option adalah konstanta bilangan bulat di orjson . Untuk menentukan beberapa opsi, sembunyikan semuanya, misalnya, option=orjson.OPT_STRICT_INTEGER | orjson.OPT_NAIVE_UTC .

OPT_APPEND_NEWLINE

Tambahkan n ke output. Ini adalah kenyamanan dan optimasi untuk pola dumps(...) + "n" . objek bytes tidak dapat diubah dan pola ini menyalin konten aslinya.

 > >> import orjson
> >> orjson . dumps ([])
b"[]"
> >> orjson . dumps ([], option = orjson . OPT_APPEND_NEWLINE )
b"[] n " 

OPT_INDENT_2

Hasil cetak cantik dengan indentasi dua spasi. Ini setara dengan indent=2 di perpustakaan standar. Pencetakan cantik lebih lambat dan output lebih besar. orjson adalah perpustakaan tercepat dibandingkan dalam pencetakan cantik dan memiliki lebih sedikit perlambatan dalam pencetakan cantik dibandingkan perpustakaan standar. Opsi ini kompatibel dengan semua opsi lainnya.

 > >> import orjson
> >> orjson . dumps ({ "a" : "b" , "c" : { "d" : True }, "e" : [ 1 , 2 ]})
b'{"a":"b","c":{"d":true},"e":[1,2]}'
> >> orjson . dumps (
    { "a" : "b" , "c" : { "d" : True }, "e" : [ 1 , 2 ]},
    option = orjson . OPT_INDENT_2
)
b'{ n  "a": "b", n  "c": { n    "d": true n  }, n  "e": [ n    1, n    2 n  ] n }'

Jika ditampilkan maka akan muncul indentasi dan linebreak seperti ini:

{
  "a" : " b " ,
  "c" : {
    "d" : true
  },
  "e" : [
    1 ,
    2
  ]
}

Ini mengukur serialisasi perlengkapan github.json sebagai kompak (52KiB) atau cantik (64KiB):

Perpustakaan	kompak (ms)	cantik (ms)	vs.orjson
orjson	0,01	0,02	1
json	0,13	0,54	34

Tindakan ini membuat serialisasi perlengkapan citm_catalog.json, lebih merupakan kasus terburuk karena jumlah sarang dan baris baru, sebagai kompak (489KiB) atau cantik (1,1MiB):

Perpustakaan	kompak (ms)	cantik (ms)	vs.orjson
orjson	0,25	0,45	1
json	3.01	24.42	54.4

Ini dapat direproduksi menggunakan skrip pyindent .

OPT_NAIVE_UTC

Buat serial objek datetime.datetime tanpa tzinfo sebagai UTC. Ini tidak berpengaruh pada objek datetime.datetime yang memiliki tzinfo yang disetel.

 > >> import orjson , datetime
> >> orjson . dumps (
        datetime . datetime ( 1970 , 1 , 1 , 0 , 0 , 0 ),
    )
b'"1970-01-01T00:00:00"'
> >> orjson . dumps (
        datetime . datetime ( 1970 , 1 , 1 , 0 , 0 , 0 ),
        option = orjson . OPT_NAIVE_UTC ,
    )
b'"1970-01-01T00:00:00+00:00"' 

OPT_NON_STR_KEYS

Buat serial kunci dict dengan tipe selain str . Hal ini memungkinkan kunci dict menjadi salah satu dari str , int , float , bool , None , datetime.datetime , datetime.date , datetime.time , enum.Enum , dan uuid.UUID . Sebagai perbandingan, pustaka standar membuat serial str , int , float , bool atau None secara default. tolok ukur orjson lebih cepat dalam membuat serial kunci non- str dibandingkan perpustakaan lain. Opsi ini lebih lambat untuk kunci str dibandingkan default.

 > >> import orjson , datetime , uuid
> >> orjson . dumps (
        { uuid . UUID ( "7202d115-7ff3-4c81-a7c1-2a1f067b1ece" ): [ 1 , 2 , 3 ]},
        option = orjson . OPT_NON_STR_KEYS ,
    )
b'{"7202d115-7ff3-4c81-a7c1-2a1f067b1ece":[1,2,3]}'
> >> orjson . dumps (
        { datetime . datetime ( 1970 , 1 , 1 , 0 , 0 , 0 ): [ 1 , 2 , 3 ]},
        option = orjson . OPT_NON_STR_KEYS | orjson . OPT_NAIVE_UTC ,
    )
b'{"1970-01-01T00:00:00+00:00":[1,2,3]}'

Tipe ini umumnya diserialkan sebagai nilai, misalnya, datetime.datetime masih berupa string RFC 3339 dan menghormati opsi yang memengaruhinya. Pengecualiannya adalah serialisasi int tidak menghormati OPT_STRICT_INTEGER .

Opsi ini berisiko membuat kunci duplikat. Hal ini karena objek non- str mungkin bersambung ke str yang sama dengan kunci yang ada, misalnya, {"1": true, 1: false} . Kunci terakhir yang dimasukkan ke dict akan diserialkan terakhir dan deserializer JSON mungkin akan mengambil kemunculan kunci terakhir (di atas, false ). Nilai pertama akan hilang.

Opsi ini kompatibel dengan orjson.OPT_SORT_KEYS . Jika pengurutan digunakan, perhatikan bahwa pengurutan tidak stabil dan tidak dapat diprediksi untuk kunci duplikat.

 > >> import orjson , datetime
> >> orjson . dumps (
    { "other" : 1 , datetime . date ( 1970 , 1 , 5 ): 2 , datetime . date ( 1970 , 1 , 3 ): 3 },
    option = orjson . OPT_NON_STR_KEYS | orjson . OPT_SORT_KEYS
)
b'{"1970-01-03":3,"1970-01-05":2,"other":1}'

Ini mengukur serialisasi 589KiB JSON yang terdiri dari list 100 dict yang setiap dict memiliki 365 kunci int yang diurutkan secara acak yang mewakili stempel waktu zaman serta satu kunci str dan nilai untuk setiap kunci adalah bilangan bulat tunggal. Dalam "kunci str", kunci diubah menjadi str sebelum serialisasi, dan orjson masih menentukan option=orjson.OPT_NON_STR_KEYS (yang selalu agak lebih lambat).

Perpustakaan	tombol str (ms)	kunci int (ms)	kunci int diurutkan (ms)
orjson	0,5	0,93	2.08
json	2.72	3.59

json kosong karena memunculkan TypeError saat mencoba mengurutkan sebelum mengonversi semua kunci menjadi str . Ini dapat direproduksi menggunakan skrip pynonstr .

OPT_OMIT_MICROSECONDS

Jangan membuat serial bidang microsecond pada instance datetime.datetime dan datetime.time .

 > >> import orjson , datetime
> >> orjson . dumps (
        datetime . datetime ( 1970 , 1 , 1 , 0 , 0 , 0 , 1 ),
    )
b'"1970-01-01T00:00:00.000001"'
> >> orjson . dumps (
        datetime . datetime ( 1970 , 1 , 1 , 0 , 0 , 0 , 1 ),
        option = orjson . OPT_OMIT_MICROSECONDS ,
    )
b'"1970-01-01T00:00:00"' 

OPT_PASSTHROUGH_DATACLASS

Lewati instance dataclasses.dataclass ke default . Hal ini memungkinkan penyesuaian keluarannya tetapi jauh lebih lambat.

 > >> import orjson , dataclasses
> >>
@ dataclasses . dataclass
class User :
    id : str
    name : str
    password : str

def default ( obj ):
    if isinstance ( obj , User ):
        return { "id" : obj . id , "name" : obj . name }
    raise TypeError

> >> orjson . dumps ( User ( "3b1" , "asd" , "zxc" ))
b'{"id":"3b1","name":"asd","password":"zxc"}'
> >> orjson . dumps ( User ( "3b1" , "asd" , "zxc" ), option = orjson . OPT_PASSTHROUGH_DATACLASS )
TypeError : Type is not JSON serializable : User
> >> orjson . dumps (
        User ( "3b1" , "asd" , "zxc" ),
        option = orjson . OPT_PASSTHROUGH_DATACLASS ,
        default = default ,
    )
b'{"id":"3b1","name":"asd"}' 

OPT_PASSTHROUGH_DATETIME

Lewati instance datetime.datetime , datetime.date , dan datetime.time ke default . Hal ini memungkinkan serialisasi tanggal waktu ke format khusus, misalnya tanggal HTTP:

 > >> import orjson , datetime
> >>
def default ( obj ):
    if isinstance ( obj , datetime . datetime ):
        return obj . strftime ( "%a, %d %b %Y %H:%M:%S GMT" )
    raise TypeError

> >> orjson . dumps ({ "created_at" : datetime . datetime ( 1970 , 1 , 1 )})
b'{"created_at":"1970-01-01T00:00:00"}'
> >> orjson . dumps ({ "created_at" : datetime . datetime ( 1970 , 1 , 1 )}, option = orjson . OPT_PASSTHROUGH_DATETIME )
TypeError : Type is not JSON serializable : datetime . datetime
> >> orjson . dumps (
        { "created_at" : datetime . datetime ( 1970 , 1 , 1 )},
        option = orjson . OPT_PASSTHROUGH_DATETIME ,
        default = default ,
    )
b'{"created_at":"Thu, 01 Jan 1970 00:00:00 GMT"}'

Ini tidak mempengaruhi waktu tanggal di kunci dict jika menggunakan OPT_NON_STR_KEYS.

OPT_PASSTHROUGH_SUBCLASS

Lewati subkelas tipe bawaan ke default .

 > >> import orjson
> >>
class Secret ( str ):
    pass

def default ( obj ):
    if isinstance ( obj , Secret ):
        return "******"
    raise TypeError

> >> orjson . dumps ( Secret ( "zxc" ))
b'"zxc"'
> >> orjson . dumps ( Secret ( "zxc" ), option = orjson . OPT_PASSTHROUGH_SUBCLASS )
TypeError : Type is not JSON serializable : Secret
> >> orjson . dumps ( Secret ( "zxc" ), option = orjson . OPT_PASSTHROUGH_SUBCLASS , default = default )
b'"******"'

Ini tidak mempengaruhi serialisasi subkelas sebagai kunci dict jika menggunakan OPT_NON_STR_KEYS.

OPT_SERIALIZE_DATACLASS

Ini sudah tidak digunakan lagi dan tidak berpengaruh pada versi 3. Dalam versi 2, hal ini diperlukan untuk membuat serial dataclasses.dataclass instance. Untuk lebih lanjut, lihat kelas data.

OPT_SERIALIZE_NUMPY

Buat serial instance numpy.ndarray . Untuk lebih lanjut, lihat numpy.

OPT_SERIALIZE_UUID

Ini sudah tidak digunakan lagi dan tidak berpengaruh pada versi 3. Dalam versi 2, hal ini diperlukan untuk membuat serialisasi instance uuid.UUID . Selengkapnya lihat UUID.

OPT_SORT_KEYS

Buat serial kunci dict dalam urutan yang diurutkan. Standarnya adalah membuat serial dalam urutan yang tidak ditentukan. Ini setara dengan sort_keys=True di perpustakaan standar.

Ini dapat digunakan untuk memastikan urutan bersifat deterministik untuk hashing atau pengujian. Ini memiliki penalti kinerja yang besar dan tidak direkomendasikan secara umum.

 > >> import orjson
> >> orjson . dumps ({ "b" : 1 , "c" : 2 , "a" : 3 })
b'{"b":1,"c":2,"a":3}'
> >> orjson . dumps ({ "b" : 1 , "c" : 2 , "a" : 3 }, option = orjson . OPT_SORT_KEYS )
b'{"a":3,"b":1,"c":2}'

Tindakan ini membuat serialisasi perlengkapan twitter.json tidak disortir dan diurutkan:

Perpustakaan	tidak disortir (ms)	diurutkan (ms)	vs.orjson
orjson	0,11	0,3	1
json	1.36	1.93	6.4

Benchmark dapat direproduksi menggunakan skrip pysort .

Penyortiran ini tidak sesuai dengan susunan/sadar lokal:

 > >> import orjson
> >> orjson . dumps ({ "a" : 1 , "ä" : 2 , "A" : 3 }, option = orjson . OPT_SORT_KEYS )
b'{"A":3,"a":1," xc3 xa4 ":2}'

Ini adalah perilaku penyortiran yang sama seperti perpustakaan standar.

dataclass juga bersambung sebagai peta tetapi ini tidak berpengaruh pada mereka.

OPT_STRICT_INTEGER

Terapkan batas 53-bit pada bilangan bulat. Batasnya adalah 64 bit, sama dengan perpustakaan standar Python. Untuk lebih lanjut, lihat ke dalam.

OPT_UTC_Z

Buat serial zona waktu UTC pada instance datetime.datetime sebagai Z bukan +00:00 .

 > >> import orjson , datetime , zoneinfo
> >> orjson . dumps (
        datetime . datetime ( 1970 , 1 , 1 , 0 , 0 , 0 , tzinfo = zoneinfo . ZoneInfo ( "UTC" )),
    )
b'"1970-01-01T00:00:00+00:00"'
> >> orjson . dumps (
        datetime . datetime ( 1970 , 1 , 1 , 0 , 0 , 0 , tzinfo = zoneinfo . ZoneInfo ( "UTC" )),
        option = orjson . OPT_UTC_Z
    )
b'"1970-01-01T00:00:00Z"' 

Fragmen

orjson.Fragment menyertakan JSON yang sudah diserialkan dalam sebuah dokumen. Ini adalah cara yang efisien untuk memasukkan blob JSON dari cache, bidang JSONB, atau objek serial secara terpisah tanpa terlebih dahulu melakukan deserialisasi ke objek Python melalui loads() .

 > >> import orjson
> >> orjson . dumps ({ "key" : "zxc" , "data" : orjson . Fragment ( b'{"a": "b", "c": 1}' )})
b'{"key":"zxc","data":{"a": "b", "c": 1}}'

Tidak ada pemformatan ulang: orjson.OPT_INDENT_2 tidak akan memengaruhi gumpalan kompak dan gumpalan JSON yang dicetak cantik tidak akan ditulis ulang sebagai gumpalan kompak.

Inputnya harus berupa bytes atau str dan diberikan sebagai argumen posisi.

Ini memunculkan orjson.JSONEncodeError jika str diberikan dan input UTF-8 tidak valid. Jika tidak, ia tidak melakukan validasi dan ada kemungkinan untuk menulis JSON yang tidak valid. Hal ini tidak luput dari karakter. Implementasinya diuji agar tidak crash jika diberikan string yang tidak valid atau JSON yang tidak valid.

Deserialisasi

 def loads ( __obj : Union [ bytes , bytearray , memoryview , str ]) -> Any : ...

loads() membatalkan serialisasi JSON ke objek Python. Ini dideserialisasi menjadi objek dict , list , int , float , str , bool , dan None .

bytes , bytearray , memoryview , dan input str diterima. Jika masukan ada sebagai objek memoryview , bytearray , atau bytes , disarankan untuk meneruskannya secara langsung daripada membuat objek str yang tidak perlu. Artinya, orjson.loads(b"{}") bukan orjson.loads(b"{}".decode("utf-8")) . Ini memiliki penggunaan memori yang lebih rendah dan latensi yang lebih rendah.

Masukannya harus UTF-8 yang valid.

orjson menyimpan cache kunci peta selama proses berlangsung. Hal ini menyebabkan pengurangan bersih dalam penggunaan memori dengan menghindari duplikat string. Kunci harus berukuran maksimal 64 byte untuk di-cache dan 2048 entri disimpan.

Kunci juru bahasa global (GIL) ditahan selama panggilan berlangsung.

Ini memunculkan JSONDecodeError jika diberikan tipe yang tidak valid atau JSON yang tidak valid. Ini termasuk jika masukan berisi NaN , Infinity , atau -Infinity , yang diizinkan oleh pustaka standar, namun bukan JSON yang valid.

Ini memunculkan JSONDecodeError jika kombinasi array atau objek berulang sedalam 1024 level.

JSONDecodeError adalah subkelas dari json.JSONDecodeError dan ValueError . Ini untuk kompatibilitas dengan perpustakaan standar.

Jenis

kelas data

orjson membuat serial instance dataclasses.dataclass secara asli. Ini membuat serial instance 40-50x lebih cepat dari perpustakaan lain dan menghindari perlambatan parah yang terlihat di perpustakaan lain dibandingkan dengan membuat serial dict .

Hal ini didukung untuk meneruskan semua varian kelas data, termasuk kelas data yang menggunakan __slots__ , kelas data beku, kelas dengan atribut opsional atau default, dan subkelas. Ada manfaat kinerja jika tidak menggunakan __slots__ .

Perpustakaan	dikte (ms)	kelas data (ms)	vs.orjson
orjson	0,43	0,95	1
json	5.81	38.32	40

Ini mengukur pembuatan serial 555KiB JSON, orjson secara asli, dan pustaka lain menggunakan default untuk membuat serial keluaran dataclasses.asdict() . Ini dapat direproduksi menggunakan skrip pydataclass .

Kelas data diserialkan sebagai peta, dengan setiap atribut diserialkan dan sesuai urutan yang diberikan pada definisi kelas:

 > >> import dataclasses , orjson , typing

@ dataclasses . dataclass
class Member :
    id : int
    active : bool = dataclasses . field ( default = False )

@ dataclasses . dataclass
class Object :
    id : int
    name : str
    members : typing . List [ Member ]

> >> orjson . dumps ( Object ( 1 , "a" , [ Member ( 1 , True ), Member ( 2 )]))
b'{"id":1,"name":"a","members":[{"id":1,"active":true},{"id":2,"active":false}]}'

tanggalwaktu

orjson membuat serial objek datetime.datetime ke format RFC 3339, misalnya, "1970-01-01T00:00:00+00:00". Ini adalah bagian dari ISO 8601 dan kompatibel dengan isoformat() di perpustakaan standar.

 > >> import orjson , datetime , zoneinfo
> >> orjson . dumps (
    datetime . datetime ( 2018 , 12 , 1 , 2 , 3 , 4 , 9 , tzinfo = zoneinfo . ZoneInfo ( "Australia/Adelaide" ))
)
b'"2018-12-01T02:03:04.000009+10:30"'
> >> orjson . dumps (
    datetime . datetime ( 2100 , 9 , 1 , 21 , 55 , 2 ). replace ( tzinfo = zoneinfo . ZoneInfo ( "UTC" ))
)
b'"2100-09-01T21:55:02+00:00"'
> >> orjson . dumps (
    datetime . datetime ( 2100 , 9 , 1 , 21 , 55 , 2 )
)
b'"2100-09-01T21:55:02"'

datetime.datetime mendukung instance dengan tzinfo yaitu None , datetime.timezone.utc , instance zona waktu dari modul python3.9+ zoneinfo , atau instance zona waktu dari pustaka pendulum , pytz , atau dateutil / arrow pihak ketiga.

Cara tercepat adalah menggunakan zoneinfo.ZoneInfo perpustakaan standar untuk zona waktu.

objek datetime.time tidak boleh memiliki tzinfo .

 > >> import orjson , datetime
> >> orjson . dumps ( datetime . time ( 12 , 0 , 15 , 290 ))
b'"12:00:15.000290"'

objek datetime.date akan selalu bersambung.

 > >> import orjson , datetime
> >> orjson . dumps ( datetime . date ( 1900 , 1 , 2 ))
b'"1900-01-02"'

Kesalahan dengan tzinfo mengakibatkan JSONEncodeError dimunculkan.

Untuk menonaktifkan serialisasi objek datetime tentukan opsi orjson.