StartExternalSession

StartExternalSession["sys"]

starts an external session using the external evaluator sys, returning an external session object.

StartExternalSession[assoc]

starts the external evaluator specified by assoc.

StartExternalSession[{"sys",opts}]

uses the options opts for the external evaluator.

StartExternalSession[systype]

specifies that output from the external evaluator should be converted to the specified type.

StartExternalSession[DatabaseReference[ref]]

uses the database specified by ref to start a database session.

Details

  • StartExternalSession starts an external process that can be used to implement an external evaluator session in which there are multiple evaluations requested by ExternalEvaluate.
  • In StartExternalSession[assoc], elements of the association can include:
  • "System"the external system or language to start
    "Evaluator"the specific evaluator to execute code
    "Name"the registered name of an evaluator
    "ReturnType"type of object to return ("String", "Expression", ...)
    "Prolog"code to run before the command
    "Epilog"code to run after the command
    "SessionProlog"code to run before the session
    "SessionEpilog"code to run after the session
  • "System" is the only required key; all others are optional.
  • In StartExternalSession[sys], possible choices of sys include:
  • "Python"Python
    "NodeJS"JavaScript running through Node.js
    "Julia"Julia
    "Ruby"Ruby
    "R"R
    "Shell"Bash, Sh, Zsh, ...
    "Jupyter"Jupyter kernel
    "SQL"SQL database
    "SQL-JDBC"SQL database using JDBC
  • Possible settings for "type" in StartExternalSession[sys"type",…], or for "ReturnType", are dependent on the evaluation system, and typically include:
  • "Expression"attempt to convert to a Wolfram Language expression
    "String"give the raw string output by the external evaluator
  • The possible settings for evaluator in StartExternalSession[{sys,"Evaluator"evaluator},…] depend on sys, and include:
  • "path"path to a language executable
    DatabaseReference[…]an SQL database connection
    SQLConnection[…]an SQL-JDBC database connection
  • Typically, StartExternalSession uses the setting "ReturnType""Expression".
  • StartExternalSession[{"sys",opts}] is equivalent to StartExternalSession[<|"System""sys",opts|>].
  • FindExternalEvaluators gives a dataset of evaluator systems that can be used.
  • ExternalSessions gives a list of active external sessions.
  • DeleteObject[ExternalSessionObject[…]] kills and removes an external session started by StartExternalSession.

Examples

open allclose all

Basic Examples  (3)

Start an external Python session, automatically discovering any usable installations:

Evaluate code in the session:

Stop the session with DeleteObject:

Start a session using Python Version 3:

Verify the version:

End the session:

Start a new Python session in a provisioned environment:

Scope  (15)

Multiple external sessions can be run simultaneously:

Delete the session objects:

Start an external Python session using the executable in /usr/bin/python2.7:

Use the session for multiple calls to ExternalEvaluate:

Stop the session with DeleteObject:

Session Options  (13)

"ReturnType"  (4)

For most systems, the default return type is "Expression":

Delete the session objects:

Numbers, strings, lists and associations are automatically imported for the "Expression" return type:

Delete the session objects:

The return type of "String" returns a string of the result in the external language:

Delete the session objects:

When using a database, the default return type is "Dataset":

"ReturnType" can be used to return data in a different form:

Delete the session objects:

"Evaluator"  (3)

Evaluate code using a specified "Evaluator":

Delete the session objects:

An Association can be used to start a Python provisioned environment:

Use the session to evaluate the code:

Delete the session objects:

When using a File with the "SQL" evaluator, the target can be a path to an SQLite file or a DatabaseReference specification:

Delete the session objects:

"Name"  (1)

Register an evaluator using a name:

Start a session using the registered evaluator by referring to it by name:

Use the session:

Close the session:

"SessionProlog"  (2)

Use "SessionProlog" to perform a side effect at the start of a session:

Delete the session objects:

Start an external session and import a library at the beginning of the session:

Evaluate a function from the imported library:

Delete the session object:

"SessionEpilog"  (1)

Use "SessionEpilog" to perform a side effect at the end of a session:

Delete the session object:

"Prolog"  (1)

Use "Prolog" to perform a side effect before every evaluation:

Delete the session object:

"Epilog"  (1)

Use "Epilog" to perform a side effect after every evaluation:

Delete the session object:

Properties & Relations  (4)

Each session runs in its own process:

The process IDs for each session are different:

Delete the session objects:

If only the language is specified, the first evaluator returned by FindExternalEvaluators is used:

Stop the session:

Start a database session:

Run a query:

Manually close the session:

External language cells implicitly call StartExternalSession:

x=2

A new session has been started:

By default, all cells of a given system use that session:

x*x

End the session so that subsequent evaluations start in a new session:

Wolfram Research (2017), StartExternalSession, Wolfram Language function, https://reference.wolfram.com/language/ref/StartExternalSession.html (updated 2020).

Text

Wolfram Research (2017), StartExternalSession, Wolfram Language function, https://reference.wolfram.com/language/ref/StartExternalSession.html (updated 2020).

CMS

Wolfram Language. 2017. "StartExternalSession." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2020. https://reference.wolfram.com/language/ref/StartExternalSession.html.

APA

Wolfram Language. (2017). StartExternalSession. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/StartExternalSession.html

BibTeX

@misc{reference.wolfram_2023_startexternalsession, author="Wolfram Research", title="{StartExternalSession}", year="2020", howpublished="\url{https://reference.wolfram.com/language/ref/StartExternalSession.html}", note=[Accessed: 20-April-2024 ]}

BibLaTeX

@online{reference.wolfram_2023_startexternalsession, organization={Wolfram Research}, title={StartExternalSession}, year={2020}, url={https://reference.wolfram.com/language/ref/StartExternalSession.html}, note=[Accessed: 20-April-2024 ]}