Pacote google.appengine.api.memcache

Resumo

Memcache API.

APIs semelhantes a memcached são fornecidas aos desenvolvedores de aplicativos para o armazenamento de dados na memória quando o armazenamento confiável por meio da DataStore API não é necessário e um desempenho mais alto é desejado.

Índice

class google.appengine.api.memcache.Client(servers=None, debug=0, pickleProtocol=2, pickler=function, unpickler=function, pload=None, pid=None, make_sync_call=None, _app_id=None)source

Bases: objeto

Objeto do cliente do memcache, em que todas as operações do memcache são invocadas.

Vários métodos são autônomos para a retenção da compatibilidade no nível de origem com a famosa biblioteca de memcache do Python.

Em qualquer método que receba um argumento 'key', essa chave será aceita como um string (unicode ou não) ou uma tupla de (hash_value, string) em que o hash_value, normalmente usado para fragmentação em uma instância do memcache, será ignorado, já que, no Google App Engine, a fragmentação é feita de forma transparente. As chaves no memcache são apenas bytes, sem uma codificação específica. Em todos esses métodos, um TypeError pode ser gerado se eles receberem um valor de chave falso, e um ValueError, se a chave for muito grande.

Nos métodos que aceitem um argumento "value", qualquer string (unicode ou não), int, long ou objeto Python serializável será aceita como valor, incluindo todos os tipos nativos. Você receberá de volta do cache o mesmo tipo que informou originalmente.

A classe Client não é segura para thread em relação aos métodos gets(), cas() e cas_multi() e outros métodos relacionados a comparar e definir. Portanto, os objetos Client não devem ser usados por mais de um thread para fins de CAS. Observe que o Client global para as funções no nível do módulo está correto porque, com ele, nenhum dos métodos de CAS é exposto.

add(key, value, time=0, min_compress_len=0, namespace=None)source

Definição do valor de uma chave se o item ainda não estiver no memcache.

Parâmetros
  • key – a chave a ser definida. Para mais detalhes, veja os documentos de Client.

  • valor – o valor a ser definido. Qualquer tipo. Se for complexo, será serializado.

  • time – o tempo de expiração opcional. Pode ser um número relativo de segundos a partir da hora atual (até um mês) ou um tempo de época absoluto Unix. Por padrão, os itens nunca expiram, mas há possibilidade de despejo de itens devido à pressão da memória. Valores flutuantes serão arredondados para o segundo inteiro mais próximo.

  • min_compress_len – opção ignorada por questões de compatibilidade.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

Retorna

Verdadeiro se adicionado. Falso em caso de erro.

add_multi(mapping, time=0, key_prefix='', min_compress_len=0, namespace=None)source

Definição de valores de várias chaves se os itens ainda não estiverem no memcache.

Parâmetros
  • mapping – dicionário de chaves para valores.

  • time – o tempo de expiração opcional. Pode ser um número relativo de segundos a partir da hora atual (até um mês) ou um tempo de época absoluto Unix. Por padrão, os itens nunca expiram, mas há possibilidade de despejo de itens devido à pressão da memória. Valores flutuantes serão arredondados para o segundo inteiro mais próximo.

  • key_prefix – prefixo a ser anexado a todas as chaves.

  • min_compress_len – opção de compatibilidade não implementada.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

Retorna

Uma lista de chaves com valores que NÃO foram definidos porque já estão no memcache. Quando houver êxito, essa lista deverá estar vazia.

add_multi_async(mapping, time=0, key_prefix='', min_compress_len=0, namespace=None, rpc=None)source

Versão assíncrona de add_multi() – observe o valor de retorno diferente.

Retorna

Veja _set_multi_async_with_policy().

cas(key, value, time=0, min_compress_len=0, namespace=None)source

Atualização do método de comparação e definição.

É necessário que a chave tenha sido recuperada com sucesso com gets() ou get(…, for_cas=True) e que nenhuma alteração tenha sido feita na chave desde essa recuperação. O uso típico é:

key = client = memcache.Client() value = client.gets(key) # OU client.get(key, for_cas=True) <updated value> ok = client.cas(key, value)

Se dois processos executarem códigos semelhantes, o primeiro que chamar cas() terá sucesso (ok == True), enquanto o segundo falhará (ok == False). Isso pode ser usado para detectar condições de corrida.

