"zipfile" --- Trabalha com arquivos ZIP
***************************************

**Código-fonte:** Lib/zipfile/

======================================================================

O formato de arquivo ZIP é um padrão de compactação e arquivamento.
Este módulo fornece ferramentas para criar, ler, escrever, adicionar,
e listar um arquivo ZIP. Qualquer uso avançado deste módulo vai exigir
um entendimento do formato, como definido nas Notas de Aplicação do
PKZIP.

Esse módulo atualmente não suporta arquivos ZIP multi-disco. Ele pode
manipular arquivos ZIP que usam as extensões ZIP64 (ou seja arquivos
ZIP com tamanho maior do que 4 Gb). Ele suporta descriptografia de
arquivos criptografados dentro do ZIP, mas atualmente não pode criar
um arquivo criptografado. A descriptografia é extremamente lenta pois
é implementada em Python nativo ao invés de C.

Este módulo define os seguintes itens:

exception zipfile.BadZipFile

   Este erro é levantado para arquivos ZIP corrompidos.

   Adicionado na versão 3.2.

exception zipfile.BadZipfile

   Alias para "BadZipFile", para compatibilidade com versões mais
   antigas de Python.

   Descontinuado desde a versão 3.2.

exception zipfile.LargeZipFile

   Este erro é levantado quando um arquivo ZIP precisa da
   funcionalidade ZIP64 que não está habilitada.

class zipfile.ZipFile

   A classe para ler e escrever arquivos ZIP. Veja a seção Objetos
   ZipFile para detalhes do construtor.

class zipfile.Path

   Classe que implementa um subconjunto da interface fornecida por
   "pathlib.Path", incluindo a interface completa
   "importlib.resources.abc.Traversable".

   Adicionado na versão 3.8.

class zipfile.PyZipFile

   Classe para criar arquivos ZIP contendo bibliotecas Python.

class zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))

   Classe usada para representar informação sobre um membro de um
   archive. Instâncias desta classe são retornadas pelos métodos
   "getinfo()" e "infolist()" de objetos da classe "ZipFile". A
   maioria dos usuários do módulo "zipfile" não vai precisar criar,
   mas apenas usar objetos criados pelo módulo. *filename* deveria ser
   o caminho completo do membro do arquivo, e *date_time* deveria ser
   uma tupla contendo seis campos que descrevem o momento da última
   modificação no arquivo; os campos são descritos na seção Objetos
   ZipInfo.

   Alterado na versão 3.13: Um atributo público "compress_level" foi
   adicionado para expor o "_compresslevel" anteriormente protegido. O
   nome protegido mais antigo continua a funcionar como uma
   propriedade para compatibilidade com versões anteriores.

   _for_archive(archive)

      Resolve os atributos date_time, compression e external para
      padrões adequados, conforme usado por "ZipFile.writestr()".

      Retorna self para encadeamento.

      Adicionado na versão 3.14.

zipfile.is_zipfile(filename)

   Retorna "True" se *filename* é um arquivo ZIP válido baseado no seu
   "magic number", caso contrário retorna "False". *filename* pode ser
   um arquivo ou um objeto arquivo ou similar também.

   Alterado na versão 3.1: Suporte para arquivo e objetos arquivo ou
   similares.

zipfile.ZIP_STORED

   Código numérico para um membro de um arquivo descompactado

zipfile.ZIP_DEFLATED

   Código numérico para o método de compactação usual. Requer o módulo
   "zlib" .

zipfile.ZIP_BZIP2

   Código numérico para o método de compactação BZIP2. Requer o módulo
   "bz2".

   Adicionado na versão 3.3.

zipfile.ZIP_LZMA

   Código numérico para o método de compactação LZMA. Requer o módulo
   "lzma".

   Adicionado na versão 3.3.

zipfile.ZIP_ZSTANDARD

   Código numérico para a compactação com Zstandard. Requer o módulo
   "compression.zstd".

   Nota:

     No APPNOTE 6.3.7, o ID do método "20" foi atribuído à compactação
     Zstandard. No APPNOTE 6.3.8, esse ID foi alterado para o ID do
     método "93" para evitar conflitos, com o ID do método "20" sendo
     descontinuado. Para compatibilidade, o módulo "zipfile" lê ambos
     os IDs de método, mas gravará apenas dados com o ID do método
     "93".

   Adicionado na versão 3.14.

Nota:

  A especificação do formato ZIP incluiu suporte para compactação
  bzip2 desde 2001, para compactação LZMA desde 2006 e para
  compactação Zstandard desde 2020. Porém, algumas ferramentas
  (incluindo versões mais antigas de Python) não suportam esses
  métodos de compactação, e podem recusar processar o arquivo ZIP como
  um todo, ou falhar em extrair arquivos individuais.

