Migração de scripts para Python 3.13 na Workiva

Workiva Scripting e fim do suporte para Python 3.9

Para garantir que suas automações estejam preparadas para o futuro, a Workiva introduziu o suporte ao Python 3.13 , juntamente com uma configuração no nível do script que permite escolher a versão do ambiente de execução para cada script. Este manual explica como você pode mover com segurança da versão 3.9 para a 3.13, o que testar e como implementar as alterações com o mínimo de interrupção.

Até de outubro de 2025 , o Workiva Scripting utilizava a versão oficial do Python 3.9 da Python Software Foundation ; essa versão chegou ao fim de vida útil em outubro de 2025 e, consequentemente, não recebe mais atualizações de segurança nem correções de bugs.

Em resposta a isso, o Workiva Scripting passou a utilizar a imagem Amazon Linux 2023 (AL2023) , que oferece suas próprias compilações e suporte tanto para o Python 3.9 quanto para o Python 3.13. Essa mudança garante que o Python 3.9 receba atualizações de segurança contínuas e manutenção por meio do ciclo de atualizações da Amazon, mesmo que a versão original do Python não esteja mais recebendo correções da comunidade de código aberto.

Como resultado dessa transição, o Workiva Scripting continuará oferecendo suporte à execução segura de scripts no Python 3.9 até de outubro de 2027 .

Quem deve pensar sobre essa migração? Qualquer pessoa que esteja executando as automações da Workiva Scripting em Python 3.9- seja acionada manualmente, a partir de Cadeias ou por meio de Automações Integradas.

E se eu não fizer nada? Seus scripts permanecerão seguros por meio dos patches do AL2023 até outubro de 2027, mas recomendamos que você migre para o Python 3.13, pois essa é a versão mais recente com suporte.

Para obter mais informações sobre cronogramas de fim de vida útil e versões suportadas, reveja a página oficial de status da versão do Python .

Como a Workiva está apoiando essas alterações

A Workiva lançou uma atualização para permitir que os desenvolvedores controlem qual ambiente de execução do Python seus scripts utilizam. Esta atualização trouxe as seguintes mudanças:

Suporte ao Python 3.13: Todos os novos scripts agora são executados por padrão no Python 3.13, a versão estável mais recente.
Migração em tempo de execução por script: Os scripts existentes em Python 3.9 podem ser migrados para o Python 3.13. Depois que um script é migrado para o Python 3.13, ele não pode mais ser revertido para o Python 3.9.
Compatibilidade com versões anteriores: Todos os scripts existentes continuam a usar o Python 3.9 até que você os atualize.
Editor e suporte à API: Você pode definir ou atualizar o tempo de execução diretamente no Editor de Scripts do Workiva ou por meio da API de Scripts.

Isso garante que você possa migrar em sua própria linha do tempo, testar com segurança e alternar os scripts de produção somente quando tiver certeza de que eles estão prontos.

Cronograma para esta mudança

Para ajudar você a se planejar, aqui está o cronograma de lançamento:

Python 3.13 disponível no Workiva (setembro de 2025): Os scripts existentes em Python 3.9 podem ser migrados para o Python 3.13 usando a API de Scripting ou o Editor de Scripting. Os novos scripts utilizam o Python 3.13.
Fim do suporte ao Python 3.9 (outubro de 2025): O suporte oficial da comunidade Python chega ao fim. A Workiva continuará oferecendo suporte à versão AL2023 até outubro de 2027, mas a migração é altamente recomendada.
Outubro de 2027: A Workiva planeja encerrar o suporte ao Python 3.9 em outubro de 2027; a partir dessa data, todos os scripts serão executados no Python 3.13.

Fazendo a transição

Você deve começar a testar os scripts no Python 3.13 o mais rápido possível, mantendo a produção apenas na versão 3.9 até ter confirmado que eles funcionam corretamente na versão 3.13. Quando você se sentir confortável com o uso do Python 3.13, mude seus scripts de produção para o tempo de execução do Python 3.13 sem demora.

Mudando um script para o Python 3.13

Nosso padrão de implementação recomendado: crie uma cópia, atualize a versão, teste e, em seguida, promova. Isso minimiza o risco para a produção e permite que você mantenha o histórico de execuções, se necessário.

Etapa 1 - Faça uma cópia

Na Workiva, faça uma cópia do script de produção.
A cópia será configurada para o Python 3.13.

Etapa 2 - Teste e adapte a cópia

