All the reading

Python

8 lessons, about 35 minutes. The check's questions come from these.

Choosing data shapes

1. Think in Python data

5 min

Start with shapes

Before you write a Python tool, decide what your data looks like in memory.

Most small command-line tools use only a few shapes: strings, numbers, booleans, lists, and dictionaries. If you can model your data with these, your script becomes easier to read, test, and change.

Key point

One idea

Python tools are mostly data going through steps. Pick a clear shape for the data first, then write code that transforms it.

Use the right type

Use a string for one piece of text, like a name or email. Use an int or float for numbers you may calculate with. Use a boolean for yes/no state.

Use a list when you have many similar items. Use a dictionary when each item has named fields, like a row from a CSV or a response from an API.

Example

Model a record

Imagine your tool checks student project ideas and creates a short review. One project can be a dictionary. Many projects can be a list of dictionaries.

This is close to how JSON and APIs usually look, so it will help in later lessons.

project = {
    "team": "ByteBoys",
    "college": "Pune Institute of Computer Technology",
    "idea": "UPI expense splitter for hostel students",
    "uses_ai": True,
    "score": 7
}

projects = [
    project,
    {
        "team": "NullPointers",
        "college": "SRM Chennai",
        "idea": "Resume feedback bot",
        "uses_ai": True,
        "score": 8
    }
]

print(projects[0]["idea"])
print(projects[1]["score"])

Common mistake

2. Shape data with comprehensions

4 min

Why this matters

Most Python tools start with raw data. Names, emails, marks, product lists, bug reports, prompts, or API results.

Before you call an API, you often need to clean and reshape that data. Comprehensions help you do that in one readable line.

Key point

One idea

A comprehension means: make a new collection from an old one, while changing or filtering each item.

Use it when the logic is simple. If it becomes hard to read, use a normal loop.

Example

List comprehension

Say your sample input has student names from a college event form. Some have extra spaces. Some are blank.

You can clean them before saving or sending them anywhere.

raw_names = [" Asha ", "", "Ravi", "  Meera", " "]

clean_names = [name.strip() for name in raw_names if name.strip()]

print(clean_names)
# ['Asha', 'Ravi', 'Meera']

Writing reusable code

3. Write functions and modules

4 min

Key point

One idea

A runnable tool is easier to trust when the work is inside functions, not floating at the top of the file.

Keep one file for reusable logic and one file for the command people run.

Why this matters

In hackathon repos, reviewers often open your code before they run it. If everything is one long script, it is hard to see what reads input, what processes data, and what writes output.

Functions give names to those steps. Modules let you reuse those functions later when you add JSON files, APIs, or tests.

Your to-do

Split the job

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Reading files and running tools

5. Read files and JSON

5 min

Key point

One core habit

Treat files as the input layer of your tool. Read the file, convert it into Python data, then let the rest of your code work with lists and dictionaries.

Do not mix file reading, API calls, and output writing in one big block. Your future self will find bugs faster when each part has one job.

Why this matters

Your hackathon repo must prove that your script reads data. A sample input file is the easiest proof.

For an AI-adjacent tool, the input may be student feedback, product reviews, job descriptions, support tickets, or prompts. Keep a small sample in the repo so anyone can test it without asking you for data.

Your to-do

Pick file types

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

10 questions, 7 to pass.

# Hard to maintain
teams = ["ByteBoys", "NullPointers"]
ideas = ["UPI expense splitter", "Resume feedback bot"]
scores = [7, 8]

# Better for tool data
projects = [
    {"team": "ByteBoys", "idea": "UPI expense splitter", "score": 7},
    {"team": "NullPointers", "idea": "Resume feedback bot", "score": 8}
]

Example

Transform the data

A tool should not only store data. It should produce something useful.

Here, the script reads in-memory project records, adds a simple label, and prints a report line. Later, the same records can come from a file or API.

projects = [
    {"team": "ByteBoys", "idea": "UPI expense splitter", "uses_ai": True, "score": 7},
    {"team": "NullPointers", "idea": "Resume feedback bot", "uses_ai": True, "score": 8},
    {"team": "StackSeniors", "idea": "Mess menu tracker", "uses_ai": False, "score": 5}
]

