You have decided to learn Python. It can be a scary moment. The thought of having the empty canvas of your computer screen in front of you and not knowing where to start can be overwhelming. But don't worry, with a couple of key pieces of knowledge you will be able to start building your first Python project in no time. To start, some knowledge about how computers work is useful. It can help build a mental model around what is going on and will make things much less mysterious. I will try to give you a minimum of key concepts so we can start building your first Python project with some common ground.

Files and Directories

Thinking about how a computer works can be complex. However we can simplify it by thinking about it as a big filing cabinet. A filling cabinet has many files spread across many folders. In the same way we can think about everything in a computer as either a file or a folder. A folder (also called directory) is just a collection of other directories and/or files so its not very interesting. All the interesting work is done in the files. Every day you use different kinds of files, like text files, image files, video files, and more. In the end all files are just a text sequence that the computer can read and write if you tell it exactly how.

Tasks and Programs

Anythin a computer does, wheter its a website, a game, a word processor, or a backend service we can call a task. A task is a running instance of a program, which in itself is nothing more than a file with text. The program has the writen instructions that the computer will follow. Every program is written on a programming language and for the computer to understand it, it needs to be translated to machine code. The computer doesnt care about the original language you wrote in. Ultimately the code will be translated into machine code (another file) that the computer will understand and run.

What is Python?

Python, the language

As we have talked about before, Python is a programming language. Like any language it has words and rules for how to use them. Python is designed to be easy to read and write, It can often read like english, which makes it easy to learn. Python has some words that you can use to build your programs. These are a few examples: 'if', 'else', 'for', 'while', 'def', 'class', 'import', 'return'. It also makes use of logic symbols for comparisons and operations like '=', '==', '!=', '>', '<', '+', '-', '*', '/'. Finally it has different data types like numbers, texts and lists. These can be combined to create more complex data structures.

If you don't know what a lot of this means don't worry, for now the objective is to be able to start and run a program.

Python, the program

Python is also a program that reads your Python code and translates it into machine code. When we've written our code we can run it by using the Python program. The Python program might come installed on your computer or you might have to install it. There are 3 versions of Python and multiple versions of each. But by now everyone is using Python 3. At the time of the writing the most recent version is Python 3.12 but any version after 3.9 or 3.10 should be good enough. You can check your version by running the python3 --version' command in your terminal:

$ python --version

Output: Python 3.10.14

Some machines have python and in some its python3. Try both and moving forward use the one that works.

$ python3 --version

Output: Python 3.10.14

If none of the 2 work you need to install Python. Since the process varies depending on your operating system I recommend you look for a guide online. There are many high quality guides that will help you install Python on your computer.

Getting started

When someone talks about a Python project they are talking about a folder that contains all the files that are needed to run their application. Now matter how big or small the project is, it will always have the same basic structure. In theory we could put everything on a single file but that can become hard to follow. So to make it easier for us we split the code into many files and folders. This makes it easier to read, write, and maintain the code. Without getting into the weeds, I will give you a simple structure that you can use to start your Python project.

my_first_project/
├── requirements.txt
├── main.py

A lot of talk for 1 directory and 2 files. But this is the structure of the most basic Python project. The requirements.txt file will contain all the libraries that your project needs to run. The main.py file will contain the code that will run your project. Python program files use the '.py' extension to identify them.

Create a folder anywhere on your computer, in your Documents folder for example. Name it my_first_project or something else if you prefer. Inside the folder create a file called requirements.txt and another called main.py.

Soon we will start writing text on those files. For that we need a text editor. Like digital artists use Photoshop and architects use Autocad, we will use a code editor. Which in a way is similar to a word procesor like word with aditional functionality for coding. VSCode is a very popular editor that is easy to use and has many features that will help you write your code. You can download it here. Once you have it installed you can open the folder you created by going to File -> Open Folder and selecting the folder you created.

Virtual Environments

Heads up, this is the hardest part of the guide.

We've talked about installing python libraries to expand Pythons funcitonality. How can you separate which libraries you use on each proyect? This is where virtual environments and the requirements.txt file come in. A virtual environment is a folder that contains a specific version of Python and all the libraries that you need for your project. This way you can have different versions of Python and different libraries for each project. The requirements.txt will contain a list of all the libraries that you need for your project. Creating a virtual environment also helps you make sure that your project will run on any computer. To create a virtual environment you need to use the terminal.

