ciso8601

CISO8601

ciso8601 converte ISO 8601 ou RFC 3339 Data Strings Hora em objetos Python DateTime.

Como está escrito como um módulo C, é muito mais rápido que outras bibliotecas do Python. Testado com cpython 2.7, 3,4, 3,5, 3,6, 3,7, 3,8, 3,9, 3.10, 3.11, 3.12, 3.13.

(Interessado em trabalhar em projetos como este? Close está procurando grandes engenheiros para se juntar à nossa equipe)

Conteúdo

• Início rápido
• Migração para V2
• Quando não devo usar ciso8601 ?
• Manuseio de erros
• Benchmark
• Subconjunto suportado da ISO 8601
  • Formatos de data
  • Formatos de tempo
  • Informações sobre fuso horário
• RFC estrito 3339 Parsing
• Ignorando as informações do fuso horário durante a análise

Início rápido

% pip install ciso8601

 In [ 1 ]: import ciso8601

In [ 2 ]: ciso8601 . parse_datetime ( '2014-12-05T12:30:45.123456-05:30' )
Out [ 2 ]: datetime . datetime ( 2014 , 12 , 5 , 12 , 30 , 45 , 123456 , tzinfo = pytz . FixedOffset ( 330 ))

In [ 3 ]: ciso8601 . parse_datetime ( '20141205T123045' )
Out [ 3 ]: datetime . datetime ( 2014 , 12 , 5 , 12 , 30 , 45 )

Migração para V2

A versão 2.0.0 do ciso8601 alterou a implementação principal. Isso não foi totalmente compatível com versões anteriores, e deve -se tomar cuidado ao migrar, veja Changelog para o guia de migração.

Quando não devo usar ciso8601 ?

ciso8601 não é necessariamente a melhor solução para cada caso de uso (especialmente desde o Python 3.11). Veja Devo usar o CISO8601?

Manuseio de erros

A partir da v2.0.0, ciso8601 oferece fortes garantias quando se trata de analisar as cordas.

parse_datetime(dt: String): datetime é uma função que leva uma string e:

• Retorna um Python DateTime devidamente analisado, se e somente se a sequência inteira estiver em conformidade com o subconjunto suportado da ISO 8601
• Aumenta um ValueError com uma descrição da razão pela qual a string não está em conformidade com o subconjunto suportado da ISO 8601

Se as informações do fuso horário forem fornecidas, um objeto DateTime consciente será retornado. Caso contrário, um tempo ingênuo é retornado.

Benchmark

Analisando um registro de data e hora sem informações sobre funções temporais (por exemplo, 2014-01-09T21:48:00 ):

Módulo	Python 3.13	Python 3.12	Python 3.11	Python 3.10	SUDELO RELATIVA (versus CISO8601, mais recente Python)	...	Python 3.9	Python 3.8
CISO8601	64.8 NSEC	62.8 NSEC	60.1 NSEC	91.7 NSEC	N / D	...	86 NSEC	92.9 NSEC
backports.dateTime_fromisoFormat	N / D	N / D	N / D	73.6 NSEC	0,8x	...	70 NSEC	75.9 NSEC
DATETime (construído)	147 NSEC	138 NSEC	123 NSEC	N / D	2.3x	...	N / D	N / D
pêndulo	171 NSEC	181 NSEC	175 NSEC	214 NSEC	2.6x	...	179 NSEC	180 NSEC
UdateTime	542 NSEC	563 NSEC	525 NSEC	555 NSEC	8.4x	...	551 NSEC	553 NSEC
str2Date	3.29 USEC	3.53 USEC	3.52 USEC	3.85 Usoc	50,8x	...	3.72 USEC	3.9 USEC
ISO8601UTILS	N / D	N / D	N / D	N / D	56.9x	...	4.89 USEC	4.89 USEC
ISO8601	5.1 USEC	5.4 USEC	5.18 USEC	5.38 USEC	78.8x	...	5.36 USEC	5.55 USEC
isodate	5.76 USEC	5.85 USEC	5.21 USEC	5.91 USEC	89.0x	...	5.97 USEC	6.07 USEC
PYSO8601	10 USEC	11.5 USEC	7.99 USEC	10.9 USEC	155.0x	...	9.83 USEC	9.81 USEC
ANISO8601	12.1 USEC	12.5 USEC	11.1 USEC	15.1 USEC	186.9x	...	15.4 USEC	15.6 USEC
zulu	12.3 USEC	13.6 USEC	12.6 USEC	14.2 USEC	189.4x	...	14.5 USEC	14.2 USEC
Maya	35.9 USEC	N / D	40.6 Usec	46.7 USEC	554.3x	...	45.4 USEC	46.3 USEC
Python-Dateutil	36.2 USEC	36.9 USEC	36.1 USEC	44 USEC	558.5x	...	46.4 USEC	45.2 USEC
seta	42.9 USEC	43.8 USEC	41.2 USEC	48.8 USEC	662.7x	...	50.7 USEC	50.1 USEC
Metomi-isodateTime	828 USEC	822 USEC	791 USEC	1,09 ms	12781.0x	...	1.1 ms	1,11 ms
momento	1,28 ms	1,32 ms	1,29 ms	1,36 ms	19696.9x	...	1,37 ms	1,34 ms