for project in projects:
    if project["score"] >= 7:
        label = "shortlist"
    else:
        label = "needs work"

    ai_note = "AI feature" if project["uses_ai"] else "No AI feature"

    print(f'{project["team"]}: {label} - {ai_note} - {project["idea"]}')

Example

Shape rows

Your tool may read rows later from a CSV or JSON file. For now, think of rows as a list of dictionaries.

This example keeps only valid rows and shapes them into a smaller format for an API request.

students = [
    {"name": "Asha", "email": "[email protected]", "score": 82},
    {"name": "Ravi", "email": "", "score": 76},
    {"name": "Meera", "email": "[email protected]", "score": 91},
]

api_payload = [
    {"student_name": s["name"], "contact": s["email"]}
    for s in students
    if s["email"]
]

print(api_payload)
# [{'student_name': 'Asha', 'contact': '[email protected]'}, {'student_name': 'Meera', 'contact': '[email protected]'}]

Tip

Ask AI carefully

AI tools are useful for writing comprehensions from a plain English rule. Give the input shape and the exact output shape.

Always check three things in the answer: missing keys, empty values, and whether the code changes the original data by mistake.

Prompt you can use:
I have this Python list of dictionaries. Write a readable list comprehension that keeps only rows with email and creates dictionaries with keys student_name and contact. Do not mutate the original list.

students = [
    {"name": "Asha", "email": "[email protected]", "score": 82},
    {"name": "Ravi", "email": "", "score": 76}
]

Example

Small module

Create a file named processor.py. This file holds logic you can import without running the whole tool.

# processor.py

def clean_text(text):
    return text.strip().lower()


def make_label(record):
    name = clean_text(record["name"])
    city = clean_text(record["city"])
    return f"{name} from {city}"


def build_output(records):
    labels = []
    for record in records:
        labels.append(make_label(record))
    return labels

Example

Runnable script

Create a second file named run_tool.py. This is the file someone will run from the terminal.

The if block means the tool runs only when this file is executed directly. It will not run by accident when another file imports it.

# run_tool.py

from processor import build_output


def main():
    sample_records = [
        {"name": " Asha ", "city": " Pune "},
        {"name": " Ravi ", "city": " Kochi "},
    ]

    labels = build_output(sample_records)

    for label in labels:
        print(label)


if __name__ == "__main__":
    main()

Tip

Ask AI well

AI tools are useful for refactoring a long script into functions. Paste only the relevant code and ask for small functions with clear names.

Check that the AI did not change your data shape, hide errors, or move file reading into every function. Run the script after every change.

Refactor this Python script into small functions.
Keep the same input and output.
Put reusable logic in processor.py.
Put the runnable main() in run_tool.py.
Do not add new libraries.

Common mistake

Do not call main() at the bottom of a module file that you plan to import. That can make code run twice or run at the wrong time.

Use the __name__ check in the script that is meant to be executed.

# Good
if __name__ == "__main__":
    main()

4. Use virtual environments cleanly

4 min

Key point

One project, one env

A virtual environment is a local Python setup for one project. It keeps your packages inside the project folder, not mixed with your system Python.

This matters when your hackathon teammate clones your repo. They should install the same packages you used, not guess from your laptop.

Why it matters

Without an env, you may install packages globally. Later, one project needs requests 2.x and another needs a different version. Your scripts start failing in confusing ways.

A clean env also makes your repo look internship-ready. It shows you know how to make code runnable on another machine.

Your to-do

Create the env

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Open a terminal in your project folder.
Run the Python venv command for your system.
Activate the environment before installing packages.
Check that python and pip now point to the env.

0 of 4 done

# macOS / Linux
python3 -m venv .venv
source .venv/bin/activate
which python
which pip

# Windows PowerShell
py -m venv .venv
.venv\Scripts\Activate.ps1
where python
where pip

Example

Install one package

After activation, install packages normally. They go into .venv, not your global Python.

For this track, requests is a common package you will use later when calling APIs. Install it now only if your current script needs it.

pip install requests
python -c "import requests; print(requests.__version__)"

Your to-do

