PythonMonkey

Pythonmonkey

Sobre

O Pythonmonkey é um mecanismo JavaScript Mozilla Spidermonkey incorporado no tempo de execução do Python, usando o mecanismo Python para fornecer o ambiente do host JavaScript.

Apresentamos métodos de matriz JavaScript e objetos implementados na lista de Python e dicionários usando a API Cpython C, e o inverso usando o API C ++ do Mozilla Firefox Spidermonkey JavaScript C ++.

Este projeto atingiu o MVP em setembro de 2024. Está sob manutenção por distributiva.

Contribuições e feedback externos são bem -vindos e incentivados.

tl; dr

$ pip install pythonmonkey

 from pythonmonkey import eval as js_eval

js_eval ( "console.log" )( 'hello, world' )

Metas

• Rápido e com eficiência de memória
• Faça o código de escrita em JS ou Python uma preferência de desenvolvedor
• Use bibliotecas JavaScript da Python
• Use Bibliotecas Python de JavaScript
• O mesmo processo executa JavaScript e Python VirtualMachines - sem serialização, tubos, etc.
• As listas de Python se comportam como matrizes e objetos de Javacript e vice-versa, se adaptando totalmente ao contexto fornecido.

Intercâmbio de dados

• As strings compartilham lojas de apoio imutáveis ​​sempre que possível (quando a alocação do mecanismo escolhe a representação interna do UCS-2 ou do Latin-1) para manter o consumo de memória sob controle e possibilitar mover seqüências de cordas muito grandes entre o código JavaScript e Python Library sem sobrecarga de cópia de memória.
• TypeDarrays compartilham lojas de apoio mutáveis.
• Os objetos JS são representados pelo Python Dicts através de uma subclasse DICT para compatibilidade ideal. Da mesma forma, para matrizes JS e listas de Python.
• Os objetos de data js são representados por Python DateTime.DateTime Objects
• Intrinsics (booleano, número, nulo, indefinido) é passado por valor
• As funções JS são embrulhadas automaticamente para que elas se comportem como funções python e vice-versa
• As listas de Python são representadas pelo JS True Angrays e suportam todos os métodos de matriz por meio de um proxy da API JS. Da mesma forma, para ditos de python e objetos JS.

Roteiro

• [Concluído] JS Instrinsics coagia a Python Intrinsics
• [Concluído] JS Strings coagra -se a Strings Python
• [Concluído] Os objetos JS coagiam a Python Dicts [somente propriedades próprias]
• [feito] As funções JS coagiram para que as funções de função Python
• [feito] JS exceções se propagam ao Python
• [Coned] Implementar eval() Função em Python, que aceita o código JS e retorna JS-> valores coagidos por Python
• [done] NodeJS+Sistema de módulo Commonjs compatível com NPM
• [done] Strings Python coagra -se com as cordas JS
• [done] Python Intrinsics coagia a JS Intrinsics
• [done] Python Dicts coage -se aos objetos JS
• [feito] O Python require função, retorna um ditado coagido das exportações de módulos
• [done] Python Functions coage -se a JS Function Wrappers
• [Done] Commonjs Module System .py Loader, carrega módulos Python para uso por JS
• [Done] Python Host Environment Supplies Event Loop, incluindo EventEmitter, Settimeout, etc.
• [Done] Python Host Environment Supplies XmlhttPrequest
• [done] Python tipedarrays coage -se a JS typearRays
• [Concluído] JS typeDarrays coage -se a Python typearrays
• [feito] listas de Python coerce para JS Matrizes
• [Concluído] JS Arrays coage para listas de Python
• [90%] O PythonMonkey pode executar o pacote NPM do DCP-Client da Distributive.

Construir instruções

Leia isso se quiser criar uma versão local.

1. Você precisará do seguinte instalado (que pode ser feito automaticamente executando ./setup.sh ):

   • Bash
   • cmake
   • DOXYGEN 1.9 Series (se você quiser construir os documentos)
   • GraphViz (se você quiser construir os documentos)
   • llvm
   • ferrugem
   • python3.8 ou posterior com arquivos de cabeçalho (python3-dev)
   • Spidermonkey mais recente de Mozilla-Central
   • NPM (NodeJS)
   • Poesia
   • VERIÇÃO DE POESIA-DINAMICA