The terminal is a program that allows you to interact with your computer with text commands. We wont use it that much so if its your fist time using it hopefully you can follow with my instructions and maybe some Googling or ChatGPTing. If you would like to learn more about it you can read more about it here or here.

Open a terminal by going to Terminal -> New Terminal.

Once you have the terminal open lets validate that we are in the right place. You can run 'pwd' to print working directory and 'ls' to list the files in the directory.:

$ pwd

Output: /some/path/to/my_first_project

$ ls

Output: requirements.txt main.py

Now to create the virtual environment you need to run the following command:

python -m venv venv

This should create a folder called venv inside your project folder. Your root directory should now look like this:

my_first_project/
├── requirements.txt
├── main.py
├── venv/

If the command doesn't work you might need to install the venv module. Since the process varies depending on your operating system I recommend you look for a guide online.

Finally you need to activate the virtual environment. This will tell your computer to use the Python program and libraries that are inside the venv folder. To activate the virtual environment you need to run the following command:

source venv/bin/activate

Your terminal should now have (venv) at the beginning of the line. This means that the virtual environment is active. At this point the worst has passed and you are ready to start writing code.

If you want to deactivate the virtual environment you can user 'deactivate' and you will no longer see (venv) at the beginning of the line.

(venv)$ deactivate

First Project

Initial Setup

As an example we will create a simple program that allows you to create QR codes for any URL. First we need to install the qrcode library. To do this we need to add it to the requirements.txt file. Open the file and add the following line:

#!/requirements.txt

qrcode[pil]

Now we need to install the library. To do this you need to run the following command to install all the libraries in the requirements.txt file:

(venv)$ pip install -r requirements.txt

To make sure it was installed correctly you can run the following command:

(venv)$ pip list

This will print a list of all the libraries that are installed in your virtual environment. You should see the qrcode library in the list.

Main program

Now we can start writing the code. Open the main.py file and add the following code:

#!/main.py

import qrcode # Adds the qrcode library to the program so we can use it

# Defines a function that creates a QR code

# Creates an qrcode for the given url and saves it to filename

def create_qr(url, filename): 

    """

    Creates a QR code from the given url and saves it as an image file.

    """

    img = qrcode.make(url) # Make the qrcode

    img.save(filename) # Save the qrcode as an image file

    print(f"QR code saved as {filename}")

# Run the function with the wanted url and filename

create_qr("https://www.python.org", "python_qr.png") 

This code creates a function called create_qr that can create a QR code for any URL and save it as an image file when used. The function is defined by the 'def' keyword followed by the name of the function and the arguments it takes. The function is then called with the URL of the website you want to create a QR code for and the name of the file you want to save the QR code as. The function will print a message to the terminal when it is done.

Functions are one of the most important building blocks in programming and together with data they are the core of any program. The serve like legos that you can use to split long and complex processes into smaller more manageable pieces. Functions are what allow a piece of code to be reused, shared and modified. They also make it easy to share funcitonality with others as a library is just a collection of functions that someone else wrote that you can install and use.

At this point you might see an error wiggle line under the qrcode import.

This is because VSCode doesn't know which version of Python and libraries you are using. To fix this you need to point your editor to the right direction. First let's find the path to the Python program in the virtual environment. With your environment activated run the following command:

(venv)$ which python

Output: /some/path/to/my_first_project/venv/bin/python

Copy the path to the Python program. Now go with your main.py file open click on the Python version in the bottom right corner of the screen. This will open a menu, click on 'Enter interpreter path...', paste the path to the Python program and press enter.

You will now see (venv) in the version at the bottom right of your editor and the wiggle line should be gone.

(venv)$ python main.py

You should have a python_qr.png file in your project folder. You can open it with an image viewer to see the QR code.

my_first_project/
├── python_qr.png
├── other files...

And just like that you have created your first Python project. Congratulations! You are officially a Python programmer. While this project is very simple you can use this set up to start exploring topics like numerical analysis using pandas, machine learning using scikit-learn, or web development using FastAPI. The possibilities are endless.

Extra Content

Growing the Project