Ver também:

  Notas da Aplicação do PKZIP
     Documentação do formato de arquivo ZIP feita por Phil Katz,
     criador do formato e dos algoritmos usados.

  Site do Info-ZIP
     Informações sobre o programas de arquivamento e desenvolvimento
     de bibliotecas do projeto Info-ZIP.


Objetos ZipFile
===============

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None)

   Abre um arquivo ZIP, onde *file* pode ser um caminho para um
   arquivo (uma string), um objeto arquivo ou similar, ou um *objeto
   caminho ou similar*.

   O parâmetro *mode* deve ser "'r'" para ler um arquivo existente,
   "'w'" para truncar e gravar um novo arquivo, "'a'" para adicionar a
   um arquivo existente, ou "'x'" exclusivamente para criar e gravar
   um novo arquivo. Se o *mode* é "'x'" e *file* se refere a um
   arquivo existente, um "FileExistsError" vai ser levantado. Se o
   *mode* é "'a'" e *file* se refere a um arquivo ZIP existente, então
   arquivos adicionais são adicionados ao mesmo. Se *file* não se
   refere a um arquivo ZIP, então um novo arquivo ZIP é adicionado ao
   arquivo. Isso diz respeito a adicionar um arquivo ZIP a um outro
   arquivo (como por exemplo "python.exe"). Se o *mode* é "'a'" e o
   arquivo não existe, ele será criado. Se o *mode* é "'r'" ou "'a'",
   o arquivo deve ser percorrível.

   *compression* é o método de compactação ZIP para usar ao escrever o
   arquivo, e deve ser "ZIP_STORED", "ZIP_DEFLATED", "ZIP_BZIP2",
   "ZIP_LZMA" e "ZIP_ZSTANDARD"; valores desconhecidos devem causar
   "NotImplementedError" ser levantada. Se "ZIP_DEFLATED",
   "ZIP_BZIP2", "ZIP_LZMA" ou "ZIP_ZSTANDARD" for especificado mas o
   módulo correspondente ("zlib", "bz2", "lzma" e "compression.zstd")
   não estiver disponível, é levantada uma exceção "RuntimeError". O
   valor padrão é "ZIP_STORED".

   Se *allowZip64* é "True" (valor padrão), então zipfile vai criar
   arquivos ZIP que usem as extensões ZIP64 quando o arquivo ZIP é
   maior do que 4 GiB. Se é "false", "zipfile" levanta uma exceção
   quando o arquivo ZIP precisaria das extensões ZIP64.

   O parâmetro *compresslevel* controla o nível de compactação para
   usar ao gravar no arquivo ZIP. Quando usado "ZIP_STORED" ou
   "ZIP_LZMA" não tem efeito. Quando usado "ZIP_DEFLATED" inteiros de
   "0" a "9" são aceitos (veja "zlib" para mais informações). Quando
   usado "ZIP_BZIP2" inteiros de "1" a "9" são aceitos (veja "bz2"
   para mais informações). Ao usar "ZIP_ZSTANDARD", os inteiros
   "-131072" a "22" são comumente aceitos (consulte
   "CompressionParameter.compression_level" para obter mais
   informações sobre como recuperar valores válidos e seus
   significados).

   O argumento *strict_timestamps*, quando definido como "False",
   permite compactar arquivos anteriores a 1980-01-01 com o custo de
   definir o carimbo de data/hora para 1980-01-01. Comportamento
   semelhante ocorre com arquivos mais recentes que 2107-12-31, o
   carimbo de data/hora também é definido como o limite.

   Quando o modo é "'r'", *metadata_encoding* pode ser definido como o
   nome de um codec, que será usado para decodificar metadados, como
   os nomes dos membros e comentários ZIP.

   Se o arquivo é criado com modo "'w'", "'x'" ou "'a'" e então
   "closed()" sem adicionar nada ao arquivo, a estrutura própria para
   um arquivo vazio será escrita no arquivo.

   ZipFile também é um gerenciador de contexto e portanto suporta a
   instrução "with". Neste exemplo, *myzip* é fechado ao final da
   execução da instrução "with" -- mesmo que ocorra uma exceção:

      with ZipFile('spam.zip', 'w') as myzip:
          myzip.write('eggs.txt')

   Nota:

     *metadata_encoding* é uma configuração em toda a instância para o
     ZipFile. Atualmente, não é possível definir isso em uma base por
     membro.Este atributo é uma solução alternativa para
     implementações legadas que produzem arquivos com nomes na
     codificação da localidade atual ou página de código
     (principalmente no Windows). De acordo com o padrão .ZIP, a
     codificação dos metadados pode ser especificada como página de
     código IBM (padrão) ou UTF-8 por meio de um sinalizador no
     cabeçalho do arquivo. Esse sinalizador tem precedência sobre
     *metadata_encoding*, que é uma extensão específica do Python.

   Alterado na versão 3.2: Adicionado o uso de "ZipFile" como um
   gerenciador de contexto.

   Alterado na versão 3.3: Adicionado suporte para compactação "bzip2"
   e "lzma".

   Alterado na versão 3.4: Extensões ZIP64 são habilitadas por padrão.

   Alterado na versão 3.5: Adicionado suporte para escrever em streams
   não percorríveis. Adicionado suporte ao modo "'x'".

   Alterado na versão 3.6: Anteriormente, um simples "RuntimeError"
   era levantado para valores de compactação desconhecidos.

   Alterado na versão 3.6.2: O parâmetro *file* aceita um *objeto
   caminho ou similar*.

   Alterado na versão 3.7: Adicionado o parâmetro *compresslevel*.

   Alterado na versão 3.8: O parâmetro somente-nomeado
   *strict_timestamps*.

   Alterado na versão 3.11: Adicionado suporte para especificar a
   codificação do nome do membro ao ler metadados no diretório e
   cabeçalhos de arquivo do arquivo zip.