2. Execute poetry install . Este comando compila automaticamente o projeto e instala o projeto, bem como dependências na poesia virtualenv. Se você deseja construir os documentos, defina a variável de ambiente BUILD_DOCS , como assim: BUILD_DOCS=1 poetry install . O PythonMonKey suporta vários tipos de construção, que você pode criar definindo a variável de ambiente BUILD_TYPE , como assim: BUILD_TYPE=Debug poetry install . Os tipos de construção são (insensíveis ao caso):

• Release : Símbolos despojados, otimizações máximas (padrão)
• DRelease : o mesmo que Release , exceto os símbolos não são despojados
• Debug : otimizações mínimas
• Sanitize : o mesmo que Debug , exceto com o endereço de endereço ativado
• Profile : o mesmo que Debug , exceto o perfil está ativado
• None : não compilar (útil se você deseja construir apenas os documentos)

Se você estiver usando o VSCode, basta pressionar Ctrl + Shift + B para executar a tarefa de compilação - temos o arquivo tasks.json configurado para você.

Testes de execução

1. Compilar o projeto
2. Instale dependências de desenvolvimento: poetry install --no-root --only=dev
3. No diretório raiz, execute poetry run pytest ./tests/python
4. No diretório raiz, execute poetry run bash ./peter-jr ./tests/js/

Para usuários do VSCODE, semelhante à tarefa de compilação, temos uma tarefa de teste pronta para uso.

Usando a biblioteca

O NPM (Node.js) é necessário durante a instalação apenas para preencher as dependências do JS.

Instale a partir de Pypi

$ pip install pythonmonkey

Instale a construção noturna

$ pip install --extra-index-url https://nightly.pythonmonkey.io/ --pre pythonmonkey

Use a versão local

pythonmonkey está disponível na poesia VirtualEnv depois que você compilou o projeto usando poesia.

$ poetry run python

 Python 3.10 .6 ( main , Nov 14 2022 , 16 : 10 : 14 ) [ GCC 11.3 .0 ] on linux
Type "help" , "copyright" , "credits" or "license" for more information .
> >> import pythonmonkey as pm
>> > hello = pm . eval ( "() => {return 'Hello from Spidermonkey!'}" )
>> > hello ()
'Hello from Spidermonkey!'

Como alternativa, você pode criar pacotes instaláveis ​​executando

$ cd python/pminit && poetry build --format=sdist && cd - && mv -v python/pminit/dist/ * ./dist/
$ poetry build --format=wheel