As you write code you will notice that the file becomes long and hard to track. To make it easier to work with you can split the code into multiple files. The code you write on one file can be imported and used in another file. This topic can get complex but for now we'll keep it simple. Lets say you want to split the code into two files. You can create a new file called qr.py and move the create_qr function to it. Make sure not to name your files the same as the packages you install. I added a couple of extra lines to show you how to add some new functionality. Also to give you some additional basic Python tools. Ill try my best to explain everything that is happening. Make them look like this:

my_first_project/
├── requirements.txt
├── main.py
├── qr.py

#!/main.py

from pathlib import Path # *1

from qr import create_qr

if __name__ == "__main__": # *2

    images_path = Path(__file__).parent / "images" # *3

    if not images_path.exists(): # *4

        images_path.mkdir(exist_ok=True, parents=True) # *5

    urls = ["https://www.python.org", "https://www.djangoproject.com"]

    for i, url in enumerate(urls): # *6

        create_qr(url, images_path / f"qr_{i}.png")

#!/qr.py

import qrcode

def create_qr(url, filename): 

    """

    Creates a QR code from the given url and saves it as an image file.

    """

    img = qrcode.make(url)

    img.save(filename)

    print(f"QR code saved as {filename}")

if __name__ == "__main__": # *2

    create_qr("https://www.python.org", "python_qr.png") 

There are a ton of new things going on. Since it was going to get long I couldn't explain it in the comments.

1. At this point you might understand that pathlib is a library. But, how are we using it if we didn't install it? Python comes with a set of included libraries commonly referred to as 'The Standard Library'. Pathlib is one of those libraries. It makes it easy to work with files and directories. In this case we are using it to create a directory to save the images. Here you see all the libraries that Python already includes. Knowledge of the Standard Library is one of the things that differentiates a beginner from an advanced Python programmer. Packages in the stdlib are usually very well tested, are safe to use and serve common use cases. So it is a good idea to get to know them.

2. This line can seem weird but it serves a very clear purpose. It tells Python to only run the code if the file is being run directly. This is useful because it allows you to import the code from another file without running it. In our example we can safely import 'qr.py' without the code that creates a QR code being run and we can also run the 'qr.py' file by itself. Right now it would be optional to have it on the 'main.py' file but I like to always put it in there.

3. To not clutter the project root folder we are creating a folder called images to save the QR codes. This line creates a variable that will store the Path to were we want to save our images. It fist gets the path to the current file with 'Path(__file__)' and then gets the parent directory with '.parent'. Finally it adds the images folder with '/ "images". The '/' operator is used to join paths in Python.

4. This line might be more intuitive. 'images_path.exists()' checks if the images folder already exists. We use 'if not' to check if it doesn't exist. If that is so the code bellow will run.

5. This line creates the images folder. The 'mkdir' method creates the folder. The 'exist_ok=True' argument tells Python to not raise an error if the folder already exists. The 'parents=True' argument tells Python to create the parent directories if they don't exist. This makes sure that that line never gives an error.

6. This line is a for loop with and i, ... enumerate included. The 'for' loop allows us to loop over a list of items. The 'enumerate' function allows us to loop over a list of items and get the index of the item(its place starting on 0). Remember that the index starts at 0 so to access the first element of a list you would use list[0]. [] are used to get by index. In this case we are looping over the urls list and getting the index and the url. The index is stored in the variable i and the url in the variable url. This allows us to create a QR code for each url and save it with a different name.

More Arguments For Python

In this section I wanted to go deeper into why I think Python is an underated language even if it's already #1.

Type Safety

One of the major arguments against Python is it's lack of type safety due to its dynamic and flexible nature. This is a fair criticism becuase strong typing makes it easier to grow applications while making the code more reliable in live environments. However, recently with the introduction of type hints and libraries like Pydantic, Python has become a much more type safe language and to me Pydantic is a game changer that can give you all the type safety you need.

Performance

While I admint that out of all of the programming languages Python is the slowest one that doesnt mean that it is slow or that you can design a fast system with it. First of all the language is rarely the bottle neck in an application. Network operations, reads and writes to files and databases, and other operations can be orders of magnitue slower relative to the language. Also, often a correct design choices in the architecture of the application can make a much bigger difference in the performance of a system. And finally, Python has many ways in which you can optimize your code. You can use libraries like Numpy, Joblib and celery to make your code faster and more scalable.

However it is clear that fundametally because of the way Python is built it is orders of magnitude slower compared to alternatives like Java, Go or C++. And if you find yourself in a situation where that is a concern then you should consider using one of those languages.