Migrar para o PyMongo async

Importante

O driver PyMongo Async é experimental.Não recomendamos usá-lo em ambientes de produção. As classes, métodos e comportamentos descritos neste guia podem mudar antes da versão de produção. Se você encontrar algum problema com o PyMongo Async, saiba como denunciá-lo na página de ajuda.

Visão geral

O driver PyMongo Async é uma unificação do PyMongo e da biblioteca Motor. Neste guia, você pode identificar as alterações que deve fazer para migrar um aplicação do PyMongo ou Motor para o driver do PyMongo Async.

Síncrono versus Assíncrono

Para determinar se você deve migrar para o driver do PyMongo Async ou continuar usando o PyMongo síncrono, considere as informações nesta seção.

O PyMongo síncrono é preferível se os seguintes critérios se aplicarem ao seu aplicação ou caso de uso:

Seu aplicação é simples de executar ou você prefere evitar chamadas assíncronas em seu código
Seu aplicação depende de cargas de trabalho em série ou cargas de trabalho com tempos de resposta muito rápidos
Você prefere a simplicidade da lógica síncrona ao depurar seu aplicação

Considere migrar para o driver do PyMongo Async se os critérios a seguir se aplicarem ao seu aplicação ou caso de uso:

Seu aplicação implementa volumes de trabalho grandes e altamente simultâneos (da ordem de milhares de operações simultâneas)
Seu aplicação depende de volumes de trabalho que passam muito tempo aguardando respostas ou gravando dados
Seu aplicação depende de outras bibliotecas ou estruturas assíncronas, como FastAPI

Migrar do Motor

Aviso

Descontinuação do Motor

O driver PyMongo Async é experimental. Não recomendamos usá-lo em ambientes de produção.

O Motor será descontinuado um ano após o lançamento da produção do driver PyMongo Async. É altamente recomendável que os usuários do Motor migrem para o driver PyMongo Async enquanto o Motor ainda for suportado.

O driver PyMongo Async funciona de forma semelhante à biblioteca Motor, mas permite latência e taxa de transferência aprimoradas devido ao uso direto do Python Asyncio em vez de delegar trabalho a um pool de threads. Na maioria dos casos, você pode migrar diretamente os aplicativos Motor existentes para o PyMongo Async usando AsyncMongoClient no lugar de MotorClient e alterando as declarações de importação do aplicativo para importar de pymongo.

O exemplo a seguir mostra a diferença nas importações para usar um cliente para operações de leitura e escrita no Motor em comparação com o PyMongo Async:

# Motor client import
from motor.motor_asyncio import AsyncIOMotorClient
# PyMongo Async client import
from pymongo import AsyncMongoClient

Para ver uma lista dos métodos assíncronos disponíveis no driver PyMongo Async, consulte a seção Métodos assíncronos. Para saber mais sobre as versões do Motor que correspondem ao PyMongo, consulte a seção Compatibilidade do Motor do guia de Compatibilidade.

A seção a seguir mostra as alterações na assinatura do método que você deve implementar em seu aplicação ao migrar do driver Motor para o PyMongo Async.

Aviso

O driver do PyMongo Async não suporta o Tornado.

Alterações na assinatura do método

As seguintes assinaturas de método do Motor se comportam de forma diferente no driver PyMongo Async:

AsyncMongoClient.__init__() não aceita um parâmetro io_loop.
AsyncCursor.each() não existe no driver PyMongo Async.
MotorGridOut.stream_to_handler() não existe no driver PyMongo Async.
AsyncCursor.to_list(0) não é válido no driver PyMongo Async. Em vez disso, use to_list(None).
MongoClient é thread seguro e pode ser usado por muitos threads, no entanto, um AsyncMongoClient não é seguro para threads e deve ser usado apenas por um único loop de eventos.

Aviso

Os usuários do Motor podem sofrer uma degradação do desempenho ao mudar para o driver PyMongo Async. Isso se deve ao driver PyMongo Async usar tarefas asyncio nativas em vez de executores baseados em thread. Os executores baseados em thread têm características de desempenho semelhantes às do driver síncrono, mas mais lentos. Isso significa que eles têm melhor desempenho para volumes de trabalho que não se encaixam nos critérios anteriores do driver PyMongo Async.

Se você estiver enfrentando lentidão no desempenho, identifique se o driver PyMongo Async é necessário para seu caso de uso. Se você determinar que seu caso de uso é mais bem atendido pelo PyMongo síncrono, considere usar o driver síncrono com asyncio.loop.run_in_executor() para compatibilidade assíncrona. Para saber mais, consulte a documentação da API do Event Loop.

Migrar do PyMongo

O driver PyMongo Async se comporta de forma semelhante ao PyMongo, mas todos os métodos que executam operações de rede são corrotinas e devem ser aguardadas. Para migrar do PyMongo para o PyMongo Async, você deve atualizar seu código das seguintes maneiras:

Substitua todos os usos de MongoClient por AsyncMongoClient.
Adicione a palavra-chave await a todas as chamadas de método assíncrono.
Se você chamar um método assíncrono dentro de uma função, marque a função como async.

Tenha em mente os seguintes pontos ao migrar do driver PyMongo síncrono para o driver PyMongo Async:

Para converter um AsyncCursor em uma lista, você deve utilizar o método cursor.to_list() assíncrono.
O método AsyncCollection.find() no driver PyMongo Async é síncrono, mas retorna um AsyncCursor. Para iterar pelo cursor, você deve usar um loop async for.
O objeto AsyncMongoClient não suporta o argumento de palavra-chave connect.
Não é possível compartilhar AsyncMongoClient objetos entre threads ou loops de evento .
Para acessar uma propriedade ou método de um resultado retornado por uma chamada assíncrona, você deve encapsular corretamente a chamada entre parênteses, conforme mostrado no exemplo a seguir:
```
id = (await posts.insert_one(doc)).inserted_id
```

Métodos assíncronos

Para obter uma lista completa dos métodos assíncronos disponíveis no driver PyMongo Async, consulte a documentação da API.

Observação

Todos os métodos não listados na documentação da API anterior são síncronos.

Informações adicionais

Para saber mais sobre Python assíncrono, consulte a documentação do Python Asyncio.

Voltar

Guias de atualização

Versões anteriores