O CISO8601 leva 64,8 NSEC, que é 2,3x mais rápido que o DateTime (embutido) , o próximo analisador mais rápido do Python 3.13 nesta comparação.

Analisando um registro de data e hora com as informações do fuso horário (por exemplo, 2014-01-09T21:48:00-05:30 ):

Módulo	Python 3.13	Python 3.12	Python 3.11	Python 3.10	SUDELO RELATIVA (versus CISO8601, mais recente Python)	...	Python 3.9	Python 3.8
CISO8601	73.9 NSEC	71 NSEC	65.6 NSEC	97.5 NSEC	N / D	...	92.9 NSEC	96.6 NSEC
backports.dateTime_fromisoFormat	N / D	N / D	N / D	99.2 NSEC	1.0x	...	93 NSEC	99.4 NSEC
DATETime (construído)	205 NSEC	198 NSEC	178 NSEC	N / D	2.8x	...	N / D	N / D
pêndulo	251 NSEC	259 NSEC	251 NSEC	262 NSEC	3.4x	...	264 NSEC	264 NSEC
UdateTime	684 NSEC	700 nsec	646 NSEC	684 NSEC	9.3x	...	688 NSEC	676 NSEC
str2Date	5.95 USEC	4.34 USEC	4.11 USEC	4.58 USEC	80,5x	...	4.6 USEC	4.82 USEC
ISO8601	7.68 USEC	8.56 USEC	7.62 USEC	7.99 USEC	103.9x	...	7.83 USEC	8.16 USEC
isodate	7.77 USEC	8.53 USEC	7.54 USEC	7.88 USEC	105.0x	...	8.12 USEC	8.4 USEC
ISO8601UTILS	N / D	N / D	N / D	N / D	152.2x	...	14.1 USEC	14.6 USEC
zulu	17.8 USEC	16.9 USEC	15.7 USEC	17.3 Usec	241.3x	...	17.3 Usec	17.6 Usec
ANISO8601	18 usos	18.7 USEC	16.4 USEC	21.5 USEC	243.1x	...	22.5 USEC	22.8 USEC
PYSO8601	18.3 Usec	16.6 USEC	14.3 Usec	15.8 USEC	247.5x	...	16.2 USEC	16.4 USEC
Maya	46.2 USEC	N / D	41 USEC	47.5 USEC	625.0x	...	45.2 USEC	47 USEC
Python-Dateutil	47.1 USEC	48.2 USEC	47.1 USEC	57.3 USEC	636.5x	...	60.4 USEC	58.9 Usec
seta	57.7 USEC	53.8 USEC	50.8 USEC	60.2 USEC	780.2x	...	59.4 USEC	60.1 USEC
Metomi-isodateTime	876 USEC	823 USEC	795 USEC	1,09 ms	11846.4x	...	1,09 ms	1,13 ms
momento					2070678.8x	...

O CISO8601 leva 73,9 NSEC, que é 2,8x mais rápido que o DateTime (construído) , o próximo analisador mais rápido do Python 3.13 nesta comparação.

Testado no Linux 6.11.5-orbstack-00280-g96d99c92a42b usando os seguintes módulos:

 aniso8601 == 9.0 . 1
arrow == 1.3 . 0
backports . datetime_fromisoformat == 2.0 . 2
ciso8601 == 2.3 . 1
iso8601 == 2.1 . 0
iso8601utils == 0.1 . 2
isodate == 0.7 . 2
maya == 0.6 . 1
metomi - isodatetime == 1 ! 3.1 . 0
moment == 0.12 . 1
pendulum == 3.0 . 0
PySO8601 == 0.2 . 0
python - dateutil == 2.9 . 0. post0
str2date == 0.905
udatetime == 0.0 . 17
zulu == 2.0 . 1

Para detalhes completos de benchmarking (ou para executar a referência), consulte Benchmarking/Readme.rst

Subconjunto suportado da ISO 8601