Freeze dependencies

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Install only the packages your project uses.
Run pip freeze after your script works.
Save the output into requirements.txt.
Commit requirements.txt to GitHub.
Do not commit the .venv folder.

0 of 5 done

pip freeze > requirements.txt

# See what got saved
cat requirements.txt   # macOS / Linux
type requirements.txt  # Windows

Common mistake

Do not upload .venv

The .venv folder can be large and machine-specific. Your repo should contain instructions and requirements.txt, not the installed environment itself.

Add .venv to .gitignore so Git does not track it. If you already added it by mistake, remove it from Git tracking.

.venv/
__pycache__/
*.pyc

Tip

Rebuild test

Before submitting, test your setup like a teammate would. This catches missing packages and unclear steps.

If you use AI to write setup instructions, ask it for Windows and macOS/Linux commands. Then check every command yourself in a fresh terminal.

deactivate
rm -rf .venv        # macOS / Linux
# On Windows, delete the .venv folder from File Explorer

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python your_script.py

Your to-do

Do this now

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Create a .venv folder inside your Python tool repo.
Activate it and install one package your script needs, if any.
Generate requirements.txt with pip freeze.
Add .venv/ to .gitignore.
Run your script once from the activated env.

0 of 5 done

Example

Read a text file

Use with open so Python closes the file properly. Use encoding="utf-8" so Indian names and symbols are handled better.

from pathlib import Path

input_path = Path("sample_input/feedback.txt")

with open(input_path, "r", encoding="utf-8") as file:
    lines = file.readlines()

clean_lines = [line.strip() for line in lines if line.strip()]

print(clean_lines)

Example

Read JSON data

JSON maps cleanly to Python. JSON objects become dictionaries. JSON arrays become lists.

This is useful before you call a real API. You can first test your logic with a mock JSON file.

# sample_input/jobs.json
[
  {
    "title": "Python Intern",
    "company": "Bengaluru SaaS Startup",
    "skills": ["python", "apis", "sql"]
  },
  {
    "title": "AI Tooling Intern",
    "company": "Pune Product Team",
    "skills": ["python", "json", "llm"]
  }
]

# read_json.py
import json
from pathlib import Path

input_path = Path("sample_input/jobs.json")

with open(input_path, "r", encoding="utf-8") as file:
    jobs = json.load(file)

for job in jobs:
    print(job["title"], "-", ", ".join(job["skills"]))

Example

Read CSV rows

CSV is common because people export it from spreadsheets. Python has a built-in csv module, so you do not need pandas for small inputs.

# sample_input/reviews.csv
name,rating,comment
Asha,5,Fast delivery and good support
Rohan,2,App crashed during payment

# read_csv.py
import csv
from pathlib import Path

input_path = Path("sample_input/reviews.csv")

with open(input_path, "r", encoding="utf-8", newline="") as file:
    reader = csv.DictReader(file)
    reviews = list(reader)

for review in reviews:
    print(review["name"], review["rating"], review["comment"])

6. Call APIs from Python

4 min

Key point

The one idea

An API call is just your Python script making an HTTP request and using the response. Treat it like a file read that can fail because the network, URL, key, or server may be wrong.

What you need

Most API work in Python uses the requests package. It is not part of the Python standard library, so it must go into requirements.txt.

For hackathon projects, use a real API if you have one. If keys or credits are an issue, use a mock API while keeping the same code shape.

Your to-do

Install requests

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Activate your virtual environment from lesson 4.
Install requests inside that environment.
Freeze the dependency into requirements.txt.
Run a tiny test import before writing the full script.

0 of 4 done

pip install requests
pip freeze > requirements.txt
python -c "import requests; print(requests.__version__)"

Example

Call a mock API

This example reads a city name from code for now, sends it as a query parameter, checks the response, and writes selected fields to output.json.

It uses httpbin.org, a public HTTP testing service. Later you can replace the URL with your AI API, weather API, startup data API, or college project backend.

import json
import requests

url = "https://httpbin.org/get"
params = {"city": "Bengaluru", "task": "demo"}
headers = {"User-Agent": "hackindia-python-tool/1.0"}

try:
    response = requests.get(url, params=params, headers=headers, timeout=10)
    response.raise_for_status()