OBSERVAÇÃO: parte do estado (o código de CAS) é armazenado no objeto Client para cada chave já usada com gets(). Para evitar o uso crescente de memória, use um objeto Client ao usar cas(). O tempo de vida do objeto Client será limitado ao de uma solicitação HTTP recebida. Não é possível usar a API baseada em função global.

Parâmetros
  • key – a chave a ser definida. Para mais detalhes, veja os documentos de Client.

  • value – o novo valor.

  • time – o tempo de expiração opcional. Pode ser um número relativo de segundos a partir da hora atual (até um mês) ou um tempo de época absoluto Unix. Por padrão, os itens nunca expiram, mas há possibilidade de despejo de itens devido à pressão da memória. Valores flutuantes serão arredondados para o segundo inteiro mais próximo.

  • min_compress_len – opção ignorada por questões de compatibilidade.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

Retorna

Verdadeiro se atualizado. Falso em caso de erro de RPC ou se o código de CAS não corresponder.

cas_multi(mapping, time=0, key_prefix='', min_compress_len=0, namespace=None)source

Atualização do método de comparação e definição para várias chaves.

Para uma explicação, veja o docstring do cas().

Parâmetros
  • mapping – dicionário de chaves para valores.

  • time – o tempo de expiração opcional. Pode ser um número relativo de segundos a partir da hora atual (até um mês) ou um tempo de época absoluto Unix. Por padrão, os itens nunca expiram, mas há possibilidade de despejo de itens devido à pressão da memória. Valores flutuantes serão arredondados para o segundo inteiro mais próximo.

  • key_prefix – prefixo a ser anexado a todas as chaves.

  • min_compress_len – opção de compatibilidade não implementada.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

Retorna

Uma lista de chaves com valores que NÃO foram definidos porque houve falha na comparação. Quando houver êxito, essa lista deverá estar vazia.

cas_multi_async(mapping, time=0, key_prefix='', min_compress_len=0, namespace=None, rpc=None)source

Versão assíncrona de cas_multi() – observe o valor de retorno diferente.

Retorna

Veja _set_multi_async_with_policy().

cas_reset()source

Limpeza dos códigos de CAS memorizados.

debuglog()source

Função de registro para informações de depuração.

Apenas um método de compatibilidade. No Google App Engine, é autônomo.

decr(key, delta=1, namespace=None, initial_value=None)source

Diminuição atômica do valor de uma chave.

Internamente, o valor é um inteiro de 64 bits não assinado. No memcache, o decréscimo abaixo de zero é limitado a zero.

É preciso que a chave já esteja no cache para ser diminuída. Para mais detalhes, veja os documentos de incr().

Parâmetros
  • key – a chave a ser diminuída. Se for uma coleção iterável, cada chave será deslocada. Para mais detalhes, veja o docstring de Client.

  • delta – valor inteiro não negativo (int ou long) para diminuição da chave. Seu padrão é 1.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

  • initial_value – o valor inicial a ser colocado no cache, se ainda não houver. Com o uso do valor padrão, None, a entrada de cache não será criada se já não houver uma.

Retorna

Se a chave era um valor único, o novo valor inteiro longo, ou None, se a chave não estava no cache, não pôde ser diminuída por algum outro motivo, ou se tiver ocorrido um erro de rede/RPC/servidor.

Se key for uma coleção iterável, um dicionário é retornado com o mapeamento de chaves fornecidas para valores, com os valores tendo o mesmo significado que o valor de retorno singular desse método.

Gera
  • ValueError – se o número for negativo.

  • TypeError – se delta não for int ou long.

decr_async(key, delta=1, namespace=None, initial_value=None, rpc=None)source

Versão assíncrona de decr().

Retorna

Uma instância UserRPC em que o método get_result() retorna o mesmo tipo de valor que o decr().

delete(key, seconds=0, namespace=None)source

Exclui uma chave do memcache.

Parâmetros
  • key – a chave a ser excluída. Para mais detalhes, veja os documentos de Client.

  • seconds – número opcional de segundos para que itens excluídos sejam 'bloqueados' para operações 'add'. O valor pode ser um delta do horário atual (até 1 mês) ou um tempo de época Unix absoluto. O padrão é 0, o que significa que os itens podem ser adicionados imediatamente. Com ou sem essa opção, uma operação "set" sempre funcionará. Valores flutuantes serão arredondados para o segundo inteiro mais próximo.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

Retorna

DELETE_NETWORK_FAILURE (0) em caso de falha na rede, DELETE_ITEM_MISSING (1) se o servidor tentou excluir o item, mas não o tinha, ou DELETE_SUCCESSFUL (2) se o item foi realmente excluído. Isso pode ser usado como um valor booleano, em que uma falha de rede é a única condição inadequada.