ZipFile.close()

   Fecha o arquivo. Você deve chamar "close()" antes de sair do seu
   programa ou registros essenciais não serão gravados.

ZipFile.getinfo(name)

   Retorna um objeto "ZipInfo" com informações sobre o *name* do
   membro do arquivo. Chamar "getinfo()" para um nome não encontrado
   no arquivo levanta um "KeyError".

ZipFile.infolist()

   Retorna uma lista contendo um objeto "ZipInfo" para cada membro do
   arquivo. Os objetos estão na mesma ordem das entradas no arquivo
   ZIP em disco se um arquivo existente foi aberto.

ZipFile.namelist()

   Retorna uma lista de membros do arquivo por nome.

ZipFile.open(name, mode='r', pwd=None, *, force_zip64=False)

   Acessa um membro do arquivo como um objeto binário arquivo ou
   similar. *name* pode ser o nome de um arquivo membro ou um objeto
   "ZipInfo". O parâmetro *mode*, se informado, deve ser "'r'" (valor
   padrão) or "'w'". *pwd* é a senha usada para descriptografar
   arquivos ZIP criptografados como um objeto "bytes".

   "open()" também é um gerenciador de contexto e, portanto, suporta a
   instrução "with":

      with ZipFile('spam.zip') as myzip:
          with myzip.open('eggs.txt') as myfile:
              print(myfile.read())

   Com *mode* "'r'" o objeto arquivo ou similar ("ZipExtFile") é
   somente leitura e fornece os seguintes métodos: "read()",
   "readline()", "readlines()", "seek()", "tell()", "__iter__()",
   "__next__()". Esses objetos podem operar independentemente do
   ZipFile.

   Com "mode='w'", é retornado um manipulador de arquivo, que suporta
   o método "write()". Quando um manipulador de arquivo modificável é
   aberto, tentativas de ler ou gravar outros arquivos no arquivo ZIP
   levanta um "ValueError".

   Em ambos os casos o objeto arquivo ou similar também possui
   atributos "name", que é equivalente ao nome de um arquivo dentro do
   arquivo, e "mode", que é "'rb'" ou "'wb'" dependendo do modo de
   entrada.

   Ao gravar um arquivo, se o tamanho do arquivo não é conhecido mas
   pode exceder 2 GiB, passe "force_zip64=True" para assegurar que o
   formato do header é capaz de suportar arquivos grandes. Se o
   tamanho do arquivo é conhecido, construa um objeto "ZipInfo" com
   "file_size" informado, então use-o como parâmetro *name*.

   Nota:

     Os métodos "open()", "read()" e "extract()" podem receber um nome
     de arquivo ou um objeto "ZipInfo". Você vai gostar disso quando
     tentar ler um arquivo ZIP que contém membros com nomes
     duplicados.

   Alterado na versão 3.6: Removido suporte ao "mode='U'". Uso de
   "io.TextIOWrapper" para leitura de arquivos texto compactados em
   modo de *novas linhas universais*.

   Alterado na versão 3.6: "ZipFile.open()" agora pode ser usado para
   escrever arquivos no aquivo compactado com a opção "mode='w'".

   Alterado na versão 3.6: Chama "open()" em um ZipFile fechado
   levanta um "ValueError". Anteriormente, um "RuntimeError" era
   levantado.

   Alterado na versão 3.13: Adicionados atributos "name" e "mode" para
   o objeto arquivo ou similar gravável. O valor do atributo "mode"
   para o objeto arquivo ou similar legível foi alterado de "'r'" para
   "'rb'".