except requests.RequestException as error:
    print(f"API call failed: {error}")
    raise SystemExit(1)

data = response.json()

result = {
    "called_url": data["url"],
    "sent_params": data["args"],
    "status": "ok"
}

with open("output.json", "w", encoding="utf-8") as file:
    json.dump(result, file, indent=2)

print("Wrote output.json")

Tip

Keep secrets out

Do not paste API keys into your script or commit them to GitHub. Read them from environment variables.

If you use ChatGPT or Gemini to generate API code, ask it to use environment variables and timeout handling. Then check that it did not hard-code keys, skip error handling, or write unclear output.

import os

api_key = os.getenv("MY_API_KEY")
if not api_key:
    raise SystemExit("Missing MY_API_KEY")

headers = {"Authorization": f"Bearer {api_key}"}

Common mistake

Common API mistakes

Beginners often print the full response and stop there. Your proof needs useful output: a JSON, CSV, or text file that another person can inspect.

Another common mistake is ignoring status codes. A failed API can still return text, but your script should detect the failure and exit clearly.

response.raise_for_status()

Your to-do

Do this now

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Add requests to your project and update requirements.txt.
Create api_client.py or add an API function to your current script.
Call httpbin.org or your chosen API with params and a timeout.
Write a small output.json with only the fields your project needs.
Run the script once and commit the code plus the sample output.

0 of 5 done

7. Make it runnable by others

4 min

Key point

The one test

A runnable repo passes the fresh clone test. Someone should be able to clone it, install dependencies, run one command, and see output.

Do not assume they have your folder structure, API key file, or college laptop setup.

What runnable means

Your script already reads data and calls an API or mock API. Now make it usable by another builder, mentor, or recruiter.

They should not need to message you on WhatsApp for missing files or commands.

Your to-do

Minimum repo shape

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Create one main script with a clear name, like main.py or run.py.
Add requirements.txt with the packages your script imports from pip.
Add a sample input file that is safe to share.
Write output to a file or print a clear result in the terminal.
Add setup and run commands to README.md.

0 of 5 done

Example

Simple file layout

Keep the first version boring. Boring is easy to run during judging.

ai-summary-tool/
  main.py
  requirements.txt
  README.md
  sample_input.json
  output/
    .gitkeep

Example

Requirements file

requirements.txt is just a list of pip packages. Do not include Python standard library modules like json, os, csv, or pathlib.

If you used requests to call an API, include it.

requests==2.32.3
python-dotenv==1.0.1

Common mistake

Avoid local paths

A common bug is hardcoding paths like C:\Users\Aman\Desktop\data.json or /home/you/project/input.json. That only works on your laptop.

Use paths relative to the script or accept a file path as a command-line argument.

Example

Accept input path

This pattern lets anyone run your tool with their own file. It also works well with your sample file.

import argparse
import json
from pathlib import Path

parser = argparse.ArgumentParser(description="Process input data and write output")
parser.add_argument("--input", default="sample_input.json", help="Path to input JSON")
parser.add_argument("--output", default="output/result.json", help="Path to output JSON")
args = parser.parse_args()

input_path = Path(args.input)
output_path = Path(args.output)
output_path.parent.mkdir(parents=True, exist_ok=True)

with input_path.open("r", encoding="utf-8") as f:
    data = json.load(f)

result = {
    "items_read": len(data) if isinstance(data, list) else 1,
    "status": "processed"
}

with output_path.open("w", encoding="utf-8") as f:
    json.dump(result, f, indent=2)

print(f"Wrote {output_path}")

Tip

Handle secrets safely

If your real API needs a key, do not commit the key. Read it from an environment variable or a .env file, and commit a .env.example instead.

For hackathon review, include a mock mode if possible. That lets judges run your repo without your paid or private key.

# .env.example
API_KEY=put_your_key_here

# Run with a mock mode if your script supports it
python main.py --input sample_input.json --output output/result.json --mock

Your to-do

Do this now

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Run your script from the project root using only relative paths.
Create or update requirements.txt with your pip dependencies.
Add a small sample_input.json that contains no private data.
Delete hardcoded laptop paths and secret keys from your code.
Ask a friend to run your README commands on their machine.

