Working with JSON in Python: Read, Write, and Parse Like a Pro

import json

# ── CASE 1: Parsing a JSON STRING (e.g. from an API response) ──
# Imagine requests.get(...).text returned this string:
api_response_text = '{"user": "alice", "score": 42, "active": true}'

# json.loads() deserializes a STRING into a Python dict
user_data = json.loads(api_response_text)

print(type(user_data))        # Confirm it's a dict, not a string
print(user_data["user"])      # Access like any normal Python dict
print(user_data["active"])    # JSON 'true' becomes Python True (bool)

print("---")

# ── CASE 2: Reading JSON from a FILE ──
# First, let's write a sample file so the example is fully self-contained
sample_config = {
    "app_name": "DataPipeline",
    "version": "2.1.0",
    "debug": False,
    "max_retries": 3
}

# Write the config to disk first
with open("config.json", "w", encoding="utf-8") as config_file:
    json.dump(sample_config, config_file)  # dump() writes to a FILE OBJECT

# Now read it back — json.load() reads from a FILE OBJECT, not a string
with open("config.json", "r", encoding="utf-8") as config_file:
    loaded_config = json.load(config_file)

print(type(loaded_config))              # Also a dict
print(loaded_config["app_name"])        # 'DataPipeline'
print(loaded_config["debug"])           # False (Python bool)
print(loaded_config["max_retries"])     # 3 (Python int)

import json

# Real-world example: saving a user profile with international characters
user_profile = {
    "user_id": 1047,
    "full_name": "María García",       # Non-ASCII characters — common in real data
    "email": "maria.garcia@example.com",
    "preferences": {
        "theme": "dark",
        "language": "es",
        "notifications": True
    },
    "tags": ["premium", "verified", "beta-tester"]
}

# ── BAD: Default output — technically valid but unreadable ──
bad_output = json.dumps(user_profile)
print("Raw (hard to read):")
print(bad_output)
print()

# ── GOOD: Formatted, Unicode-safe, sorted keys ──
good_output = json.dumps(
    user_profile,
    indent=2,              # 2-space indentation for readability
    sort_keys=True,        # Alphabetical keys — great for version control diffs
    ensure_ascii=False     # Write 'María' not '\u004dar\u00eda'
)
print("Formatted (production-ready):")
print(good_output)

# ── Writing to a file with explicit UTF-8 encoding ──
output_path = "user_profile.json"
with open(output_path, "w", encoding="utf-8") as output_file:
    json.dump(
        user_profile,
        output_file,
        indent=2,
        sort_keys=True,
        ensure_ascii=False   # Critical: don't escape María into \u sequences
    )

print(f"\nProfile saved to {output_path}")

import json
from datetime import datetime, date
from decimal import Decimal

# ── The types that break vanilla JSON serialization ──
order_record = {
    "order_id": "ORD-9921",
    "created_at": datetime(2024, 3, 15, 10, 30, 0),  # datetime — not JSON serializable
    "ship_date": date(2024, 3, 17),                   # date — also not JSON serializable
    "total_amount": Decimal("199.99"),                # Decimal — not JSON serializable
    "item_ids": {101, 205, 309},                      # set — not JSON serializable
    "status": "pending"
}

# Try without a custom encoder — this will raise TypeError
try:
    json.dumps(order_record)
except TypeError as encoding_error:
    print(f"Without custom encoder: {encoding_error}")

print()

# ── Solution: Custom JSONEncoder subclass ──
class AppJSONEncoder(json.JSONEncoder):
    """Handles Python types that vanilla JSON can't serialize."""

    def default(self, obj):
        # datetime: serialize as ISO 8601 string — universally understood
        if isinstance(obj, datetime):
            return obj.isoformat()          # e.g. '2024-03-15T10:30:00'

        # date: serialize as ISO date string
        if isinstance(obj, date):
            return obj.isoformat()          # e.g. '2024-03-17'

        # Decimal: convert to float — fine for display, use string for finance
        if isinstance(obj, Decimal):
            return float(obj)               # or str(obj) if precision matters

        # set: JSON has arrays, not sets — convert and sort for determinism
        if isinstance(obj, set):
            return sorted(list(obj))        # sort so output is always consistent

        # Let the parent class raise TypeError for anything we don't handle
        return super().default(obj)


# Now serialize cleanly using our custom encoder
serialised_order = json.dumps(
    order_record,
    cls=AppJSONEncoder,    # Pass the encoder CLASS (not an instance)
    indent=2,
    ensure_ascii=False
)

print("Serialized order record:")
print(serialised_order)

# ── Deserializing back: parse the date string yourself ──
loaded_order = json.loads(serialised_order)
print("\nRound-trip — created_at is now a string:")
print(type(loaded_order["created_at"]), loaded_order["created_at"])

# Convert back to datetime when needed
parsed_datetime = datetime.fromisoformat(loaded_order["created_at"])
print(f"Re-parsed datetime: {parsed_datetime}")

import json
import urllib.request   # Using stdlib so no pip install needed for this example
import urllib.error
from datetime import datetime

# ── Simulating an API response (using a real public API) ──
# We'll use JSONPlaceholder — a free, stable fake REST API for testing
API_URL = "https://jsonplaceholder.typicode.com/users/1"

def fetch_user_profile(user_url: str) -> dict | None:
    """Fetch a user profile from an API and return it as a Python dict."""
    try:
        with urllib.request.urlopen(user_url, timeout=10) as response:
            # response.read() returns bytes — decode to string first
            raw_bytes = response.read()
            json_string = raw_bytes.decode("utf-8")

            # Parse the JSON string into a Python dict
            user_data = json.loads(json_string)
            return user_data

    except urllib.error.URLError as network_error:
        print(f"Network error: {network_error}")
        return None
    except json.JSONDecodeError as parse_error:
        print(f"Response wasn't valid JSON: {parse_error}")
        return None


def save_profile_snapshot(user_data: dict, output_path: str) -> None:
    """Enrich the profile with a timestamp and save it to a JSON file."""
    # Add metadata before saving — this is extremely common in pipelines
    enriched_profile = {
        "fetched_at": datetime.utcnow().isoformat() + "Z",  # ISO 8601 UTC
        "source_url": API_URL,
        "profile": user_data
    }

    with open(output_path, "w", encoding="utf-8") as output_file:
        json.dump(
            enriched_profile,
            output_file,
            indent=2,
            ensure_ascii=False   # Safe for names with accents or non-Latin chars
        )
    print(f"Snapshot saved to: {output_path}")


# ── Main flow ──
print(f"Fetching profile from {API_URL}...")
user = fetch_user_profile(API_URL)

if user:
    # Defensive access — check keys exist before using them
    user_name = user.get("name", "Unknown")
    user_email = user.get("email", "No email provided")
    company_name = user.get("company", {}).get("name", "No company")

    print(f"Name:    {user_name}")
    print(f"Email:   {user_email}")
    print(f"Company: {company_name}")

    # Save the enriched snapshot
    save_profile_snapshot(user, "user_snapshot.json")

    # ── Reading it back to verify the round-trip ──
    print("\nVerifying saved file...")
    with open("user_snapshot.json", "r", encoding="utf-8") as saved_file:
        reloaded = json.load(saved_file)

    print(f"Fetched at: {reloaded['fetched_at']}")
    print(f"Stored name: {reloaded['profile']['name']}")