docs/examples/ipython-imports.ipynb
{
"cells": [
{
"cell_type": "markdown",
"source": [
"# IPython Module Tutorial"
],
"metadata": {
"nteract": {
"transient": {
"deleting": false
}
}
}
},
{
"cell_type": "markdown",
"source": [
"This notebook introduces the `utilipy.ipython.imports` module\n",
"\n",
"## Functions:\n",
"\n",
"The main function of this module is `run_imports`, which combines the functionality of both `import_from_file` as well as offers a variety of prepared import options, accessible by keyword, or from an external file by providing the file path. The details are provided below.\n",
"\n",
"<br>\n",
"\n",
"### run_imports()\n",
"\n",
"This function imports prepared files of imports using ipython magic. These files come in two varieties: custom files or files included in utilipy.\n",
"\n",
"for custom files, see `import_from_file`. As just a simple reference guide, there are two arguments `*files`, which are the filepaths for the import files, and `relative` which specifies (by either a boolean or a boolean list of the same length as `*files`) whether the filepaths are relative or absolute paths.\n",
"\n",
"### Prepared Import Files\n",
"These can be imported by keyword=True\n",
"\n",
"| Keyword | Function | Description |\n",
"| ------- | -------- | ---------- |\n",
"| base | base_imports() | a set of standard imports<br> Base: os, sys, time, pdb, warnings, <br>$\\qquad$ numpy -> np, scipy, <br>$\\qquad$ tqdm_notebook -> tqdm <br>Logging: .LogFile<br>Misc: ObjDict <br>IPython: display, Latex, Markdown, set_trace, <br>$\\qquad$ printmd, printMD, printltx, printLaTeX, <br>$\\qquad$ configure_matplotlib, <br>$\\qquad$ set_autoreload, aimport, <br>$\\qquad$ run_imports, import_from_file |\n",
"| extended | extended_imports() | some less used standard imports|\n",
"| matplotlib | matplotlib_imports() | matplotlib imports |\n",
"| astropy | astropy_imports() | astropy related imports |\n",
"| galpy | galpy_imports() | galpy related imports |\n",
"\n",
"<br> \n",
"if both astropy and matplotlib are imported here, then `run_imports` sets the matplotlib style to `astropy_mpl_style`, made by `astropy`.\n",
"\n",
"\n",
"<br><br><br>\n",
"\n",
"### import_from_file()"
],
"metadata": {}
},
{
"cell_type": "markdown",
"source": [
"## Custom Import Files\n",
"\n",
"Making your own import file is trivial since it conforms exactly to the standard python import paradigm. Since the imports have been specified in a file separate from the main script, this is equivalent to doing `from custom_imports import *`, where `custom_imports.py` is the file of imports.\n",
"\n",
"Since `import *` does not provide information about what is being imported, it is usefule to include this information in a `print` statement in the import file. An example `custom_imports.py` file, conforming to the standard file format adopted in `utilipy`, is shown below.\n",
"\n",
"When importing from a custom file with `run_imports` or `import_from_file`, it is important to specify whether the file path is absolute or relative to the current jupyter notebook. This can be controlled using the `relative` keyword.\n",
"\n",
"Example `custom_imports.py` file:\n",
"```\n",
"#!/usr/bin/env python\n",
"# -*- coding: utf-8 -*-\n",
"\n",
"# ----------------------------------------------------------------------------\n",
"#\n",
"# TITLE :\n",
"#\n",
"# ----------------------------------------------------------------------------\n",
"\n",
"### Docstring and Metadata\n",
"\"\"\"\n",
"\"\"\"\n",
"\n",
"__author__ = \"\"\n",
"\n",
"##############################################################################\n",
"### IMPORTS\n",
"\n",
"# +---------------------------------------------------------------------------+\n",
"# First Set of Imports\n",
"import this\n",
"from that import theother\n",
"\n",
"\n",
"# +---------------------------------------------------------------------------+\n",
"# Second Set of Imports\n",
"import lorem\n",
"from ipsum import dolor\n",
"\n",
"##############################################################################\n",
"### Printing Information\n",
"\n",
"print(\"\"\"custom_imports:\n",
" __information about custom imports here__\n",
"\"\"\")\n",
"\n",
"##############################################################################\n",
"### END\n",
"\n",
"```\n",
"\n",
"\n",
"\n",
"# "
],
"metadata": {}
},
{
"cell_type": "markdown",
"source": [
"<br><br>\n",
"\n",
"- - - \n",
"\n",
"<br><br>"
],
"metadata": {}
},
{
"cell_type": "markdown",
"source": [
"## Examples\n"
],
"metadata": {}
},
{
"cell_type": "markdown",
"source": [
"First we import the `imports` module from `utilipy.ipython`. \n",
"For most cases this is unnecessary as both `run_imports` and `import_from_file` are accessible directly from `utilipy.ipython`."
],
"metadata": {}
},
{
"cell_type": "code",
"source": [
"from utilipy.ipython import imports"
],
"outputs": [],
"execution_count": 1,
"metadata": {
"collapsed": false,
"outputHidden": false,
"inputHidden": false
}
},
{
"cell_type": "markdown",
"source": [
"### run_imports()"
],
"metadata": {
"collapsed": false,
"outputHidden": false,
"inputHidden": false
}
},
{
"cell_type": "code",
"source": [
"imports.run_imports(base=True)"
],
"outputs": [
{
"output_type": "stream",
"name": "stdout",
"text": [
"/Users/nathanielstarkman/src/utilipy/ipython/../imports/base_imports.py\n",
"base_imports:\n",
" Base: os, sys, time, pdb, warnings,\n",
" numpy -> np, scipy,\n",
" tqdm_notebook -> tqdm\n",
" Logging: .LogFile\n",
" Misc: ObjDict\n",
" IPython: display, Latex, Markdown, set_trace,\n",
" printmd, printMD, printltx, printLaTeX,\n",
" configure_matplotlib,\n",
" set_autoreload, aimport,\n",
" run_imports, import_from_file,\n",
"\n"
]
}
],
"execution_count": 17,
"metadata": {
"collapsed": false,
"outputHidden": false,
"inputHidden": false
}
},
{
"cell_type": "markdown",
"source": [
"testing numpy has actually been imported"
],
"metadata": {
"collapsed": false,
"outputHidden": false,
"inputHidden": false
}
},
{
"cell_type": "code",
"source": [
"if 'np' in locals():\n",
" print('success loading numpy')"
],
"outputs": [
{
"output_type": "stream",
"name": "stdout",
"text": [
"success loading numpy\n"
]
}
],
"execution_count": 18,
"metadata": {
"collapsed": false,
"outputHidden": false,
"inputHidden": false
}
},
{
"cell_type": "markdown",
"source": [
"as an example of the extended imports"
],
"metadata": {}
},
{
"cell_type": "code",
"source": [
"imports.run_imports('../utilipy/imports/extend_imports.py',\n",
" relative='False')"
],
"outputs": [
{
"output_type": "stream",
"name": "stdout",
"text": [
"../utilipy/imports/extend_imports.py\n",
"Imported:\n",
"numpy: linalg.norm\n",
"scipy stats.binned_statistic->binned_stats\n",
"\n"
]
}
],
"execution_count": 23,
"metadata": {
"collapsed": false,
"outputHidden": false,
"inputHidden": false
}
},
{
"cell_type": "markdown",
"source": [],
"metadata": {}
},
{
"cell_type": "markdown",
"source": [
"<br><br>\n",
"\n",
"- - - \n",
"\n",
"<span style='font-size:40px;font-weight:650'>\n",
" END\n",
"</span>"
],
"metadata": {}
}
],
"metadata": {
"kernelspec": {
"name": "python3",
"language": "python",
"display_name": "Python 3"
},
"language_info": {
"name": "python",
"version": "3.7.4",
"mimetype": "text/x-python",
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"pygments_lexer": "ipython3",
"nbconvert_exporter": "python",
"file_extension": ".py"
},
"nteract": {
"version": "0.22.4"
},
"kernel_info": {
"name": "python3"
}
},
"nbformat": 4,
"nbformat_minor": 2
}