0 of 5 done

8. Submit your Python repo

5 min

Key point

Think like a reviewer

Your repo is not done when it works on your laptop. It is done when a stranger can clone it, set it up, run it, and see useful output.

For this track, your proof is simple: a public repo with a runnable Python script, requirements.txt, sample input, and output from an API or mock API.

Your to-do

Final repo check

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Open your GitHub repo in a private window to check it is public.
Check that your main script has a clear name, like main.py or run.py.
Confirm requirements.txt exists and has only the packages your tool needs.
Add a sample input file, such as data/sample_jobs.json or sample_input.json.
Add a README with setup, run command, expected output, and API or mock API note.

0 of 5 done

Example

Good README shape

Keep your README short. A reviewer should not search for the run command.

Use commands that work from a fresh clone. If your tool needs an API key, show where it goes, but do not commit the key.

# Internship Match Helper

Reads sample student skills, calls a mock API, and writes ranked internship matches.

## Setup
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

On Windows PowerShell:
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

## Run
python main.py --input data/sample_students.json --output output/matches.json

## What it does
- Reads JSON input from data/sample_students.json
- Calls a mock API in mock_api.py
- Writes useful output to output/matches.json

## Sample output
See output/sample_matches.json

Common mistake

Do not submit secrets

Never push API keys, tokens, or .env files. This can cost money and can get your account blocked.

If you used a real API, commit a .env.example file instead. It shows the variable names without real values.

# .env.example
API_KEY=your_api_key_here
API_URL=https://example.com/api

Tip

Include proof files

A screenshot is optional. Files are better. Commit a small sample input and a sample output so your project can be understood without running it first.

If your API is paid, rate-limited, or unreliable, include a mock mode. Hackathon reviewers should still be able to test your flow.

Your to-do

Test a fresh clone

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Create a new folder outside your project, like Desktop/repo-test.
Clone your own public repo into that folder.
Follow only the README setup steps, not your memory.
Run the exact command from the README.
Fix anything that fails, then commit and push again.

0 of 5 done

git clone https://github.com/YOUR-USERNAME/YOUR-REPO.git
cd YOUR-REPO
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py --input data/sample_students.json --output output/matches.json

Example

Submission checklist

Use this before you paste the repo link into HackIndia. It prevents the common last-minute misses.

Must have:
[ ] Public GitHub repo
[ ] README with setup steps
[ ] README with run command
[ ] requirements.txt
[ ] Runnable Python script
[ ] Sample input file
[ ] Output file or output folder
[ ] API call or mock API call
[ ] No API keys or .env secrets committed

Your to-do

Do this now

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Open your repo and make it public if it is private.
Add or update README setup and run steps.
Commit sample input and sample output files.
Test the project from a fresh clone.
Submit the public GitHub repo link on HackIndia.

0 of 5 done

Python

1. Think in Python data

Start with shapes

One idea

Use the right type

Model a record

2. Shape data with comprehensions

Why this matters

One idea

List comprehension

3. Write functions and modules

One idea

Why this matters

Split the job

5. Read files and JSON

One core habit

Why this matters

Pick file types

Common mistake

Transform the data

Name fields clearly

Do this now

Shape rows

Read the pattern

Ask AI carefully

Common mistake

Do this now

Small module

Runnable script

Ask AI well

Common mistake

Do this now

4. Use virtual environments cleanly

One project, one env

Why it matters

Create the env

Install one package

Freeze dependencies

Do not upload .venv

Rebuild test

Do this now

Read a text file

Read JSON data

Read CSV rows

Common mistake

Use AI carefully

Do this now

6. Call APIs from Python

The one idea

What you need

Install requests

Call a mock API

Keep secrets out

Common API mistakes

Do this now

7. Make it runnable by others

The one test

What runnable means

Minimum repo shape

Simple file layout

Requirements file

Avoid local paths

Accept input path

Handle secrets safely

Do this now

8. Submit your Python repo

Think like a reviewer

Final repo check

Good README shape

Do not submit secrets

Include proof files

Test a fresh clone

Submission checklist

Do this now