Você está na página 1de 4

shelve - persistência de objeto Python

Código fonte: Lib / shelve.py

Uma “prateleira” é um objeto persistente, semelhante a um dicionário. A diferença com os


bancos de dados “dbm” é que os valores (não as chaves!) Em uma prateleira podem ser
objetos Python essencialmente arbitrários - qualquer coisa que o pickle módulo possa
manipular. Isso inclui a maioria das instâncias de classe, tipos de dados recursivos e objetos
que contêm muitos subobjetos compartilhados. As teclas são cordas comuns.

shelve. open( nome do arquivo , sinalizador = 'c' , protocolo = Nenhum , write-back = Falso )
Abra um dicionário persistente. O nome do arquivo especificado é o nome do arquivo
base para o banco de dados subjacente. Como efeito colateral, uma extensão pode ser
adicionada ao nome do arquivo e mais de um arquivo pode ser criado. Por padrão, o
arquivo de banco de dados subjacente é aberto para leitura e gravação. O parâmetro
opcional flag tem a mesma interpretação que o parâmetro flag de dbm.open() .

Por padrão, os pickles da versão 3 são usados para serializar valores. A versão do
protocolo pickle pode ser especificada com o parâmetro protocol

Devido à semântica do Python, uma prateleira não pode saber quando uma entrada
mutável de dicionário persistente é modificada. Por padrão, os objetos modificados são
gravados apenas quando atribuídos à prateleira (consulte Exemplo ). Se o parâmetro
opcional write-back estiver definido como True , todas as entradas acessadas também
serão armazenadas em cache na memória e gravadas novamente sync() e close() ; isso
pode facilitar a mutação de entradas mutáveis no dicionário persistente, mas, se muitas
entradas forem acessadas, poderá consumir grandes quantidades de memória para o
cache e tornar a operação de fechamento muito lenta, pois todas as entradas acessadas
são gravadas novamente ( não há como determinar quais entradas acessadas são
mutáveis nem quais foram realmente mutadas).

Nota: Não confie na prateleira sendo fechada automaticamente; sempre chame


close() explicitamente quando não precisar mais dele ou use shelve.open() como um
gerenciador de contexto:

with shelve.open('spam') as db:


db['eggs'] = 'eggs'

Aviso: Como o shelve módulo é suportado pickle , não é seguro carregar uma prateleira de
uma fonte não confiável. Como com pickle, carregar uma prateleira pode executar código
arbitrário.

Objetos de prateleira suportam todos os métodos suportados por dicionários. Isso facilita a
transição de scripts baseados em dicionário para aqueles que exigem armazenamento
persistente.
Dois métodos adicionais são suportados:

Shelf. sync( )
Escreva de volta todas as entradas no cache se a prateleira foi aberta com o writeback
definido como True . Esvazie também o cache e sincronize o dicionário persistente no
disco, se possível. Isso é chamado automaticamente quando a prateleira é fechada com
close() .

Shelf. close( )
Sincronize e feche o objeto de dict persistente . As operações em uma prateleira fechada
falharão com a ValueError .

Veja também: Receita de dicionário persistente com formatos de armazenamento


amplamente suportados e com a velocidade de dicionários nativos.

Restrições
A escolha de qual pacote de banco de dados será usado (como dbm.ndbm ou dbm.gnu )
depende de qual interface está disponível. Portanto, não é seguro abrir o banco de
dados diretamente usando dbm . O banco de dados também está (infelizmente) sujeito
às limitações de dbm , se for usado - isso significa que (a representação em pickled) dos
objetos armazenados no banco de dados deve ser bastante pequeno e, em casos raros,
colisões de chaves podem fazer com que o banco de dados se recuse atualizações.
O shelve módulo não suporta acesso simultâneo de leitura / gravação a objetos
arquivados. (Vários acessos simultâneos de leitura são seguros.) Quando um programa
tem uma prateleira aberta para gravação, nenhum outro programa deve tê-lo aberto para
leitura ou gravação. O bloqueio de arquivo Unix pode ser usado para resolver isso, mas
isso difere nas versões do Unix e requer conhecimento sobre a implementação do
banco de dados usada.