ciso8601 suporta apenas um subconjunto da ISO 8601, mas suporta um superconjunto do que é suportado pelo próprio Python ( datetime.fromisoformat ) e suporta a totalidade da especificação RFC 3339.

Formatos de data

Os seguintes formatos de data são suportados:

Formatar	Exemplo	Suportado
YYYY-MM-DD (estendida)	2018-04-29	✅
YYYY-MM	2018-04	✅
YYYYMMDD (BASIC)	20180429	✅
YYYY-Www-D	2009-W01-1	✅
YYYY-Www (data da semana)	2009-W01	✅
YYYYWwwD (data da semana)	2009W011	✅
YYYYWww (data da semana)	2009W01	✅
YYYY-DDD (data ordinal)	1981-095	✅
YYYYDDD (data ordinal)	1981095	✅

Os formatos incomuns de data ISO 8601 não são suportados:

Formatar	Exemplo	Suportado
--MM-DD (ano omitido)	--04-29
--MMDD (ano omitido)	--0429
±YYYYY-MM (> 4 dígitos ano)	+10000-04
+YYYY-MM (Leading +)	+2018-04
-YYYY-MM (negativo -)	-2018-04

Formatos de tempo

Os horários são opcionais e são separados da data pela letra T .

Consistente com o RFC 3339, ciso8601 também permite que um caractere espacial ou um caso mais baixo t , seja usado em vez de um T .

Os formatos de tempo seguinte são suportados:

Formatar	Exemplo	Suportado
hh	11	✅
hhmm	1130	✅
hh:mm	11:30	✅
hhmmss	113059	✅
hh:mm:ss	11:30:59	✅
hhmmss.ssssss	113059.123456	✅
hh:mm:ss.ssssss	11:30:59.123456	✅
hhmmss,ssssss	113059,123456	✅
hh:mm:ss,ssssss	11:30:59,123456	✅
Meia -noite (caso especial)	24:00:00	✅
hh.hhh (horário fracionário)	11.5
hh:mm.mmm (minutos fracionários)	11:30.5

NOTA: Os objetos Python DateTime têm apenas precisão de microssegundos (6 dígitos). Qualquer precisão adicional será truncada.

Informações sobre fuso horário

As informações do fuso horário podem ser fornecidas em um dos seguintes formatos:

Formatar	Exemplo	Suportado
Z	Z	✅
z	z	✅
±hh	+11	✅
±hhmm	+1130	✅
±hh:mm	+11:30	✅

Enquanto a especificação ISO 8601 permite o uso de sinal menos (U+2212) no separador do fuso horário, ciso8601 suporta apenas o uso do caractere hífen-minus (U+002D).

Consistente com o RFC 3339, ciso8601 também permite que um z de baixo caso seja usado em vez de Z .

RFC estrito 3339 Parsing

ciso8601 passa ISO 8601 DATETETES, que pode ser considerado um superconjunto do RFC 3339 (aproximadamente). Nos casos em que você pode querer a análise estrita do RFC 3339, ciso8601 oferece um método parse_rfc3339 , que se comporta de maneira semelhante ao parse_datetime :

parse_rfc3339(dt: String): datetime é uma função que leva uma string e:

• Retorna um Python DateTime devidamente analisado, se e somente se a sequência inteira estiver em conformidade com a RFC 3339.
• Aumenta um ValueError com uma descrição da razão pela qual a string não está em conformidade com a RFC 3339.

Ignorando as informações do fuso horário durante a análise

Leva mais tempo para analisar os registros de data e hora com as informações do fuso horário, especialmente se não estiverem no UTC. No entanto, há momentos em que você não se importa com as informações do fuso horário e deseja produzir dados ingênuos. Por exemplo, se você tiver certeza de que seu programa analisará apenas os registros de data e hora de um único fuso horário, convém tirar as informações do fuso horário e produzir apenas dados ingênuos.

Nesses casos limitados, há uma segunda função fornecida. parse_datetime_as_naive ignorará as informações do fuso horário que encontrar e, como resultado, é mais rápido para o registro de data e hora contendo informações sobre fuso horário.

 In [ 1 ]: import ciso8601

In [ 2 ]: ciso8601 . parse_datetime_as_naive ( '2014-12-05T12:30:45.123456-05:30' )
Out [ 2 ]: datetime . datetime ( 2014 , 12 , 5 , 12 , 30 , 45 , 123456 )

Nota: parse_datetime_as_naive é útil apenas no caso em que seus registros de data e hora têm informações sobre funções de tempo, mas você deseja ignorá -las. Isso é um tanto incomum. Se seus registros de data e hora não tiverem informações sobre funções de tempo (ou seja, ingênuas), basta usar parse_datetime . É tão rápido.