A versão 3.0.0 do SDK do Vonage para Python já está disponível!

Resumo: A versão 3.0.0 do SDK do Python já está disponível! A maior parte das pull requests consiste em refatoração interna para preparar o terreno para melhorias futuras, mas também adicionamos alguns novos recursos para ajudar você a aproveitar ao máximo o uso do SDK.

Desde que eu (Max) entrei na Vonage, há 4 meses, tenho dedicado uma quantidade significativa de tempo à refatoração do SDK principal em Pythonda Vonage. Nesta versão, concentrei-me em melhorias para reduzir a dívida técnica e aumentar a legibilidade. Como resultado, as alterações feitas na versão v3.0.0 servem principalmente para preparar o terreno para que novos recursos interessantes possam ser adicionados posteriormente.

Nesta postagem, vou explicar algumas das mudanças que fiz na versão 3.0.0 e qual foi a motivação por trás de cada uma delas.

Uma visão geral

A principal mudança estrutural consistiu em organizar os métodos de cada API em classes e módulos separados. Isso deixa mais claro qual API você está chamando, além de nos permitir definir o tipo de autenticação para cada API quando você faz uma solicitação por meio do SDK.

Havia também muita duplicação. Por exemplo, havia cinco métodos distintos, distribuídos por mais de três arquivos diferentes, para fazer a mesma solicitação POST básica com algumas variações. Consolidei todos esses métodos em uma única função que realiza uma chamada REST com o requests pacote, levando em conta os diferentes métodos de autenticação e tipos de corpo de resposta esperados por cada API.

A principal diferença entre a v2 e a v3 é que grande parte do código obsoleto foi removido, portanto, há várias alterações que quebram a compatibilidade. Todos os Client métodos de classe que, na verdade, chamavam uma API específica foram removidos, já que agora são acessados a partir do módulo específico dessa API. Havia também alguns métodos que deveriam ter sido considerados obsoletos e removidos há muito tempo, ou que nunca deveriam ter sido adicionados, os quais agora consideramos obsoletos e removeremos em uma versão futura.

Adicionamos parâmetros opcionais à Client classe para permitir que você personalize o tempo limite, as tentativas de reconexão e as opções de pool para toda a sessão com um cliente da Vonage. Também adicionamos algumas melhorias à API de Preços, com um novo método e a capacidade de realizar consultas com base no tráfego de SMS ou Voice.

Vamos dar uma olhada!

Baixe a nova versão

Para baixar a nova versão 3.0.0, basta executar este comando (talvez seja melhor fazer isso dentro de um ambiente virtual!):

Isso fará o download da nova versão desde o início ou atualizará uma versão existente do SDK para a versão mais recente.

Uma breve observação

Nas versões anteriores, eu adicionei uma Messages classe e mudei a forma como os métodos podiam ser chamados. Por exemplo, para enviar um SMS, antes era preciso fazer assim:

client = vonage.Client(key='my_key', secret='my_secret')
sms = vonage.Sms(client)
sms.send_message([message_details_go_here])

Considerando que agora é possível fazer isso para todas as chamadas de API:

client = vonage.Client(key='my_key', secret='my_secret')
client.sms.send_message([message_details_go_here])

Os exemplos que apresentarei neste post seguirão esse último padrão.

Novas aulas

Inicialmente, todo o código estava em uma única Client classe. Ou seja, todos os métodos, para todos os tipos de solicitação que podem ser feitas com o SDK. Há alguns anos, foi iniciada uma refatoração para modularizar essas solicitações em classes com base nas APIs que elas chamam: Voice, Sms, Verify e assim por diante. Essa refatoração nunca foi concluída, então, nos últimos meses, marquei os métodos da Client classe e adicionei novos módulos como number_insight, messages, account, etc. Agora, os métodos relacionados a uma API específica são chamados a partir desse módulo específico.

Por exemplo, para fazer uma solicitação básica de informações sobre Numbers, agora você pode fazer o seguinte:

client = vonage.Client(key='my_key', secret='my_secret')
client.number_insight.get_basic_number_insight(number=MY_NUMBER)

Portanto, agora o código está modularizado, mas pode ser acessado por meio de uma única classe cliente. A versão 3.0.0 remove os métodos que estavam originalmente na Client classe; portanto, agora eles devem ser chamados conforme descrito acima.

Novas opções de conexão para clientes

Ao instanciar um Client objeto, agora é possível especificar o max_retries, timeout, pool_connections e pool_maxsize argumentos de palavra-chave opcionais, que serão usados em todas as solicitações feitas com esse Client objeto. As opções podem ser especificadas desta forma:

