> ## Documentation Index
> Fetch the complete documentation index at: https://fastapi.codewithsiva.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Modules & Packages

> Organize your Python code into reusable files and directories, and leverage the built-in Standard Library

## 1. What is a Module?

A **module** is simply a Python file (with a `.py` extension) containing variables, functions, or classes that you want to reuse in other parts of your program.

### Creating and Importing a Module

Suppose we create a file named `calculator.py`:

```python theme={null}
# calculator.py
def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

PI = 3.14159
```

Now, we can use these functions in another file (e.g., `main.py`) in the same folder by importing it:

```python theme={null}
# main.py
import calculator

result = calculator.add(5, 3)
print(result)           # 8
print(calculator.PI)    # 3.14159
```

***

## 2. What is a Package?

A **package** is a directory (folder) that contains multiple modules. It allows you to organize related modules hierarchically.

### The Role of `__init__.py`

To turn a standard folder into a Python package, it must contain a file named `__init__.py`. This file does several things:

1. **Marks Directories**: It tells Python that this directory is an importable package.
2. **Initialization Code**: Python executes `__init__.py` first when the package or any sub-module is imported.
3. **Creates Public APIs**: You can import sub-modules inside `__init__.py` to make them accessible directly from the package root:
   ```python theme={null}
   # mypackage/__init__.py
   from .utils import format_text
   ```
   Now consumers can write:
   ```python theme={null}
   from mypackage import format_text
   ```
4. **Controls Wildcard Imports**: Define a list called `__all__` to restrict what gets imported when someone uses `from package import *`:
   ```python theme={null}
   __all__ = ['utils']
   ```

***

## 3. Python's Standard Library Essentials

Python follows a "batteries included" philosophy, providing powerful built-in modules that are ready to use immediately.

### A. The `pathlib` Module

Modern Python uses `pathlib` for object-oriented filesystem paths:

```python theme={null}
from pathlib import Path

# Get home directory or current directory
current_dir = Path.cwd()
file_path = current_dir / "data" / "users.json"

# Check if path exists
print(file_path.exists())

# Read and write text easily
if file_path.exists():
    content = file_path.read_text()
```

### B. The `os` Module

Used for interacting with the operating system:

```python theme={null}
import os

# Get current working directory
print(os.getcwd())

# Get environment variables
database_url = os.environ.get("DATABASE_URL", "sqlite:///local.db")
```

### C. The `datetime` Module

Provides classes for manipulating dates and times:

```python theme={null}
import datetime

# Current date and time
now = datetime.datetime.now()
print(now)

# Formatting to string (strftime)
formatted = now.strftime("%Y-%m-%d %H:%M:%S")

# Parsing string to datetime (strptime)
parsed = datetime.datetime.strptime("2026-07-20", "%Y-%m-%d")
```

### D. The `uuid` Module

Generates RFC 4122 compliant universally unique identifiers (UUIDs):

```python theme={null}
import uuid

# Generate a random UUID (UUID4)
unique_id = uuid.uuid4()
print(unique_id)  # e.g., "d3b07384-d113-4956-a5cc-484d2d476100"
```

### E. The `json` Module

JSON is the standard data format for web APIs. Python's `json` module parses and serializes JSON:

```python theme={null}
import json

data = {"name": "Alice", "role": "admin"}

# Serialization (Dict -> JSON String)
json_str = json.dumps(data)

# Deserialization (JSON String -> Dict)
parsed_data = json.loads(json_str)
```

***

## 4. Third-Party Packages (e.g., `requests`)

While the Standard Library provides `urllib` for handling HTTP requests, the community standard is the third-party **`requests`** library due to its clean, human-readable API.

To use it, you must first install it within your virtual environment:

```bash theme={null}
pip install requests
```

### Making HTTP Requests

Here is how you can perform typical GET and POST operations using `requests`:

```python theme={null}
import requests

# 1. GET Request
response = requests.get("https://jsonplaceholder.typicode.com/posts/1")
if response.status_code == 200:
    post_data = response.json()
    print("Title:", post_data["title"])

# 2. POST Request (sending JSON data)
payload = {
    "title": "Hello FastAPI",
    "body": "Learning about modules and packages",
    "userId": 1
}
headers = {"Content-Type": "application/json"}
post_response = requests.post(
    "https://jsonplaceholder.typicode.com/posts",
    json=payload,
    headers=headers
)
print("Status Code:", post_response.status_code) # 201 Created
print("Response JSON:", post_response.json())
```

***

## Practice & Exercises

To reinforce what you've learned in this section (creating modules/packages, standard library utilities like pathlib, os, datetime, uuid, and json, and using requests), practice with these interactive notebooks:

<CardGroup cols={2}>
  <Card title="Follow-Along Practice" icon="laptop-code">
    Practice importing local module files, filesystem navigation with pathlib, retrieving env variables with os, date-time formatting, UUID generation, JSON parsing, and GET/POST API requests.

    [💻 VS Code](vscode://file/Users/sivaprasad/Downloads/python%20material/fastapi-course/public/notebooks/basics_exercises/Modules_Packages_Practice.ipynb) | [🚀 Colab](https://colab.research.google.com/github/prasad230776/fastapi-course/blob/master/public/notebooks/basics_exercises/Modules_Packages_Practice.ipynb) | <a href="/public/notebooks/basics_exercises/Modules_Packages_Practice.ipynb" download>📥 Download</a>
  </Card>

  <Card title="Practice Exercises" icon="pen-to-square">
    Test your knowledge with hands-on exercises including programmatic module creation, pathlib subdirectories, setting env variables, datetime delta offsets, JSON formatting, and HTTP API parsing.

    [💻 VS Code](vscode://file/Users/sivaprasad/Downloads/python%20material/fastapi-course/public/notebooks/basics_exercises/Modules_Packages_Exercises.ipynb) | [🚀 Colab](https://colab.research.google.com/github/prasad230776/fastapi-course/blob/master/public/notebooks/basics_exercises/Modules_Packages_Exercises.ipynb) | <a href="/public/notebooks/basics_exercises/Modules_Packages_Exercises.ipynb" download>📥 Download</a>
  </Card>
</CardGroup>