Execute a cópia em um contexto seguro/teste.
Corrija todas as alterações que possam estar quebrando (consulte "Problemas comuns e correções").
Valide as saídas, os efeitos colaterais e o desempenho.

Etapa 3 - Altere para a versão 3.13 (duas opções)

Opção A - Isso manterá o histórico de execução da produção

Cole o código atualizado do script copy de volta para o script original copiando e colando.
Altere o tempo de execução do script original para Python 3.13.
Execute novamente os testes e, em seguida, continue/retome o agendamento/triggers normais no original.
(Opção) Arquive ou retire a cópia.

Opção B - Isso não manterá o histórico de execução da produção

Altere o acionador de produção (ou seja, o acionador Cadeias) para apontar do script original para o script copiado.
A cópia se torna o novo script de produção (executado em Python 3.13).
(Opção) Arquive ou retire o original.

Chamada à ação: Seja qual for a opção escolhida, transfira todos os seus scripts ativos para Python 3.13 até outubro de 2027.

Atualizar a versão de tempo de execução do Python

Usando a API de script

Antes de começar, certifique-se de que sua autorização de API inclua os escopos script:read e script:write . Para obter instruções sobre como criar ou atualizar uma autorização de API, consulte Configuração da API da Workiva .

Determine o tempo de execução do script.
```
GET /scripts/{scriptId} Autorização: Bearer {token} X-Versão: 2026-01-01
```
Verifique o valor de runtime na resposta.

Atualize o script para Python 3.13.

PATCH /scripts/{scriptId} Autorização: Bearer {token} X-Version: 2026-01-01 Content-Type: application/json [{ "op": "replace", "path": "/runtime", "value": "python3.13" }]

Alterar o tempo de execução não gera automaticamente o pacote de dependências do script. Se o script contiver uma fonte do tipo requirements.txt , inicie a geração de dependências após atualizar o ambiente de execução e aguarde a conclusão da operação antes de executar o script. Scripts sem os arquivos ` ` e `requirements.txt` não exigem a geração de dependências.

Para obter mais detalhes, consulte estas páginas do Workiva para desenvolvedores:

Exemplo: Alterando e lendo a versão de tempo de execução do Python

O código de exemplo a seguir recupera a versão atual de um script, o migra para o Python 3.13 e regenera seu pacote de dependências usando a API de Scripting.

import os import time import requests CLIENT_ID = os.environ["CLIENT_ID"] CLIENT_SECRET = os.environ["CLIENT_SECRET"] SCRIPT_ID = os.environ["SCRIPT_ID"] API_VERSION = "2026-01-01" API_BASE_URL = "https://api.app.wdesk.com" SCRIPTS_API_URL = f"{API_BASE_URL}/scripts" AUTH_URL = f"{API_BASE_URL}/oauth2/token" def get_auth_headers(client_id, client_secret): response = requests.post( AUTH_URL, headers={ "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8", "X-Version": API_VERSION, }, data={ "client_id": client_id, "client_secret": client_secret, "grant_type": "client_credentials", }, timeout=30, ) response.raise_for_status() return { "Authorization": f"Bearer {response.json()['access_token']}", "X-Version": API_VERSION, } def read_version(script_id, headers): response = requests.get( f"{SCRIPTS_API_URL}/{script_id}", headers=headers, timeout=30, ) response.raise_for_status() script = response.json() print( f"Versão do Python para o script '{script['name']}': " f"{script['runtime'].replace('python', '')}" ) def change_to_python_313(script_id, headers): response = requests.patch( f"{SCRIPTS_API_URL}/{script_id}", headers={ **headers, "Content-Type": "application/json", }, json=[{ "op": "replace", "path": "/runtime", "value": "python3.13", }], timeout=30, ) response.raise_for_status() script = response.json() print( f"A versão do Python para o script '{script['name']}' foi alterada para: " f"{script['runtime'].replace('python', '')}" ) def has_requirements(script_id, headers): response = requests.get( f"{SCRIPTS_API_URL}/{script_id}/sources", headers=headers, timeout=30, ) response.raise_for_status() return any( source["path"] == "requirements.txt" for source in response.json()["data"] ) def regenerate_dependencies(script_id, headers): response = requests.post( f"{SCRIPTS_API_URL}/{script_id}/dependencies/generation", headers=headers, timeout=30, ) response.raise_for_status() operation_url = response.json()["operationLocation"] while True: operation_response = requests.get( operation_url, headers=headers, timeout=30, ) operation_response.raise_for_status() operação = operação_resposta.json() se operação["status"] estiver em {"completed", "failed", "cancelled"}: break time.sleep( int(operação_resposta.headers.get("Retry-After", "5")) ) if operation["status"] != "completed": raise RuntimeError( f"A geração de dependências terminou com o status " f"{operation['status']}: {operation}" ) headers = get_auth_headers(CLIENT_ID, CLIENT_SECRET) read_version(SCRIPT_ID, headers) change_to_python_313(SCRIPT_ID, headers) se has_requirements(SCRIPT_ID, headers): regenerate_dependencies(SCRIPT_ID, headers) print("Dependências regeneradas com sucesso.") else: print("Nenhum arquivo source requirements.txt encontrado; geração de dependências ignorada.")

