Skip to content
This repository has been archived by the owner on Oct 15, 2022. It is now read-only.

Latest commit

 

History

History
250 lines (185 loc) · 10.4 KB

Day1-writing-scripts.rst

File metadata and controls

250 lines (185 loc) · 10.4 KB
Raw

Script Files (*.py)

As you may be noticing by now, it isn't that convenient to type in all of the commands you would like to use in the IPython interpreter window. An alternative to typing in all of the commands you would like to run is the list them in a Python script file. A Python script file is simple a file containing a list of the command you would like to run, with one command per line, and formatted in the same way as if you were to type them in. Python script files traditionally use the .py file extension in their names.

Getting started

  1. To start creating and editing our Python script file, we'll need to open a text editor.

The general concept of a .py script file

A Python script file is simply a list of commands that you might otherwise type into the IPython interpreter window. As such, we can quite easily create a basic script file and test things out.

  1. Start by copying and pasting the text below into your text editor window.

    SampleID = "DW-NP-48-16"
SampleWeightLbs = 6.89
print("Sample", SampleID, "weighs", SampleWeightLbs, "pounds")

  2. Save this script file as sampleinfo.py in your home directory /home/geo by clicking on File -> Save in the menu bar of the gedit window. Click on the Home icon on the top left of the Save As window that appears, and enter the file name as sampleinfo.py. Click the Save button on the lower right of the window to save the file.

  3. Return to your IPython interpreter window (or start a new one if you have closed it), change the directory in IPython to the home directory by typing cd, and run the script using the %run magic command in IPython. Before pressing Enter on the second line, what do you expect to see as output when the script runs?

    >>> cd
>>> %run sampleinfo.py
Sample DW-NP-48-16 weighs 6.89 pounds

    No surprises here. The script simply executes the commands exactly as you would have if you had typed them in to the IPython interpreter.

  4. Now let's make a small change to the script. Go back to gedit and edit the script so that it now reads

    SampleID = "DW-NP-48-16"
SampleWeightLbs = 6.89
SampleRockType = "Mica schist"
print("Sample", SampleID, "is a", SampleWeightLbs, "pound chunk of", SampleRockType)

    Save your changes.

  5. Once again, go back to the IPython interpreter and use the %run magic command to run the modified script. Don't worry, we'll cover a much better way to edit and test scripts later in today's lesson.

    >>> %run sampleinfo.py
Sample DW-NP-48-16 is a 6.89 pound chunk of Mica schist

Writing our scripts the "right" way

The script above works, but one of the big advantages of using scripts is the ability to include comments that describe what the code does. As your programs get longer and more complicated, comments and other changes to how you write the code will help make sure you (and other users) can understand what the code does. Below are some suggestions to make sure your code is easy to understand.

  1. Add inline comments to the code to explain what different sections do. It may seem obvious how the code should work, but if you share it with another person perhaps they will not feel the same way. It is a very good idea to make the code as easy to read as possible for people.

    # Information for sample 48 from the 2016 Nepal (NP) field excursion collected by Dave Whipp (DW)
# Sample 48 was from the footwall of the MCT just north of where the Nyadi river joins the Marsyandi
# Basic sample information
SampleID = "DW-NP-48-16"
SampleRockType = "Mica schist"
# Sample weight given in pounds (sorry, most of the world)
SampleWeightLbs = 6.89
# Print basic information about this sample to the screen
print("Sample", SampleID, "is a", SampleWeightLbs, "pound chunk of", SampleRockType)

    Here, we have provided a great deal more information about the data in this script by adding inline comments. Comments in Python are not executed by the computer, but provide useful information for people reading the script. Inline comments begin with a # (number sign or hash), and all characters that follow on that line will be ignored by Python. Adding comments to scripts is essential for scientists like ourselves to both help us remember how a script works and to make it easier to share with colleagues. It is best to get into the habit of adding comments as you write.


  1. Use blank lines to visually divide your script. Perhaps it is obvious, but Python will ignore blank lines in a script. They don't matter to Python, but they are very helpful to users.

    # Information for sample 48 from the 2016 Nepal (NP) field excursion collected by Dave Whipp (DW)
# Sample 48 was from the footwall of the MCT just north of where the Nyadi river joins the Marsyandi

# Basic sample information
SampleID = "DW-NP-48-16"
SampleRockType = "Mica schist"

# Sample weight given in pounds (sorry, most of the world)
SampleWeightLbs = 6.89

# Print basic information about this sample to the screen
print("Sample", SampleID, "is a", SampleWeightLbs, "pound chunk of", SampleRockType)

    Dividing even a short script into section using blank lines makes it much easier to read the code.


  1. Add a block comment section at the start of the script to state its purpose, how it is run, who wrote it, and possibly some licencing information. In contrast to the inline comments above that describe the different sections of the code, a block comment at the top of the script is intended to help users run the code and be aware of its author (and licensing restrictions stated by the author). At the minimum, you should include what the script does, your name, and the date in the block comments at the start of script files. Let's add some of this basic information.

    '''sampleinfo.py

A simple Python script to print information for a rock sample on the screen.

Usage: ./sampleinfo.py

David Whipp - 12.9.2016
'''

# Information for sample 48 from the 2016 Nepal (NP) field excursion collected by Dave Whipp (DW)
# Sample 48 was from the footwall of the MCT just north of where the Nyadi river joins the Marsyandi

# Basic sample information
SampleID = "DW-NP-48-16"
SampleRockType = "Mica schist"

# Sample weight given in pounds (sorry, most of the world)
SampleWeightLbs = 6.89

# Print basic information about this sample to the screen
print("Sample", SampleID, "is a", SampleWeightLbs, "pound chunk of", SampleRockType)

    Here we have added the basic information to the top of our script file using block comments. Block comments start with ''' and end with '''. Everything between the triple quotes will be ignored when the script is run, even if the text is spread over multiple lines. In our case, the script is simple, but many Python programs have optional values that can be used by the code when it is run, making the usage statement crucial. Another example to consider is using a formal software license in the code to state the conditions under which the code can be used or modified. There are many helpful web resources to teach you about software licenses and how to choose a license. In most cases my preference is the MIT License, which is simple and allows software use by anyone. An example is below.

    '''sampleinfo.py

A simple Python script to print information for a rock sample on the screen.

Usage: ./sampleinfo.py

MIT License

Copyright (c) 2016 David Whipp

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
'''

# Information for sample 48 from the 2016 Nepal (NP) field excursion collected by Dave Whipp (DW)
# Sample 48 was from the footwall of the MCT just north of where the Nyadi river joins the Marsyandi

# Basic sample information
SampleID = "DW-NP-48-16"
SampleRockType = "Mica schist"

# Sample weight given in pounds (sorry, most of the world)
SampleWeightLbs = 6.89

# Print basic information about this sample to the screen
print("Sample", SampleID, "is a", SampleWeightLbs, "pound chunk of", SampleRockType)

    In this case I have taken the license information directly from an online software license template. Software licensing is an important consideration when posting your software in online repositories such as GitHub. It is one way to protect your intellectual property from being used in ways you do not wish.

Page summary

An expectation in this course is that you stick to the general template described above when writing your code, which means including appropriate use of inline comments, blank lines, block comments, and starting with a shebang.