client = vonage.client(
key='my_key',
secret='my_secret',
timeout=10,  # timeout in seconds
pool_connections=10,
pool_maxsize=10,
max_retries=5
)

Essas opções são úteis se você estiver enviando muitas solicitações ao mesmo tempo ou quiser permitir que as solicitações atinjam o tempo limite e sejam repetidas.

Por padrão, a solicitação não terá tempo limite, mas é possível especificar qualquer valor em segundos. O número máximo padrão de tentativas é 3, mas qualquer valor inteiro é válido. Da mesma forma, você pode especificar qualquer valor inteiro para o número de conexões do pool e o tamanho máximo do pool (embora ambos tenham o valor padrão de 10).

Novos argumentos de palavras-chave de preços nas chamadas à API de Preços

Agora é possível especificar se você deseja ver os preços de SMS ou chamadas de voz ao acessar a API de Preços. O padrão é SMS, e os preços das chamadas de voz podem ser solicitados da seguinte forma:

client.account.get_country_pricing(country_code='GB', type='voice')

Foi adicionado um método para obter os preços de todos os países

Adicionamos um get_all_countries_pricing método à Account classe. Isso permite que você veja os preços para todos os países suportados, tanto para SMS quanto para chamadas de Voice.

client.account.get_all_countries_pricing() # returns sms pricing for all countries
client.account.get_all_countries_pricing(type='voice') # returns voice pricing for all countries

Métodos removidos da API de pesquisa de mensagens

A Messages API foi removida pela Vonage, então removi os métodos que a chamavam. Consulte este aviso sobre a especificação da API para obter mais informações.

A Vonage recomenda migrar todas as chamadas para a Reports API. Como se trata de um recurso em fase beta, ele não é compatível com o SDK do Python, mas este guia explica como fazer a migração para a Reports API.

Removida a criação automática de clientes

Anteriormente, era possível instanciar uma classe de API (por exemplo, Sms) diretamente, passando as credenciais, já que um cliente era criado ao fazer isso. Isso foi removido, pois queremos que todos utilizem as classes criando um cliente e usando-o para chamar métodos da API.

Removidos métodos obsoletos das classes `Voice` e `NumberInsight`

A Voice classe continha métodos (initiate_call, initiate_tts_call e initiate_tts_prompt_call) que expunham pontos de extremidade que foram descontinuados pela Vonage em 2017! Eles já foram removidos do SDK. Da mesma forma, o request_number_insight método foi removido, pois foi substituído pelos get_{basic/standard/advanced}_number_insight métodos e pontos de extremidade.

Renomeando um método de segredos

O Account.delete_secret método foi renomeado para revoke_secret para ficar de acordo com a documentação. Não há muito o que dizer aqui, havia apenas uma pequena discrepância que já corrigimos.

Funcionalidades obsoletas

Descontinuamos o uso da ApplicationV2 classe e criamos uma Application classe para alinhar a nomenclatura com a de outros métodos. A migração é simples:

ApplicationV2.list_applications() # Old class
Application.list_applications() # New class

Dois métodos antigos da API de preços (get_sms_pricing e get_voice_pricing) foram considerados obsoletos, pois chamam pontos de extremidade obsoletos.

Por fim, o método que chama a Redact API (redact_transaction) foi descontinuado, pois se trata de um produto em pré-visualização para desenvolvedores que não é compatível com os SDKs de servidor da Vonage.

Todos esses itens serão removidos em uma versão futura.

Atualização da versão 2.x

Se você estiver atualizando da versão 2.x para a nova versão, certifique-se de que, caso esteja utilizando algum método da API diretamente da classe cliente, passe a utilizar os métodos da classe de API correspondente.

Por exemplo:

client.get_basic_number_insight(number=MY_NUMBER) # API methods have been removed from the client class - this won't work
client.number_insight.get_basic_number_insight(number=MY_NUMBER) # Call the methods using the relevant API classes instead

Para onde vamos?

Como você pode ver, fizemos várias alterações na forma como as APIs são chamadas nesta versão. Em versões futuras, adicionaremos funcionalidades de vídeo ao SDK. Também planejamos remover os métodos obsoletos, adicionar suporte para asyncio e, eventualmente, tomar mais medidas para validar as entradas, utilizando uma ferramenta como o Pydantic.

Fique à vontade para baixar a nova versão e nos contar o que achou! Se houver mais alguma coisa que você gostaria de ver ou alguma contribuição que queira fazer, todo o SDK é de código aberto e disponível no GitHub. Você pode começar hoje mesmo com créditos gratuitos no site do Vonage Developer.