workspace.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0577b863",
   "metadata": {},
   "source": [
    "\n",
    "<a id='workspace'></a>\n",
    "<div id=\"qe-notebook-header\" align=\"right\" style=\"text-align:right;\">\n",
    "        <a href=\"https://quantecon.org/\" title=\"quantecon.org\">\n",
    "                <img style=\"width:250px;display:inline;\" width=\"250px\" src=\"https://assets.quantecon.org/img/qe-menubar-logo.svg\" alt=\"QuantEcon\">\n",
    "        </a>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40de2869",
   "metadata": {},
   "source": [
    "# Writing Longer Programs"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6c3ca9b8",
   "metadata": {},
   "source": [
    "## Contents\n",
    "\n",
    "- [Writing Longer Programs](#Writing-Longer-Programs)  \n",
    "  - [Overview](#Overview)  \n",
    "  - [Working with Python files](#Working-with-Python-files)  \n",
    "  - [Development environments](#Development-environments)  \n",
    "  - [A step forward from Jupyter Notebooks: JupyterLab](#A-step-forward-from-Jupyter-Notebooks:-JupyterLab)  \n",
    "  - [A walk through Visual Studio Code](#A-walk-through-Visual-Studio-Code)  \n",
    "  - [Git your hands dirty](#Git-your-hands-dirty)  "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dd20568a",
   "metadata": {},
   "source": [
    "## Overview\n",
    "\n",
    "So far, we have explored the use of Jupyter Notebooks in writing and executing Python code.\n",
    "\n",
    "While they are efficient and adaptable when working with short pieces of code, Notebooks are not the best choice for longer programs and scripts.\n",
    "\n",
    "Jupyter Notebooks are well suited to interactive computing (i.e. data science workflows) and can help execute chunks of code one at a time.\n",
    "\n",
    "Text files and scripts allow for long pieces of code to be written and executed in a single go.\n",
    "\n",
    "We will explore the use of Python scripts as an alternative.\n",
    "\n",
    "The Jupyter Lab and Visual Studio Code (VS Code) development environments are then introduced along with a primer on version control (Git).\n",
    "\n",
    "In this lecture, you will learn to\n",
    "\n",
    "- work with Python scripts  \n",
    "- set up various development environments  \n",
    "- get started with GitHub  \n",
    "\n",
    "\n",
    ">**Note**\n",
    ">\n",
    ">Going forward, it is assumed that you have an Anaconda environment up and running.\n",
    "\n",
    "You may want to [create a new conda environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands) if you haven’t done so already."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32c18e9b",
   "metadata": {},
   "source": [
    "## Working with Python files\n",
    "\n",
    "Python files are used when writing long, reusable blocks of code - by convention, they have a `.py` suffix.\n",
    "\n",
    "Let us begin by working with the following example.\n",
    "\n",
    "sine_wave.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7adce1a5",
   "metadata": {
    "hide-output": false
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "x = np.linspace(0, 10, 100)\n",
    "y = np.sin(x)\n",
    "\n",
    "plt.plot(x, y)\n",
    "plt.xlabel('x')\n",
    "plt.ylabel('y')\n",
    "plt.title('Sine Wave')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b93abbf9",
   "metadata": {},
   "source": [
    "The code is first saved locally on the computer before it is executed.\n",
    "\n",
    "As there are various ways to execute the code, we will explore them in the context of different development environments.\n",
    "\n",
    "One major advantage of using Python scripts lies in the fact that you can “import” functionality from other scripts into your current script or Jupyter Notebook.\n",
    "\n",
    "Let’s rewrite the earlier code into a function.\n",
    "\n",
    "sine_wave.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0ae94f8d",
   "metadata": {
    "hide-output": false
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "# Define the plot_wave function.\n",
    "def plot_wave(title : str = 'Sine Wave'):\n",
    "  x = np.linspace(0, 10, 100)\n",
    "  y = np.sin(x)\n",
    "\n",
    "  plt.plot(x, y)\n",
    "  plt.xlabel('x')\n",
    "  plt.ylabel('y')\n",
    "  plt.title(title)\n",
    "  plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "129b7e8d",
   "metadata": {},
   "source": [
    "second_script.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7259f92d",
   "metadata": {
    "hide-output": false
   },
   "outputs": [],
   "source": [
    "import sine_wave # Import the sine_wave script\n",
    " \n",
    "# Call the plot_wave function.\n",
    "sine_wave.plot_wave(\"Sine Wave - Called from the Second Script\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3409d156",
   "metadata": {},
   "source": [
    "This allows you to split your code into chunks and structure your codebase better.\n",
    "\n",
    "Look into the use of [modules](https://docs.python.org/3/tutorial/modules.html) and [packages](https://docs.python.org/3/tutorial/modules.html#packages) for more information on importing functionality."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "efa260a4",
   "metadata": {},
   "source": [
    "## Development environments\n",
    "\n",
    "A development environment is a one stop workspace where you can\n",
    "\n",
    "- edit and run your code  \n",
    "- test and debug  \n",
    "- manage project files  \n",
    "\n",
    "\n",
    "This lecture takes you through the workings of two development environments."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c7617b20",
   "metadata": {},
   "source": [
    "## A step forward from Jupyter Notebooks: JupyterLab\n",
    "\n",
    "JupyterLab is a browser based development environment for Jupyter Notebooks, code scripts, and data files.\n",
    "\n",
    "You can [try JupyterLab in the browser](https://jupyter.org/try#jupyterlab) if you want to test it out before installing it locally.\n",
    "\n",
    "You can install JupyterLab using pip"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "790b2957",
   "metadata": {
    "hide-output": false
   },
   "outputs": [],
   "source": [
    "> pip install jupyterlab"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1a97ae1",
   "metadata": {},
   "source": [
    "and launch it in the browser, similar to Jupyter Notebooks."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "76debe2e",
   "metadata": {
    "hide-output": false
   },
   "outputs": [],
   "source": [
    "> jupyter-lab"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6c672b2f",
   "metadata": {},
   "source": [
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/jupyter_lab_cmd.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/jupyter_lab_cmd.png)\n",
    "\n",
    "  \n",
    "You can see that the Jupyter Server is running on port 8888 on the localhost.\n",
    "\n",
    "The following interface should open up on your default browser automatically - if not, CTRL + Click the server URL.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/jupyter_lab.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/jupyter_lab.png)\n",
    "\n",
    "  \n",
    "Click on\n",
    "\n",
    "- the Python 3 (ipykernel) button under Notebooks to open a new Jupyter Notebook  \n",
    "- the Python File button to open a new Python script (.py)  \n",
    "\n",
    "\n",
    "You can always open this launcher tab by clicking the ‘+’ button on the top.\n",
    "\n",
    "All the files and folders in your working directory can be found in the File Browser (tab on the left).\n",
    "\n",
    "You can create new files and folders using the buttons available at the top of the File Browser tab.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/file_browser.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/file_browser.png)\n",
    "\n",
    "  \n",
    "You can install extensions that increase the functionality of JupyterLab by visiting the Extensions tab.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/extensions.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/extensions.png)\n",
    "\n",
    "  \n",
    "Coming back to the example scripts from earlier, there are two ways to work with them in JupyterLab.\n",
    "\n",
    "- Using magic commands  \n",
    "- Using the terminal  "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c8d35ff2",
   "metadata": {},
   "source": [
    "### Using magic commands\n",
    "\n",
    "Jupyter Notebooks and JupyterLab support the use of [magic commands](https://ipython.readthedocs.io/en/stable/interactive/magics.html) - commands that extend the capabilities of a standard Jupyter Notebook.\n",
    "\n",
    "The `%run` magic command allows you to run a Python script from within a Notebook.\n",
    "\n",
    "This is a convenient way to run scripts that you are working on in the same directory as your Notebook and present the outputs within the Notebook.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/jupyter_lab_py_run.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/jupyter_lab_py_run.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "48e280a7",
   "metadata": {},
   "source": [
    "### Using the terminal\n",
    "\n",
    "However, if you are looking into just running the `.py` file, it is sometimes easier to use the terminal.\n",
    "\n",
    "Open a terminal from the launcher and run the following command."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1adb0b2f",
   "metadata": {
    "hide-output": false
   },
   "outputs": [],
   "source": [
    "> python <path to file.py>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ed5947e3",
   "metadata": {},
   "source": [
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/jupyter_lab_py_run_term.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/jupyter_lab_py_run_term.png)\n",
    "\n",
    "  \n",
    ">**Note**\n",
    ">\n",
    ">You can also run the script line by line by opening an ipykernel console either\n",
    "\n",
    "- from the launcher  \n",
    "- by right clicking within the Notebook and selecting Create Console for Editor  \n",
    "\n",
    "\n",
    "Use Shift + Enter to run a line of code.\n",
    "\n",
    "More on ipykernel consoles [here](https://ipython.readthedocs.io/en/stable/interactive/reference.html#ipykernel)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "086955ed",
   "metadata": {},
   "source": [
    "## A walk through Visual Studio Code\n",
    "\n",
    "Visual Studio Code (VS Code) is a code editor and development workspace that can run\n",
    "\n",
    "- in the [browser](https://vscode.dev/).  \n",
    "- as a local [installation](https://code.visualstudio.com/docs/?dv=win).  \n",
    "\n",
    "\n",
    "Both interfaces are identical.\n",
    "\n",
    "When you launch VS Code, you will see the following interface.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_home.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_home.png)\n",
    "\n",
    "  \n",
    "Explore how to customize VS Code to your liking through the guided walkthroughs.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_walkthrough.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_walkthrough.png)\n",
    "\n",
    "  \n",
    "When presented with the following prompt, go ahead an install all recommended extensions.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_install_ext.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_install_ext.png)\n",
    "\n",
    "  \n",
    "You can also install extensions from the Extensions tab.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_extensions.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_extensions.png)\n",
    "\n",
    "  \n",
    "Jupyter Notebooks (`.ipynb` files) can be worked on in VS Code.\n",
    "\n",
    "Make sure to install the Jupyter extension from the Extensions tab before you try to open a Jupyter Notebook.\n",
    "\n",
    "Create a new file (in the file Explorer tab) and save it with the `.ipynb` extension.\n",
    "\n",
    "Choose a kernel/environment to run the Notebook in by clicking on the Select Kernel button on the top right corner of the editor.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_kernels.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_kernels.png)\n",
    "\n",
    "  \n",
    "VS Code also has excellent version control functionality through the Source Control tab.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_git.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_git.png)\n",
    "\n",
    "  \n",
    "Link your GitHub account to VS Code to push and pull changes to and from your repositories.\n",
    "\n",
    "Further discussions about version control can be found in the next section.\n",
    "\n",
    "To open a new Terminal in VS Code, click on the Terminal tab and select New Terminal.\n",
    "\n",
    "VS Code opens a new Terminal in the same directory you are working in - a PowerShell in Windows and a Bash in Linux.\n",
    "\n",
    "You can change the shell or open a new instance through the dropdown menu on the right end of the terminal tab.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_terminal_opts.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_terminal_opts.png)\n",
    "\n",
    "  \n",
    "VS Code helps you manage conda environments without using the command line.\n",
    "\n",
    "Open the Command Palette (CTRL + SHIFT + P or from the dropdown menu under View tab) and search for `Python: Select Interpreter`.\n",
    "\n",
    "This loads existing environments.\n",
    "\n",
    "You can also create new environments using `Python: Create Environment` in the Command Palette.\n",
    "\n",
    "A new environment (.conda folder) is created in the the current working directory.\n",
    "\n",
    "Coming to the example scripts from earlier, there are again two ways to work with them in VS Code.\n",
    "\n",
    "- Using the run button  \n",
    "- Using the terminal  "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bbdd977b",
   "metadata": {},
   "source": [
    "### Using the run button\n",
    "\n",
    "You can run the script by clicking on the run button on the top right corner of the editor.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_run.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_run.png)\n",
    "\n",
    "  \n",
    "You can also run the script interactively by selecting the **Run Current File in Interactive Window** option from the dropdown.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_run_button.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/vs_code_run_button.png)\n",
    "\n",
    "  \n",
    "This creates an ipykernel console and runs the script."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11953e37",
   "metadata": {},
   "source": [
    "### Using the terminal\n",
    "\n",
    "The command `python <path to file.py>` is executed on the console of your choice.\n",
    "\n",
    "If you are using a Windows machine, you can either use the Anaconda Prompt or the Command Prompt - but, generally not the PowerShell.\n",
    "\n",
    "Here’s an execution of the earlier code.\n",
    "\n",
    "![https://python-programming.quantecon.org/_static/lecture_specific/workspace/sine_wave_import.png](https://python-programming.quantecon.org/_static/lecture_specific/workspace/sine_wave_import.png)\n",
    "\n",
    "  \n",
    ">**Note**\n",
    ">\n",
    ">If you would like to develop packages and build tools using Python, you may want to look into [the use of Docker containers and VS Code](https://github.com/RamiKrispin/vscode-python).\n",
    "\n",
    "However, this is outside the focus of these lectures."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0fab2bce",
   "metadata": {},
   "source": [
    "## Git your hands dirty\n",
    "\n",
    "This section will familiarize you with git and GitHub.\n",
    "\n",
    "[Git](http://git-scm.com/) is a *version control system* — a piece of software used to manage digital projects such as code libraries.\n",
    "\n",
    "In many cases, the associated collections of files — called *repositories* — are stored on [GitHub](https://github.com/).\n",
    "\n",
    "GitHub is a wonderland of collaborative coding projects.\n",
    "\n",
    "For example, it hosts many of the scientific libraries we’ll be using later\n",
    "on, such as [this one](https://github.com/pydata/pandas).\n",
    "\n",
    "Git is the underlying software used to manage these projects.\n",
    "\n",
    "Git is an extremely powerful tool for distributed collaboration — for\n",
    "example, we use it to share and synchronize all the source files for these\n",
    "lectures.\n",
    "\n",
    "There are two main flavors of Git\n",
    "\n",
    "1. the plain vanilla [command line Git](http://git-scm.com/downloads) version  \n",
    "1. the various point-and-click GUI versions  \n",
    "  - See, for example, the [GitHub version](https://desktop.github.com/) or Git GUI integrated into your IDE.  \n",
    "\n",
    "\n",
    "In case you already haven’t, try\n",
    "\n",
    "1. Installing Git.  \n",
    "1. Getting a copy of [QuantEcon.py](https://github.com/QuantEcon/QuantEcon.py) using Git.  \n",
    "\n",
    "\n",
    "For example, if you’ve installed the command line version, open up a terminal and enter."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bd18caa7",
   "metadata": {
    "hide-output": false
   },
   "source": [
    "```bash\n",
    "git clone https://github.com/QuantEcon/QuantEcon.py\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "42f06ee8",
   "metadata": {},
   "source": [
    "(This is just `git clone` in front of the URL for the repository)\n",
    "\n",
    "This command will download all necessary components to rebuild the lecture you are reading now.\n",
    "\n",
    "As the 2nd task,\n",
    "\n",
    "1. Sign up to [GitHub](https://github.com/).  \n",
    "1. Look into ‘forking’ GitHub repositories (forking means making your own copy of a GitHub repository, stored on GitHub).  \n",
    "1. Fork [QuantEcon.py](https://github.com/QuantEcon/QuantEcon.py).  \n",
    "1. Clone your fork to some local directory, make edits, commit them, and push them back up to your forked GitHub repo.  \n",
    "1. If you made a valuable improvement, send us a [pull request](https://help.github.com/articles/about-pull-requests/)!  \n",
    "\n",
    "\n",
    "For reading on these and other topics, try\n",
    "\n",
    "- [The official Git documentation](http://git-scm.com/doc).  \n",
    "- Reading through the docs on [GitHub](https://docs.github.com/en).  \n",
    "- [Pro Git Book](http://git-scm.com/book) by Scott Chacon and Ben Straub.  \n",
    "- One of the thousands of Git tutorials on the Net.  "
   ]
  }
 ],
 "metadata": {
  "date": 1710455933.1478722,
  "filename": "workspace.md",
  "kernelspec": {
   "display_name": "Python",
   "language": "python3",
   "name": "python3"
  },
  "title": "Writing Longer Programs"
 },
 "nbformat": 4,
 "nbformat_minor": 5
}