Usando o Scripting Editor

Com o Editor de Scripts, você pode configurar o ambiente de execução diretamente na interface do usuário. Para um script existente que utiliza o Python 3.9, acesse Propriedades d → Versão de execução para migrá-lo para o Python 3.13. Após salvar, não será possível reverter o script para o Python 3.9.

Para atualizar um script no Editor:

Abra o script no Scripting Editor.
Vá para o painel Properties à direita.
Em Runtime Version, selecione Python 3.13 na lista suspensa.
Salve as alterações que você fez.
Execute o script em um ambiente seguro/teste antes de promover a produção.

Dicas:

Certifique-se de que todos os pacotes de terceiros em seus scripts sejam compatíveis com o Python 3.13.
Atualize todas as versões de pacotes fixadas no arquivo requirements.txt (por exemplo, ao contrário do Python 3.9, requests==2.28 não é necessário no 3.13).
Leia a documentação oficial do Python para obter detalhes sobre as principais alterações nas versões do Python 3.10, 3.11, 3.12, e 3.13, incluindo:
- Correspondência de padrões estruturais, atualizações de strings f, mensagens de erro aprimoradas
- Melhorias significativas no desempenho (chamadas de função, operações com strings, gerenciamento de memória, serialização/deserialização de JSON)
- Preterição de pacotes e remoção de determinados parâmetros de pacotes (cgi, cgitb, distutils, etc. foram preteridos; o parâmetro "loop" do asyncio foi removido)

Problemas comuns de migração e correções que você pode encontrar ao mover da versão 3.9 para a 3.13

Aqui estão alguns problemas comuns que você pode enfrentar ao mover scripts do Python 3.9 para o 3.13, juntamente com as correções sugeridas para eles:

Bibliotecas de terceiros: Alguns pacotes talvez ainda não sejam compatíveis com o Python 3.13.
- Correção: Atualize para a versão compatível mais recente ou substitua por uma alternativa. Você deve testar cuidadosamente todos os requisitos fixados. Você pode verificar o suporte para suas bibliotecas em pyreadiness.org/3.13 e revisar o artigo de ajuda "Supported scripting libraries and dependentes" para obter mais informações.
Versão da biblioteca solicitada: A biblioteca , solicitada pelo , é a biblioteca de terceiros mais comum no Workiva Scripting. Nas primeiras versões do Python 3.9, os scripts serão interrompidos com requests versão 2.30.0 ou mais recente. Depois de migrar para o Python 3.13, você poderá usar as versões mais recentes de solicitações sem problemas.
O Python 3.13 apresenta diferenças no tratamento de strings e bytes: Verificações de tipo mais rigorosas podem revelar problemas ocultos.
- Correção: Verifique se há códigos que misturam str e bytes e garanta a codificação/decodificação explícita.
Comportamento de data/hora e fuso horário: O Python 3.13 apresenta diferenças na biblioteca zoneinfo e uma análise mais rigorosa. Correção: Teste toda a lógica de data/hora, especialmente a formatação e as conversões de fuso horário.
Serialização JSON: Alguns objetos podem não ser serializados devido a regras mais rígidas.
- Correção: Certifique-se de que os objetos personalizados sejam convertidos antes de json.dumps, ou use codificadores padrão.
APIs obsoletas: Algumas funções do Python da biblioteca padrão (por exemplo, asyncio.get_event_loop , distutils e certas APIs de localização) que foram marcadas como obsoletas no Python 3.9 foram removidas. Correção: Atualize o código para usar as alternativas compatíveis.
Alterações no desempenho: Os loops e as tarefas assíncronas podem apresentar um comportamento diferente.
- Correção: Execute testes em caminhos críticos; atualize a lógica de simultaneidade, se necessário.

Dica: Sempre teste primeiro as cópias dos scripts de produção. As correções aplicadas em um ambiente de teste controlado reduzem o risco de problemas na produção.