ZipFile.extract(member, path=None, pwd=None)

   Extrai um membro do arquivo para o diretório atual; *member* deve
   ser o nome completo ou um objeto "ZipInfo". A informação do arquivo
   é extraída com maior precisão possível. *path* especifica um outro
   diretório em que deve ser gravado. *member* pode ser um nome de
   arquivo ou um objeto "ZipInfo". *pwd* é a senha usada para
   criptografar arquivos como um objeto "bytes".

   Retorna o caminho normalizado criado (um diretório ou novo
   arquivo).

   Nota:

     Se um nome de arquivo membro é um caminho absoluto, o drive/UNC e
     (contra)barras no início serão removidos, por exemplo:
     "///foo/bar" se torna "foo/bar" no Unix, e "C:\foo\bar" vira
     "foo\bar" no Windows. E todos os componentes "".."" no nome de um
     arquivo membro serão removidos, por exemplo:
     "../../foo../../ba..r" vira "foo../ba..r". No Windows caracteres
     ilegais (":", "<", ">", "|", """, "?", and "*") são substituídos
     por underscore ("_").

   Alterado na versão 3.6: Chama "extract()" em um ZipFile fechado
   levanto um "ValueError". Anteriormente, um "RuntimeError" era
   levantado.

   Alterado na versão 3.6.2: O parâmetro *path* aceita um *objeto
   caminho ou similar*.

ZipFile.extractall(path=None, members=None, pwd=None)

   Extrai todos os membros de um arquivo para o diretório atual.
   *path* especifica um diretório diferente para gravar os arquivos
   extraídos. *members* é opcional e deve ser um sub-conjunto da lista
   retornada por "namelist()". *pwd* é uma senha usada para
   criptografar arquivos como um objeto "bytes".

   Aviso:

     Nunca extrai arquivos de fontes não confiáveis sem inspeção
     prévia. É possível que os arquivos sejam criados fora do *path*,
     por exemplo membros que tem nomes absolutos de arquivos começando
     com ""/"" ou nomes com dois pontos "".."". Este módulo tenta
     prevenir isto. Veja nota em "extract()".

   Alterado na versão 3.6: Chama "extractall()" em um ZipFile fechado
   levanta um "ValueError". Anteriormente, um "RuntimeError" era
   levantado.

   Alterado na versão 3.6.2: O parâmetro *path* aceita um *objeto
   caminho ou similar*.

ZipFile.printdir()

   Imprime a tabela de conteúdos de um arquivo para "sys.stdout".

ZipFile.setpassword(pwd)

   Define *pwd* (um objeto "bytes") como senha padrão para extrair
   arquivos criptografados.

ZipFile.read(name, pwd=None)

   Retorna os bytes do arquivo *name* no arquivo compactado. *name* é
   o nome do arquivo no arquivo compactado, ou um objeto "ZipInfo". O
   arquivo compactado deve estar aberto para leitura ou acréscimo.
   *pwd* é a senha usada para arquivos criptografados como um objeto
   "bytes" e, se especificada, substitui a senha padrão configurada
   com "setpassword()". Chamar "read()" em um ZipFile que use um
   método de compactação diferente de "ZIP_STORED", "ZIP_DEFLATED",
   "ZIP_BZIP2", "ZIP_LZMA" e "ZIP_ZSTANDARD" levanta um
   "NotImplementedError". Um erro também é levantado se o módulo de
   compactação correspondente não está disponível.

   Alterado na versão 3.6: Chama "read()" em um ZipFile fechado
   levanta um "ValueError". Anteriormente, um "RuntimeError" era
   levantado.

ZipFile.testzip()

   Lê todos os arquivos no arquivo compactado e verifica seus CRC's e
   cabeçalhos de arquivo. Retorna o nome do primeiro arquivo
   corrompido, or então retorna "None".

   Alterado na versão 3.6: Chama "testzip()" em um ZipFile fechado
   levanta um "ValueError". Anteriormente, um "RuntimeError" era
   levantado.

ZipFile.write(filename, arcname=None, compress_type=None, compresslevel=None)

   Grava o arquivo chamado *filename* no arquivo compactado, dando ao
   arquivo compactado o nome *arcname* (por padrão, este é o mesmo de
   *filename*, mas sem a letra do drive e com separadores removidos do
   início do nome). Se informado, *compress_type* sobrescreve o valor
   dado ao parâmetro *compression* do construtor para a nova entrada.
   Da mesma forma, *compresslevel* vai sobrescrever o construtor se
   informado. O arquivo compactado deve ser aberto em modo "'w'",
   "'x'" ou "'a'".

   Nota:

     O padrão de arquivo ZIP historicamente não especificava uma
     codificação de metadados, mas recomendava fortemente o CP437 (a
     codificação original do PC da IBM) para interoperabilidade.
     Versões recentes permitem o uso de (somente) UTF-8. Neste módulo,
     o UTF-8 será automaticamente usado para escrever os nomes dos
     membros se eles contiverem caracteres não ASCII. Não é possível
     escrever nomes de membros em qualquer codificação que não seja
     ASCII ou UTF-8.

   Nota:

     Nomes de arquivo compactado devem ser relativos a raiz do mesmo,
     isto é, não devem começar com um separador de caminho.

   Nota:

     Se "arcname" (ou "filename", se "arcname" não for informado)
     contém um byte nulo, o nome do arquivo no arquivo compactado será
     truncado no byte nulo.

   Nota:

     Uma barra inicial no nome do arquivo pode fazer com que o arquivo
     seja impossível de abrir em alguns programas zip em sistemas
     Windows.

   Alterado na versão 3.6: Chama "write()" em um ZipFile criado com
   modo "'r'" ou em um ZipFile fechado levanta um "ValueError".
   Anteriormente, um "RuntimeError" era levantado

ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, compresslevel=None)

   Grava um arquivo no arquivo compactado. O conteúdo é *data*, que
   pode ser uma instância de "str" ou de "bytes"; Se é uma "str", ela
   é encodada como UTF-8 primeiro. *zinfo_or_arcname* é o nome que
   será dado ao arquivo no arquivo compactado, ou uma instância de
   "ZipInfo". Se é uma instância, pelo menos o nome do arquivo, a
   data, e a hora devem ser informados. Se é um nome, a data e hora
   recebem a data e hora atual. O arquivo compactado deve ser aberto
   em modo "'w'", "'x'" ou "'a'".

   Se informado, *compress_type* sobrescreve o valor do parâmetro
   *compression* do construtor para a nova entrada, ou no
   *zinfo_or_arcname* (se é uma instância de "ZipInfo"). Da mesma
   forma, *compresslevel* vai sobrescrever o construtor se informado.

   Nota:

     Quando é passada uma instância de "ZipInfo" ou o parâmetro
     *zinfo_or_arcname*, o método de compactação usado será aquele
     especificado no *compress_type* da instância de "ZipInfo". Por
     padrão, o construtor da classe "ZipInfo" seta este membro para
     "ZIP_STORED".

   Alterado na versão 3.2: O argumento *compress_type*.

   Alterado na versão 3.6: Chama "writestr()" em um ZipFile criado com
   modo "'r'" ou em um ZipFile fechado levanta um "ValueError".
   Anteriormente, um "RuntimeError" era levantado.

ZipFile.mkdir(zinfo_or_directory, mode=511)

   Cria um diretório dentro do arquivo. Se *zinfo_or_directory* for
   uma string, um diretório é criado dentro do arquivo com o modo
   especificado no argumento *mode*. No entanto, se
   *zinfo_or_directory* for uma instância "ZipInfo", o argumento
   *mode* é ignorado.

   O arquivo deve ser aberto com o modo "'w'", "'x'" ou "'a'".

   Adicionado na versão 3.11.

Os seguintes atributos de dados também estão disponíveis:

ZipFile.filename

   Nome do arquivo ZIP.

ZipFile.debug

   O nível de saída de debug para usar. Pode ser setado de "0" (valor
   padrão, sem nenhuma saída) a "3" (com mais saída). A informação de
   debug é escrita em "sys.stdout".

ZipFile.comment

   O comentário associado ao arquivo ZIP como um objeto "bytes". Se
   atribuir um comentário a uma instância "ZipFile" criada com o modo
   "'w'", "'x'" ou "'a'", não deve ser maior que 65535 bytes.
   Comentários mais longos do que isso serão truncados.


Objetos Path
============

class zipfile.Path(root, at='')

   Construir um objeto Path a partir de um arquivo zip "root" (que
   pode ser uma instância "ZipFile" ou "file" adequado para passar
   para o construtor "ZipFile").

   "at" especifica a localização deste caminho dentro do arquivo zip,
   por exemplo, "dir/arquivo.txt", "dir/" ou "". O padrão é a string
   vazia, indicando a raiz.

   Nota:

     A classe "Path" não sanitiza nomes de arquivos dentro do arquivo
     ZIP. Ao contrário dos métodos "ZipFile.extract()" e
     "ZipFile.extractall()", é responsabilidade do chamador validar ou
     sanitizar nomes de arquivos para evitar vulnerabilidades de
     travessia de caminho (por exemplo, nomes de arquivos contendo
     ".." ou caminhos absolutos). Ao lidar com arquivos não
     confiáveis, considere resolver nomes de arquivos usando
     "os.path.abspath()" e verificar o diretório de destino com
     "os.path.commonpath()".

Objetos Path expõem os seguintes recursos de objetos "pathlib.Path":

Objetos Path podem ser percorridos usando o operador "/" ou
"joinpath".

Path.name

   O componente final do caminho.

Path.open(mode='r', *, pwd, **)

   Invoca "ZipFile.open()" no caminho atual. Permite a abertura para
   leitura ou escrita, texto ou binário através dos modos suportados:
   "r", "w", "rb", "wb". Argumentos posicionais e argumentos nomeados
   são passados para "io.TextIOWrapper" quando abertos como texto e
   ignorados caso contrário. "pwd" é o parâmetro "pwd" para
   "ZipFile.open()".

   Alterado na versão 3.9: Adicionado suporte para modos de texto e
   binários para aberto. O modo padrão agora é texto.

   Alterado na versão 3.11.2: O parâmetro "encoding" pode ser
   fornecido como um argumento posicional sem causar um "TypeError".
   Como poderia em 3.9. O código que precisa ser compatível com as
   versões 3.10 e 3.11 não corrigidas deve passar todos os argumentos
   de "io.TextIOWrapper", incluindo "encoding", como palavras
   reservadas.

Path.iterdir()

   Enumera os filhos do diretório atual.

Path.is_dir()

   Retorna "True" se o contexto atual fizer referência a um diretório.

Path.is_file()

   Retorna "True" se o contexto atual fizer referência a um arquivo.

Path.is_symlink()

   Retorna "True" se o contexto atual fizer referência a um link
   simbólico.

   Adicionado na versão 3.12.

   Alterado na versão 3.13: Anteriormente, "is_symlink" retornava
   "False" incondicionalmente.

Path.exists()

   Retorna "True" se o contexto atual fizer referência a um arquivo ou
   diretório no arquivo zip.

Path.suffix

   A última parte separada por pontos do componente final, se houver.
   Isso é comumente chamado de extensão de arquivo.

   Adicionado na versão 3.11: Adicionada a propriedade "Path.suffix".

Path.stem

   O componente final do caminho, sem seu sufixo.

   Adicionado na versão 3.11: Adicionada a propriedade "Path.stem".

Path.suffixes

   Uma lista dos sufixos do caminho, comumente chamados de extensões
   de arquivo.

   Adicionado na versão 3.11: Adicionada a propriedade
   "Path.suffixes".

Path.read_text(*, **)

   Leia o arquivo atual como texto Unicode. Argumentos posicionais e
   argumentos nomeados são passados para "io.TextIOWrapper" (exceto
   "buffer", que está implícito no contexto).

   Alterado na versão 3.11.2: O parâmetro "encoding" pode ser
   fornecido como um argumento posicional sem causar um "TypeError".
   Como poderia em 3.9. O código que precisa ser compatível com as
   versões 3.10 e 3.11 não corrigidas deve passar todos os argumentos
   de "io.TextIOWrapper", incluindo "encoding", como palavras
   reservadas.

Path.read_bytes()

   Lê o arquivo atual como bytes.

Path.joinpath(*other)

   Retorna um novo objeto Path com cada um dos *outros* argumentos
   unidos. Os seguintes são equivalentes:

      >>> Path(...).joinpath('child').joinpath('grandchild')
      >>> Path(...).joinpath('child', 'grandchild')
      >>> Path(...) / 'child' / 'grandchild'

   Alterado na versão 3.10: Antes de 3.10, "joinpath" não estava
   documentado e aceitava exatamente um parâmetro.

O projeto zipp fornece backports da funcionalidade mais recente de
objeto caminho para versões mais antigas do Pythons. Use "zipp.Path"
internamente de "zipfile.Path" para acesso antecipado às alterações.


Objetos PyZipFile
=================

O construtor "PyZipFile" usa os mesmos parâmetros que o construtor
"ZipFile", e um parâmetro adicional, *otimize*.

class zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)

   Alterado na versão 3.2: Adicionado o parâmetro *optimize*.

   Alterado na versão 3.4: Extensões ZIP64 são habilitadas por padrão.

   As instâncias têm um método além daqueles dos objetos "ZipFile":

   writepy(pathname, basename='', filterfunc=None)

      Pesquisa por arquivos "*.py" e adiciona o arquivo correspondente
      ao arquivo.

      Se o parâmetro *optimize* para "PyZipFile" não foi fornecido ou
      "-1", o arquivo correspondente é um arquivo "*.pyc", compilando
      se necessário.

      Se o parâmetro *Optimize* para "PyZipFile" era "0", "1" ou "2",
      apenas arquivos com esse nível de otimização (ver "compile()")
      são adicionados ao o arquivo, compilando se necessário.

      Se *pathname* for um arquivo, o nome do arquivo deverá terminar
      com ".py", e apenas o arquivo ("*.pyc" correspondente) será
      adicionado no nível superior (sem informações do caminho). Se
      *pathname* for um arquivo que não termine com ".py", um
      "RuntimeError" será levantado. Se for um diretório, e o
      diretório não for um diretório de pacotes, todos os arquivos
      "*.pyc" serão adicionados no nível superior. Se o diretório for
      um diretório de pacotes, todos "*.pyc" serão adicionados sob o
      nome do pacote como um caminho de arquivo e, se algum
      subdiretório for um diretório de pacotes, todos serão
      adicionados recursivamente na ordem de classificação.

      *basename* destina-se apenas a uso interno.

      *filterfunc*, se fornecido, deve ser uma função que recebe um
      único argumento de string. Cada caminho será passado (incluindo
      cada caminho de arquivo completo individual) antes de ser
      adicionado ao arquivo. Se *filterfunc* retornar um valor falso,
      o caminho não será adicionado e, se for um diretório, seu
      conteúdo será ignorado. Por exemplo, se nossos arquivos de teste
      estão todos nos diretórios "test" ou começam com a string
      "test_", podemos usar um *filterfunc* para excluí-los:

         >>> zf = PyZipFile('myprog.zip')
         >>> def notests(s):
         ...     fn = os.path.basename(s)
         ...     return (not (fn == 'test' or fn.startswith('test_')))
         ...
         >>> zf.writepy('myprog', filterfunc=notests)

      O método "writepy()" faz arquivos com nomes de arquivo como
      este:

         string.pyc                   # Nome de nível superior
         test/__init__.pyc            # Diretório do pacote
         test/testall.pyc             # Módulo test.testall
         test/bogus/__init__.pyc      # Diretório do subpacote
         test/bogus/myfile.pyc        # Submódulo test.bogus.myfile

      Alterado na versão 3.4: Adicionado o parâmetro *filterfunc*.

      Alterado na versão 3.6.2: O parâmetro *pathname* aceita um
      *objeto caminho ou similar*.

      Alterado na versão 3.7: A recursão classifica as entradas de
      diretório.


Objetos ZipInfo
===============

Instâncias da classe "ZipInfo" são retornadas pelos métodos
"getinfo()" e "infolist()" dos objetos "ZipFile". Cada objeto armazena
informações sobre um único membro do arquivo ZIP.

Existe um método de classe para fazer uma instância "ZipInfo" para um
arquivo de sistema de arquivos:

classmethod ZipInfo.from_file(filename, arcname=None, *, strict_timestamps=True)

   Constrói uma instância "ZipInfo" para um arquivo no sistema de
   arquivos, em preparação para adicioná-lo a um arquivo zip.

   *filename* deve ser o caminho para um arquivo ou diretório no
   sistema de arquivos.

   Se *arcname* for especificado, ele será usado como o nome dentro do
   arquivo. Se *arcname* não for especificado, o nome será igual a
   *filename*, mas com qualquer letra de unidade e separadores de
   caminho removidos.

   O argumento *strict_timestamps*, quando definido como "False",
   permite compactar arquivos anteriores a 1980-01-01 com o custo de
   definir o carimbo de data/hora para 1980-01-01. Comportamento
   semelhante ocorre com arquivos mais recentes que 2107-12-31, o
   carimbo de data/hora também é definido como o limite.

   Adicionado na versão 3.6.

   Alterado na versão 3.6.2: O parâmetro *filename* aceita um *objeto
   caminho ou similar*.

   Alterado na versão 3.8: Adicionado o parâmetro somente-nomeado
   *strict_timestamps*.

As instâncias têm os seguintes métodos e atributos:

ZipInfo.is_dir()

   Retorna "True" se este membro do arquivo for um diretório.

   Isso usa o nome da entrada: os diretórios devem sempre terminar com
   "/".

   Adicionado na versão 3.6.

ZipInfo.filename

   Nome do arquivo no pacote.

ZipInfo.date_time

   A hora e a data da última modificação no membro do arquivo. Esta é
   uma tupla de seis valores que representam os campos "last
   [modified] file time" (última hora [de modificado] do arquivo) e
   "last [modified] file date" (última data [de modificação] do
   arquivo) do diretório central do arquivo ZIP.

   A tupla contém:

   +---------+----------------------------+
   | Índice  | Valor                      |
   |=========|============================|
   | "0"     | Ano (>= 1980)              |
   +---------+----------------------------+
   | "1"     | Mês (iniciado em 1)        |
   +---------+----------------------------+
   | "2"     | Dia do mês (iniciado em 1) |
   +---------+----------------------------+
   | "3"     | Horas (iniciado em 0)      |
   +---------+----------------------------+
   | "4"     | Minutos (base zero)        |
   +---------+----------------------------+
   | "5"     | Segundos (iniciado em 0)   |
   +---------+----------------------------+

   Nota:

     O formato ZIP oferece suporte a vários campos de registro de data
     e hora em diferentes locais (diretório central, campos extras
     para sistemas NTFS/UNIX, etc.). Este atributo retorna
     especificamente o registro de data e hora do diretório central. O
     formato de registro de data e hora do diretório central em
     arquivos ZIP não oferece suporte a registros de data e hora
     anteriores a 1980. Embora alguns formatos de campos extras (como
     registros de data e hora do UNIX) possam representar datas
     anteriores, este atributo retorna apenas o registro de data e
     hora do diretório central.O registro de data e hora do diretório
     central é interpretado como representando a hora local, em vez da
     hora UTC, para corresponder ao comportamento de outras
     ferramentas zip.

ZipInfo.compress_type

   Tipo de compressão do membro do pacote.

ZipInfo.comment

   Comentário para o membro individual do pacote como um objeto
   "bytes".

ZipInfo.extra

   Dados do campo de expansão. O PKZIP Application Note contém alguns
   comentários sobre a estrutura interna dos dados contidos neste
   objeto "bytes".

ZipInfo.create_system

   O sistema que criou o pacote ZIP.

ZipInfo.create_version

   A versão do PKZIP que criou o pacote ZIP.

ZipInfo.extract_version

   A versão do PKZIP necessária para extrair o pacote.

ZipInfo.reserved

   Deve ser zero

ZipInfo.flag_bits

   Bits de sinalizador do ZIP.

ZipInfo.volume

   Número de volume do cabeçalho do arquivo.

ZipInfo.internal_attr

   Atributos internos.

ZipInfo.external_attr

   Atributos de arquivo externo.

ZipInfo.header_offset

   Deslocamento de byte para o cabeçalho do arquivo.

ZipInfo.CRC

   CRC-32 do arquivo não comprimido.

ZipInfo.compress_size

   Tamanho dos dados comprimidos.

ZipInfo.file_size

   Tamanho do arquivo não comprimido.


Interface de Linha de Comando
=============================

O módulo "zipfile" fornece uma interface de linha de comando simples
para interagir com arquivos ZIP.

Se você deseja criar um novo arquivo ZIP, especifique seu nome após a
opção "-c" e, em seguida, liste os nomes dos arquivos que devem ser
incluídos:

   $ python -m zipfile -c monty.zip spam.txt eggs.txt

Passar um diretório também é aceitável:

   $ python -m zipfile -c monty.zip life-of-brian_1979/

Se você deseja extrair um arquivo ZIP para o diretório especificado,
use a opção "-e":

   $ python -m zipfile -e monty.zip target-dir/

Para obter uma lista dos arquivos em um arquivo ZIP, use a opção "-l":

   $ python -m zipfile -l monty.zip


Opções de linha de comando
--------------------------

-l <zipfile>
--list <zipfile>

   Lista arquivos em um arquivo zip.

-c <zipfile> <source1> ... <sourceN>
--create <zipfile> <source1> ... <sourceN>

   Cria um arquivo zip a partir dos arquivos fonte.

-e <zipfile> <output_dir>
--extract <zipfile> <output_dir>

   Extrai um arquivo zip para um diretório de destino.

-t <zipfile>
--test <zipfile>

   Testa se o arquivo zip é válido ou não.

--metadata-encoding <encoding>

   Especifica a codificação dos nomes dos membros para "-l", "-e" e
   "-t".

   Adicionado na versão 3.11.


Armadilhas de descompressão
===========================

A extração no módulo zipfile pode falhar devido a algumas armadilhas
listadas abaixo.


Do próprio arquivo
------------------

A descompactação pode falhar devido a senha / soma de verificação CRC
/ formato ZIP incorretos ou método de compactação / descriptografia
não compatível.


Limitações do sistema de arquivos
---------------------------------

Exceder as limitações em sistemas de arquivos diferentes pode causar
falha na descompactação. Como caracteres permitidos nas entradas do
diretório, comprimento do nome do arquivo, comprimento do caminho,
tamanho de um único arquivo e número de arquivos, etc.


Limitações de recursos
----------------------

A falta de memória ou volume de disco levaria a uma falha de
descompactação. Por exemplo, bombas de descompressão (também
conhecidas como ZIP bomb) aplicam-se à biblioteca de arquivos zip que
podem causar o esgotamento do volume do disco.


Interrupção
-----------

A interrupção durante a descompressão, como pressionar Control-C ou
interromper o processo de descompressão pode resultar na descompressão
incompleta do arquivo.


Comportamentos padrão da extração
---------------------------------

Não saber os comportamentos de extração padrão pode causar resultados
de descompressão inesperados. Por exemplo, ao extrair o mesmo arquivo
duas vezes, ele sobrescreve os arquivos sem perguntar.