delete_multi(keys, seconds=0, key_prefix='', namespace=None)source

Exclua várias chaves de uma vez só.

Parâmetros
  • keys – lista de chaves a serem excluídas.

  • seconds – número opcional de segundos para que itens excluídos sejam 'bloqueados' para operações 'add'. O valor pode ser um delta do horário atual (até 1 mês) ou um tempo de época Unix absoluto. O padrão é 0, o que significa que os itens podem ser adicionados imediatamente. Com ou sem essa opção, uma operação "set" sempre funcionará. Valores flutuantes serão arredondados para o segundo inteiro mais próximo.

  • key_prefix – prefixo a ser anexado a todas as chaves durante o envio de chaves específicas ao memcache. Veja a documentação de get_multi() e set_multi().

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

Retorna

Verdadeiro se todas as operações forem concluídas com êxito. Falso se uma ou mais operações não forem concluídas com êxito.

delete_multi_async(keys, seconds=0, key_prefix='', namespace=None, rpc=None)source

Versão assíncrona de delete_multi() – observe o valor de retorno diferente.

Retorna

Uma instância UserRPC em que o método get_result() retorna os valores None, se houver um erro de rede ou uma lista de valores de status em que os status correspondem a chaves e podem ser DELETE_SUCCESSFUL, DELETE_ITEM_MISSING ou DELETE_NETWORK_FAILURE. Para detalhes, veja o docstring de delete().

disconnect_all()source

Fechamento de todas as conexões a servidores de memcache.

Apenas um método de compatibilidade. No Google App Engine, é autônomo.

flush_all()source

Exclui tudo do memcache.

Retorna

Verdadeiro em caso de sucesso, falso em caso de erro de RPC ou do servidor.

flush_all_async(rpc=None)source

Versão assíncrona de flush_all().

Retorna

Uma instância UserRPC em que o método get_result() retorna os valores True em caso de sucesso e False em caso de erro de RPC ou do servidor.

forget_dead_hosts()source

Redefinição de todos os servidores para o status ativo.

Apenas um método de compatibilidade. No Google App Engine, é autônomo.

get(key, namespace=None, for_cas=False)source

Procura uma única chave no memcache.

No entanto, se você tiver vários itens para carregar, é muito mais eficiente usar get_multi(), em que eles são carregados em uma operação em massa, reduzindo a latência de rede que seria necessária para executar várias operações get() serializadas.

Parâmetros
  • key – a chave a ser pesquisada no memcache. Para detalhes do formato, veja os documentos de Client.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

  • for_cas – se for verdadeiro, a solicitação e o armazenamento de códigos de CAS são feitos no cliente (veja a operação cas() abaixo).

Retorna

O valor da chave, se encontrado no memcache, ou None.

get_multi(keys, key_prefix='', namespace=None, for_cas=False)source

Procura várias chaves do memcache em uma operação.

Essa é a maneira recomendada de fazer carregamentos em massa.

Parâmetros
  • keys – a lista de chaves a serem pesquisadas. As chaves podem ser strings ou tuplas de (hash_value, string). A fragmentação e o hash são feitos automaticamente pelo Google App Engine. Portanto, o valor do hash é ignorado. Para o memcache, as chaves são apenas séries de bytes e não estão em nenhuma codificação específica.

  • key_prefix – prefixo a ser anexado a todas as chaves durante a comunicação com o servidor e que não está incluído no dicionário retornado.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

  • for_cas – se for verdadeiro, a solicitação e o armazenamento de códigos de CAS são feitos no cliente.

Retorna

Um dicionário de chaves e valores que estavam presentes no memcache. Mesmo que o key_prefix seja especificado, ele não estará nas chaves do dicionário retornado.

get_multi_async(keys, key_prefix='', namespace=None, for_cas=False, rpc=None)source

Versão assíncrona de get_multi().

Retorna

Uma instância UserRPC em que o método get_result() retorna {} em caso de erro de rede ou, como retorna o get_multi(), um dict.

get_stats()source

Obtém estatísticas do memcache para este aplicativo.

Todas essas estatísticas podem ser redefinidas graças a várias condições transitórias. Elas contêm as melhores informações disponíveis no momento da chamada.

Retorna

Um dicionário com o mapeamento dos nomes de estatísticas aos valores associados. Estatísticas e respectivos significados associados:

hits: número de solicitações get de cache resultando em um hit de cache. misses: número de solicitações get de cache resultando em uma ausência no cache. byte_hits: soma de bytes transferidos em solicitações get. Volta a

zero em caso de ultrapassagem.

items: número de pares chave/valor no cache. bytes: tamanho total de todos os itens no cache. oldest_item_age: quanto tempo, em segundos, desde que o item mais antigo no

cache foi acessado. Efetivamente, indica por quanto tempo um novo item sobrevive no cache sem ser acessado. Essa não é a quantidade de tempo decorrida desde a criação do item.

Em caso de erro, None é retornado.

get_stats_async(rpc=None)source

Versão assíncrona de get_stats().

Retorna

Uma instância UserRPC em que o método get_result() retorna None, em caso de erro de rede ou, como retorna o get_stats(), um dict.

gets(key, namespace=None)source

Um alias para get(…, for_cas=True).

incr(key, delta=1, namespace=None, initial_value=None)source

Incrementação atômica do valor de uma chave.

Internamente, o valor é um inteiro de 64 bits não assinado. Ultrapassagens de 64 bits não são verificadas no memcache. O valor, se for muito grande, será quebrado.

A não ser que um initial_value seja especificado, é preciso que a chave já esteja no cache para ser incrementada. Para inicializar um contador, especifique initial_value ou set() para o valor inicial, como um inteiro decimal ASCII. Futuros get()s da chave, pós-incremento, ainda serão valores decimais ASCII.

Parâmetros
  • key – a chave a ser incrementada. Se for uma coleção iterável, cada chave será deslocada. Para mais detalhes, veja o docstring de Client.

  • delta – valor inteiro não negativo (int ou long) para incrementação da chave. O padrão é 1.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

  • initial_value – o valor inicial a ser colocado no cache, se ainda não houver. Com o uso do valor padrão, None, a entrada de cache não será criada se já não houver uma.

Retorna

Se a chave era um valor único, o novo valor inteiro longo, ou None, se a chave não estava no cache, não pôde ser incrementada por algum outro motivo, ou se tiver ocorrido um erro de rede/RPC/servidor.

Se key for uma coleção iterável, um dicionário é retornado com o mapeamento de chaves fornecidas para valores, com os valores tendo o mesmo significado que o valor de retorno singular desse método.

Gera
  • ValueError – se o número for negativo.

  • TypeError – se delta não for int ou long.

incr_async(key, delta=1, namespace=None, initial_value=None, rpc=None)source

Versão assíncrona de incr().

Retorna

Uma instância UserRPC em que o método get_result() retorna o mesmo tipo de valor que é retornado pelo incr().

offset_multi(mapping, key_prefix='', namespace=None, initial_value=None)source

Deslocamento de várias chaves em um delta, incrementando e decrementando em lote.

Parâmetros
  • mapping – dicionário do mapeamento de chaves para deltas (inteiros positivos ou negativos) a serem aplicados a cada chave correspondente.

  • key_prefix – prefixo a ser anexado a todas as chaves.

  • initial_value – o valor inicial a ser colocado no cache, se ainda não houver. Com o uso do valor padrão, None, a entrada de cache não será criada se já não houver uma.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

Retorna

Teclas de entrada de mapeamento de dicionário para novos valores inteiros. O novo valor será None se ocorrer um erro, se não houver uma chave ou se o valor não for um tipo inteiro. Os valores atingem um máximo inteiro de 64 bits não sinalizado e o que ultrapassar é reduzido a zero.

offset_multi_async(mapping, key_prefix='', namespace=None, initial_value=None, rpc=None)source

Versão assíncrona de offset_multi().

Retorna

Uma instância UserRPC em que o método get_result() retorna um dict, da mesma forma que o offset_multi().

replace(key, value, time=0, min_compress_len=0, namespace=None)source

Substituição do valor de uma chave. Ocorrerá uma falha se o item ainda não estiver no memcache.

Parâmetros
  • key – a chave a ser definida. Para mais detalhes, veja os documentos de Client.

  • valor – o valor a ser definido. Qualquer tipo. Se for complexo, será serializado.

  • time – o tempo de expiração opcional. Pode ser um número relativo de segundos a partir da hora atual (até um mês) ou um tempo de época absoluto Unix. Por padrão, os itens nunca expiram, mas há possibilidade de despejo de itens devido à pressão da memória. Valores flutuantes serão arredondados para o segundo inteiro mais próximo.

  • min_compress_len – opção ignorada por questões de compatibilidade.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

