Show More
This diff has been collapsed as it changes many lines, (2523 lines changed) Show them Hide them | |||
@@ -1035,7 +1035,7 b' Regular Options' | |||
|
1035 | 1035 | After the above threading options have been given, regular options can |
|
1036 | 1036 | follow in any order. All options can be abbreviated to their shortest |
|
1037 | 1037 | non-ambiguous form and are case-sensitive. One or two dashes can be |
|
1038 | used. Some options have an alternate short form, indicated after a |. | |
|
1038 | used. Some options have an alternate short form, indicated after a ``|``. | |
|
1039 | 1039 | |
|
1040 | 1040 | Most options can also be set from your ipythonrc configuration file. See |
|
1041 | 1041 | the provided example for more details on what the options do. Options |
@@ -1373,1244 +1373,1246 b' typing %magic at the prompt, but that will also give you information' | |||
|
1373 | 1373 | about magic commands you may have added as part of your personal |
|
1374 | 1374 | customizations. |
|
1375 | 1375 | |
|
1376 | ||
|
1377 | %Exit: Exit IPython without confirmation. | |
|
1378 | ||
|
1379 | ||
|
1380 | %Pprint: Toggle pretty printing on/off. | |
|
1381 | ||
|
1382 | ||
|
1383 | %alias: Define an alias for a system command. | |
|
1384 | ||
|
1385 | '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd' | |
|
1386 | ||
|
1387 | Then, typing 'alias_name params' will execute the system command 'cmd | |
|
1388 | params' (from your underlying operating system). | |
|
1389 | ||
|
1390 | Aliases have lower precedence than magic functions and Python normal | |
|
1391 | variables, so if 'foo' is both a Python variable and an alias, the alias | |
|
1392 | can not be executed until 'del foo' removes the Python variable. | |
|
1393 | ||
|
1394 | You can use the %l specifier in an alias definition to represent the | |
|
1395 | whole line when the alias is called. For example: | |
|
1396 | ||
|
1397 | In [2]: alias all echo "Input in brackets: <%l>" | |
|
1398 | In [3]: all hello world | |
|
1399 | Input in brackets: <hello world> | |
|
1400 | ||
|
1401 | You can also define aliases with parameters using %s specifiers (one per | |
|
1402 | parameter): | |
|
1403 | ||
|
1404 | In [1]: alias parts echo first %s second %s | |
|
1405 | In [2]: %parts A B | |
|
1406 | first A second B | |
|
1407 | In [3]: %parts A | |
|
1408 | Incorrect number of arguments: 2 expected. | |
|
1409 | parts is an alias to: 'echo first %s second %s' | |
|
1410 | ||
|
1411 | Note that %l and %s are mutually exclusive. You can only use one or the | |
|
1412 | other in your aliases. | |
|
1413 | ||
|
1414 | Aliases expand Python variables just like system calls using ! or !! do: | |
|
1415 | all expressions prefixed with '$' get expanded. For details of the | |
|
1416 | semantic rules, see PEP-215: http://www.python.org/peps/pep-0215.html. | |
|
1417 | This is the library used by IPython for variable expansion. If you want | |
|
1418 | to access a true shell variable, an extra $ is necessary to prevent its | |
|
1419 | expansion by IPython: | |
|
1420 | ||
|
1421 | In [6]: alias show echo | |
|
1422 | In [7]: PATH='A Python string' | |
|
1423 | In [8]: show $PATH | |
|
1424 | A Python string | |
|
1425 | In [9]: show $$PATH | |
|
1426 | /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:... | |
|
1427 | ||
|
1428 | You can use the alias facility to acess all of $PATH. See the %rehash | |
|
1429 | and %rehashx functions, which automatically create aliases for the | |
|
1430 | contents of your $PATH. | |
|
1431 | ||
|
1432 | If called with no parameters, %alias prints the current alias table. | |
|
1433 | ||
|
1434 | ||
|
1435 | %autocall: Make functions callable without having to type parentheses. | |
|
1436 | ||
|
1437 | Usage: | |
|
1438 | ||
|
1439 | %autocall [mode] | |
|
1440 | ||
|
1441 | The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the | |
|
1442 | value is toggled on and off (remembering the previous state). | |
|
1443 | ||
|
1444 | In more detail, these values mean: | |
|
1445 | ||
|
1446 | 0 -> fully disabled | |
|
1447 | ||
|
1448 | 1 -> active, but do not apply if there are no arguments on the line. | |
|
1449 | ||
|
1450 | In this mode, you get: | |
|
1451 | ||
|
1452 | In [1]: callable Out[1]: <built-in function callable> | |
|
1453 | ||
|
1454 | In [2]: callable 'hello' ---> callable('hello') Out[2]: False | |
|
1455 | ||
|
1456 | 2 -> Active always. Even if no arguments are present, the callable | |
|
1457 | object is called: | |
|
1458 | ||
|
1459 | In [4]: callable ---> callable() | |
|
1460 | ||
|
1461 | Note that even with autocall off, you can still use '/' at the start of | |
|
1462 | a line to treat the first argument on the command line as a function and | |
|
1463 | add parentheses to it: | |
|
1464 | ||
|
1465 | In [8]: /str 43 ---> str(43) Out[8]: '43' | |
|
1466 | ||
|
1467 | ||
|
1468 | %autoindent: Toggle autoindent on/off (if available). | |
|
1469 | ||
|
1470 | ||
|
1471 | %automagic: Make magic functions callable without having to type the | |
|
1472 | initial %. | |
|
1473 | ||
|
1474 | Without argumentsl toggles on/off (when off, you must call it as | |
|
1475 | %automagic, of course). With arguments it sets the value, and you can | |
|
1476 | use any of (case insensitive): | |
|
1477 | ||
|
1478 | - on,1,True: to activate | |
|
1479 | ||
|
1480 | - off,0,False: to deactivate. | |
|
1481 | ||
|
1482 | Note that magic functions have lowest priority, so if there's a variable | |
|
1483 | whose name collides with that of a magic fn, automagic won't work for | |
|
1484 | that function (you get the variable instead). However, if you delete the | |
|
1485 | variable (del var), the previously shadowed magic function becomes | |
|
1486 | visible to automagic again. | |
|
1487 | ||
|
1488 | ||
|
1489 | %bg: Run a job in the background, in a separate thread. | |
|
1490 | ||
|
1491 | For example, | |
|
1492 | ||
|
1493 | %bg myfunc(x,y,z=1) | |
|
1494 | ||
|
1495 | will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the | |
|
1496 | execution starts, a message will be printed indicating the job number. | |
|
1497 | If your job number is 5, you can use | |
|
1498 | ||
|
1499 | myvar = jobs.result(5) or myvar = jobs[5].result | |
|
1500 | ||
|
1501 | to assign this result to variable 'myvar'. | |
|
1502 | ||
|
1503 | IPython has a job manager, accessible via the 'jobs' object. You can | |
|
1504 | type jobs? to get more information about it, and use jobs.<TAB> to see | |
|
1505 | its attributes. All attributes not starting with an underscore are meant | |
|
1506 | for public use. | |
|
1507 | ||
|
1508 | In particular, look at the jobs.new() method, which is used to create | |
|
1509 | new jobs. This magic %bg function is just a convenience wrapper around | |
|
1510 | jobs.new(), for expression-based jobs. If you want to create a new job | |
|
1511 | with an explicit function object and arguments, you must call jobs.new() | |
|
1512 | directly. | |
|
1513 | ||
|
1514 | The jobs.new docstring also describes in detail several important | |
|
1515 | caveats associated with a thread-based model for background job | |
|
1516 | execution. Type jobs.new? for details. | |
|
1517 | ||
|
1518 | You can check the status of all jobs with jobs.status(). | |
|
1519 | ||
|
1520 | The jobs variable is set by IPython into the Python builtin namespace. | |
|
1521 | If you ever declare a variable named 'jobs', you will shadow this name. | |
|
1522 | You can either delete your global jobs variable to regain access to the | |
|
1523 | job manager, or make a new name and assign it manually to the manager | |
|
1524 | (stored in IPython's namespace). For example, to assign the job manager | |
|
1525 | to the Jobs name, use: | |
|
1526 | ||
|
1527 | Jobs = __builtins__.jobs | |
|
1528 | ||
|
1529 | ||
|
1530 | %bookmark: Manage IPython's bookmark system. | |
|
1531 | ||
|
1532 | %bookmark <name> - set bookmark to current dir %bookmark <name> <dir> - | |
|
1533 | set bookmark to <dir> %bookmark -l - list all bookmarks %bookmark -d | |
|
1534 |
|
|
|
1535 | ||
|
1536 | You can later on access a bookmarked folder with: %cd -b <name> or | |
|
1537 | simply '%cd <name>' if there is no directory called <name> AND there is | |
|
1538 | such a bookmark defined. | |
|
1539 | ||
|
1540 | Your bookmarks persist through IPython sessions, but they are associated | |
|
1541 | with each profile. | |
|
1542 | ||
|
1543 | ||
|
1544 | %cd: Change the current working directory. | |
|
1545 | ||
|
1546 | This command automatically maintains an internal list of directories you | |
|
1547 | visit during your IPython session, in the variable _dh. The command | |
|
1548 | %dhist shows this history nicely formatted. You can also do 'cd -<tab>' | |
|
1549 | to see directory history conveniently. | |
|
1550 | ||
|
1551 | Usage: | |
|
1552 | ||
|
1553 | cd 'dir': changes to directory 'dir'. | |
|
1554 | ||
|
1555 | cd -: changes to the last visited directory. | |
|
1556 | ||
|
1557 | cd -<n>: changes to the n-th directory in the directory history. | |
|
1558 | ||
|
1559 | cd -b <bookmark_name>: jump to a bookmark set by %bookmark (note: cd | |
|
1560 | <bookmark_name> is enough if there is no directory <bookmark_name>, but | |
|
1561 | a bookmark with the name exists.) 'cd -b <tab>' allows you to | |
|
1562 | tab-complete bookmark names. | |
|
1563 | ||
|
1564 | Options: | |
|
1565 | ||
|
1566 | -q: quiet. Do not print the working directory after the cd command is | |
|
1567 | executed. By default IPython's cd command does print this directory, | |
|
1568 | since the default prompts do not display path information. | |
|
1569 | ||
|
1570 | Note that !cd doesn't work for this purpose because the shell where | |
|
1571 | !command runs is immediately discarded after executing 'command'. | |
|
1572 | ||
|
1573 | ||
|
1574 | %color_info: Toggle color_info. | |
|
1575 | ||
|
1576 | The color_info configuration parameter controls whether colors are used | |
|
1577 | for displaying object details (by things like %psource, %pfile or the | |
|
1578 | '?' system). This function toggles this value with each call. | |
|
1579 | ||
|
1580 | Note that unless you have a fairly recent pager (less works better than | |
|
1581 | more) in your system, using colored object information displays will not | |
|
1582 | work properly. Test it and see. | |
|
1583 | ||
|
1584 | ||
|
1585 | %colors: Switch color scheme for prompts, info system and exception | |
|
1586 | handlers. | |
|
1587 | ||
|
1588 | Currently implemented schemes: NoColor, Linux, LightBG. | |
|
1589 | ||
|
1590 | Color scheme names are not case-sensitive. | |
|
1591 | ||
|
1592 | ||
|
1593 | %cpaste: Allows you to paste & execute a pre-formatted code block from | |
|
1594 | clipboard | |
|
1595 | ||
|
1596 | You must terminate the block with '-' (two minus-signs) alone on the | |
|
1597 | line. You can also provide your own sentinel with '%paste -s %%' ('%%' | |
|
1598 | is the new sentinel for this operation) | |
|
1599 | ||
|
1600 | The block is dedented prior to execution to enable execution of method | |
|
1601 | definitions. '>' and '+' characters at the beginning of a line are | |
|
1602 | ignored, to allow pasting directly from e-mails or diff files. The | |
|
1603 | executed block is also assigned to variable named 'pasted_block' for | |
|
1604 | later editing with '%edit pasted_block'. | |
|
1605 | ||
|
1606 | You can also pass a variable name as an argument, e.g. '%cpaste foo'. | |
|
1607 | This assigns the pasted block to variable 'foo' as string, without | |
|
1608 | dedenting or executing it. | |
|
1609 | ||
|
1610 | Do not be alarmed by garbled output on Windows (it's a readline bug). | |
|
1611 | Just press enter and type - (and press enter again) and the block will | |
|
1612 | be what was just pasted. | |
|
1613 | ||
|
1614 | IPython statements (magics, shell escapes) are not supported (yet). | |
|
1615 | ||
|
1616 | ||
|
1617 | %debug: Activate the interactive debugger in post-mortem mode. | |
|
1618 | ||
|
1619 | If an exception has just occurred, this lets you inspect its stack | |
|
1620 | frames interactively. Note that this will always work only on the last | |
|
1621 | traceback that occurred, so you must call this quickly after an | |
|
1622 | exception that you wish to inspect has fired, because if another one | |
|
1623 | occurs, it clobbers the previous one. | |
|
1624 | ||
|
1625 | If you want IPython to automatically do this on every exception, see the | |
|
1626 | %pdb magic for more details. | |
|
1627 | ||
|
1628 | ||
|
1629 | %dhist: Print your history of visited directories. | |
|
1630 | ||
|
1631 | %dhist -> print full history | |
|
1632 |
%dhist |
|
|
1633 | %dhist n1 n2 -> print entries between n1 and n2 (n1 not included) | |
|
1634 | ||
|
1635 | This history is automatically maintained by the %cd command, and always | |
|
1636 | available as the global list variable _dh. You can use %cd -<n> to go to | |
|
1637 | directory number <n>. | |
|
1638 | ||
|
1639 | Note that most of time, you should view directory history by entering cd | |
|
1640 | -<TAB>. | |
|
1641 | ||
|
1642 | ||
|
1643 | %dirs: Return the current directory stack. | |
|
1644 | ||
|
1645 | ||
|
1646 | %doctest_mode: Toggle doctest mode on and off. | |
|
1647 | ||
|
1648 | This mode allows you to toggle the prompt behavior between normal | |
|
1649 | IPython prompts and ones that are as similar to the default IPython | |
|
1650 | interpreter as possible. | |
|
1651 | ||
|
1652 | It also supports the pasting of code snippets that have leading 'Β»>' and | |
|
1653 | '...' prompts in them. This means that you can paste doctests from files | |
|
1654 | or docstrings (even if they have leading whitespace), and the code will | |
|
1655 | execute correctly. You can then use '%history -tn' to see the translated | |
|
1656 | history without line numbers; this will give you the input after removal | |
|
1657 | of all the leading prompts and whitespace, which can be pasted back into | |
|
1658 | an editor. | |
|
1659 | ||
|
1660 | With these features, you can switch into this mode easily whenever you | |
|
1661 | need to do testing and changes to doctests, without having to leave your | |
|
1662 | existing IPython session. | |
|
1663 | ||
|
1664 | ||
|
1665 | %ed: Alias to %edit. | |
|
1666 | ||
|
1667 | ||
|
1668 | %edit: Bring up an editor and execute the resulting code. | |
|
1669 | ||
|
1670 | Usage: %edit [options] [args] | |
|
1671 | ||
|
1672 | %edit runs IPython's editor hook. The default version of this hook is | |
|
1673 | set to call the __IPYTHON__.rc.editor command. This is read from your | |
|
1674 | environment variable $EDITOR. If this isn't found, it will default to vi | |
|
1675 | under Linux/Unix and to notepad under Windows. See the end of this | |
|
1676 | docstring for how to change the editor hook. | |
|
1677 | ||
|
1678 | You can also set the value of this editor via the command line option | |
|
1679 | '-editor' or in your ipythonrc file. This is useful if you wish to use | |
|
1680 | specifically for IPython an editor different from your typical default | |
|
1681 | (and for Windows users who typically don't set environment variables). | |
|
1682 | ||
|
1683 | This command allows you to conveniently edit multi-line code right in | |
|
1684 | your IPython session. | |
|
1685 | ||
|
1686 | If called without arguments, %edit opens up an empty editor with a | |
|
1687 | temporary file and will execute the contents of this file when you close | |
|
1688 | it (don't forget to save it!). | |
|
1689 | ||
|
1690 | Options: | |
|
1691 | ||
|
1692 | -n <number>: open the editor at a specified line number. By default, the | |
|
1693 | IPython editor hook uses the unix syntax 'editor +N filename', but you | |
|
1694 | can configure this by providing your own modified hook if your favorite | |
|
1695 | editor supports line-number specifications with a different syntax. | |
|
1696 | ||
|
1697 | -p: this will call the editor with the same data as the previous time it | |
|
1698 | was used, regardless of how long ago (in your current session) it was. | |
|
1699 | ||
|
1700 | -r: use 'raw' input. This option only applies to input taken from the | |
|
1701 | user's history. By default, the 'processed' history is used, so that | |
|
1702 | magics are loaded in their transformed version to valid Python. If this | |
|
1703 | option is given, the raw input as typed as the command line is used | |
|
1704 | instead. When you exit the editor, it will be executed by IPython's own | |
|
1705 | processor. | |
|
1706 | ||
|
1707 | -x: do not execute the edited code immediately upon exit. This is mainly | |
|
1708 | useful if you are editing programs which need to be called with command | |
|
1709 | line arguments, which you can then do using %run. | |
|
1710 | ||
|
1711 | Arguments: | |
|
1712 | ||
|
1713 | If arguments are given, the following possibilites exist: | |
|
1714 | ||
|
1715 | - The arguments are numbers or pairs of colon-separated numbers (like 1 | |
|
1716 | 4:8 9). These are interpreted as lines of previous input to be loaded | |
|
1717 | into the editor. The syntax is the same of the %macro command. | |
|
1718 | ||
|
1719 | - If the argument doesn't start with a number, it is evaluated as a | |
|
1720 | variable and its contents loaded into the editor. You can thus edit any | |
|
1721 | string which contains python code (including the result of previous edits). | |
|
1722 | ||
|
1723 | - If the argument is the name of an object (other than a string), | |
|
1724 | IPython will try to locate the file where it was defined and open the | |
|
1725 | editor at the point where it is defined. You can use '%edit function' to | |
|
1726 |
|
|
|
1727 | and have the file be executed automatically. | |
|
1728 | ||
|
1729 | If the object is a macro (see %macro for details), this opens up your | |
|
1730 | specified editor with a temporary file containing the macro's data. Upon | |
|
1731 | exit, the macro is reloaded with the contents of the file. | |
|
1732 | ||
|
1733 | Note: opening at an exact line is only supported under Unix, and some | |
|
1734 | editors (like kedit and gedit up to Gnome 2.8) do not understand the | |
|
1735 | '+NUMBER' parameter necessary for this feature. Good editors like | |
|
1736 | (X)Emacs, vi, jed, pico and joe all do. | |
|
1737 | ||
|
1738 | - If the argument is not found as a variable, IPython will look for a | |
|
1739 | file with that name (adding .py if necessary) and load it into the | |
|
1740 | editor. It will execute its contents with execfile() when you exit, | |
|
1741 | loading any code in the file into your interactive namespace. | |
|
1742 | ||
|
1743 | After executing your code, %edit will return as output the code you | |
|
1744 | typed in the editor (except when it was an existing file). This way you | |
|
1745 | can reload the code in further invocations of %edit as a variable, via | |
|
1746 | _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of the | |
|
1747 | output. | |
|
1748 | ||
|
1749 | Note that %edit is also available through the alias %ed. | |
|
1750 | ||
|
1751 | This is an example of creating a simple function inside the editor and | |
|
1752 | then modifying it. First, start up the editor:: | |
|
1753 | ||
|
1754 | In [1]: ed | |
|
1755 | Editing... done. Executing edited code... | |
|
1756 | Out[1]: 'def foo():\n print "foo() was defined in an editing session"\n' | |
|
1757 | ||
|
1758 | We can then call the function foo(): | |
|
1759 | ||
|
1760 | In [2]: foo() | |
|
1761 | foo() was defined in an editing session | |
|
1762 | ||
|
1763 | Now we edit foo. IPython automatically loads the editor with the | |
|
1764 | (temporary) file where foo() was previously defined: | |
|
1765 | ||
|
1766 | In [3]: ed foo | |
|
1767 | Editing... done. Executing edited code... | |
|
1768 | ||
|
1769 | And if we call foo() again we get the modified version: | |
|
1770 | ||
|
1771 | In [4]: foo() | |
|
1772 | foo() has now been changed! | |
|
1773 | ||
|
1774 | Here is an example of how to edit a code snippet successive times. First | |
|
1775 | we call the editor: | |
|
1776 | ||
|
1777 | In [8]: ed | |
|
1778 | Editing... done. Executing edited code... | |
|
1779 | hello | |
|
1780 | Out[8]: "print 'hello'\n" | |
|
1781 | ||
|
1782 | Now we call it again with the previous output (stored in _): | |
|
1783 | ||
|
1784 | In [9]: ed _ | |
|
1785 | Editing... done. Executing edited code... | |
|
1786 | hello world | |
|
1787 |
|
|
|
1788 | ||
|
1789 | Now we call it with the output #8 (stored in _8, also as Out[8]): | |
|
1790 | ||
|
1791 | In [10]: ed _8 | |
|
1792 | Editing... done. Executing edited code... | |
|
1793 | hello again | |
|
1794 | Out[10]: "print 'hello again'\n" | |
|
1795 | ||
|
1796 | Changing the default editor hook: | |
|
1797 | ||
|
1798 | If you wish to write your own editor hook, you can put it in a | |
|
1799 | configuration file which you load at startup time. The default hook is | |
|
1800 | defined in the IPython.hooks module, and you can use that as a starting | |
|
1801 | example for further modifications. That file also has general | |
|
1802 | instructions on how to set a new hook for use once you've defined it. | |
|
1803 | ||
|
1804 | ||
|
1805 | %env: List environment variables. | |
|
1806 | ||
|
1807 | ||
|
1808 | %exit: Exit IPython, confirming if configured to do so. | |
|
1809 | ||
|
1810 | You can configure whether IPython asks for confirmation upon exit by | |
|
1811 | setting the confirm_exit flag in the ipythonrc file. | |
|
1812 | ||
|
1813 | ||
|
1814 | %logoff: Temporarily stop logging. | |
|
1815 | ||
|
1816 | You must have previously started logging. | |
|
1817 | ||
|
1818 | ||
|
1819 | %logon: Restart logging. | |
|
1820 | ||
|
1821 | This function is for restarting logging which you've temporarily stopped | |
|
1822 | with %logoff. For starting logging for the first time, you must use the | |
|
1823 | %logstart function, which allows you to specify an optional log filename. | |
|
1824 | ||
|
1825 | ||
|
1826 | %logstart: Start logging anywhere in a session. | |
|
1827 | ||
|
1828 | %logstart [-o|-r|-t] [log_name [log_mode]] | |
|
1829 | ||
|
1830 | If no name is given, it defaults to a file named 'ipython_log.py' in | |
|
1831 | your current directory, in 'rotate' mode (see below). | |
|
1832 | ||
|
1833 | '%logstart name' saves to file 'name' in 'backup' mode. It saves your | |
|
1834 | history up to that point and then continues logging. | |
|
1835 | ||
|
1836 | %logstart takes a second optional parameter: logging mode. This can be | |
|
1837 | one of (note that the modes are given unquoted): | |
|
1838 | append: well, that says it. | |
|
1839 | backup: rename (if exists) to name and start name. | |
|
1840 | global: single logfile in your home dir, appended to. | |
|
1841 | over : overwrite existing log. | |
|
1842 | rotate: create rotating logs name.1 , name.2 , etc. | |
|
1843 | ||
|
1844 | Options: | |
|
1845 | ||
|
1846 | -o: log also IPython's output. In this mode, all commands which generate | |
|
1847 | an Out[NN] prompt are recorded to the logfile, right after their | |
|
1848 | corresponding input line. The output lines are always prepended with a | |
|
1849 | '#[Out]# ' marker, so that the log remains valid Python code. | |
|
1850 | ||
|
1851 | Since this marker is always the same, filtering only the output from a | |
|
1852 | log is very easy, using for example a simple awk call: | |
|
1853 | ||
|
1854 | awk -F'# | |
|
1855 | ||
|
1856 | \begin{displaymath}Out\end{displaymath} | |
|
1857 | ||
|
1858 | # ' 'if($2) print $2' ipython_log.py | |
|
1859 | ||
|
1860 | -r: log 'raw' input. Normally, IPython's logs contain the processed | |
|
1861 | input, so that user lines are logged in their final form, converted into | |
|
1862 | valid Python. For example, %Exit is logged as '_ip.magic("Exit"). If the | |
|
1863 | -r flag is given, all input is logged exactly as typed, with no | |
|
1864 | transformations applied. | |
|
1865 | ||
|
1866 | -t: put timestamps before each input line logged (these are put in | |
|
1867 | comments). | |
|
1868 | ||
|
1869 | ||
|
1870 | %logstate: Print the status of the logging system. | |
|
1871 | ||
|
1872 | ||
|
1873 | %logstop: Fully stop logging and close log file. | |
|
1874 | ||
|
1875 | In order to start logging again, a new %logstart call needs to be made, | |
|
1876 | possibly (though not necessarily) with a new filename, mode and other | |
|
1877 | options. | |
|
1878 | ||
|
1879 | ||
|
1880 | %lsmagic: List currently available magic functions. | |
|
1881 | ||
|
1882 | ||
|
1883 | %macro: Define a set of input lines as a macro for future re-execution. | |
|
1884 | ||
|
1885 | Usage: | |
|
1886 | %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ... | |
|
1887 | ||
|
1888 | Options: | |
|
1889 | ||
|
1890 | -r: use 'raw' input. By default, the 'processed' history is used, so | |
|
1891 | that magics are loaded in their transformed version to valid Python. If | |
|
1892 | this option is given, the raw input as typed as the command line is used | |
|
1893 | instead. | |
|
1894 | ||
|
1895 | This will define a global variable called 'name' which is a string made | |
|
1896 | of joining the slices and lines you specify (n1,n2,... numbers above) | |
|
1897 | from your input history into a single string. This variable acts like an | |
|
1898 | automatic function which re-executes those lines as if you had typed | |
|
1899 | them. You just type 'name' at the prompt and the code executes. | |
|
1900 | ||
|
1901 | The notation for indicating number ranges is: n1-n2 means 'use line | |
|
1902 | numbers n1,...n2' (the endpoint is included). That is, '5-7' means using | |
|
1903 | the lines numbered 5,6 and 7. | |
|
1904 | ||
|
1905 | Note: as a 'hidden' feature, you can also use traditional python slice | |
|
1906 | notation, where N:M means numbers N through M-1. | |
|
1907 | ||
|
1908 | For example, if your history contains (%hist prints it): | |
|
1909 | ||
|
1910 | 44: x=1 | |
|
1911 | 45: y=3 | |
|
1912 | 46: z=x+y | |
|
1913 | 47: print x | |
|
1914 | 48: a=5 | |
|
1915 | 49: print 'x',x,'y',y | |
|
1916 | ||
|
1917 | you can create a macro with lines 44 through 47 (included) and line 49 | |
|
1918 | called my_macro with: | |
|
1919 | ||
|
1920 | In [51]: %macro my_macro 44-47 49 | |
|
1921 | ||
|
1922 | Now, typing 'my_macro' (without quotes) will re-execute all this code in | |
|
1923 | one pass. | |
|
1924 | ||
|
1925 | You don't need to give the line-numbers in order, and any given line | |
|
1926 | number can appear multiple times. You can assemble macros with any lines | |
|
1927 | from your input history in any order. | |
|
1928 | ||
|
1929 | The macro is a simple object which holds its value in an attribute, but | |
|
1930 | IPython's display system checks for macros and executes them as code | |
|
1931 | instead of printing them when you type their name. | |
|
1932 | ||
|
1933 | You can view a macro's contents by explicitly printing it with: | |
|
1934 | ||
|
1935 | 'print macro_name'. | |
|
1936 | ||
|
1937 | For one-off cases which DON'T contain magic function calls in them you | |
|
1938 | can obtain similar results by explicitly executing slices from your | |
|
1939 | input history with: | |
|
1940 | ||
|
1941 | In [60]: exec In[44:48]+In[49] | |
|
1942 | ||
|
1943 | ||
|
1944 | %magic: Print information about the magic function system. | |
|
1945 | ||
|
1946 | ||
|
1947 | %page: Pretty print the object and display it through a pager. | |
|
1948 | ||
|
1949 | %page [options] OBJECT | |
|
1950 | ||
|
1951 | If no object is given, use _ (last output). | |
|
1952 | ||
|
1953 | Options: | |
|
1954 | ||
|
1955 | -r: page str(object), don't pretty-print it. | |
|
1956 | ||
|
1957 | ||
|
1958 | %pdb: Control the automatic calling of the pdb interactive debugger. | |
|
1959 | ||
|
1960 | Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without | |
|
1961 | argument it works as a toggle. | |
|
1962 | ||
|
1963 | When an exception is triggered, IPython can optionally call the | |
|
1964 | interactive pdb debugger after the traceback printout. %pdb toggles this | |
|
1965 | feature on and off. | |
|
1966 | ||
|
1967 | The initial state of this feature is set in your ipythonrc configuration | |
|
1968 | file (the variable is called 'pdb'). | |
|
1969 | ||
|
1970 | If you want to just activate the debugger AFTER an exception has fired, | |
|
1971 | without having to type '%pdb on' and rerunning your code, you can use | |
|
1972 | the %debug magic. | |
|
1973 | ||
|
1974 | ||
|
1975 | %pdef: Print the definition header for any callable object. | |
|
1976 | ||
|
1977 | If the object is a class, print the constructor information. | |
|
1978 | ||
|
1979 | ||
|
1980 | %pdoc: Print the docstring for an object. | |
|
1981 | ||
|
1982 | If the given object is a class, it will print both the class and the | |
|
1983 | constructor docstrings. | |
|
1984 | ||
|
1985 | ||
|
1986 | %pfile: Print (or run through pager) the file where an object is defined. | |
|
1987 | ||
|
1988 | The file opens at the line where the object definition begins. IPython | |
|
1989 | will honor the environment variable PAGER if set, and otherwise will do | |
|
1990 | its best to print the file in a convenient form. | |
|
1991 | ||
|
1992 | If the given argument is not an object currently defined, IPython will | |
|
1993 | try to interpret it as a filename (automatically adding a .py extension | |
|
1994 | if needed). You can thus use %pfile as a syntax highlighting code viewer. | |
|
1995 | ||
|
1996 | ||
|
1997 | %pinfo: Provide detailed information about an object. | |
|
1998 | ||
|
1999 | '%pinfo object' is just a synonym for object? or ?object. | |
|
2000 | ||
|
2001 | ||
|
2002 | %popd: Change to directory popped off the top of the stack. | |
|
2003 | ||
|
2004 | ||
|
2005 | %profile: Print your currently active IPyhton profile. | |
|
2006 | ||
|
2007 | ||
|
2008 | %prun: Run a statement through the python code profiler. | |
|
2009 | ||
|
2010 | Usage: | |
|
2011 | %prun [options] statement | |
|
2012 | ||
|
2013 | The given statement (which doesn't require quote marks) is run via the | |
|
2014 | python profiler in a manner similar to the profile.run() function. | |
|
2015 | Namespaces are internally managed to work correctly; profile.run cannot | |
|
2016 | be used in IPython because it makes certain assumptions about namespaces | |
|
2017 | which do not hold under IPython. | |
|
2018 | ||
|
2019 | Options: | |
|
2020 | ||
|
2021 | -l <limit>: you can place restrictions on what or how much of the | |
|
2022 | profile gets printed. The limit value can be: | |
|
2023 | ||
|
2024 | * A string: only information for function names containing this string | |
|
2025 | is printed. | |
|
2026 | ||
|
2027 | * An integer: only these many lines are printed. | |
|
2028 | ||
|
2029 | * A float (between 0 and 1): this fraction of the report is printed (for | |
|
2030 | example, use a limit of 0.4 to see the topmost 40% only). | |
|
2031 | ||
|
2032 | You can combine several limits with repeated use of the option. For | |
|
2033 | example, '-l __init__ -l 5' will print only the topmost 5 lines of | |
|
2034 | information about class constructors. | |
|
2035 | ||
|
2036 | -r: return the pstats.Stats object generated by the profiling. This | |
|
2037 | object has all the information about the profile in it, and you can | |
|
2038 | later use it for further analysis or in other functions. | |
|
2039 | ||
|
2040 | -s <key>: sort profile by given key. You can provide more than one key | |
|
2041 | by using the option several times: '-s key1 -s key2 -s key3...'. The | |
|
2042 | default sorting key is 'time'. | |
|
2043 | ||
|
2044 | The following is copied verbatim from the profile documentation | |
|
2045 | referenced below: | |
|
2046 | ||
|
2047 | When more than one key is provided, additional keys are used as | |
|
2048 | secondary criteria when the there is equality in all keys selected | |
|
2049 | before them. | |
|
2050 | ||
|
2051 | Abbreviations can be used for any key names, as long as the abbreviation | |
|
2052 | is unambiguous. The following are the keys currently defined: | |
|
2053 | ||
|
2054 | Valid Arg Meaning | |
|
2055 | "calls" call count | |
|
2056 | "cumulative" cumulative time | |
|
2057 | "file" file name | |
|
2058 |
|
|
|
2059 | "pcalls" primitive call count | |
|
2060 | "line" line number | |
|
2061 | "name" function name | |
|
2062 | "nfl" name/file/line | |
|
2063 | "stdname" standard name | |
|
2064 | "time" internal time | |
|
2065 | ||
|
2066 | Note that all sorts on statistics are in descending order (placing most | |
|
2067 | time consuming items first), where as name, file, and line number | |
|
2068 | searches are in ascending order (i.e., alphabetical). The subtle | |
|
2069 | distinction between "nfl" and "stdname" is that the standard name is a | |
|
2070 | sort of the name as printed, which means that the embedded line numbers | |
|
2071 | get compared in an odd way. For example, lines 3, 20, and 40 would (if | |
|
2072 | the file names were the same) appear in the string order "20" "3" and | |
|
2073 | "40". In contrast, "nfl" does a numeric compare of the line numbers. In | |
|
2074 | fact, sort_stats("nfl") is the same as sort_stats("name", "file", "line"). | |
|
2075 | ||
|
2076 | -T <filename>: save profile results as shown on screen to a text file. | |
|
2077 | The profile is still shown on screen. | |
|
2078 | ||
|
2079 | -D <filename>: save (via dump_stats) profile statistics to given | |
|
2080 | filename. This data is in a format understod by the pstats module, and | |
|
2081 | is generated by a call to the dump_stats() method of profile objects. | |
|
2082 | The profile is still shown on screen. | |
|
2083 | ||
|
2084 | If you want to run complete programs under the profiler's control, use | |
|
2085 | '%run -p [prof_opts] filename.py [args to program]' where prof_opts | |
|
2086 | contains profiler specific options as described here. | |
|
2087 | ||
|
2088 | You can read the complete documentation for the profile module with: | |
|
2089 | In [1]: import profile; profile.help() | |
|
2090 | ||
|
2091 | ||
|
2092 | %psearch: Search for object in namespaces by wildcard. | |
|
2093 | ||
|
2094 | %psearch [options] PATTERN [OBJECT TYPE] | |
|
2095 | ||
|
2096 | Note: ? can be used as a synonym for %psearch, at the beginning or at | |
|
2097 | the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the | |
|
2098 | rest of the command line must be unchanged (options come first), so for | |
|
2099 | example the following forms are equivalent | |
|
2100 | ||
|
2101 | %psearch -i a* function -i a* function? ?-i a* function | |
|
2102 | ||
|
2103 | Arguments: | |
|
2104 | ||
|
2105 | PATTERN | |
|
2106 | ||
|
2107 | where PATTERN is a string containing * as a wildcard similar to its use | |
|
2108 | in a shell. The pattern is matched in all namespaces on the search path. | |
|
2109 | By default objects starting with a single _ are not matched, many | |
|
2110 | IPython generated objects have a single underscore. The default is case | |
|
2111 | insensitive matching. Matching is also done on the attributes of objects | |
|
2112 | and not only on the objects in a module. | |
|
2113 | ||
|
2114 | [OBJECT TYPE] | |
|
2115 | ||
|
2116 | Is the name of a python type from the types module. The name is given in | |
|
2117 | lowercase without the ending type, ex. StringType is written string. By | |
|
2118 | adding a type here only objects matching the given type are matched. | |
|
2119 | Using all here makes the pattern match all types (this is the default). | |
|
2120 | ||
|
2121 | Options: | |
|
2122 | ||
|
2123 | -a: makes the pattern match even objects whose names start with a single | |
|
2124 | underscore. These names are normally ommitted from the search. | |
|
2125 | ||
|
2126 | -i/-c: make the pattern case insensitive/sensitive. If neither of these | |
|
2127 | options is given, the default is read from your ipythonrc file. The | |
|
2128 | option name which sets this value is 'wildcards_case_sensitive'. If this | |
|
2129 | option is not specified in your ipythonrc file, IPython's internal | |
|
2130 | default is to do a case sensitive search. | |
|
2131 | ||
|
2132 | -e/-s NAMESPACE: exclude/search a given namespace. The pattern you | |
|
2133 | specifiy can be searched in any of the following namespaces: 'builtin', | |
|
2134 | 'user', 'user_global','internal', 'alias', where 'builtin' and 'user' | |
|
2135 | are the search defaults. Note that you should not use quotes when | |
|
2136 | specifying namespaces. | |
|
2137 | ||
|
2138 | 'Builtin' contains the python module builtin, 'user' contains all user | |
|
2139 | data, 'alias' only contain the shell aliases and no python objects, | |
|
2140 | 'internal' contains objects used by IPython. The 'user_global' namespace | |
|
2141 | is only used by embedded IPython instances, and it contains module-level | |
|
2142 | globals. You can add namespaces to the search with -s or exclude them | |
|
2143 | with -e (these options can be given more than once). | |
|
2144 | ||
|
2145 | Examples: | |
|
2146 | ||
|
2147 | %psearch a* -> objects beginning with an a %psearch -e builtin a* -> | |
|
2148 | objects NOT in the builtin space starting in a %psearch a* function -> | |
|
2149 | all functions beginning with an a %psearch re.e* -> objects beginning | |
|
2150 | with an e in module re %psearch r*.e* -> objects that start with e in | |
|
2151 | modules starting in r %psearch r*.* string -> all strings in modules | |
|
2152 | beginning with r | |
|
2153 | ||
|
2154 | Case sensitve search: | |
|
2155 | ||
|
2156 | %psearch -c a* list all object beginning with lower case a | |
|
2157 | ||
|
2158 | Show objects beginning with a single _: | |
|
2159 | ||
|
2160 | %psearch -a _* list objects beginning with a single underscore | |
|
2161 | ||
|
2162 | ||
|
2163 | %psource: Print (or run through pager) the source code for an object. | |
|
2164 | ||
|
2165 | ||
|
2166 | %pushd: Place the current dir on stack and change directory. | |
|
2167 | ||
|
2168 | Usage: | |
|
2169 | %pushd ['dirname'] | |
|
2170 | ||
|
2171 | ||
|
2172 | %pwd: Return the current working directory path. | |
|
2173 | ||
|
2174 | ||
|
2175 | %pycat: Show a syntax-highlighted file through a pager. | |
|
2176 | ||
|
2177 | This magic is similar to the cat utility, but it will assume the file to | |
|
2178 | be Python source and will show it with syntax highlighting. | |
|
2179 | ||
|
2180 | ||
|
2181 | %quickref: Show a quick reference sheet | |
|
2182 | ||
|
2183 | ||
|
2184 | %quit: Exit IPython, confirming if configured to do so (like %exit) | |
|
2185 | ||
|
2186 | ||
|
2187 | %r: Repeat previous input. | |
|
2188 | ||
|
2189 | Note: Consider using the more powerfull %rep instead! | |
|
2190 | ||
|
2191 | If given an argument, repeats the previous command which starts with the | |
|
2192 | same string, otherwise it just repeats the previous input. | |
|
2193 | ||
|
2194 | Shell escaped commands (with ! as first character) are not recognized by | |
|
2195 | this system, only pure python code and magic commands. | |
|
2196 | ||
|
2197 | ||
|
2198 | %rehashx: Update the alias table with all executable files in $PATH. | |
|
2199 | ||
|
2200 | This version explicitly checks that every entry in $PATH is a file with | |
|
2201 | execute access (os.X_OK), so it is much slower than %rehash. | |
|
2202 | ||
|
2203 | Under Windows, it checks executability as a match agains a '|'-separated | |
|
2204 | string of extensions, stored in the IPython config variable | |
|
2205 | win_exec_ext. This defaults to 'exe|com|bat'. | |
|
2206 | ||
|
2207 | This function also resets the root module cache of module completer, | |
|
2208 | used on slow filesystems. | |
|
2209 | ||
|
2210 | ||
|
2211 | %reset: Resets the namespace by removing all names defined by the user. | |
|
2212 | ||
|
2213 | Input/Output history are left around in case you need them. | |
|
2214 | ||
|
2215 | ||
|
2216 | %run: Run the named file inside IPython as a program. | |
|
2217 | ||
|
2218 | Usage: | |
|
2219 | %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args] | |
|
2220 | ||
|
2221 | Parameters after the filename are passed as command-line arguments to | |
|
2222 | the program (put in sys.argv). Then, control returns to IPython's prompt. | |
|
2223 | ||
|
2224 | This is similar to running at a system prompt: | |
|
2225 | $ python file args | |
|
2226 | but with the advantage of giving you IPython's tracebacks, and of | |
|
2227 | loading all variables into your interactive namespace for further use | |
|
2228 | (unless -p is used, see below). | |
|
2229 | ||
|
2230 | The file is executed in a namespace initially consisting only of | |
|
2231 | __name__=='__main__' and sys.argv constructed as indicated. It thus sees | |
|
2232 | its environment as if it were being run as a stand-alone program (except | |
|
2233 | for sharing global objects such as previously imported modules). But | |
|
2234 | after execution, the IPython interactive namespace gets updated with all | |
|
2235 | variables defined in the program (except for __name__ and sys.argv). | |
|
2236 | This allows for very convenient loading of code for interactive work, | |
|
2237 | while giving each program a 'clean sheet' to run in. | |
|
2238 | ||
|
2239 | Options: | |
|
2240 | ||
|
2241 | -n: __name__ is NOT set to '__main__', but to the running file's name | |
|
2242 | without extension (as python does under import). This allows running | |
|
2243 | scripts and reloading the definitions in them without calling code | |
|
2244 | protected by an ' if __name__ == "__main__" ' clause. | |
|
2245 | ||
|
2246 | -i: run the file in IPython's namespace instead of an empty one. This is | |
|
2247 | useful if you are experimenting with code written in a text editor which | |
|
2248 | depends on variables defined interactively. | |
|
2249 | ||
|
2250 | -e: ignore sys.exit() calls or SystemExit exceptions in the script being | |
|
2251 | run. This is particularly useful if IPython is being used to run | |
|
2252 | unittests, which always exit with a sys.exit() call. In such cases you | |
|
2253 | are interested in the output of the test results, not in seeing a | |
|
2254 | traceback of the unittest module. | |
|
2255 | ||
|
2256 | -t: print timing information at the end of the run. IPython will give | |
|
2257 | you an estimated CPU time consumption for your script, which under Unix | |
|
2258 | uses the resource module to avoid the wraparound problems of | |
|
2259 | time.clock(). Under Unix, an estimate of time spent on system tasks is | |
|
2260 | also given (for Windows platforms this is reported as 0.0). | |
|
2261 | ||
|
2262 | If -t is given, an additional -N<N> option can be given, where <N> must | |
|
2263 | be an integer indicating how many times you want the script to run. The | |
|
2264 | final timing report will include total and per run results. | |
|
2265 | ||
|
2266 | For example (testing the script uniq_stable.py): | |
|
2267 | ||
|
2268 | In [1]: run -t uniq_stable | |
|
2269 | ||
|
2270 | IPython CPU timings (estimated): | |
|
2271 | User : 0.19597 s. | |
|
2272 | System: 0.0 s. | |
|
2273 | ||
|
2274 | In [2]: run -t -N5 uniq_stable | |
|
2275 | ||
|
2276 | IPython CPU timings (estimated): | |
|
2277 | Total runs performed: 5 | |
|
2278 | Times : Total Per run | |
|
2279 | User : 0.910862 s, 0.1821724 s. | |
|
2280 |
|
|
|
2281 | ||
|
2282 | -d: run your program under the control of pdb, the Python debugger. This | |
|
2283 | allows you to execute your program step by step, watch variables, etc. | |
|
2284 | Internally, what IPython does is similar to calling: | |
|
2285 | ||
|
2286 | pdb.run('execfile("YOURFILENAME")') | |
|
2287 | ||
|
2288 | with a breakpoint set on line 1 of your file. You can change the line | |
|
2289 | number for this automatic breakpoint to be <N> by using the -bN option | |
|
2290 | (where N must be an integer). For example: | |
|
2291 | ||
|
2292 | %run -d -b40 myscript | |
|
2293 | ||
|
2294 | will set the first breakpoint at line 40 in myscript.py. Note that the | |
|
2295 | first breakpoint must be set on a line which actually does something | |
|
2296 | (not a comment or docstring) for it to stop execution. | |
|
2297 | ||
|
2298 | When the pdb debugger starts, you will see a (Pdb) prompt. You must | |
|
2299 | first enter 'c' (without qoutes) to start execution up to the first | |
|
2300 | breakpoint. | |
|
2301 | ||
|
2302 | Entering 'help' gives information about the use of the debugger. You can | |
|
2303 | easily see pdb's full documentation with "import pdb;pdb.help()" at a | |
|
2304 | prompt. | |
|
2305 | ||
|
2306 | -p: run program under the control of the Python profiler module (which | |
|
2307 | prints a detailed report of execution times, function calls, etc). | |
|
2308 | ||
|
2309 | You can pass other options after -p which affect the behavior of the | |
|
2310 | profiler itself. See the docs for %prun for details. | |
|
2311 | ||
|
2312 | In this mode, the program's variables do NOT propagate back to the | |
|
2313 | IPython interactive namespace (because they remain in the namespace | |
|
2314 | where the profiler executes them). | |
|
2315 | ||
|
2316 | Internally this triggers a call to %prun, see its documentation for | |
|
2317 | details on the options available specifically for profiling. | |
|
2318 | ||
|
2319 | There is one special usage for which the text above doesn't apply: if | |
|
2320 | the filename ends with .ipy, the file is run as ipython script, just as | |
|
2321 | if the commands were written on IPython prompt. | |
|
2322 | ||
|
2323 | ||
|
2324 | %runlog: Run files as logs. | |
|
2325 | ||
|
2326 | Usage: | |
|
2327 | %runlog file1 file2 ... | |
|
2328 | ||
|
2329 | Run the named files (treating them as log files) in sequence inside the | |
|
2330 | interpreter, and return to the prompt. This is much slower than %run | |
|
2331 | because each line is executed in a try/except block, but it allows | |
|
2332 | running files with syntax errors in them. | |
|
2333 | ||
|
2334 | Normally IPython will guess when a file is one of its own logfiles, so | |
|
2335 | you can typically use %run even for logs. This shorthand allows you to | |
|
2336 | force any file to be treated as a log file. | |
|
2337 | ||
|
2338 | ||
|
2339 | %save: Save a set of lines to a given filename. | |
|
2340 | ||
|
2341 | Usage: | |
|
2342 | %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ... | |
|
2343 | ||
|
2344 | Options: | |
|
2345 | ||
|
2346 | -r: use 'raw' input. By default, the 'processed' history is used, so | |
|
2347 | that magics are loaded in their transformed version to valid Python. If | |
|
2348 | this option is given, the raw input as typed as the command line is used | |
|
2349 | instead. | |
|
2350 | ||
|
2351 | This function uses the same syntax as %macro for line extraction, but | |
|
2352 | instead of creating a macro it saves the resulting string to the | |
|
2353 | filename you specify. | |
|
2354 | ||
|
2355 | It adds a '.py' extension to the file if you don't do so yourself, and | |
|
2356 | it asks for confirmation before overwriting existing files. | |
|
2357 | ||
|
2358 | ||
|
2359 | %sc: Shell capture - execute a shell command and capture its output. | |
|
2360 | ||
|
2361 | DEPRECATED. Suboptimal, retained for backwards compatibility. | |
|
2362 | ||
|
2363 | You should use the form 'var = !command' instead. Example: | |
|
2364 | ||
|
2365 | "%sc -l myfiles = ls " should now be written as | |
|
2366 | ||
|
2367 | "myfiles = !ls " | |
|
2368 | ||
|
2369 | myfiles.s, myfiles.l and myfiles.n still apply as documented below. | |
|
2370 | ||
|
2371 | - %sc [options] varname=command | |
|
2372 | ||
|
2373 | IPython will run the given command using commands.getoutput(), and will | |
|
2374 | then update the user's interactive namespace with a variable called | |
|
2375 | varname, containing the value of the call. Your command can contain | |
|
2376 | shell wildcards, pipes, etc. | |
|
2377 | ||
|
2378 | The '=' sign in the syntax is mandatory, and the variable name you | |
|
2379 | supply must follow Python's standard conventions for valid names. | |
|
2380 | ||
|
2381 | (A special format without variable name exists for internal use) | |
|
2382 | ||
|
2383 | Options: | |
|
2384 | ||
|
2385 | -l: list output. Split the output on newlines into a list before | |
|
2386 | assigning it to the given variable. By default the output is stored as a | |
|
2387 | single string. | |
|
2388 | ||
|
2389 | -v: verbose. Print the contents of the variable. | |
|
2390 | ||
|
2391 | In most cases you should not need to split as a list, because the | |
|
2392 | returned value is a special type of string which can automatically | |
|
2393 | provide its contents either as a list (split on newlines) or as a | |
|
2394 | space-separated string. These are convenient, respectively, either for | |
|
2395 | sequential processing or to be passed to a shell command. | |
|
2396 | ||
|
2397 | For example: | |
|
2398 | ||
|
2399 | # Capture into variable a In [9]: sc a=ls *py | |
|
2400 | ||
|
2401 | # a is a string with embedded newlines In [10]: a Out[10]: 'setup.py | |
|
2402 | win32_manual_post_install.py' | |
|
2403 | ||
|
2404 | # which can be seen as a list: In [11]: a.l Out[11]: ['setup.py', | |
|
2405 | 'win32_manual_post_install.py'] | |
|
2406 | ||
|
2407 | # or as a whitespace-separated string: In [12]: a.s Out[12]: 'setup.py | |
|
2408 | win32_manual_post_install.py' | |
|
2409 | ||
|
2410 | # a.s is useful to pass as a single command line: In [13]: !wc -l $a.s | |
|
2411 | 146 setup.py 130 win32_manual_post_install.py 276 total | |
|
2412 | ||
|
2413 | # while the list form is useful to loop over: In [14]: for f in a.l: | |
|
2414 | ....: !wc -l $f ....: 146 setup.py 130 win32_manual_post_install.py | |
|
2415 | ||
|
2416 | Similiarly, the lists returned by the -l option are also special, in the | |
|
2417 | sense that you can equally invoke the .s attribute on them to | |
|
2418 | automatically get a whitespace-separated string from their contents: | |
|
2419 | ||
|
2420 | In [1]: sc -l b=ls *py | |
|
2421 | ||
|
2422 | In [2]: b Out[2]: ['setup.py', 'win32_manual_post_install.py'] | |
|
2423 | ||
|
2424 | In [3]: b.s Out[3]: 'setup.py win32_manual_post_install.py' | |
|
2425 | ||
|
2426 | In summary, both the lists and strings used for ouptut capture have the | |
|
2427 | following special attributes: | |
|
2428 | ||
|
2429 | .l (or .list) : value as list. .n (or .nlstr): value as | |
|
2430 | newline-separated string. .s (or .spstr): value as space-separated string. | |
|
2431 | ||
|
2432 | ||
|
2433 | %sx: Shell execute - run a shell command and capture its output. | |
|
2434 | ||
|
2435 | %sx command | |
|
2436 | ||
|
2437 | IPython will run the given command using commands.getoutput(), and | |
|
2438 | return the result formatted as a list (split on '\n'). Since the output | |
|
2439 | is _returned_, it will be stored in ipython's regular output cache | |
|
2440 | Out[N] and in the '_N' automatic variables. | |
|
2441 | ||
|
2442 | Notes: | |
|
2443 | ||
|
2444 | 1) If an input line begins with '!!', then %sx is automatically invoked. | |
|
2445 | That is, while: !ls causes ipython to simply issue system('ls'), typing | |
|
2446 | !!ls is a shorthand equivalent to: %sx ls | |
|
2447 | ||
|
2448 | 2) %sx differs from %sc in that %sx automatically splits into a list, | |
|
2449 | like '%sc -l'. The reason for this is to make it as easy as possible to | |
|
2450 | process line-oriented shell output via further python commands. %sc is | |
|
2451 | meant to provide much finer control, but requires more typing. | |
|
2452 | ||
|
2453 | 3) Just like %sc -l, this is a list with special attributes: | |
|
2454 | ||
|
2455 | .l (or .list) : value as list. .n (or .nlstr): value as | |
|
2456 | newline-separated string. .s (or .spstr): value as whitespace-separated | |
|
2457 | string. | |
|
2458 | ||
|
2459 | This is very useful when trying to use such lists as arguments to system | |
|
2460 | commands. | |
|
2461 | ||
|
2462 | ||
|
2463 | %system_verbose: Set verbose printing of system calls. | |
|
2464 | ||
|
2465 | If called without an argument, act as a toggle | |
|
2466 | ||
|
2467 | ||
|
2468 | %time: Time execution of a Python statement or expression. | |
|
2469 | ||
|
2470 | The CPU and wall clock times are printed, and the value of the | |
|
2471 | expression (if any) is returned. Note that under Win32, system time is | |
|
2472 | always reported as 0, since it can not be measured. | |
|
2473 | ||
|
2474 | This function provides very basic timing functionality. In Python 2.3, | |
|
2475 | the timeit module offers more control and sophistication, so this could | |
|
2476 | be rewritten to use it (patches welcome). | |
|
2477 | ||
|
2478 | Some examples: | |
|
2479 | ||
|
2480 | In [1]: time 2**128 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s | |
|
2481 | Wall time: 0.00 Out[1]: 340282366920938463463374607431768211456L | |
|
2482 | ||
|
2483 | In [2]: n = 1000000 | |
|
2484 | ||
|
2485 | In [3]: time sum(range(n)) CPU times: user 1.20 s, sys: 0.05 s, total: | |
|
2486 | 1.25 s Wall time: 1.37 Out[3]: 499999500000L | |
|
2487 | ||
|
2488 | In [4]: time print 'hello world' hello world CPU times: user 0.00 s, | |
|
2489 | sys: 0.00 s, total: 0.00 s Wall time: 0.00 | |
|
2490 | ||
|
2491 | Note that the time needed by Python to compile the given expression will | |
|
2492 | be reported if it is more than 0.1s. In this example, the actual | |
|
2493 | exponentiation is done by Python at compilation time, so while the | |
|
2494 | expression can take a noticeable amount of time to compute, that time is | |
|
2495 | purely due to the compilation: | |
|
2496 | ||
|
2497 | In [5]: time 3**9999; CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s | |
|
2498 | Wall time: 0.00 s | |
|
2499 | ||
|
2500 | In [6]: time 3**999999; CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 | |
|
2501 | s Wall time: 0.00 s Compiler : 0.78 s | |
|
2502 | ||
|
2503 | ||
|
2504 | %timeit: Time execution of a Python statement or expression | |
|
2505 | ||
|
2506 | Usage: | |
|
2507 | %timeit [-n<N> -r<R> [-t|-c]] statement | |
|
2508 | ||
|
2509 | Time execution of a Python statement or expression using the timeit module. | |
|
2510 | ||
|
2511 | Options: -n<N>: execute the given statement <N> times in a loop. If this | |
|
2512 | value is not given, a fitting value is chosen. | |
|
2513 | ||
|
2514 | -r<R>: repeat the loop iteration <R> times and take the best result. | |
|
2515 | Default: 3 | |
|
2516 | ||
|
2517 | -t: use time.time to measure the time, which is the default on Unix. | |
|
2518 | This function measures wall time. | |
|
2519 | ||
|
2520 | -c: use time.clock to measure the time, which is the default on Windows | |
|
2521 | and measures wall time. On Unix, resource.getrusage is used instead and | |
|
2522 | returns the CPU user time. | |
|
2523 | ||
|
2524 | -p<P>: use a precision of <P> digits to display the timing result. | |
|
2525 | Default: 3 | |
|
2526 | ||
|
2527 | Examples: | |
|
2528 | In [1]: %timeit pass 10000000 loops, best of 3: 53.3 ns per loop | |
|
2529 | ||
|
2530 | In [2]: u = None | |
|
2531 | ||
|
2532 | In [3]: %timeit u is None 10000000 loops, best of 3: 184 ns per loop | |
|
2533 | ||
|
2534 | In [4]: %timeit -r 4 u == None 1000000 loops, best of 4: 242 ns per loop | |
|
2535 | ||
|
2536 | In [5]: import time | |
|
2537 | ||
|
2538 | In [6]: %timeit -n1 time.sleep(2) 1 loops, best of 3: 2 s per loop | |
|
2539 | ||
|
2540 | The times reported by %timeit will be slightly higher than those | |
|
2541 | reported by the timeit.py script when variables are accessed. This is | |
|
2542 | due to the fact that %timeit executes the statement in the namespace of | |
|
2543 | the shell, compared with timeit.py, which uses a single setup statement | |
|
2544 | to import function or create variables. Generally, the bias does not | |
|
2545 | matter as long as results from timeit.py are not mixed with those from | |
|
2546 | %timeit. | |
|
2547 | ||
|
2548 | ||
|
2549 | %unalias: Remove an alias | |
|
2550 | ||
|
2551 | ||
|
2552 | %upgrade: Upgrade your IPython installation | |
|
2553 | ||
|
2554 | This will copy the config files that don't yet exist in your ipython dir | |
|
2555 | from the system config dir. Use this after upgrading IPython if you | |
|
2556 | don't wish to delete your .ipython dir. | |
|
2557 | ||
|
2558 | Call with -nolegacy to get rid of ipythonrc* files (recommended for new | |
|
2559 | users) | |
|
2560 | ||
|
2561 | ||
|
2562 | %who: Print all interactive variables, with some minimal formatting. | |
|
2563 | ||
|
2564 | If any arguments are given, only variables whose type matches one of | |
|
2565 | these are printed. For example: | |
|
2566 | ||
|
2567 | %who function str | |
|
2568 | ||
|
2569 | will only list functions and strings, excluding all other types of | |
|
2570 | variables. To find the proper type names, simply use type(var) at a | |
|
2571 | command line to see how python prints type names. For example: | |
|
2572 | ||
|
2573 | In [1]: type('hello') | |
|
2574 | Out[1]: <type 'str'> | |
|
2575 | ||
|
2576 | indicates that the type name for strings is 'str'. | |
|
2577 | ||
|
2578 | %who always excludes executed names loaded through your configuration | |
|
2579 | file and things which are internal to IPython. | |
|
2580 | ||
|
2581 | This is deliberate, as typically you may load many modules and the | |
|
2582 | purpose of %who is to show you only what you've manually defined. | |
|
2583 | ||
|
2584 | ||
|
2585 | %who_ls: Return a sorted list of all interactive variables. | |
|
2586 | ||
|
2587 | If arguments are given, only variables of types matching these arguments | |
|
2588 | are returned. | |
|
2589 | ||
|
2590 | ||
|
2591 | %whos: Like %who, but gives some extra information about each variable. | |
|
2592 | ||
|
2593 | The same type filtering of %who can be applied here. | |
|
2594 | ||
|
2595 | For all variables, the type is printed. Additionally it prints: | |
|
2596 | ||
|
2597 | - For ,[],(): their length. | |
|
2598 | ||
|
2599 | - For numpy and Numeric arrays, a summary with shape, number of | |
|
2600 | elements, typecode and size in memory. | |
|
2601 | ||
|
2602 | - Everything else: a string representation, snipping their middle if too | |
|
2603 | long. | |
|
2604 | ||
|
2605 | ||
|
2606 | %xmode: Switch modes for the exception handlers. | |
|
2607 | ||
|
2608 | Valid modes: Plain, Context and Verbose. | |
|
2609 | ||
|
2610 | If called without arguments, acts as a toggle. | |
|
2611 | ||
|
2612 | ||
|
2613 | Access to the standard Python help | |
|
1376 | :: | |
|
1377 | ||
|
1378 | %Exit: Exit IPython without confirmation. | |
|
1379 | ||
|
1380 | ||
|
1381 | %Pprint: Toggle pretty printing on/off. | |
|
1382 | ||
|
1383 | ||
|
1384 | %alias: Define an alias for a system command. | |
|
1385 | ||
|
1386 | '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd' | |
|
1387 | ||
|
1388 | Then, typing 'alias_name params' will execute the system command 'cmd | |
|
1389 | params' (from your underlying operating system). | |
|
1390 | ||
|
1391 | Aliases have lower precedence than magic functions and Python normal | |
|
1392 | variables, so if 'foo' is both a Python variable and an alias, the alias | |
|
1393 | can not be executed until 'del foo' removes the Python variable. | |
|
1394 | ||
|
1395 | You can use the %l specifier in an alias definition to represent the | |
|
1396 | whole line when the alias is called. For example: | |
|
1397 | ||
|
1398 | In [2]: alias all echo "Input in brackets: <%l>" | |
|
1399 | In [3]: all hello world | |
|
1400 | Input in brackets: <hello world> | |
|
1401 | ||
|
1402 | You can also define aliases with parameters using %s specifiers (one per | |
|
1403 | parameter): | |
|
1404 | ||
|
1405 | In [1]: alias parts echo first %s second %s | |
|
1406 | In [2]: %parts A B | |
|
1407 | first A second B | |
|
1408 | In [3]: %parts A | |
|
1409 | Incorrect number of arguments: 2 expected. | |
|
1410 | parts is an alias to: 'echo first %s second %s' | |
|
1411 | ||
|
1412 | Note that %l and %s are mutually exclusive. You can only use one or the | |
|
1413 | other in your aliases. | |
|
1414 | ||
|
1415 | Aliases expand Python variables just like system calls using ! or !! do: | |
|
1416 | all expressions prefixed with '$' get expanded. For details of the | |
|
1417 | semantic rules, see PEP-215: http://www.python.org/peps/pep-0215.html. | |
|
1418 | This is the library used by IPython for variable expansion. If you want | |
|
1419 | to access a true shell variable, an extra $ is necessary to prevent its | |
|
1420 | expansion by IPython: | |
|
1421 | ||
|
1422 | In [6]: alias show echo | |
|
1423 | In [7]: PATH='A Python string' | |
|
1424 | In [8]: show $PATH | |
|
1425 | A Python string | |
|
1426 | In [9]: show $$PATH | |
|
1427 | /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:... | |
|
1428 | ||
|
1429 | You can use the alias facility to acess all of $PATH. See the %rehash | |
|
1430 | and %rehashx functions, which automatically create aliases for the | |
|
1431 | contents of your $PATH. | |
|
1432 | ||
|
1433 | If called with no parameters, %alias prints the current alias table. | |
|
1434 | ||
|
1435 | ||
|
1436 | %autocall: Make functions callable without having to type parentheses. | |
|
1437 | ||
|
1438 | Usage: | |
|
1439 | ||
|
1440 | %autocall [mode] | |
|
1441 | ||
|
1442 | The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the | |
|
1443 | value is toggled on and off (remembering the previous state). | |
|
1444 | ||
|
1445 | In more detail, these values mean: | |
|
1446 | ||
|
1447 | 0 -> fully disabled | |
|
1448 | ||
|
1449 | 1 -> active, but do not apply if there are no arguments on the line. | |
|
1450 | ||
|
1451 | In this mode, you get: | |
|
1452 | ||
|
1453 | In [1]: callable Out[1]: <built-in function callable> | |
|
1454 | ||
|
1455 | In [2]: callable 'hello' ---> callable('hello') Out[2]: False | |
|
1456 | ||
|
1457 | 2 -> Active always. Even if no arguments are present, the callable | |
|
1458 | object is called: | |
|
1459 | ||
|
1460 | In [4]: callable ---> callable() | |
|
1461 | ||
|
1462 | Note that even with autocall off, you can still use '/' at the start of | |
|
1463 | a line to treat the first argument on the command line as a function and | |
|
1464 | add parentheses to it: | |
|
1465 | ||
|
1466 | In [8]: /str 43 ---> str(43) Out[8]: '43' | |
|
1467 | ||
|
1468 | ||
|
1469 | %autoindent: Toggle autoindent on/off (if available). | |
|
1470 | ||
|
1471 | ||
|
1472 | %automagic: Make magic functions callable without having to type the | |
|
1473 | initial %. | |
|
1474 | ||
|
1475 | Without argumentsl toggles on/off (when off, you must call it as | |
|
1476 | %automagic, of course). With arguments it sets the value, and you can | |
|
1477 | use any of (case insensitive): | |
|
1478 | ||
|
1479 | - on,1,True: to activate | |
|
1480 | ||
|
1481 | - off,0,False: to deactivate. | |
|
1482 | ||
|
1483 | Note that magic functions have lowest priority, so if there's a variable | |
|
1484 | whose name collides with that of a magic fn, automagic won't work for | |
|
1485 | that function (you get the variable instead). However, if you delete the | |
|
1486 | variable (del var), the previously shadowed magic function becomes | |
|
1487 | visible to automagic again. | |
|
1488 | ||
|
1489 | ||
|
1490 | %bg: Run a job in the background, in a separate thread. | |
|
1491 | ||
|
1492 | For example, | |
|
1493 | ||
|
1494 | %bg myfunc(x,y,z=1) | |
|
1495 | ||
|
1496 | will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the | |
|
1497 | execution starts, a message will be printed indicating the job number. | |
|
1498 | If your job number is 5, you can use | |
|
1499 | ||
|
1500 | myvar = jobs.result(5) or myvar = jobs[5].result | |
|
1501 | ||
|
1502 | to assign this result to variable 'myvar'. | |
|
1503 | ||
|
1504 | IPython has a job manager, accessible via the 'jobs' object. You can | |
|
1505 | type jobs? to get more information about it, and use jobs.<TAB> to see | |
|
1506 | its attributes. All attributes not starting with an underscore are meant | |
|
1507 | for public use. | |
|
1508 | ||
|
1509 | In particular, look at the jobs.new() method, which is used to create | |
|
1510 | new jobs. This magic %bg function is just a convenience wrapper around | |
|
1511 | jobs.new(), for expression-based jobs. If you want to create a new job | |
|
1512 | with an explicit function object and arguments, you must call jobs.new() | |
|
1513 | directly. | |
|
1514 | ||
|
1515 | The jobs.new docstring also describes in detail several important | |
|
1516 | caveats associated with a thread-based model for background job | |
|
1517 | execution. Type jobs.new? for details. | |
|
1518 | ||
|
1519 | You can check the status of all jobs with jobs.status(). | |
|
1520 | ||
|
1521 | The jobs variable is set by IPython into the Python builtin namespace. | |
|
1522 | If you ever declare a variable named 'jobs', you will shadow this name. | |
|
1523 | You can either delete your global jobs variable to regain access to the | |
|
1524 | job manager, or make a new name and assign it manually to the manager | |
|
1525 | (stored in IPython's namespace). For example, to assign the job manager | |
|
1526 | to the Jobs name, use: | |
|
1527 | ||
|
1528 | Jobs = __builtins__.jobs | |
|
1529 | ||
|
1530 | ||
|
1531 | %bookmark: Manage IPython's bookmark system. | |
|
1532 | ||
|
1533 | %bookmark <name> - set bookmark to current dir %bookmark <name> <dir> - | |
|
1534 | set bookmark to <dir> %bookmark -l - list all bookmarks %bookmark -d | |
|
1535 | <name> - remove bookmark %bookmark -r - remove all bookmarks | |
|
1536 | ||
|
1537 | You can later on access a bookmarked folder with: %cd -b <name> or | |
|
1538 | simply '%cd <name>' if there is no directory called <name> AND there is | |
|
1539 | such a bookmark defined. | |
|
1540 | ||
|
1541 | Your bookmarks persist through IPython sessions, but they are associated | |
|
1542 | with each profile. | |
|
1543 | ||
|
1544 | ||
|
1545 | %cd: Change the current working directory. | |
|
1546 | ||
|
1547 | This command automatically maintains an internal list of directories you | |
|
1548 | visit during your IPython session, in the variable _dh. The command | |
|
1549 | %dhist shows this history nicely formatted. You can also do 'cd -<tab>' | |
|
1550 | to see directory history conveniently. | |
|
1551 | ||
|
1552 | Usage: | |
|
1553 | ||
|
1554 | cd 'dir': changes to directory 'dir'. | |
|
1555 | ||
|
1556 | cd -: changes to the last visited directory. | |
|
1557 | ||
|
1558 | cd -<n>: changes to the n-th directory in the directory history. | |
|
1559 | ||
|
1560 | cd -b <bookmark_name>: jump to a bookmark set by %bookmark (note: cd | |
|
1561 | <bookmark_name> is enough if there is no directory <bookmark_name>, but | |
|
1562 | a bookmark with the name exists.) 'cd -b <tab>' allows you to | |
|
1563 | tab-complete bookmark names. | |
|
1564 | ||
|
1565 | Options: | |
|
1566 | ||
|
1567 | -q: quiet. Do not print the working directory after the cd command is | |
|
1568 | executed. By default IPython's cd command does print this directory, | |
|
1569 | since the default prompts do not display path information. | |
|
1570 | ||
|
1571 | Note that !cd doesn't work for this purpose because the shell where | |
|
1572 | !command runs is immediately discarded after executing 'command'. | |
|
1573 | ||
|
1574 | ||
|
1575 | %color_info: Toggle color_info. | |
|
1576 | ||
|
1577 | The color_info configuration parameter controls whether colors are used | |
|
1578 | for displaying object details (by things like %psource, %pfile or the | |
|
1579 | '?' system). This function toggles this value with each call. | |
|
1580 | ||
|
1581 | Note that unless you have a fairly recent pager (less works better than | |
|
1582 | more) in your system, using colored object information displays will not | |
|
1583 | work properly. Test it and see. | |
|
1584 | ||
|
1585 | ||
|
1586 | %colors: Switch color scheme for prompts, info system and exception | |
|
1587 | handlers. | |
|
1588 | ||
|
1589 | Currently implemented schemes: NoColor, Linux, LightBG. | |
|
1590 | ||
|
1591 | Color scheme names are not case-sensitive. | |
|
1592 | ||
|
1593 | ||
|
1594 | %cpaste: Allows you to paste & execute a pre-formatted code block from | |
|
1595 | clipboard | |
|
1596 | ||
|
1597 | You must terminate the block with '-' (two minus-signs) alone on the | |
|
1598 | line. You can also provide your own sentinel with '%paste -s %%' ('%%' | |
|
1599 | is the new sentinel for this operation) | |
|
1600 | ||
|
1601 | The block is dedented prior to execution to enable execution of method | |
|
1602 | definitions. '>' and '+' characters at the beginning of a line are | |
|
1603 | ignored, to allow pasting directly from e-mails or diff files. The | |
|
1604 | executed block is also assigned to variable named 'pasted_block' for | |
|
1605 | later editing with '%edit pasted_block'. | |
|
1606 | ||
|
1607 | You can also pass a variable name as an argument, e.g. '%cpaste foo'. | |
|
1608 | This assigns the pasted block to variable 'foo' as string, without | |
|
1609 | dedenting or executing it. | |
|
1610 | ||
|
1611 | Do not be alarmed by garbled output on Windows (it's a readline bug). | |
|
1612 | Just press enter and type - (and press enter again) and the block will | |
|
1613 | be what was just pasted. | |
|
1614 | ||
|
1615 | IPython statements (magics, shell escapes) are not supported (yet). | |
|
1616 | ||
|
1617 | ||
|
1618 | %debug: Activate the interactive debugger in post-mortem mode. | |
|
1619 | ||
|
1620 | If an exception has just occurred, this lets you inspect its stack | |
|
1621 | frames interactively. Note that this will always work only on the last | |
|
1622 | traceback that occurred, so you must call this quickly after an | |
|
1623 | exception that you wish to inspect has fired, because if another one | |
|
1624 | occurs, it clobbers the previous one. | |
|
1625 | ||
|
1626 | If you want IPython to automatically do this on every exception, see the | |
|
1627 | %pdb magic for more details. | |
|
1628 | ||
|
1629 | ||
|
1630 | %dhist: Print your history of visited directories. | |
|
1631 | ||
|
1632 | %dhist -> print full history | |
|
1633 | %dhist n -> print last n entries only | |
|
1634 | %dhist n1 n2 -> print entries between n1 and n2 (n1 not included) | |
|
1635 | ||
|
1636 | This history is automatically maintained by the %cd command, and always | |
|
1637 | available as the global list variable _dh. You can use %cd -<n> to go to | |
|
1638 | directory number <n>. | |
|
1639 | ||
|
1640 | Note that most of time, you should view directory history by entering cd | |
|
1641 | -<TAB>. | |
|
1642 | ||
|
1643 | ||
|
1644 | %dirs: Return the current directory stack. | |
|
1645 | ||
|
1646 | ||
|
1647 | %doctest_mode: Toggle doctest mode on and off. | |
|
1648 | ||
|
1649 | This mode allows you to toggle the prompt behavior between normal | |
|
1650 | IPython prompts and ones that are as similar to the default IPython | |
|
1651 | interpreter as possible. | |
|
1652 | ||
|
1653 | It also supports the pasting of code snippets that have leading 'Β»>' and | |
|
1654 | '...' prompts in them. This means that you can paste doctests from files | |
|
1655 | or docstrings (even if they have leading whitespace), and the code will | |
|
1656 | execute correctly. You can then use '%history -tn' to see the translated | |
|
1657 | history without line numbers; this will give you the input after removal | |
|
1658 | of all the leading prompts and whitespace, which can be pasted back into | |
|
1659 | an editor. | |
|
1660 | ||
|
1661 | With these features, you can switch into this mode easily whenever you | |
|
1662 | need to do testing and changes to doctests, without having to leave your | |
|
1663 | existing IPython session. | |
|
1664 | ||
|
1665 | ||
|
1666 | %ed: Alias to %edit. | |
|
1667 | ||
|
1668 | ||
|
1669 | %edit: Bring up an editor and execute the resulting code. | |
|
1670 | ||
|
1671 | Usage: %edit [options] [args] | |
|
1672 | ||
|
1673 | %edit runs IPython's editor hook. The default version of this hook is | |
|
1674 | set to call the __IPYTHON__.rc.editor command. This is read from your | |
|
1675 | environment variable $EDITOR. If this isn't found, it will default to vi | |
|
1676 | under Linux/Unix and to notepad under Windows. See the end of this | |
|
1677 | docstring for how to change the editor hook. | |
|
1678 | ||
|
1679 | You can also set the value of this editor via the command line option | |
|
1680 | '-editor' or in your ipythonrc file. This is useful if you wish to use | |
|
1681 | specifically for IPython an editor different from your typical default | |
|
1682 | (and for Windows users who typically don't set environment variables). | |
|
1683 | ||
|
1684 | This command allows you to conveniently edit multi-line code right in | |
|
1685 | your IPython session. | |
|
1686 | ||
|
1687 | If called without arguments, %edit opens up an empty editor with a | |
|
1688 | temporary file and will execute the contents of this file when you close | |
|
1689 | it (don't forget to save it!). | |
|
1690 | ||
|
1691 | Options: | |
|
1692 | ||
|
1693 | -n <number>: open the editor at a specified line number. By default, the | |
|
1694 | IPython editor hook uses the unix syntax 'editor +N filename', but you | |
|
1695 | can configure this by providing your own modified hook if your favorite | |
|
1696 | editor supports line-number specifications with a different syntax. | |
|
1697 | ||
|
1698 | -p: this will call the editor with the same data as the previous time it | |
|
1699 | was used, regardless of how long ago (in your current session) it was. | |
|
1700 | ||
|
1701 | -r: use 'raw' input. This option only applies to input taken from the | |
|
1702 | user's history. By default, the 'processed' history is used, so that | |
|
1703 | magics are loaded in their transformed version to valid Python. If this | |
|
1704 | option is given, the raw input as typed as the command line is used | |
|
1705 | instead. When you exit the editor, it will be executed by IPython's own | |
|
1706 | processor. | |
|
1707 | ||
|
1708 | -x: do not execute the edited code immediately upon exit. This is mainly | |
|
1709 | useful if you are editing programs which need to be called with command | |
|
1710 | line arguments, which you can then do using %run. | |
|
1711 | ||
|
1712 | Arguments: | |
|
1713 | ||
|
1714 | If arguments are given, the following possibilites exist: | |
|
1715 | ||
|
1716 | - The arguments are numbers or pairs of dash-separated numbers (like 1 | |
|
1717 | 4-8 9). These are interpreted as lines of previous input to be loaded | |
|
1718 | into the editor. The syntax is the same of the %macro command. | |
|
1719 | ||
|
1720 | - If the argument doesn't start with a number, it is evaluated as a | |
|
1721 | variable and its contents loaded into the editor. You can thus edit any | |
|
1722 | string which contains python code (including the result of previous edits). | |
|
1723 | ||
|
1724 | - If the argument is the name of an object (other than a string), | |
|
1725 | IPython will try to locate the file where it was defined and open the | |
|
1726 | editor at the point where it is defined. You can use '%edit function' to | |
|
1727 | load an editor exactly at the point where 'function' is defined, edit it | |
|
1728 | and have the file be executed automatically. | |
|
1729 | ||
|
1730 | If the object is a macro (see %macro for details), this opens up your | |
|
1731 | specified editor with a temporary file containing the macro's data. Upon | |
|
1732 | exit, the macro is reloaded with the contents of the file. | |
|
1733 | ||
|
1734 | Note: opening at an exact line is only supported under Unix, and some | |
|
1735 | editors (like kedit and gedit up to Gnome 2.8) do not understand the | |
|
1736 | '+NUMBER' parameter necessary for this feature. Good editors like | |
|
1737 | (X)Emacs, vi, jed, pico and joe all do. | |
|
1738 | ||
|
1739 | If the argument is not found as a variable, IPython will look for a | |
|
1740 | file with that name (adding .py if necessary) and load it into the | |
|
1741 | editor. It will execute its contents with execfile() when you exit, | |
|
1742 | loading any code in the file into your interactive namespace. | |
|
1743 | ||
|
1744 | After executing your code, %edit will return as output the code you | |
|
1745 | typed in the editor (except when it was an existing file). This way you | |
|
1746 | can reload the code in further invocations of %edit as a variable, via | |
|
1747 | _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of the | |
|
1748 | output. | |
|
1749 | ||
|
1750 | Note that %edit is also available through the alias %ed. | |
|
1751 | ||
|
1752 | This is an example of creating a simple function inside the editor and | |
|
1753 | then modifying it. First, start up the editor:: | |
|
1754 | ||
|
1755 | In [1]: ed | |
|
1756 | Editing... done. Executing edited code... | |
|
1757 | Out[1]: 'def foo():\n print "foo() was defined in an editing session"\n' | |
|
1758 | ||
|
1759 | We can then call the function foo(): | |
|
1760 | ||
|
1761 | In [2]: foo() | |
|
1762 | foo() was defined in an editing session | |
|
1763 | ||
|
1764 | Now we edit foo. IPython automatically loads the editor with the | |
|
1765 | (temporary) file where foo() was previously defined: | |
|
1766 | ||
|
1767 | In [3]: ed foo | |
|
1768 | Editing... done. Executing edited code... | |
|
1769 | ||
|
1770 | And if we call foo() again we get the modified version: | |
|
1771 | ||
|
1772 | In [4]: foo() | |
|
1773 | foo() has now been changed! | |
|
1774 | ||
|
1775 | Here is an example of how to edit a code snippet successive times. First | |
|
1776 | we call the editor: | |
|
1777 | ||
|
1778 | In [8]: ed | |
|
1779 | Editing... done. Executing edited code... | |
|
1780 | hello | |
|
1781 | Out[8]: "print 'hello'\n" | |
|
1782 | ||
|
1783 | Now we call it again with the previous output (stored in _): | |
|
1784 | ||
|
1785 | In [9]: ed _ | |
|
1786 | Editing... done. Executing edited code... | |
|
1787 | hello world | |
|
1788 | Out[9]: "print 'hello world'\n" | |
|
1789 | ||
|
1790 | Now we call it with the output #8 (stored in _8, also as Out[8]): | |
|
1791 | ||
|
1792 | In [10]: ed _8 | |
|
1793 | Editing... done. Executing edited code... | |
|
1794 | hello again | |
|
1795 | Out[10]: "print 'hello again'\n" | |
|
1796 | ||
|
1797 | Changing the default editor hook: | |
|
1798 | ||
|
1799 | If you wish to write your own editor hook, you can put it in a | |
|
1800 | configuration file which you load at startup time. The default hook is | |
|
1801 | defined in the IPython.hooks module, and you can use that as a starting | |
|
1802 | example for further modifications. That file also has general | |
|
1803 | instructions on how to set a new hook for use once you've defined it. | |
|
1804 | ||
|
1805 | ||
|
1806 | %env: List environment variables. | |
|
1807 | ||
|
1808 | ||
|
1809 | %exit: Exit IPython, confirming if configured to do so. | |
|
1810 | ||
|
1811 | You can configure whether IPython asks for confirmation upon exit by | |
|
1812 | setting the confirm_exit flag in the ipythonrc file. | |
|
1813 | ||
|
1814 | ||
|
1815 | %logoff: Temporarily stop logging. | |
|
1816 | ||
|
1817 | You must have previously started logging. | |
|
1818 | ||
|
1819 | ||
|
1820 | %logon: Restart logging. | |
|
1821 | ||
|
1822 | This function is for restarting logging which you've temporarily stopped | |
|
1823 | with %logoff. For starting logging for the first time, you must use the | |
|
1824 | %logstart function, which allows you to specify an optional log filename. | |
|
1825 | ||
|
1826 | ||
|
1827 | %logstart: Start logging anywhere in a session. | |
|
1828 | ||
|
1829 | %logstart [-o|-r|-t] [log_name [log_mode]] | |
|
1830 | ||
|
1831 | If no name is given, it defaults to a file named 'ipython_log.py' in | |
|
1832 | your current directory, in 'rotate' mode (see below). | |
|
1833 | ||
|
1834 | '%logstart name' saves to file 'name' in 'backup' mode. It saves your | |
|
1835 | history up to that point and then continues logging. | |
|
1836 | ||
|
1837 | %logstart takes a second optional parameter: logging mode. This can be | |
|
1838 | one of (note that the modes are given unquoted): | |
|
1839 | append: well, that says it. | |
|
1840 | backup: rename (if exists) to name and start name. | |
|
1841 | global: single logfile in your home dir, appended to. | |
|
1842 | over : overwrite existing log. | |
|
1843 | rotate: create rotating logs name.1 , name.2 , etc. | |
|
1844 | ||
|
1845 | Options: | |
|
1846 | ||
|
1847 | -o: log also IPython's output. In this mode, all commands which generate | |
|
1848 | an Out[NN] prompt are recorded to the logfile, right after their | |
|
1849 | corresponding input line. The output lines are always prepended with a | |
|
1850 | '#[Out]# ' marker, so that the log remains valid Python code. | |
|
1851 | ||
|
1852 | Since this marker is always the same, filtering only the output from a | |
|
1853 | log is very easy, using for example a simple awk call: | |
|
1854 | ||
|
1855 | awk -F'# | |
|
1856 | ||
|
1857 | \begin{displaymath}Out\end{displaymath} | |
|
1858 | ||
|
1859 | # ' 'if($2) print $2' ipython_log.py | |
|
1860 | ||
|
1861 | -r: log 'raw' input. Normally, IPython's logs contain the processed | |
|
1862 | input, so that user lines are logged in their final form, converted into | |
|
1863 | valid Python. For example, %Exit is logged as '_ip.magic("Exit"). If the | |
|
1864 | -r flag is given, all input is logged exactly as typed, with no | |
|
1865 | transformations applied. | |
|
1866 | ||
|
1867 | -t: put timestamps before each input line logged (these are put in | |
|
1868 | comments). | |
|
1869 | ||
|
1870 | ||
|
1871 | %logstate: Print the status of the logging system. | |
|
1872 | ||
|
1873 | ||
|
1874 | %logstop: Fully stop logging and close log file. | |
|
1875 | ||
|
1876 | In order to start logging again, a new %logstart call needs to be made, | |
|
1877 | possibly (though not necessarily) with a new filename, mode and other | |
|
1878 | options. | |
|
1879 | ||
|
1880 | ||
|
1881 | %lsmagic: List currently available magic functions. | |
|
1882 | ||
|
1883 | ||
|
1884 | %macro: Define a set of input lines as a macro for future re-execution. | |
|
1885 | ||
|
1886 | Usage: | |
|
1887 | %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ... | |
|
1888 | ||
|
1889 | Options: | |
|
1890 | ||
|
1891 | -r: use 'raw' input. By default, the 'processed' history is used, so | |
|
1892 | that magics are loaded in their transformed version to valid Python. If | |
|
1893 | this option is given, the raw input as typed as the command line is used | |
|
1894 | instead. | |
|
1895 | ||
|
1896 | This will define a global variable called 'name' which is a string made | |
|
1897 | of joining the slices and lines you specify (n1,n2,... numbers above) | |
|
1898 | from your input history into a single string. This variable acts like an | |
|
1899 | automatic function which re-executes those lines as if you had typed | |
|
1900 | them. You just type 'name' at the prompt and the code executes. | |
|
1901 | ||
|
1902 | The notation for indicating number ranges is: n1-n2 means 'use line | |
|
1903 | numbers n1,...n2' (the endpoint is included). That is, '5-7' means using | |
|
1904 | the lines numbered 5,6 and 7. | |
|
1905 | ||
|
1906 | Note: as a 'hidden' feature, you can also use traditional python slice | |
|
1907 | notation, where N:M means numbers N through M-1. | |
|
1908 | ||
|
1909 | For example, if your history contains (%hist prints it): | |
|
1910 | ||
|
1911 | 44: x=1 | |
|
1912 | 45: y=3 | |
|
1913 | 46: z=x+y | |
|
1914 | 47: print x | |
|
1915 | 48: a=5 | |
|
1916 | 49: print 'x',x,'y',y | |
|
1917 | ||
|
1918 | you can create a macro with lines 44 through 47 (included) and line 49 | |
|
1919 | called my_macro with: | |
|
1920 | ||
|
1921 | In [51]: %macro my_macro 44-47 49 | |
|
1922 | ||
|
1923 | Now, typing 'my_macro' (without quotes) will re-execute all this code in | |
|
1924 | one pass. | |
|
1925 | ||
|
1926 | You don't need to give the line-numbers in order, and any given line | |
|
1927 | number can appear multiple times. You can assemble macros with any lines | |
|
1928 | from your input history in any order. | |
|
1929 | ||
|
1930 | The macro is a simple object which holds its value in an attribute, but | |
|
1931 | IPython's display system checks for macros and executes them as code | |
|
1932 | instead of printing them when you type their name. | |
|
1933 | ||
|
1934 | You can view a macro's contents by explicitly printing it with: | |
|
1935 | ||
|
1936 | 'print macro_name'. | |
|
1937 | ||
|
1938 | For one-off cases which DON'T contain magic function calls in them you | |
|
1939 | can obtain similar results by explicitly executing slices from your | |
|
1940 | input history with: | |
|
1941 | ||
|
1942 | In [60]: exec In[44:48]+In[49] | |
|
1943 | ||
|
1944 | ||
|
1945 | %magic: Print information about the magic function system. | |
|
1946 | ||
|
1947 | ||
|
1948 | %page: Pretty print the object and display it through a pager. | |
|
1949 | ||
|
1950 | %page [options] OBJECT | |
|
1951 | ||
|
1952 | If no object is given, use _ (last output). | |
|
1953 | ||
|
1954 | Options: | |
|
1955 | ||
|
1956 | -r: page str(object), don't pretty-print it. | |
|
1957 | ||
|
1958 | ||
|
1959 | %pdb: Control the automatic calling of the pdb interactive debugger. | |
|
1960 | ||
|
1961 | Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without | |
|
1962 | argument it works as a toggle. | |
|
1963 | ||
|
1964 | When an exception is triggered, IPython can optionally call the | |
|
1965 | interactive pdb debugger after the traceback printout. %pdb toggles this | |
|
1966 | feature on and off. | |
|
1967 | ||
|
1968 | The initial state of this feature is set in your ipythonrc configuration | |
|
1969 | file (the variable is called 'pdb'). | |
|
1970 | ||
|
1971 | If you want to just activate the debugger AFTER an exception has fired, | |
|
1972 | without having to type '%pdb on' and rerunning your code, you can use | |
|
1973 | the %debug magic. | |
|
1974 | ||
|
1975 | ||
|
1976 | %pdef: Print the definition header for any callable object. | |
|
1977 | ||
|
1978 | If the object is a class, print the constructor information. | |
|
1979 | ||
|
1980 | ||
|
1981 | %pdoc: Print the docstring for an object. | |
|
1982 | ||
|
1983 | If the given object is a class, it will print both the class and the | |
|
1984 | constructor docstrings. | |
|
1985 | ||
|
1986 | ||
|
1987 | %pfile: Print (or run through pager) the file where an object is defined. | |
|
1988 | ||
|
1989 | The file opens at the line where the object definition begins. IPython | |
|
1990 | will honor the environment variable PAGER if set, and otherwise will do | |
|
1991 | its best to print the file in a convenient form. | |
|
1992 | ||
|
1993 | If the given argument is not an object currently defined, IPython will | |
|
1994 | try to interpret it as a filename (automatically adding a .py extension | |
|
1995 | if needed). You can thus use %pfile as a syntax highlighting code viewer. | |
|
1996 | ||
|
1997 | ||
|
1998 | %pinfo: Provide detailed information about an object. | |
|
1999 | ||
|
2000 | '%pinfo object' is just a synonym for object? or ?object. | |
|
2001 | ||
|
2002 | ||
|
2003 | %popd: Change to directory popped off the top of the stack. | |
|
2004 | ||
|
2005 | ||
|
2006 | %profile: Print your currently active IPyhton profile. | |
|
2007 | ||
|
2008 | ||
|
2009 | %prun: Run a statement through the python code profiler. | |
|
2010 | ||
|
2011 | Usage: | |
|
2012 | %prun [options] statement | |
|
2013 | ||
|
2014 | The given statement (which doesn't require quote marks) is run via the | |
|
2015 | python profiler in a manner similar to the profile.run() function. | |
|
2016 | Namespaces are internally managed to work correctly; profile.run cannot | |
|
2017 | be used in IPython because it makes certain assumptions about namespaces | |
|
2018 | which do not hold under IPython. | |
|
2019 | ||
|
2020 | Options: | |
|
2021 | ||
|
2022 | -l <limit>: you can place restrictions on what or how much of the | |
|
2023 | profile gets printed. The limit value can be: | |
|
2024 | ||
|
2025 | * A string: only information for function names containing this string | |
|
2026 | is printed. | |
|
2027 | ||
|
2028 | * An integer: only these many lines are printed. | |
|
2029 | ||
|
2030 | * A float (between 0 and 1): this fraction of the report is printed (for | |
|
2031 | example, use a limit of 0.4 to see the topmost 40% only). | |
|
2032 | ||
|
2033 | You can combine several limits with repeated use of the option. For | |
|
2034 | example, '-l __init__ -l 5' will print only the topmost 5 lines of | |
|
2035 | information about class constructors. | |
|
2036 | ||
|
2037 | -r: return the pstats.Stats object generated by the profiling. This | |
|
2038 | object has all the information about the profile in it, and you can | |
|
2039 | later use it for further analysis or in other functions. | |
|
2040 | ||
|
2041 | -s <key>: sort profile by given key. You can provide more than one key | |
|
2042 | by using the option several times: '-s key1 -s key2 -s key3...'. The | |
|
2043 | default sorting key is 'time'. | |
|
2044 | ||
|
2045 | The following is copied verbatim from the profile documentation | |
|
2046 | referenced below: | |
|
2047 | ||
|
2048 | When more than one key is provided, additional keys are used as | |
|
2049 | secondary criteria when the there is equality in all keys selected | |
|
2050 | before them. | |
|
2051 | ||
|
2052 | Abbreviations can be used for any key names, as long as the abbreviation | |
|
2053 | is unambiguous. The following are the keys currently defined: | |
|
2054 | ||
|
2055 | Valid Arg Meaning | |
|
2056 | "calls" call count | |
|
2057 | "cumulative" cumulative time | |
|
2058 | "file" file name | |
|
2059 | "module" file name | |
|
2060 | "pcalls" primitive call count | |
|
2061 | "line" line number | |
|
2062 | "name" function name | |
|
2063 | "nfl" name/file/line | |
|
2064 | "stdname" standard name | |
|
2065 | "time" internal time | |
|
2066 | ||
|
2067 | Note that all sorts on statistics are in descending order (placing most | |
|
2068 | time consuming items first), where as name, file, and line number | |
|
2069 | searches are in ascending order (i.e., alphabetical). The subtle | |
|
2070 | distinction between "nfl" and "stdname" is that the standard name is a | |
|
2071 | sort of the name as printed, which means that the embedded line numbers | |
|
2072 | get compared in an odd way. For example, lines 3, 20, and 40 would (if | |
|
2073 | the file names were the same) appear in the string order "20" "3" and | |
|
2074 | "40". In contrast, "nfl" does a numeric compare of the line numbers. In | |
|
2075 | fact, sort_stats("nfl") is the same as sort_stats("name", "file", "line"). | |
|
2076 | ||
|
2077 | -T <filename>: save profile results as shown on screen to a text file. | |
|
2078 | The profile is still shown on screen. | |
|
2079 | ||
|
2080 | -D <filename>: save (via dump_stats) profile statistics to given | |
|
2081 | filename. This data is in a format understod by the pstats module, and | |
|
2082 | is generated by a call to the dump_stats() method of profile objects. | |
|
2083 | The profile is still shown on screen. | |
|
2084 | ||
|
2085 | If you want to run complete programs under the profiler's control, use | |
|
2086 | '%run -p [prof_opts] filename.py [args to program]' where prof_opts | |
|
2087 | contains profiler specific options as described here. | |
|
2088 | ||
|
2089 | You can read the complete documentation for the profile module with: | |
|
2090 | In [1]: import profile; profile.help() | |
|
2091 | ||
|
2092 | ||
|
2093 | %psearch: Search for object in namespaces by wildcard. | |
|
2094 | ||
|
2095 | %psearch [options] PATTERN [OBJECT TYPE] | |
|
2096 | ||
|
2097 | Note: ? can be used as a synonym for %psearch, at the beginning or at | |
|
2098 | the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the | |
|
2099 | rest of the command line must be unchanged (options come first), so for | |
|
2100 | example the following forms are equivalent | |
|
2101 | ||
|
2102 | %psearch -i a* function -i a* function? ?-i a* function | |
|
2103 | ||
|
2104 | Arguments: | |
|
2105 | ||
|
2106 | PATTERN | |
|
2107 | ||
|
2108 | where PATTERN is a string containing * as a wildcard similar to its use | |
|
2109 | in a shell. The pattern is matched in all namespaces on the search path. | |
|
2110 | By default objects starting with a single _ are not matched, many | |
|
2111 | IPython generated objects have a single underscore. The default is case | |
|
2112 | insensitive matching. Matching is also done on the attributes of objects | |
|
2113 | and not only on the objects in a module. | |
|
2114 | ||
|
2115 | [OBJECT TYPE] | |
|
2116 | ||
|
2117 | Is the name of a python type from the types module. The name is given in | |
|
2118 | lowercase without the ending type, ex. StringType is written string. By | |
|
2119 | adding a type here only objects matching the given type are matched. | |
|
2120 | Using all here makes the pattern match all types (this is the default). | |
|
2121 | ||
|
2122 | Options: | |
|
2123 | ||
|
2124 | -a: makes the pattern match even objects whose names start with a single | |
|
2125 | underscore. These names are normally ommitted from the search. | |
|
2126 | ||
|
2127 | -i/-c: make the pattern case insensitive/sensitive. If neither of these | |
|
2128 | options is given, the default is read from your ipythonrc file. The | |
|
2129 | option name which sets this value is 'wildcards_case_sensitive'. If this | |
|
2130 | option is not specified in your ipythonrc file, IPython's internal | |
|
2131 | default is to do a case sensitive search. | |
|
2132 | ||
|
2133 | -e/-s NAMESPACE: exclude/search a given namespace. The pattern you | |
|
2134 | specifiy can be searched in any of the following namespaces: 'builtin', | |
|
2135 | 'user', 'user_global','internal', 'alias', where 'builtin' and 'user' | |
|
2136 | are the search defaults. Note that you should not use quotes when | |
|
2137 | specifying namespaces. | |
|
2138 | ||
|
2139 | 'Builtin' contains the python module builtin, 'user' contains all user | |
|
2140 | data, 'alias' only contain the shell aliases and no python objects, | |
|
2141 | 'internal' contains objects used by IPython. The 'user_global' namespace | |
|
2142 | is only used by embedded IPython instances, and it contains module-level | |
|
2143 | globals. You can add namespaces to the search with -s or exclude them | |
|
2144 | with -e (these options can be given more than once). | |
|
2145 | ||
|
2146 | Examples: | |
|
2147 | ||
|
2148 | %psearch a* -> objects beginning with an a %psearch -e builtin a* -> | |
|
2149 | objects NOT in the builtin space starting in a %psearch a* function -> | |
|
2150 | all functions beginning with an a %psearch re.e* -> objects beginning | |
|
2151 | with an e in module re %psearch r*.e* -> objects that start with e in | |
|
2152 | modules starting in r %psearch r*.* string -> all strings in modules | |
|
2153 | beginning with r | |
|
2154 | ||
|
2155 | Case sensitve search: | |
|
2156 | ||
|
2157 | %psearch -c a* list all object beginning with lower case a | |
|
2158 | ||
|
2159 | Show objects beginning with a single _: | |
|
2160 | ||
|
2161 | %psearch -a _* list objects beginning with a single underscore | |
|
2162 | ||
|
2163 | ||
|
2164 | %psource: Print (or run through pager) the source code for an object. | |
|
2165 | ||
|
2166 | ||
|
2167 | %pushd: Place the current dir on stack and change directory. | |
|
2168 | ||
|
2169 | Usage: | |
|
2170 | %pushd ['dirname'] | |
|
2171 | ||
|
2172 | ||
|
2173 | %pwd: Return the current working directory path. | |
|
2174 | ||
|
2175 | ||
|
2176 | %pycat: Show a syntax-highlighted file through a pager. | |
|
2177 | ||
|
2178 | This magic is similar to the cat utility, but it will assume the file to | |
|
2179 | be Python source and will show it with syntax highlighting. | |
|
2180 | ||
|
2181 | ||
|
2182 | %quickref: Show a quick reference sheet | |
|
2183 | ||
|
2184 | ||
|
2185 | %quit: Exit IPython, confirming if configured to do so (like %exit) | |
|
2186 | ||
|
2187 | ||
|
2188 | %r: Repeat previous input. | |
|
2189 | ||
|
2190 | Note: Consider using the more powerfull %rep instead! | |
|
2191 | ||
|
2192 | If given an argument, repeats the previous command which starts with the | |
|
2193 | same string, otherwise it just repeats the previous input. | |
|
2194 | ||
|
2195 | Shell escaped commands (with ! as first character) are not recognized by | |
|
2196 | this system, only pure python code and magic commands. | |
|
2197 | ||
|
2198 | ||
|
2199 | %rehashx: Update the alias table with all executable files in $PATH. | |
|
2200 | ||
|
2201 | This version explicitly checks that every entry in $PATH is a file with | |
|
2202 | execute access (os.X_OK), so it is much slower than %rehash. | |
|
2203 | ||
|
2204 | Under Windows, it checks executability as a match agains a ``|``-separated | |
|
2205 | string of extensions, stored in the IPython config variable | |
|
2206 | win_exec_ext. This defaults to ``exe|com|bat``. | |
|
2207 | ||
|
2208 | This function also resets the root module cache of module completer, | |
|
2209 | used on slow filesystems. | |
|
2210 | ||
|
2211 | ||
|
2212 | %reset: Resets the namespace by removing all names defined by the user. | |
|
2213 | ||
|
2214 | Input/Output history are left around in case you need them. | |
|
2215 | ||
|
2216 | ||
|
2217 | %run: Run the named file inside IPython as a program. | |
|
2218 | ||
|
2219 | Usage: | |
|
2220 | %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args] | |
|
2221 | ||
|
2222 | Parameters after the filename are passed as command-line arguments to | |
|
2223 | the program (put in sys.argv). Then, control returns to IPython's prompt. | |
|
2224 | ||
|
2225 | This is similar to running at a system prompt: | |
|
2226 | $ python file args | |
|
2227 | but with the advantage of giving you IPython's tracebacks, and of | |
|
2228 | loading all variables into your interactive namespace for further use | |
|
2229 | (unless -p is used, see below). | |
|
2230 | ||
|
2231 | The file is executed in a namespace initially consisting only of | |
|
2232 | __name__=='__main__' and sys.argv constructed as indicated. It thus sees | |
|
2233 | its environment as if it were being run as a stand-alone program (except | |
|
2234 | for sharing global objects such as previously imported modules). But | |
|
2235 | after execution, the IPython interactive namespace gets updated with all | |
|
2236 | variables defined in the program (except for __name__ and sys.argv). | |
|
2237 | This allows for very convenient loading of code for interactive work, | |
|
2238 | while giving each program a 'clean sheet' to run in. | |
|
2239 | ||
|
2240 | Options: | |
|
2241 | ||
|
2242 | -n: __name__ is NOT set to '__main__', but to the running file's name | |
|
2243 | without extension (as python does under import). This allows running | |
|
2244 | scripts and reloading the definitions in them without calling code | |
|
2245 | protected by an ' if __name__ == "__main__" ' clause. | |
|
2246 | ||
|
2247 | -i: run the file in IPython's namespace instead of an empty one. This is | |
|
2248 | useful if you are experimenting with code written in a text editor which | |
|
2249 | depends on variables defined interactively. | |
|
2250 | ||
|
2251 | -e: ignore sys.exit() calls or SystemExit exceptions in the script being | |
|
2252 | run. This is particularly useful if IPython is being used to run | |
|
2253 | unittests, which always exit with a sys.exit() call. In such cases you | |
|
2254 | are interested in the output of the test results, not in seeing a | |
|
2255 | traceback of the unittest module. | |
|
2256 | ||
|
2257 | -t: print timing information at the end of the run. IPython will give | |
|
2258 | you an estimated CPU time consumption for your script, which under Unix | |
|
2259 | uses the resource module to avoid the wraparound problems of | |
|
2260 | time.clock(). Under Unix, an estimate of time spent on system tasks is | |
|
2261 | also given (for Windows platforms this is reported as 0.0). | |
|
2262 | ||
|
2263 | If -t is given, an additional -N<N> option can be given, where <N> must | |
|
2264 | be an integer indicating how many times you want the script to run. The | |
|
2265 | final timing report will include total and per run results. | |
|
2266 | ||
|
2267 | For example (testing the script uniq_stable.py): | |
|
2268 | ||
|
2269 | In [1]: run -t uniq_stable | |
|
2270 | ||
|
2271 | IPython CPU timings (estimated): | |
|
2272 | User : 0.19597 s. | |
|
2273 | System: 0.0 s. | |
|
2274 | ||
|
2275 | In [2]: run -t -N5 uniq_stable | |
|
2276 | ||
|
2277 | IPython CPU timings (estimated): | |
|
2278 | Total runs performed: 5 | |
|
2279 | Times : Total Per run | |
|
2280 | User : 0.910862 s, 0.1821724 s. | |
|
2281 | System: 0.0 s, 0.0 s. | |
|
2282 | ||
|
2283 | -d: run your program under the control of pdb, the Python debugger. This | |
|
2284 | allows you to execute your program step by step, watch variables, etc. | |
|
2285 | Internally, what IPython does is similar to calling: | |
|
2286 | ||
|
2287 | pdb.run('execfile("YOURFILENAME")') | |
|
2288 | ||
|
2289 | with a breakpoint set on line 1 of your file. You can change the line | |
|
2290 | number for this automatic breakpoint to be <N> by using the -bN option | |
|
2291 | (where N must be an integer). For example: | |
|
2292 | ||
|
2293 | %run -d -b40 myscript | |
|
2294 | ||
|
2295 | will set the first breakpoint at line 40 in myscript.py. Note that the | |
|
2296 | first breakpoint must be set on a line which actually does something | |
|
2297 | (not a comment or docstring) for it to stop execution. | |
|
2298 | ||
|
2299 | When the pdb debugger starts, you will see a (Pdb) prompt. You must | |
|
2300 | first enter 'c' (without qoutes) to start execution up to the first | |
|
2301 | breakpoint. | |
|
2302 | ||
|
2303 | Entering 'help' gives information about the use of the debugger. You can | |
|
2304 | easily see pdb's full documentation with "import pdb;pdb.help()" at a | |
|
2305 | prompt. | |
|
2306 | ||
|
2307 | -p: run program under the control of the Python profiler module (which | |
|
2308 | prints a detailed report of execution times, function calls, etc). | |
|
2309 | ||
|
2310 | You can pass other options after -p which affect the behavior of the | |
|
2311 | profiler itself. See the docs for %prun for details. | |
|
2312 | ||
|
2313 | In this mode, the program's variables do NOT propagate back to the | |
|
2314 | IPython interactive namespace (because they remain in the namespace | |
|
2315 | where the profiler executes them). | |
|
2316 | ||
|
2317 | Internally this triggers a call to %prun, see its documentation for | |
|
2318 | details on the options available specifically for profiling. | |
|
2319 | ||
|
2320 | There is one special usage for which the text above doesn't apply: if | |
|
2321 | the filename ends with .ipy, the file is run as ipython script, just as | |
|
2322 | if the commands were written on IPython prompt. | |
|
2323 | ||
|
2324 | ||
|
2325 | %runlog: Run files as logs. | |
|
2326 | ||
|
2327 | Usage: | |
|
2328 | %runlog file1 file2 ... | |
|
2329 | ||
|
2330 | Run the named files (treating them as log files) in sequence inside the | |
|
2331 | interpreter, and return to the prompt. This is much slower than %run | |
|
2332 | because each line is executed in a try/except block, but it allows | |
|
2333 | running files with syntax errors in them. | |
|
2334 | ||
|
2335 | Normally IPython will guess when a file is one of its own logfiles, so | |
|
2336 | you can typically use %run even for logs. This shorthand allows you to | |
|
2337 | force any file to be treated as a log file. | |
|
2338 | ||
|
2339 | ||
|
2340 | %save: Save a set of lines to a given filename. | |
|
2341 | ||
|
2342 | Usage: | |
|
2343 | %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ... | |
|
2344 | ||
|
2345 | Options: | |
|
2346 | ||
|
2347 | -r: use 'raw' input. By default, the 'processed' history is used, so | |
|
2348 | that magics are loaded in their transformed version to valid Python. If | |
|
2349 | this option is given, the raw input as typed as the command line is used | |
|
2350 | instead. | |
|
2351 | ||
|
2352 | This function uses the same syntax as %macro for line extraction, but | |
|
2353 | instead of creating a macro it saves the resulting string to the | |
|
2354 | filename you specify. | |
|
2355 | ||
|
2356 | It adds a '.py' extension to the file if you don't do so yourself, and | |
|
2357 | it asks for confirmation before overwriting existing files. | |
|
2358 | ||
|
2359 | ||
|
2360 | %sc: Shell capture - execute a shell command and capture its output. | |
|
2361 | ||
|
2362 | DEPRECATED. Suboptimal, retained for backwards compatibility. | |
|
2363 | ||
|
2364 | You should use the form 'var = !command' instead. Example: | |
|
2365 | ||
|
2366 | "%sc -l myfiles = ls " should now be written as | |
|
2367 | ||
|
2368 | "myfiles = !ls " | |
|
2369 | ||
|
2370 | myfiles.s, myfiles.l and myfiles.n still apply as documented below. | |
|
2371 | ||
|
2372 | - %sc [options] varname=command | |
|
2373 | ||
|
2374 | IPython will run the given command using commands.getoutput(), and will | |
|
2375 | then update the user's interactive namespace with a variable called | |
|
2376 | varname, containing the value of the call. Your command can contain | |
|
2377 | shell wildcards, pipes, etc. | |
|
2378 | ||
|
2379 | The '=' sign in the syntax is mandatory, and the variable name you | |
|
2380 | supply must follow Python's standard conventions for valid names. | |
|
2381 | ||
|
2382 | (A special format without variable name exists for internal use) | |
|
2383 | ||
|
2384 | Options: | |
|
2385 | ||
|
2386 | -l: list output. Split the output on newlines into a list before | |
|
2387 | assigning it to the given variable. By default the output is stored as a | |
|
2388 | single string. | |
|
2389 | ||
|
2390 | -v: verbose. Print the contents of the variable. | |
|
2391 | ||
|
2392 | In most cases you should not need to split as a list, because the | |
|
2393 | returned value is a special type of string which can automatically | |
|
2394 | provide its contents either as a list (split on newlines) or as a | |
|
2395 | space-separated string. These are convenient, respectively, either for | |
|
2396 | sequential processing or to be passed to a shell command. | |
|
2397 | ||
|
2398 | For example: | |
|
2399 | ||
|
2400 | # Capture into variable a In [9]: sc a=ls *py | |
|
2401 | ||
|
2402 | # a is a string with embedded newlines In [10]: a Out[10]: 'setup.py | |
|
2403 | win32_manual_post_install.py' | |
|
2404 | ||
|
2405 | # which can be seen as a list: In [11]: a.l Out[11]: ['setup.py', | |
|
2406 | 'win32_manual_post_install.py'] | |
|
2407 | ||
|
2408 | # or as a whitespace-separated string: In [12]: a.s Out[12]: 'setup.py | |
|
2409 | win32_manual_post_install.py' | |
|
2410 | ||
|
2411 | # a.s is useful to pass as a single command line: In [13]: !wc -l $a.s | |
|
2412 | 146 setup.py 130 win32_manual_post_install.py 276 total | |
|
2413 | ||
|
2414 | # while the list form is useful to loop over: In [14]: for f in a.l: | |
|
2415 | ....: !wc -l $f ....: 146 setup.py 130 win32_manual_post_install.py | |
|
2416 | ||
|
2417 | Similiarly, the lists returned by the -l option are also special, in the | |
|
2418 | sense that you can equally invoke the .s attribute on them to | |
|
2419 | automatically get a whitespace-separated string from their contents: | |
|
2420 | ||
|
2421 | In [1]: sc -l b=ls *py | |
|
2422 | ||
|
2423 | In [2]: b Out[2]: ['setup.py', 'win32_manual_post_install.py'] | |
|
2424 | ||
|
2425 | In [3]: b.s Out[3]: 'setup.py win32_manual_post_install.py' | |
|
2426 | ||
|
2427 | In summary, both the lists and strings used for ouptut capture have the | |
|
2428 | following special attributes: | |
|
2429 | ||
|
2430 | .l (or .list) : value as list. .n (or .nlstr): value as | |
|
2431 | newline-separated string. .s (or .spstr): value as space-separated string. | |
|
2432 | ||
|
2433 | ||
|
2434 | %sx: Shell execute - run a shell command and capture its output. | |
|
2435 | ||
|
2436 | %sx command | |
|
2437 | ||
|
2438 | IPython will run the given command using commands.getoutput(), and | |
|
2439 | return the result formatted as a list (split on '\n'). Since the output | |
|
2440 | is _returned_, it will be stored in ipython's regular output cache | |
|
2441 | Out[N] and in the '_N' automatic variables. | |
|
2442 | ||
|
2443 | Notes: | |
|
2444 | ||
|
2445 | 1) If an input line begins with '!!', then %sx is automatically invoked. | |
|
2446 | That is, while: !ls causes ipython to simply issue system('ls'), typing | |
|
2447 | !!ls is a shorthand equivalent to: %sx ls | |
|
2448 | ||
|
2449 | 2) %sx differs from %sc in that %sx automatically splits into a list, | |
|
2450 | like '%sc -l'. The reason for this is to make it as easy as possible to | |
|
2451 | process line-oriented shell output via further python commands. %sc is | |
|
2452 | meant to provide much finer control, but requires more typing. | |
|
2453 | ||
|
2454 | 3) Just like %sc -l, this is a list with special attributes: | |
|
2455 | ||
|
2456 | .l (or .list) : value as list. .n (or .nlstr): value as | |
|
2457 | newline-separated string. .s (or .spstr): value as whitespace-separated | |
|
2458 | string. | |
|
2459 | ||
|
2460 | This is very useful when trying to use such lists as arguments to system | |
|
2461 | commands. | |
|
2462 | ||
|
2463 | ||
|
2464 | %system_verbose: Set verbose printing of system calls. | |
|
2465 | ||
|
2466 | If called without an argument, act as a toggle | |
|
2467 | ||
|
2468 | ||
|
2469 | %time: Time execution of a Python statement or expression. | |
|
2470 | ||
|
2471 | The CPU and wall clock times are printed, and the value of the | |
|
2472 | expression (if any) is returned. Note that under Win32, system time is | |
|
2473 | always reported as 0, since it can not be measured. | |
|
2474 | ||
|
2475 | This function provides very basic timing functionality. In Python 2.3, | |
|
2476 | the timeit module offers more control and sophistication, so this could | |
|
2477 | be rewritten to use it (patches welcome). | |
|
2478 | ||
|
2479 | Some examples: | |
|
2480 | ||
|
2481 | In [1]: time 2**128 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s | |
|
2482 | Wall time: 0.00 Out[1]: 340282366920938463463374607431768211456L | |
|
2483 | ||
|
2484 | In [2]: n = 1000000 | |
|
2485 | ||
|
2486 | In [3]: time sum(range(n)) CPU times: user 1.20 s, sys: 0.05 s, total: | |
|
2487 | 1.25 s Wall time: 1.37 Out[3]: 499999500000L | |
|
2488 | ||
|
2489 | In [4]: time print 'hello world' hello world CPU times: user 0.00 s, | |
|
2490 | sys: 0.00 s, total: 0.00 s Wall time: 0.00 | |
|
2491 | ||
|
2492 | Note that the time needed by Python to compile the given expression will | |
|
2493 | be reported if it is more than 0.1s. In this example, the actual | |
|
2494 | exponentiation is done by Python at compilation time, so while the | |
|
2495 | expression can take a noticeable amount of time to compute, that time is | |
|
2496 | purely due to the compilation: | |
|
2497 | ||
|
2498 | In [5]: time 3**9999; CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s | |
|
2499 | Wall time: 0.00 s | |
|
2500 | ||
|
2501 | In [6]: time 3**999999; CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 | |
|
2502 | s Wall time: 0.00 s Compiler : 0.78 s | |
|
2503 | ||
|
2504 | ||
|
2505 | %timeit: Time execution of a Python statement or expression | |
|
2506 | ||
|
2507 | Usage: | |
|
2508 | %timeit [-n<N> -r<R> [-t|-c]] statement | |
|
2509 | ||
|
2510 | Time execution of a Python statement or expression using the timeit module. | |
|
2511 | ||
|
2512 | Options: -n<N>: execute the given statement <N> times in a loop. If this | |
|
2513 | value is not given, a fitting value is chosen. | |
|
2514 | ||
|
2515 | -r<R>: repeat the loop iteration <R> times and take the best result. | |
|
2516 | Default: 3 | |
|
2517 | ||
|
2518 | -t: use time.time to measure the time, which is the default on Unix. | |
|
2519 | This function measures wall time. | |
|
2520 | ||
|
2521 | -c: use time.clock to measure the time, which is the default on Windows | |
|
2522 | and measures wall time. On Unix, resource.getrusage is used instead and | |
|
2523 | returns the CPU user time. | |
|
2524 | ||
|
2525 | -p<P>: use a precision of <P> digits to display the timing result. | |
|
2526 | Default: 3 | |
|
2527 | ||
|
2528 | Examples: | |
|
2529 | In [1]: %timeit pass 10000000 loops, best of 3: 53.3 ns per loop | |
|
2530 | ||
|
2531 | In [2]: u = None | |
|
2532 | ||
|
2533 | In [3]: %timeit u is None 10000000 loops, best of 3: 184 ns per loop | |
|
2534 | ||
|
2535 | In [4]: %timeit -r 4 u == None 1000000 loops, best of 4: 242 ns per loop | |
|
2536 | ||
|
2537 | In [5]: import time | |
|
2538 | ||
|
2539 | In [6]: %timeit -n1 time.sleep(2) 1 loops, best of 3: 2 s per loop | |
|
2540 | ||
|
2541 | The times reported by %timeit will be slightly higher than those | |
|
2542 | reported by the timeit.py script when variables are accessed. This is | |
|
2543 | due to the fact that %timeit executes the statement in the namespace of | |
|
2544 | the shell, compared with timeit.py, which uses a single setup statement | |
|
2545 | to import function or create variables. Generally, the bias does not | |
|
2546 | matter as long as results from timeit.py are not mixed with those from | |
|
2547 | %timeit. | |
|
2548 | ||
|
2549 | ||
|
2550 | %unalias: Remove an alias | |
|
2551 | ||
|
2552 | ||
|
2553 | %upgrade: Upgrade your IPython installation | |
|
2554 | ||
|
2555 | This will copy the config files that don't yet exist in your ipython dir | |
|
2556 | from the system config dir. Use this after upgrading IPython if you | |
|
2557 | don't wish to delete your .ipython dir. | |
|
2558 | ||
|
2559 | Call with -nolegacy to get rid of ipythonrc* files (recommended for new | |
|
2560 | users) | |
|
2561 | ||
|
2562 | ||
|
2563 | %who: Print all interactive variables, with some minimal formatting. | |
|
2564 | ||
|
2565 | If any arguments are given, only variables whose type matches one of | |
|
2566 | these are printed. For example: | |
|
2567 | ||
|
2568 | %who function str | |
|
2569 | ||
|
2570 | will only list functions and strings, excluding all other types of | |
|
2571 | variables. To find the proper type names, simply use type(var) at a | |
|
2572 | command line to see how python prints type names. For example: | |
|
2573 | ||
|
2574 | In [1]: type('hello') | |
|
2575 | Out[1]: <type 'str'> | |
|
2576 | ||
|
2577 | indicates that the type name for strings is 'str'. | |
|
2578 | ||
|
2579 | %who always excludes executed names loaded through your configuration | |
|
2580 | file and things which are internal to IPython. | |
|
2581 | ||
|
2582 | This is deliberate, as typically you may load many modules and the | |
|
2583 | purpose of %who is to show you only what you've manually defined. | |
|
2584 | ||
|
2585 | ||
|
2586 | %who_ls: Return a sorted list of all interactive variables. | |
|
2587 | ||
|
2588 | If arguments are given, only variables of types matching these arguments | |
|
2589 | are returned. | |
|
2590 | ||
|
2591 | ||
|
2592 | %whos: Like %who, but gives some extra information about each variable. | |
|
2593 | ||
|
2594 | The same type filtering of %who can be applied here. | |
|
2595 | ||
|
2596 | For all variables, the type is printed. Additionally it prints: | |
|
2597 | ||
|
2598 | - For ,[],(): their length. | |
|
2599 | ||
|
2600 | - For numpy and Numeric arrays, a summary with shape, number of | |
|
2601 | elements, typecode and size in memory. | |
|
2602 | ||
|
2603 | - Everything else: a string representation, snipping their middle if too | |
|
2604 | long. | |
|
2605 | ||
|
2606 | ||
|
2607 | %xmode: Switch modes for the exception handlers. | |
|
2608 | ||
|
2609 | Valid modes: Plain, Context and Verbose. | |
|
2610 | ||
|
2611 | If called without arguments, acts as a toggle. | |
|
2612 | ||
|
2613 | ||
|
2614 | Access to the standard Python help | |
|
2615 | ---------------------------------- | |
|
2614 | 2616 | |
|
2615 | 2617 | As of Python 2.1, a help system is available with access to object |
|
2616 | 2618 | docstrings and the Python manuals. Simply type 'help' (no quotes) to |
@@ -2621,7 +2623,8 b' your environment variable PYTHONDOCS for this feature to work correctly.' | |||
|
2621 | 2623 | |
|
2622 | 2624 | |
|
2623 | 2625 | |
|
2624 |
|
|
|
2626 | Dynamic object information | |
|
2627 | -------------------------- | |
|
2625 | 2628 | |
|
2626 | 2629 | Typing ?word or word? prints detailed information about an object. If |
|
2627 | 2630 | certain strings in the object are too long (docstrings, code, etc.) they |
@@ -2662,7 +2665,8 b' are not really defined as separate identifiers. Try for example typing' | |||
|
2662 | 2665 | |
|
2663 | 2666 | |
|
2664 | 2667 | |
|
2665 |
|
|
|
2668 | Readline-based features | |
|
2669 | ----------------------- | |
|
2666 | 2670 | |
|
2667 | 2671 | These features require the GNU readline library, so they won't work if |
|
2668 | 2672 | your Python installation lacks readline support. We will first describe |
@@ -3118,7 +3122,7 b' Each of these options may appear as many times as you need it in the file.' | |||
|
3118 | 3122 | * [import_some <mod> <f1> <f2> ...:] import functions with 'from |
|
3119 | 3123 | <mod> import <f1>,<f2>,...' |
|
3120 | 3124 | * [import_all <mod1> <mod2> ...:] for each module listed import |
|
3121 |
functions with |
|
|
3125 | functions with ``from <mod> import *``. | |
|
3122 | 3126 | * [execute <python code>:] give any single-line python code to be |
|
3123 | 3127 | executed. |
|
3124 | 3128 | * [execfile <filename>:] execute the python file given with an |
@@ -3848,7 +3852,7 b' default prompts::' | |||
|
3848 | 3852 | prompt_in2 ' .\D.:' |
|
3849 | 3853 | prompt_out 'Out[\#]:' |
|
3850 | 3854 | |
|
3851 | which look like this: | |
|
3855 | which look like this:: | |
|
3852 | 3856 | |
|
3853 | 3857 | In [1]: 1+2 |
|
3854 | 3858 | Out[1]: 3 |
@@ -4304,6 +4308,7 b" Physics.PhysicalQuantities from Konrad Hinsen's ScientificPython" | |||
|
4304 | 4308 | The Physics.PhysicalQuantities module defines PhysicalQuantity objects, |
|
4305 | 4309 | but these must be declared as instances of a class. For example, to |
|
4306 | 4310 | define v as a velocity of 3 m/s, normally you would write:: |
|
4311 | ||
|
4307 | 4312 | In [1]: v = PhysicalQuantity(3,'m/s') |
|
4308 | 4313 | |
|
4309 | 4314 | Using the PhysicalQ_Input extension this can be input instead as: |
@@ -4352,18 +4357,12 b' commands instead of as Python code. The special escapes below are also' | |||
|
4352 | 4357 | recognized. !cmd is valid in single or multi-line input, all others are |
|
4353 | 4358 | only valid in single-line input:: |
|
4354 | 4359 | |
|
4355 |
|
|
|
4356 | pass 'cmd' directly to the shell | |
|
4357 |
|
|
|
4358 | execute 'cmd' and return output as a list (split on '\n') | |
|
4359 |
|
|
|
4360 | capture output of cmd into var, as a string list | |
|
4361 | ||
|
4362 | The $/$$ syntaxes make Python variables from system output, which you | |
|
4363 | can later use for further scripting. The converse is also possible: when | |
|
4364 | executing an alias or calling to the system via !/!!, you can expand any | |
|
4365 | python variable or expression by prepending it with $. Full details of | |
|
4366 | the allowed syntax can be found in Python's PEP 215. | |
|
4360 | !cmd | |
|
4361 | pass 'cmd' directly to the shell | |
|
4362 | !!cmd* | |
|
4363 | execute 'cmd' and return output as a list (split on '\n') | |
|
4364 | var=!cmd | |
|
4365 | capture output of cmd into var, as a string list | |
|
4367 | 4366 | |
|
4368 | 4367 | A few brief examples will illustrate these (note that the indentation |
|
4369 | 4368 | below may be incorrectly displayed):: |
@@ -4468,18 +4467,19 b" switching to any of them. Type 'cd?' for more details." | |||
|
4468 | 4467 | %pushd, %popd and %dirs are provided for directory stack handling. |
|
4469 | 4468 | |
|
4470 | 4469 | |
|
4471 |
|
|
|
4470 | Prompt customization | |
|
4471 | -------------------- | |
|
4472 | 4472 | |
|
4473 |
The supplied ipy |
|
|
4473 | The supplied ipy_profile_sh.py profile comes with an example of a very | |
|
4474 | 4474 | colored and detailed prompt, mainly to serve as an illustration. The |
|
4475 | 4475 | valid escape sequences, besides color names, are: |
|
4476 | 4476 | |
|
4477 | 4477 | *\#* |
|
4478 | 4478 | - Prompt number, wrapped in the color escapes for the input prompt |
|
4479 | (determined by the current color scheme). | |
|
4479 | (determined by the current color scheme). | |
|
4480 | 4480 | *\N* |
|
4481 | 4481 | - Just the prompt counter number, without any coloring wrappers. You |
|
4482 | can thus customize the actual prompt colors manually. | |
|
4482 | can thus customize the actual prompt colors manually. | |
|
4483 | 4483 | *\D* |
|
4484 | 4484 | - Dots, as many as there are digits in \# (so they align). |
|
4485 | 4485 | *\w* |
@@ -4595,8 +4595,10 b' value can be read by using the sys.getcheckinterval() function, and it' | |||
|
4595 | 4595 | can be reset via sys.setcheckinterval(N). This switching of threads can |
|
4596 | 4596 | cause subtly confusing effects if one of your threads is doing file I/O. |
|
4597 | 4597 | In text mode, most systems only flush file buffers when they encounter a |
|
4598 | '\n'. An instruction as simple as | |
|
4598 | '\n'. An instruction as simple as:: | |
|
4599 | ||
|
4599 | 4600 | print >> filehandle, ''hello world'' |
|
4601 | ||
|
4600 | 4602 | actually consists of several bytecodes, so it is possible that the |
|
4601 | 4603 | newline does not reach your file before the next thread switch. |
|
4602 | 4604 | Similarly, if you are writing to a file in binary mode, the file won't |
@@ -4608,6 +4610,7 b' example) a GUI application which will read data generated by files' | |||
|
4608 | 4610 | written to from the IPython thread, the safest approach is to open all |
|
4609 | 4611 | of your files in unbuffered mode (the third argument to the file/open |
|
4610 | 4612 | function is the buffering value):: |
|
4613 | ||
|
4611 | 4614 | filehandle = open(filename,mode,0) |
|
4612 | 4615 | |
|
4613 | 4616 | This is obviously a brute force way of avoiding race conditions with the |
General Comments 0
You need to be logged in to leave comments.
Login now