classe shelve. Shelf( dict , protocol = None , write-back = False , keyencoding = 'utf-8' )
Uma subclasse collections.abc.MutableMapping que armazena valores de pickled no
objeto dict .

Por padrão, os pickles da versão 3 são usados para serializar valores. A versão do
protocolo pickle pode ser especificada com o parâmetro protocol Consulte a
pickle documentação para uma discussão sobre os protocolos de pickle.

Se o parâmetro writeback for True , o objeto manterá um cache de todas as entradas


acessadas e as gravará de volta ao dict no momento da sincronização e do fechamento.
Isso permite operações naturais em entradas mutáveis, mas pode consumir muito mais
memória e fazer com que a sincronização e o fechamento demorem muito tempo.

O parâmetro keyencoding é a codificação usada para codificar chaves antes de serem


usadas com o dict subjacente.

Um Shelf objeto também pode ser usado como um gerenciador de contexto; nesse caso,
ele será fechado automaticamente quando o with bloco terminar.
Alterado na versão 3.2: Adicionado o parâmetro keyencoding ; anteriormente, as chaves
eram sempre codificadas em UTF-8.

Alterado na versão 3.4: Adicionado suporte ao gerenciador de contexto.

classe shelve. BsdDbShelf( dict , protocol = None , write-back = False , keyencoding = 'utf-8' )

Uma subclasse de Shelf que expõe first() , next() , previous() , last() e set_location() que
estão disponíveis no terceiro bsddb módulo do pybsddb mas não em outros módulos de
banco de dados. O objeto dict passado para o construtor deve suportar esses métodos.
Isso geralmente é realizado chamando um de bsddb.hashopen() , bsddb.btopen() ou
bsddb.rnopen() . Os parâmetros opcionais de protocolo , write-back e codificação de chave
têm a mesma interpretação da Shelf classe.

classe shelve. DbfilenameShelf( nome do arquivo , sinalizador = 'c' , protocolo = Nenhum ,


write-back = Falso )
Uma subclasse da Shelf qual aceita um nome de arquivo em vez de um objeto semelhante
a um ditado. O arquivo subjacente será aberto usando dbm.open() . Por padrão, o arquivo
será criado e aberto para leitura e gravação. O parâmetro opcional flag tem a mesma
interpretação da open() função. Os parâmetros opcionais de protocolo e write - back têm
a mesma interpretação da Shelf classe.

Exemplo
Para resumir a interface ( key é uma string, data é um objeto arbitrário):

import shelve

d = shelve.open(filename) # open -- file may get suffix added by low-level


# library

d[key] = data # store data at key (overwrites old data if


# using an existing key)
data = d[key] # retrieve a COPY of data at key (raise KeyError
# if no such key)
del d[key] # delete data stored at key (raises KeyError
# if no such key)

flag = key in d # true if the key exists


klist = list(d.keys()) # a list of all existing keys (slow!)

# as d was opened WITHOUT writeback=True, beware:


d['xx'] = [0, 1, 2] # this works as expected, but...
d['xx'].append(3) # *this doesn't!* -- d['xx'] is STILL [0, 1, 2]!

# having opened d without writeback=True, you need to code carefully:


temp = d['xx'] # extracts the copy
temp.append(5) # mutates the copy
d['xx'] = temp # stores the copy right back, to persist it

# or, d=shelve.open(filename,writeback=True) would let you just code


# d['xx'].append(5) and have it work as expected, BUT it would also
# consume more memory and make the d.close() operation slower.

d.close() # close it

Veja também:

Módulo dbm
Interface genérica para dbm bancos de dados estilo.
Módulo pickle
Serialização de objetos usada por shelve .

Você também pode gostar