This content originally appeared on Level Up Coding - Medium and was authored by Dakota Smith
A beginner-friendly guide to getting started with the macOS Terminal to call Python scripts in a few short characters
Table of Contents
- What we’ll be going over
- A brief overview of the macOS Terminal and zsh
- Using Python to retrieve data
- How to shorten calling the Python script in your Terminal
Introduction
A lot of the way I learn comes down to having the thought, “I bet there’s an easier way to do this.” Similar thoughts include: “I’m sick of writing this boilerplate code over and over,” and, “The twenty minutes a month this automation will save me will greatly enrich my life, surely.”
This impulse comes from a good place. Or at least a logically consistent one if you also enjoy coding. Quality code is documented, standardized, and reproducible. Automating simple tasks may not always be the most efficient use of time in the short term, but it embeds these characteristics into the workflow, which is useful in the long run.
For example, I had a SQL query at work I ran often, with minor adjustments here and there, against a database. Included in the WHERE clause was always a LOWER(<field>) LIKE “%<value>%” condition that for whatever reason irked me to write all the time. So I developed a Python script that could generate the query with whatever conditions were needed based on inputs from the Terminal, then wrote a zsh function to shorten the call to that script to about ten characters.
Was this necessary? No, I guess not, but it did improve my understanding of zsh and the sys Python library. Does it save me some time to this day? Yes. Does that saved time enrich my life?
Yes. You know what—yes, it does.
And it’s not difficult to replicate for other purposes. I’m going to show you how to do that exactly that here.
What we’ll be going over
- A brief overview of zsh
- How to use Python to retrieve a value from a local JSON file
- Using the sys module from the Python standard library to accept inputs from your Terminal
- How to write a simple zsh function that can be typed into your Terminal to execute a Python script in far fewer characters than python3 /Users/dakotasmith/pyProjects/path_I_will_rarely_remember.py <arg>
What you need to know
- A beginner’s knowledge of Python
- How to open the Terminal
zsh
What is zsh?
Pronounced “z-shell,” zsh is a command interpreter. You can think of it as the language you use on a Mac to talk to your Terminal (if you’re using the current macOS, Catalina or a more recent release).
It’s an extended version of Bash, but for our purposes right now we’re just going to focus on the .zshrc file.
The .zshrc file is a list of commands that are run, defined, or both, any time you open a new Terminal. It can define custom functions like the one we’ll eventually use to call our Python script. However, the .zshrc file doesn’t exist by default, so if you haven’t already done so, it has to be created.
You want the .zshrc file to be in your root directory, which is where a new Terminal will be pointed at in most cases. In a Terminal shell, type (or copy and paste) nano ~/.zshrc and hit Enter.
The resulting interface might not look familiar to inexperienced Terminal users, but it’s a text editor that comes with some handy keyboard shortcuts. We’re not going to do anything in this file right now except create it. Hit the following keys in the order described. I’ve added brief descriptions of what each keyboard shortcut does.
nano keyboard shortcuts:
- Ctrl-O: save
- Enter (following Ctrl-O): confirm save
- Ctrl-X: exit nano
We’ll come back to this .zshrc file in a bit. Let’s move on to our Python script.
What’re we doing with Python again?
We’re going to make an otherwise monotonous query to a local JSON file quick and easy. Again, this is just instructional; you can configure the script to whatever need you have.
For this tutorial, my particular JSON file — which you can find here or generate yourself with this Python script — contains some very important colors and their very important hex codes.
If you want to follow along with the example, I suggest creating a local project folder. If you want to get fancy, I also suggest creating a virtual environment for the project. (Nothing’s fancier than not having to manage dependency issues.)
However, as the only libraries used in this tutorial are from the Python standard library, you shouldn’t have any dependency issues unless you’re running Python 2.
Using and managing virtual environments is considered best practice when working on Python projects. For more info, start here. I use pyenv to manage mine. I’ll note that while I might often provide links to Real Python articles, I’m in no way personally affiliated with them; I just think they make fantastic content.
Okay. We have our project folder, we have our virtual environment (or not, woops), and we’ve created our .zshrc file. We’ve done a lot and have almost nothing to show for it. Cool, I guess!
Let’s write some code.
The Almighty Code
You can view the code for our Python script here (which, okay—it’s not that almighty). Feel free to skip this section if you’re not interested in how the code works.
In a .py file, we’ll start by importing our modules.
import json
from sys import argv
from insert_data import file_path
Note that the module insert_data is actually another .py file in the same directory (i.e., the project folder). You don’t need to import this if you don’t want to. You could just as easily assign the variable file_path within the script. I don’t like repeating myself, so since I generated the file in insert_data.py, I’ve gone ahead and imported its respective file path.
Our first module is the json module, which will allow us to read from the JSON file that contains our data.
We then import argv from the sys module to access arguments passed from the Terminal.
And finally, from our project folder, we import the file_path variable defined in our insert_data.py file. (Again: just a design choice.)
Next we’ll define a simple function that reads our JSON and returns the data therein:
def get_data() -> json:
with open(file_path, "r") as f:
return json.load(f)
Another best practice: using the with statement to make sure that after reading the JSON file, Python closes it no matter what happens (i.e., if an error occurs). The wrong loop with an unattended open() function can crash your computer.
After this, we can write the function that will serve as our main program. I’ll take it step by step, and then include the function’s code in its entirety at the end.
First:
def get_color_value(color: str) -> dict:
data = get_data()
We start by defining a function get_color_value that accepts the parameter color. Type hints indicate that color should be a string and that the value returned by the function will be a dictionary. We then call the previously defined get_data() and assign its result to the variable data.
assert color in [
item.get("color") for item in data
], "Color selected not available. Try red!"
Here, we assert that the argument passed into the parameter color is one that we actually have data on.
In layman’s terms: Sorry, but “cerulean” isn’t in our modest dict of colors. Er, I mean—in our dictionary of very important colors and their very important hex codes, cerulean didn’t make the cut. Sincerest apologies.
The assert statement acts as a checkpoint determining whether or not something is true. For example, if we’d written assert 1 == 1, nothing would happen, since 1 == 1 is true. However, if were to assert something that isn’t true, like assert 1 == 0, the application would throw an error. Accompanying that error would be whatever string is passed following the assertion.
Without our assert statement, if we entered a color that isn’t in the data, nothing would be returned by the function. This could seem like a bug, so instead we’re just going to head off at the pass all colors missing from our data, and in the error message, suggest something simpler — in this case, red.
color_dict = {
item["color"]: item["value"] for item in data if item["color"] == color
}
return color_dictHere we create our final product. We do this by using a comprehension — a for loop, essentially, enclosed by the syntax of our chosen iterable (in this case, a dictionary, as indicated by the curly braces). Though you could just as easily write a for loop if that’s more comfortable.
And then we return color_dict, the extraordinarily important color and its extraordinarily important hex code.
Finally, our get_color_value function in all its glory:
def get_color_value(color: str) -> dict:
data = get_data()
assert color in [
item.get("color") for item in data
], "Color selected not available. Try red!"
color_dict = {
item["color"]: item["value"] for item in data if item["color"] == color
}
return color_dict
Looks good! I’ll probably frame it.
Lastly, because right now our script doesn’t actually do anything, we need to call our main function inside an if __name__ == “__main__”: statement.
if __name__ == "__main__":
color = str(argv[1])
value = get_color_value(color)
print(value)
Wait—if who equals equals what?
A quick primer on if __name__ == “__main__” , because it can be a tricky concept if you’re new to Python.
Basically, it tells Python: If this script is being executed, do the following things.
So for one, it gives you an opportunity to set up what you want the script to do, and to make it readable (ideally). But more importantly, it protects you from accidentally executing the script in situations where you’re not trying to—e.g., when you’re importing it as a module in another script.
If you want to spend some time wrapping your head around this more, allow me to provide some additional reading material.
Breaking it down:
if __name__ == "__main__":
color = argv[1]
When we eventually input into the Terminal what color we’re looking for, argv[1] will read that value and pass it along to the color variable.
Spoiler alert: I’m gonna put red.
value = get_color_value(color)
print(value)
Then we call our get_color_value function, and pass in the input variable color.
This returns the color_dict dictionary into our new variable value, which then gets printed into the Terminal.
If you open your Terminal and navigate to your project folder (hint: use the cd function, which stands for change directory), you can see the script in action. Call it by entering python3 <file_path> <color>, substituting the variables for your own file path and color.
Mine looks like this: python3 zsh_python_tutorial/get_color_value.py red
Okay, but that was a lot to type out
Exactly. There simply isn’t enough time in the day to spend an extra minute frivolously hunting down a file path, relative or not.
It may seem silly given what the code does, but remember, this is a simple example. Entire workflows can be condensed to a single word using these concepts. At your pithy command, entire cities could rise and fall from the Terminal.
Maybe. Hopefully not. For now, let’s just retrieve some incredibly valuable color data.
In your Terminal, enter nano .zshrc. It’s time to create our zsh function.
Here’s what it looks like if you just want to copy and paste it into your nano editor:
get_color() {
cd /Users/dakotaleesmith/pyProjects
python3 zsh_python_tutorial/get_color_value.py "$1"
cd ~
}Obviously don’t cd to my local pyProjects directory. It won’t work unless your name happens to also be Dakota Lee Smith and you’ve followed along with the tutorial a little too closely. Insert your own paths where applicable (i.e., after the first cd and then after python3).
Now—with brevity as our guiding principle—let’s go over each line in this function.
get_color() {Here we name the function and declare it as such. The opening curly braces tell zsh that the commands that follow are to be executed as a result of calling this function.
cd /Users/dakotaleesmith/pyProjects
The first command. All we’re doing here is pointing the Terminal at our local project folder. The function executes this command first before moving onto the next:
python3 zsh_python_tutorial/get_color_value.py "$1"
This we’ve seen already. It’s a call to our Python script.
The part to note here is "$1". This is our color variable—it stands in for whatever color is passed to the zsh function as an argument.
This value is what’s returned by argv[1] in the Python script.
And finally:
cd ~
}
Which, along with closing the get_color function using the curly brace at the bottom, simply points our Terminal back at our root directory. You don’t have to include this, but to me it’s always seemed polite. To my future self, that is. Because if you open that same Terminal shell later to do something else, you might not notice that it’s pointed at a directory other than your root. (This has been a common and mildly frustrating experience for me.)
Now that your function is inside your .zshrc file, you can call it from any future Terminal shell. But first, don’t forget to save. As a reminder, here’s how:
nano keyboard shortcuts:
- Ctrl-O: save
- Enter (following Ctrl-O): confirm save
- Ctrl-X: exit nano
After this you should be back in your regular ol’ Terminal. But wait! Don’t call the function yet.
We need to close that Terminal shell and open a new one. Our current shell hasn’t ran the updated .zshrc file. It has no idea what the get_color function does, and will laugh at you, probably, if you attempt to call it.
Once you’ve opened a new Terminal, you‘ll be able to call the function and retrieve whatever data you’ve assigned the Python script to retrieve.
Conclusion
Wow! Would you look at that. Not only can I now obtain the hex code for a color with only 15 characters, but I’ve also fundamentally changed as a person:
get_color green
>>> {'green': '#0f0'}
I’ve moved on from red. I’m a green guy, now.
Feel free to connect with me on LinkedIn. And if you have any questions and/or constructive feedback, don’t hesitate to leave a comment!
Level Up Coding
Thanks for being a part of our community! Before you go:
- 👏 Clap for the story and follow the author 👉
- 📰 View more content in the Level Up Coding publication
- 💰 Free coding interview course ⇒ View Course
- 🔔 Follow us: Twitter | LinkedIn | Newsletter
🚀👉 Join the Level Up talent collective and find an amazing job
Using Python and the Terminal to Simplify Repetitive Data Tasks was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Level Up Coding - Medium and was authored by Dakota Smith
Dakota Smith | Sciencx (2023-03-08T03:44:05+00:00) Using Python and the Terminal to Simplify Repetitive Data Tasks. Retrieved from https://www.scien.cx/2023/03/08/using-python-and-the-terminal-to-simplify-repetitive-data-tasks/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.