Retorna

Verdadeiro se substituído. Falso em caso de erro de RPC ou ausência no cache.

replace_multi(mapping, time=0, key_prefix='', min_compress_len=0, namespace=None)source

Substituição de valores de várias chaves. Ocorrerá uma falha se os itens não estiverem no memcache.

Parâmetros
  • mapping – dicionário de chaves para valores.

  • time – o tempo de expiração opcional. Pode ser um número relativo de segundos a partir da hora atual (até um mês) ou um tempo de época absoluto Unix. Por padrão, os itens nunca expiram, mas há possibilidade de despejo de itens devido à pressão da memória. Valores flutuantes serão arredondados para o segundo inteiro mais próximo.

  • key_prefix – prefixo a ser anexado a todas as chaves.

  • min_compress_len – opção de compatibilidade não implementada.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

Retorna

Uma lista de chaves em que os valores NÃO foram definidos porque já estão no memcache. Quando houver êxito, essa lista deverá estar vazia.

replace_multi_async(mapping, time=0, key_prefix='', min_compress_len=0, namespace=None, rpc=None)source

Versão assíncrona de replace_multi() – observe o valor de retorno diferente.

Retorna

Veja _set_multi_async_with_policy().

set(key, value, time=0, min_compress_len=0, namespace=None)source

Definição do valor de uma chave, independentemente do conteúdo anterior em cache.

Ao contrário de add() e replace(), com este método, o valor no memcache é sempre definido ou substituído, independentemente do conteúdo anterior.

Parâmetros
  • key – a chave a ser definida. Para mais detalhes, veja os documentos de Client.

  • valor – o valor a ser definido. Qualquer tipo. Se for complexo, será serializado.

  • time – o tempo de expiração opcional. Pode ser um número relativo de segundos a partir da hora atual (até um mês) ou um tempo de época absoluto Unix. Por padrão, os itens nunca expiram, mas há possibilidade de despejo de itens devido à pressão da memória. Valores flutuantes serão arredondados para o segundo inteiro mais próximo.

  • min_compress_len – opção ignorada por questões de compatibilidade.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

Retorna

Verdadeiro se definido. Falso em caso de erro.

set_multi(mapping, time=0, key_prefix='', min_compress_len=0, namespace=None)source

Definição dos valores de várias chaves de uma só vez, independentemente do conteúdo anterior.

Parâmetros
  • mapping – dicionário de chaves para valores.

  • time – o tempo de expiração opcional. Pode ser um número relativo de segundos a partir da hora atual (até um mês) ou um tempo de época absoluto Unix. Por padrão, os itens nunca expiram, mas há possibilidade de despejo de itens devido à pressão da memória. Valores flutuantes serão arredondados para o segundo inteiro mais próximo.

  • key_prefix – prefixo a ser anexado a todas as chaves.

  • min_compress_len – opção de compatibilidade não implementada.

  • namespace – um string para a especificação de um namespace opcional a ser usado na solicitação.

Retorna

Uma lista de chaves com valores que NÃO foram definidos. Quando houver êxito, essa lista deverá estar vazia.

set_multi_async(mapping, time=0, key_prefix='', min_compress_len=0, namespace=None, rpc=None)source

Versão assíncrona de set_multi() – observe o valor de retorno diferente.

Retorna

Veja _set_multi_async_with_policy().

set_servers(servers)source

Definição do pool de servidores de memcache usados pelo cliente.

Apenas um método de compatibilidade. No Google App Engine, é autônomo.

google.appengine.api.memcache.create_rpc(deadline=None, callback=None)source

Criação de um objeto de RPC para uso com a Memcache API.

Parâmetros
  • deadline – prazo opcional em segundos para a operação. O padrão é um prazo específico do sistema, geralmente de cinco segundos.

  • callback – chamável opcional a ser invocado na conclusão.

Retorna

Um objeto apiproxy_stub_map.UserRPC especializado para este serviço.

google.appengine.api.memcache.setup_client(client_obj)source

Definição da instância do objeto Client a ser usada para todos os métodos no nível do módulo.

Use este método se você quiser ter as funções persistent_id () ou persistent_load () associadas ao cliente.

Observação: não expomos os métodos _async como funções porque eles são muito obscuros, e não expomos gets(), cas() e cas_multi() porque eles mantêm o estado no objeto do cliente.

Parâmetros

client_obj – instância do memcache. Objeto do cliente.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente padrão do App Engine para Python 2