diff --git a/website/data/category_intros/interactive-interpreter.md b/website/data/category_intros/interactive-interpreter.md index de78936f..46fa8066 100644 --- a/website/data/category_intros/interactive-interpreter.md +++ b/website/data/category_intros/interactive-interpreter.md @@ -1,19 +1,18 @@ -At a terminal, IPython replaces the built-in Python interactive interpreter; in a notebook, it runs in Jupyter Notebook, unless you pick marimo for .py files. +Exploring code is easier in IPython than in the default Python interactive interpreter. Jupyter Notebook mixes code with notes and plots. How to choose: -- A better shell in the terminal: IPython -- Notebooks in the browser, in Python or other languages: Jupyter Notebook -- Reactive notebooks saved as `.py` files, runnable as scripts or apps: marimo -- A terminal REPL that flags syntax errors before running: ptpython -- A shell inside your own program: IPython or ptpython +- A better terminal prompt, with help on any object and magic commands: IPython +- Code, notes, and plots in one shareable document: Jupyter Notebook +- A reactive notebook saved as a Python file you can run as a script or app: marimo +- A terminal REPL with syntax highlighting, multiline editing, and Vi or Emacs keys: ptpython -IPython aims to be [an interactive shell superior to Python's default](https://ipython.readthedocs.io/en/latest/overview.html#enhanced-interactive-python-shell), with tab completion, object introspection, system shell access, and command history across sessions. Install it with [`pip install ipython`](https://ipython.readthedocs.io/en/latest/install/install.html) and start it with `ipython`. Type [`object?`](https://ipython.readthedocs.io/en/latest/interactive/tutorial.html#the-four-most-helpful-commands) for details about an object, and `object??` for more. [`%run`](https://ipython.readthedocs.io/en/latest/interactive/tutorial.html#running-and-editing) runs a script and loads its variables into your session, rereading the file each time. After an exception, [`%debug`](https://ipython.readthedocs.io/en/latest/interactive/tutorial.html#debugging) drops you into pdb to look around. +IPython takes whatever you'd type at the standard Python prompt and adds [tab completion, object introspection, and system shell access](https://ipython.readthedocs.io/en/stable/overview.html). Its tutorial covers [the everyday commands](https://ipython.readthedocs.io/en/stable/interactive/tutorial.html): `object?` shows an object's details, Tab after `object_name.` lists its attributes, and `!` runs a shell command. Magic commands start with `%`: `%timeit` times a statement, `%run` runs a script and loads its variables into your session, and `%debug` opens the debugger after an exception. -Jupyter Notebook is [a simplified notebook authoring application](https://jupyter-notebook.readthedocs.io/en/latest/). A notebook is a shareable document that mixes code, text, charts, and interactive controls. Install it with [`pip install notebook`](https://jupyter.org/install) and run `jupyter notebook`, which [opens it in your web browser](https://jupyter-notebook.readthedocs.io/en/latest/notebook.html#starting-the-notebook-server). Work on a problem [in pieces](https://jupyter-notebook.readthedocs.io/en/latest/notebook.html#basic-workflow), organizing related ideas into cells and moving on once earlier ones work. Code runs in a kernel, and [kernels for other languages](https://jupyter-notebook.readthedocs.io/en/latest/notebook.html#installing-kernels) let you write notebooks in more than Python. Notebooks save as [JSON files with the `.ipynb` extension](https://jupyter-notebook.readthedocs.io/en/latest/notebook.html#notebook-documents). +Start Jupyter Notebook with [`jupyter notebook`](https://jupyter-notebook.readthedocs.io/en/stable/notebook.html#starting-the-notebook-server), which runs a server on your machine and opens the app in your browser. Its docs suggest you [work on a problem in pieces](https://jupyter-notebook.readthedocs.io/en/stable/notebook.html#basic-workflow): put related ideas into cells, and move on once the earlier ones work. Python code runs in IPython, the default kernel. Notebooks are saved as `.ipynb` files, and nbconvert [turns them into HTML, PDF, or slides](https://jupyter-notebook.readthedocs.io/en/stable/notebook.html#notebook-documents). -marimo is a [reactive Python notebook](https://docs.marimo.io/): run a cell, and marimo runs the cells that depend on it, keeping code and outputs consistent. Delete a cell and marimo [removes its variables from memory](https://docs.marimo.io/faq/#how-is-marimo-different-from-jupyter), so no hidden state is left behind. Each notebook is a pure Python file you can version with Git or run as a script with `python your_notebook.py`. Serve it as an app with `marimo run`, which hides the code. Install it with `pip install marimo`, then [create or edit a notebook](https://docs.marimo.io/getting_started/quickstart/) with `marimo edit your_notebook.py`. To bring a Jupyter notebook over, run `marimo convert your_notebook.ipynb -o your_notebook.py`. To know what order to run cells in, marimo [lets you define each variable in only one cell](https://docs.marimo.io/guides/coming_from/jupyter/#redefining-variables). +marimo is [a reactive notebook](https://docs.marimo.io/): run a cell, and marimo runs the cells that depend on it, so code and outputs stay consistent. Each notebook is [stored as a plain Python file](https://docs.marimo.io/faq/#how-is-marimo-different-from-jupyter), so you can diff it in Git, run it as a script with `python`, or serve it as an app with `marimo run`. That model comes with two rules. [Each global variable is defined in only one cell](https://docs.marimo.io/guides/reactivity/#global-variable-names-must-be-unique), so prefix a scratch variable with `_` to keep it local to its cell. And since marimo doesn't track mutations, [mutate an object only in the cell that creates it](https://docs.marimo.io/guides/best_practices/). Unlike a Jupyter notebook, a marimo file [doesn't store outputs like plots](https://docs.marimo.io/guides/coming_from/jupyter/), and IPython magic commands and `!` shell commands don't work in it. -ptpython is [an advanced Python REPL](https://github.com/prompt-toolkit/ptpython) with syntax highlighting, multiline editing, autocompletion, and both Vi and Emacs key bindings. Before it runs your input, it [checks that it's valid Python](https://github.com/prompt-toolkit/ptpython#syntax-validation) and moves the cursor to the error. Install it with `pip install ptpython` and start it with `ptpython`. With IPython installed, [`ptipython`](https://github.com/prompt-toolkit/ptpython#ipython-support) adds IPython's magic functions and shell integration. +ptpython is [a better Python REPL](https://github.com/prompt-toolkit/ptpython) for the terminal, built on prompt_toolkit. It adds syntax highlighting, multiline editing where the up arrow works, autocompletion, Vi or Emacs key bindings, and a configuration menu. Run `ptpython` to start it, or `ptipython` to add IPython's magic functions and shell integration. -Both terminal shells can open inside your own program, with access to its variables: call [`IPython.embed()`](https://ipython.readthedocs.io/en/latest/interactive/reference.html#embedding-ipython) where you want to look around, or ptpython's [`embed(globals(), locals())`](https://github.com/prompt-toolkit/ptpython#embedding-the-repl). IPython is also [the default Python kernel](https://docs.jupyter.org/en/latest/what_is_jupyter.html#ipython) in Jupyter Notebook. +Both terminal REPLs can also open inside your program, with that scope's variables at hand: call [`IPython.embed()`](https://ipython.readthedocs.io/en/stable/interactive/reference.html#embedding-ipython), or ptpython's [`embed(globals(), locals())`](https://github.com/prompt-toolkit/ptpython#embedding-the-repl). For more Jupyter tools, see [awesome-jupyter](https://github.com/markusschanta/awesome-jupyter).