O que há de novo no Python 3.13

Aqui estão alguns destaques de alterações para o Python 3.13:

Interpretador interativo aprimorado: Edição em várias linhas, cores e tracebacks coloridos.
Modo experimental de compilação com threads livres: Permite threads verdadeiramente paralelas (sem GIL) em algumas plataformas.
JIT experimental: Trabalhos preliminares para melhorias de desempenho.
Melhores ferramentas de depuração: locals() As mutações agora funcionam com uma semântica bem definida.
Novo alocador de memória: Versão modificada do mimalloc incluída e ativada por padrão, caso seja compatível.
Arquivos menores: As docstrings removem os espaços em branco à esquerda, reduzindo o uso de memória e o tamanho dos arquivos .pyc.
Novo backend dbm: Utiliza, por padrão, dbm.sqlite3 .
Atualizações da plataforma: ; macOS, versão mínima 10.13; iOS/Android, Nível 3; WASI, Nível 2.
Melhorias relacionadas a tipos: Padrões de tipos, restrição de tipos, itens somente leitura e anotações de obsolescência.
Remoções: Módulos obsoletos removidos (por exemplo, cgi , telnetlib , imghdr , lib2to3 , etc.).

Para obter as notas de lançamento completas, consulte "What's New in Python 3.13" do Python.org.

Se você quiser revisar as alterações específicas introduzidas entre a versão 3.9 e a 3.13, consulte:

Perguntas frequentes

Perguntas e respostas: Preciso migrar todos os meus scripts imediatamente?
Não. Você já pode começar a testar scripts no Python 3.13 e, ao mesmo tempo, manter o ambiente de produção na versão 3.9. Todos os scripts devem ser migrados para o Python 3.13 antes de de outubro de 2027 .

P: Meus scripts existentes deixaram de funcionar automaticamente quando o Python 3.9 chegou ao fim do ciclo de vida?
Não. O Workiva Scripting utiliza a versão 3.9 do Python da Amazon no ambiente Amazon Linux 2023 (AL2023), que continuará recebendo correções de segurança até outubro de 2027. Seus scripts não são afetados pelo fim do ciclo de vida oficial do Python 3.9.

P: Posso testar scripts na versão 3.13 e manter a produção na versão 3.9?
Sim. Crie uma cópia do seu script para testes — essa cópia é configurada automaticamente para ser executada no Python 3.13. Corrija todos os problemas na cópia antes de promovê-la à produção. Para evitar perda de compatibilidade, mantenha versões separadas - uma para a versão 3.9 e outra para a 3.13 - para que você possa alternar facilmente entre elas, se necessário.

P: O Editor de Scripts permite alterar o tempo de execução?
Sim. É possível definir o ambiente de execução Python de um script diretamente no Editor de Scripts — abra o script, acesse o painel Propriedades e selecione a versão na seção Versão do ambiente de execução.

P: Onde você pode saber mais sobre o suporte da biblioteca?
Consulte pyreadiness.org/3.13 e o artigo de ajuda da Workiva "Supported scripting libraries and dependentes".

Perguntas e respostas: O que acontece com meus dados históricos de execução se eu trocar de script?
Depende. Se você sobrescrever o script original, manterá o histórico de execuções. Se você apontar os acionadores para uma cópia, o histórico de execuções do original permanecerá com o script antigo.

P: O que acontece se eu não realizar a migração até outubro de 2027?
Seus scripts passarão automaticamente para o Python 3.13 após outubro de 2027, quando a Workiva encerrar o suporte à execução de scripts no Python 3.9 no âmbito do AL2023. Para evitar interrupções, você deve testar e migrar os scripts para o Python 3.13 bem antes de outubro de 2027.

P: Você precisa alterar minhas Cadeias ou Automações Integradas ao migrar?
Não. Suas cadeias e automações integradas continuarão funcionando conforme o esperado, desde que os scripts subjacentes sejam atualizados para o Python 3.13. A principal etapa é garantir que o script em si seja migrado.

Perguntas e respostas: Posso reverter um script do Python 3.13 para o 3.9 se ocorrerem problemas?
Não. Depois que um script é configurado para o Python 3.13, seu ambiente de execução não pode mais ser alterado de volta para o Python 3.9. Se você quiser uma opção alternativa, mantenha uma cópia separada do script no Python 3.9 — mantenha uma versão no 3.9 e outra no 3.13 — para que possa reverter para a cópia do 3.9 caso surjam problemas durante os testes.

Centro de suporte da Workiva