e instale -os por pip install ./dist/* .

Desinstalação

A instalação pythonmonkey também instalará o pacote pminit como uma dependência. No entanto, pip uninstall um pacote não removerá automaticamente suas dependências.
Se você deseja remover de maneira limpa pythonmonkey do seu sistema, faça o seguinte:

$ pip uninstall pythonmonkey pminit

Etapas de depuração

1. Construa o projeto localmente
2. Para usar o GDB, execute poetry run gdb python . Veja Python Wiki: Debuggingwithgdb

Se você estiver usando o VSCode, é mais conveniente depurar no depurador interno do VSCODE. Basta pressionar F5 em um arquivo Python aberto no editor para iniciar a depuração - temos o arquivo launch.json configurado para você.

Exemplos

• exemplos/
• https://github.com/distributive-network/pythonmonkey-examples
• https://github.com/distributive-network/pythonmonkey-crypto-js-fullstack-example

API oficial

Esses métodos são exportados do módulo Pythonmonkey. Veja definições em python/pythonmonkey/pythonmonkey.pyi.

Eval (código, opções)

Avalie o código JavaScript. A semântica desta avaliação é muito semelhante à avaliação usada no JavaScript; A última expressão avaliada na sequência code é usada como o valor de retorno desta função. Para avaliar code no modo rigoroso, a primeira expressão deve ser a string "use strict" .

opções

A função Eval suporta um objeto de opções que pode afetar como o código JS é avaliado de maneiras poderosas. Eles são amplamente baseados nas CompileOptions de Spidermonkey. As chaves de opção suportadas são:

• filename : defina o nome do arquivo deste código para fins de geração de rastreamentos de pilha etc.
• lineno : Defina o deslocamento do número da linha deste código para fins de geração de traços de pilha etc.
• column : Defina o deslocamento do número da coluna deste código para fins de geração de traços de pilha etc.
• mutedErrors : Se definido como True , avaliar erros ou rejeições não atendidas são ignoradas ("silenciadas"). Padrão False .
• noScriptRval : se False , retorne o último valor de expressão do script como o valor do resultado para o chamador. Padrão False .
• selfHosting : Experimental
• strict : Avalie à força no modo rigoroso ( "use strict" ). Padrão False .
• module : Indique que o arquivo é um módulo ECMAScript (sempre o código de modo rigoroso e proibiu os comentários HTML). Padrão False .
• fromPythonFrame : Gere o equivalente ao nome do arquivo, lineno e coluna com base na localização da chamada Python para avaliar. Isso possibilita avaliar literais de cordas multilinas Python e gerar rastreamentos de pilha em JS apontando para o erro no arquivo de origem Python.

truques

• Função Literais avaliados como undefined em JavaScript; Se você deseja retornar uma função, deve avaliar uma expressão:

   pythonmonkey . eval ( "myFunction() { return 123 }; myFunction" )

  ou

   pythonmonkey . eval ( "(myFunction() { return 123 })" )

• Expressões de função são uma ótima maneira de construir JS IIFEs que aceitam argumentos em python

   pythonmonkey . eval ( "(thing) => console.log('you said', thing)" )( "this string came from Python" )

requer (ModuleIdentifier)

Retorne as exportações de um módulo Commonjs identificado pelo moduleIdentifier , usando a semântica do Commonjs Standard

• Os módulos são singletons e nunca serão carregados ou avaliados mais de uma vez
• ModuleIdentifier é relativo ao arquivo python que a invasão require
• ModuleIdentifier não deve incluir uma extensão de arquivo
• ModuleIdentifiers que não começam com ./, ../, ou/são resolvidos pela pesquisa requer.path e module.paths.
• Os módulos são avaliados imediatamente após o carregamento
• Os módulos não são carregados até que sejam necessários
• As seguintes extensões são suportadas:

• .js - módulo JavaScript; O código -fonte decora o objeto exports
• .py - módulo python; O código -fonte decora exports dicadas
• .json - módulo json; As exportações são o resultado de analisar o texto JSON no arquivo

global

Um ditado de python que é equivalente ao objeto global deste objeto em JavaScript.

CreaterEquire (nome do arquivo, extrapatas, Ismain)

Função de fábrica que retorna uma nova função exigida

• nome do arquivo: o nome do caminho do módulo que essa exigência poderia ser usada para
• Extrapaths: [Opcional] Uma lista de caminhos extras para pesquisar para resolver identificadores de módulos não-relativos e não absolidos
• ismain: [Opcional] True se a função requerida estiver sendo criada para um módulo principal

runprogrammodule (nome do arquivo, argv, extrapatas)

Carregue e avalie um módulo de programa (principal). Os módulos do programa devem ser gravados em JavaScript. Os módulos do programa não são necessários, a menos que o ponto de entrada principal do seu programa esteja escrito no JavaScript.

• nome do arquivo: a localização do código -fonte JavaScript
• Argv: o vetor de argumento do programa
• Extrapaths: [Opcional] Uma lista de caminhos extras para pesquisar para resolver identificadores de módulos não-relativos e não absolidos

Deve -se tomar cuidado para garantir que apenas um módulo de programa seja executado por contexto JS.

IsCompilableUnit (código)

Examina o code da string e retorna false se a string puder se tornar uma instrução JS válida com a adição de mais linhas. Isso é usado internamente pelos PMJs e pode ser muito útil para a construção de REPLs JavaScript; A idéia é acumular linhas em um buffer até que o ISComPilableUnit seja verdadeiro e avaliar todo o buffer.

nova (função)

Retorna uma função python que chama function com o novo operador JS.

 import pythonmonkey as pm

> >> pm . eval ( "class MyClass { constructor() { console.log('ran ctor') }}" )
> >> MyClass = pm . eval ( "MyClass" )
> >> MyClass ()
Traceback ( most recent call last ):
  File "<stdin>" , line 1 , in < module >
pythonmonkey . SpiderMonkeyError : TypeError : class constructors must be invoked with 'new'

>> > MyClassCtor = pm . new ( MyClass )
>> > MyClassCtor ()
ran ctor
{}
>> >

TIPOOF (valor)

Este é o operador JS typeof , embrulhado em uma função para que possa ser usado facilmente a partir do Python.

Classes e globais padrão

Todas as classes padrão JS (Array, Função, Objeto, Data ...) e Objetos (Global This, FinalizationRegistry ...) estão disponíveis como exportações do módulo PythonMonkey. Essas exportações são geradas enumerando a variável global no contexto atual do Spidermonkey. A lista atual é:

undefined, Boolean, JSON, Date, Math, Number, String, RegExp, Error, InternalError, AggregateError, EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError, ArrayBuffer, Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array, Float64Array, Uint8ClampedArray, BigInt64Array, BigUint64Array, BigInt, Proxy, WeakMap, Map, Set, DataView, Symbol, Intl, Reflect, WeakSet, Promise, WebAssembly, WeakRef, Iterator, AsyncIterator, NaN, Infinity, isNaN, isFinite, parseFloat, parseInt, escape, unescape, decodeuri, codeuri, decodeuricomponent, codeuricomponent, função, objeto, depurglobal, FinalizationRegistry, Array, GlobalThis

Funções internas

Consulte Definições em Python/Pythonmonkey/global.d.ts. Incluindo:

• console
• atob
• btoa
• setTimeout
• clearTimeout

Adições de subsistema Commonjs

O subsistema Commonjs é ativado invocando as exportações require ou createRequire do módulo PythonMonkey (Python).

• require
• exports
• module
• __filename
• __dirname
• python.print - A função de impressão Python
• python.getenv - a função Python Getenv
• python.stdout - um objeto com métodos read e write , que leem e escrevem para stdout
• python.stderr - um objeto com métodos read e write , que leem e escrevem para Stderr
• python.exec - a função Python Exec
• python.eval - a função de avaliação python
• python.exit - saída via sys.exit (); O código de saída é o argumento da função ou python.exit.code .
• python.paths - A lista Python Sys.Paths, visível em JS como uma matriz

Tipo de transferência (coerção / embalagem)

Ao enviar variáveis ​​do Python para o JavaScript, o Pythonmonkey coagirá ou envolverá suas variáveis ​​com base no tipo deles. O Pythonmonkey compartilhará lojas de apoio (use a mesma memória) para ctypes, matrizes digitadas e strings; Mover esses tipos em toda a barreira do idioma é extremamente rápido porque não há cópia envolvida.

Nota: Existem planos no Python 3.12 (PEP 623) para alterar a representação interna da string, para que todo caractere da string use quatro bytes de memória. Isso quebrará transferências rápidas de string para o Pythonmonkey, pois se baseia no layout da memória sendo o mesmo em Python e JavaScript. Até o momento em que este artigo foi escrito (julho de 2023), as cordas Python "clássicas" ainda funcionam nos lançamentos beta 3.12.

Onde a loja de apoio compartilhada não é possível, o Pythonmonkey emitirá automaticamente invólucros que usam a estrutura de dados "real" como sua autoridade de valor. Apenas intrínsecos imutáveis ​​são copiados. Isso significa que, se você atualizar um objeto em JavaScript, o ditado correspondente no Python será atualizado, etc.

Os métodos de JavaScript Array e Object são implementados na lista e dicionários Python, e vice-versa.

Tipo Python	Tipo de JavaScript
Corda	corda
Inteiro	número
Bool	booleano
Função	função
Dito	objeto
Lista	Variedade
DateTime	Objeto de data
aguardável	Promessa
Erro	Objeto de erro
Buffer	ArrayBuffer

Tipo de JavaScript	Tipo Python
corda	pythonmonkey.jsstringproxy (string)
número	Flutuador
bigint	pythonmonkey.bigint (número inteiro)
booleano	Bool
função	pythonmonkey.jsfunctionProxy
objeto - a maioria	pythonmonkey.jsobjectproxy (dict)
Objeto - Data	DateTime
Objeto - Array	pythonmonkey.jsarrayproxy (lista)
Objeto - Promise	aguardável
Objeto - ArrayBuffer	Buffer
Objeto - Tipo matrizes	Buffer
objeto - erro	Erro

Truques

Coerção do tipo inteiro

Você pode forçar um número em JavaScript a ser coagido como um número inteiro, lançando -o para Bigint:

 function myFunction ( a , b ) {
  const result = calculate ( a , b ) ;
  return BigInt ( Math . floor ( result ) ) ;
}

O objeto pythonmonkey.bigint funciona como um int em Python, mas será coagido como um bigint em JavaScript:

 import pythonmonkey

def fn myFunction ()
  result = 5
  return pythonmonkey . bigint ( result )

Injeção de símbolo via iife transversal

Você pode usar um iife JavaScript para criar um escopo no qual você pode injetar símbolos python:

 globalThis . python . exit = pm . eval ( """'use strict';
(exit) => function pythonExitWrapper(exitCode) {
  if (typeof exitCode === 'number')
    exitCode = BigInt(Math.floor(exitCode));
  exit(exitCode);
}
""" )( sys . exit );

Execute o loop de eventos do Python

Você precisa de um loop de eventos em execução para usar setTimeout e Promise <=> awaitable coerção.

 import asyncio

async def async_fn ():
  await pm . eval ( """
    new Promise((resolve) => setTimeout((...args) => {
        console.log(args);
        resolve();
      }, 1000, 42, "abc")
    )
  """ )
  await pm . eval ( "async (x) => await x" )( asyncio . sleep ( 0.5 ))

asyncio . run ( async_fn ())

PMJS

Um shell javascript básico, pmjs , navios com Pythonmonkey. Este shell pode atuar como um repl ou executar programas JavaScript; É conceitualmente semelhante ao shell node que é enviado com o Node.JS.

Módulos

O PMJS inicia o subsistema Commonjs da PythonMonkey, que permite usar os módulos Commonjs, com semântica semelhante ao Node.js - por exemplo, módulo de pesquisa.paths, compreensão package.json, index.js e assim por diante. Consulte o módulo CTX para obter uma lista completa de recursos suportados.

Além dos módulos Commonjs escritos em JavaScript, o PythonMonkey suporta módulos Commonjs escritos em Python. Basta decorar um ditado denominado exports dentro de um arquivo com uma extensão .py , e ele pode ser carregado por require() - em JavaScript ou Python.

Módulo de programa

O módulo do programa, ou módulo principal, é um módulo especial no Commonjs. Em um módulo de programa:

• Variáveis ​​definidas no escopo mais externo são propriedades do globalThis
• Retornar do escopo mais externo é um erro de sintaxe
• A variável arguments em uma matriz que mantém o vetor de argumento do seu programa (argumentos da linha de comando)

$ echo " console.log('hello world') " > my-program.js
$ pmjs my-program.js
hello world
$

Módulo Commonjs: linguagem JavaScript

 // date-lib.js - require("./date-lib")
const d = new Date ( ) ;
exports . today = ` ${ d . getFullYear ( ) } - ${ String ( d . getMonth ( ) ) . padStart ( 2 , '0' ) } - ${ String ( d . getDay ( ) ) . padStart ( 2 , '0' ) } `

Módulo Commonjs: Linguagem Python

 # date-lib.py - require("./date-lib")
from datetime import date # You can use Python libraries.
exports [ 'today' ] = date . today ()

Dicas de solução de problemas

Commonjs (requer)

Se você estiver tendo problemas com o Commonjs, requer função, defina a variável de ambiente DEBUG='ctx-module*' e poderá ver os nomes de arquivos que ele tenta carregar.

pmdb

O Pythonmonkey possui um depurador de linha de comando JavaScript do tipo GDB, chamado PMDB , que seria automaticamente acionado no debugger; declarações e exceções não capturadas.

Para ativar o PMDB , basta ligar from pythonmonkey.lib import pmdb; pmdb.enable() antes de fazer qualquer coisa no Pythonmonkey.

 import pythonmonkey as pm
from pythonmonkey . lib import pmdb

pmdb . enable ()

pm . eval ( "..." )

Execute o comando help no PMDB para ver os comandos disponíveis.

 (pmdb) > help
List of commands:
• ...
• ... 

PMJS

• Existe um menu .help no repl
• Existe uma opção de linha de comando- --help
• A opção --inspect permite que o PMDB , um depurador de linha de comando JavaScript do tipo GDB
• A opção -r pode ser usada para carregar um módulo antes do seu programa ou das execuções Repl
• A opção -e pode ser usada Código de Avaliar -por exemplo, Definir variáveis ​​globais -antes do seu programa ou das execuções Replic
• O Repl pode avaliar expressões Python, armazenando -as em variáveis ​​denominadas $1 , $2 , etc.

$ pmjs

Welcome to PythonMonkey v1.0.0.
Type ".help" for more information.
> .python import sys
> .python sys.path
$1 = { '0': '/home/wes/git/pythonmonkey2',
  '1': '/usr/lib/python310.zip',
  '2': '/usr/lib/python3.10',
  '3': '/usr/lib/python3.10/lib-dynload',
  '4': '/home/wes/.cache/pypoetry/virtualenvs/pythonmonkey-StuBmUri-py3.10/lib/python3.10/site-packages',
  '5': '/home/wes/git/pythonmonkey2/python' }
> $1 [3]
'/usr/lib/python3.10/lib-dynload'
>