base64 模块 —— 二进制与文本的桥梁

import base64

# ---- 编码 ----
text = "Hello, World!"                          # 原始字符串
text_bytes = text.encode('utf-8')                # 1. 先转为 bytes
encoded = base64.b64encode(text_bytes)           # 2. Base64 编码
print(f"原始数据: {text_bytes}")                  # b'Hello, World!'
print(f"编码结果: {encoded}")                     # b'SGVsbG8sIFdvcmxkIQ=='

# ---- 解码 ----
decoded_bytes = base64.b64decode(encoded)        # 3. Base64 解码
decoded_text = decoded_bytes.decode('utf-8')     # 4. bytes → str
print(f"解码结果: {decoded_text}")                # Hello, World!

import base64

# 对比标准与 urlsafe
data = b'\xfb\xff\xbf'                           # 会产生 + / 的二进制数据

std_encoded = base64.b64encode(data)              # 标准 Base64
url_encoded = base64.urlsafe_b64encode(data)      # URL 安全 Base64

print(f"标准编码:   {std_encoded}")                # b'++/v'
print(f"URL安全编码: {url_encoded}")               # b'--_v'

# urlsafe_b64decode 也能解码标准编码（自动处理 + /）
decoded = base64.urlsafe_b64decode(url_encoded)
print(f"解码结果:   {decoded}")                    # b'\xfb\xff\xbf'

import base64

# 编码：自动每 76 字符换行
long_data = b"This is a long text that will be split into multiple lines for email transmission."
encoded = base64.encodebytes(long_data)
print("MIME 编码结果:")
print(encoded.decode('utf-8')
# VGhpcyBpcyBhIGxvbmcgdGV4dCB0aGF0IHdpbGwgYmUgc3BsaXQgaW50byBtdWx0aXBs
# ZSBsaW5lcyBmb3IgZW1haWwgdHJhbnNtaXNzaW9uLg==

# 解码：自动忽略换行符
decoded = base64.decodebytes(encoded)
print(f"解码结果: {decoded.decode('utf-8')}")

import base64

data = "Hello, World!".encode('utf-8')

# Base32：A-Z + 2-7，大小写不敏感，膨胀率 1.6x
b32_enc = base64.b32encode(data)
print(f"Base32: {b32_enc}")                        # b'JBSWY3DPFQQFO33SNRSCC==='

# Base16：0-9 + A-F，即十六进制，膨胀率 2.0x
b16_enc = base64.b16encode(data)
print(f"Base16: {b16_enc}")                        # b'48656C6C6F2C20576F726C6421'

# Base32 解码（casefold=True 允许小写）
b32_dec = base64.b32decode(b'sgvsy3dpfqqfo33snrscc===', casefold=True)
print(f"Base32 解码: {b32_dec.decode('utf-8')}")   # Hello, World!

# Base16 解码（casefold=True 允许小写）
b16_dec = base64.b16decode(b'48656c6c6f', casefold=True)
print(f"Base16 解码: {b16_dec.decode('utf-8')}")   # Hello

import base64
import binascii

data = b"Hello"

print(f"base64.b64encode:   {base64.b64encode(data)}")       # b'SGVsbG8='
print(f"base64.b16encode:   {base64.b16encode(data)}")       # b'48656C6C6F'
print(f"binascii.hexlify:   {binascii.hexlify(data)}")       # b'48656c6c6f'（小写）
print(f"binascii.b2a_base64: {binascii.b2a_base64(data)}")   # b'SGVsbG8=\n'（带换行）

import base64
import struct
import zlib

# ---- 生成一个 1x1 红色 PNG 图片（纯代码，无需文件） ----
def create_1x1_red_png() -> bytes:
    """生成 1x1 红色像素的 PNG 图片字节。"""
    # PNG 签名
    signature = b'\x89PNG\r\n\x1a\n'
    # IHDR 块：宽1 高1 8位色 RGB
    ihdr_data = struct.pack('>IIBBBBB', 1, 1, 8, 2, 0, 0, 0)
    ihdr_crc = zlib.crc32(b'IHDR' + ihdr_data) & 0xffffffff
    ihdr = struct.pack('>I', 13) + b'IHDR' + ihdr_data + struct.pack('>I', ihdr_crc)
    # IDAT 块：1x1 红色像素
    raw_data = b'\x00\xff\x00\x00'  # filter byte + R G B
    compressed = zlib.compress(raw_data)
    idat_crc = zlib.crc32(b'IDAT' + compressed) & 0xffffffff
    idat = struct.pack('>I', len(compressed)) + b'IDAT' + compressed + struct.pack('>I', idat_crc)
    # IEND 块
    iend_crc = zlib.crc32(b'IEND') & 0xffffffff
    iend = struct.pack('>I', 0) + b'IEND' + struct.pack('>I', iend_crc)
    return signature + ihdr + idat + iend

png_bytes = create_1x1_red_png()                     # 生成 PNG 二进制数据
b64_str = base64.b64encode(png_bytes).decode('utf-8') # 编码为 Base64 字符串

# ---- 构建 Data URI ----
data_uri = f"data:image/png;base64,{b64_str}"
print(f"Data URI 长度: {len(data_uri)} 字符")

# ---- 嵌入 HTML ----
html = f'<img src="{data_uri}" alt="1x1 red pixel" width="100" height="100">'
print(f"HTML 标签: {html[:80]}...")

# ---- 从 Data URI 还原图片 ----
prefix = "data:image/png;base64,"
if data_uri.startswith(prefix):
    extracted_b64 = data_uri[len(prefix):]            # 去掉前缀
    restored_png = base64.b64decode(extracted_b64)    # 解码
    print(f"还原 PNG 大小: {len(restored_png)} 字节")
    print(f"数据一致: {restored_png == png_bytes}")    # True

import base64
import smtplib
from email.mime.multipart import MIMEMultipart
from email.mime.base import MIMEBase
from email.mime.text import MIMEText
from email import encoders

def create_email_with_attachment(
    sender: str,
    recipient: str,
    subject: str,
    body: str,
    attachment_path: str
) -> MIMEMultipart:
    """创建带附件的邮件对象。"""
    msg = MIMEMultipart()                            # 1. 创建多部分邮件
    msg['From'] = sender
    msg['To'] = recipient
    msg['Subject'] = subject

    msg.attach(MIMEText(body, 'plain', 'utf-8'))     # 2. 添加正文

    with open(attachment_path, 'rb') as f:           # 3. 读取附件二进制
        part = MIMEBase('application', 'octet-stream')
        part.set_payload(f.read()
        encoders.encode_base64(part)                 # 4. Base64 编码附件
        part.add_header(                             # 5. 设置附件头
            'Content-Disposition',
            f'attachment; filename="{attachment_path}"'
        )
        msg.attach(part)

    return msg

# 使用示例（需要真实 SMTP 服务器才能发送）：
# msg = create_email_with_attachment(
#     sender="me@example.com",
#     recipient="you@example.com",
#     subject="Report",
#     body="Please find the report attached.",
#     attachment_path="report.pdf"
# )
# with smtplib.SMTP('smtp.example.com', 587) as server:
#     server.starttls()
#     server.login('user', 'password')
#     server.send_message(msg)

import base64
import json

def decode_jwt_payload(token: str) -> dict:
    """解码 JWT 的 Payload 部分（不验证签名，仅解析内容）。"""
    parts = token.split('.')                        # 1. JWT 由三部分组成
    if len(parts) != 3:
        raise ValueError("无效的 JWT 格式")

    payload_b64 = parts[1]                          # 2. 取 Payload 部分

    # JWT 使用无 padding 的 urlsafe Base64，需补齐 padding
    padding = 4 - len(payload_b64) % 4              # 3. 计算需要补的 = 数
    if padding != 4:
        payload_b64 += '=' * padding

    payload_bytes = base64.urlsafe_b64decode(payload_b64)  # 4. URL-safe 解码
    payload = json.loads(payload_bytes.decode('utf-8'))    # 5. JSON 解析
    return payload

# 模拟一个 JWT（此 token 仅用于演示，非真实签发）
demo_jwt = (
    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9."
    "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ."
    "SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
)

payload = decode_jwt_payload(demo_jwt)
print(f"JWT Payload: {json.dumps(payload, indent=2, ensure_ascii=False)}")
# {
#   "sub": "1234567890",
#   "name": "John Doe",
#   "iat": 1516239022
# }

import base64

def make_basic_auth_header(username: str, password: str) -> dict:
    """生成 HTTP Basic Authentication 请求头。"""
    credentials = f"{username}:{password}"           # 1. 拼接 user:pass
    encoded = base64.b64encode(credentials.encode('utf-8')).decode('utf-8')  # 2. Base64 编码
    return {"Authorization": f"Basic {encoded}"}     # 3. 放入 Header

def parse_basic_auth(header_value: str) -> tuple:
    """从 Basic Auth 头中提取用户名和密码。"""
    scheme, _, token = header_value.partition(' ')   # 4. 分离 "Basic" 和 token
    if scheme.lower() != 'basic':
        raise ValueError("非 Basic Auth")
    decoded = base64.b64decode(token).decode('utf-8')  # 5. 解码
    username, _, password = decoded.partition(':')   # 6. 分离 user:pass
    return username, password

# 编码
headers = make_basic_auth_header("myuser", "mypassword123")
print(f"请求头: {headers}")
# {'Authorization': 'Basic bXl1c2VyOm15cGFzc3dvcmQxMjM='}

# 解码
user, pwd = parse_basic_auth(headers['Authorization'])
print(f"用户名: {user}, 密码: {pwd}")
# 用户名: myuser, 密码: mypassword123

import base64
import urllib.parse

# 场景：在 URL 查询参数中传递二进制 token
raw_token = b'\x00\x01\x02\xfb\xff\xbf\xfe'        # 含特殊字节的 token

# 错误做法：标准 Base64 直接放 URL
std_b64 = base64.b64encode(raw_token).decode('utf-8')
print(f"标准 Base64: {std_b64}")                     # AAEK++//vg==（含 + / =）
url_with_std = f"https://api.example.com/verify?token={std_b64}"
print(f"标准 URL: {url_with_std}")
# + / = 会被 URL 编码为 %2B %2F %3D，导致 token 变长且混乱

# 正确做法：urlsafe 编码
safe_b64 = base64.urlsafe_b64encode(raw_token).decode('utf-8')
print(f"URL安全 Base64: {safe_b64}")                 # AAEK--_v_g==（- _ 替代 + /）
url_with_safe = f"https://api.example.com/verify?token={safe_b64}"
print(f"安全 URL: {url_with_safe}")

# 服务端解码
query_token = safe_b64.rstrip('=')                   # URL 中常去掉 padding
# 补齐 padding 后解码
padding_needed = 4 - len(query_token) % 4
if padding_needed != 4:
    query_token += '=' * padding_needed
restored = base64.urlsafe_b64decode(query_token)
print(f"还原 token: {restored == raw_token}")        # True

import base64
import binascii

def safe_b64decode(s: str | bytes, urlsafe: bool = False) -> bytes | None:
    """
    安全地解码 Base64 字符串。

    - 自动补齐 padding
    - 捕获所有异常，失败返回 None
    - 支持 urlsafe 模式
    """
    if isinstance(s, bytes):                         # 1. 统一转为 str
        s = s.decode('utf-8', 'ignore')

    s = s.strip()                                    # 2. 去除首尾空白
    s = ''.join(s.split())                           # 3. 去除所有换行/空格

    # 4. 补齐 padding
    padding_needed = len(s) % 4
    if padding_needed:
        s += '=' * (4 - padding_needed)

    # 5. 选择解码函数
    decode_func = base64.urlsafe_b64decode if urlsafe else base64.b64decode

    try:
        return decode_func(s)
    except (binascii.Error, TypeError, ValueError):
        return None

# 测试
print(safe_b64decode("SGVsbG8"))          # b'Hello'（自动补 padding）
print(safe_b64decode("SGVsbG8="))         # b'Hello'
print(safe_b64decode("Invalid$String"))   # None
print(safe_b64decode("--_v", urlsafe=True))  # b'\xfb\xff\xbf'

import base64

def encode_file_chunked(input_path: str, output_path: str, chunk_size: int = 57) -> None:
    """
    分块读取文件并 Base64 编码。

    chunk_size=57 是因为 57 字节编码后恰好为 76 字符（MIME 标准行宽），
    且 57 是 3 的倍数，不会产生跨块 padding 问题。
    """
    with open(input_path, 'rb') as fin, open(output_path, 'w') as fout:
        while True:
            chunk = fin.read(chunk_size)             # 1. 读取 57 字节
            if not chunk:
                break
            encoded = base64.b64encode(chunk).decode('utf-8')  # 2. 编码
            fout.write(encoded + '\n')               # 3. 写入一行

def decode_file_chunked(input_path: str, output_path: str, chunk_size: int = 8192) -> None:
    """
    分块读取 Base64 文件并解码。

    读取块大小必须是 4 的倍数，否则解码会出错。
    """
    read_size = (chunk_size // 4) * 4                # 1. 确保是 4 的倍数
    with open(input_path, 'r') as fin, open(output_path, 'wb') as fout:
        while True:
            chunk = fin.read(read_size)              # 2. 读取
            if not chunk:
                break
            chunk = chunk.replace('\n', '')          # 3. 去除换行
            if not chunk:
                continue
            decoded = base64.b64decode(chunk)        # 4. 解码
            fout.write(decoded)                      # 5. 写入

# 使用示例：
# encode_file_chunked('large_video.mp4', 'encoded.txt')
# decode_file_chunked('encoded.txt', 'restored.mp4')

import base64

def auto_padding_decode(s: str) -> bytes:
    """自动补齐 padding 后解码。"""
    s = s.strip()
    missing = len(s) % 4
    if missing:
        s += '=' * (4 - missing)
    return base64.b64decode(s)

# JWT 等场景常省略 padding
print(auto_padding_decode("SGVsbG8"))  # b'Hello'（自动补 1 个 =）

import base64

data = b'\xfb\xff\xbf'
std = base64.b64encode(data)       # b'++/v'
safe = base64.urlsafe_b64encode(data)  # b'--_v'

# urlsafe_b64decode 可以解码两种格式
print(base64.urlsafe_b64decode(std))   # b'\xfb\xff\xbf' ✓
print(base64.urlsafe_b64decode(safe))  # b'\xfb\xff\xbf' ✓

# b64decode 只能解码标准格式
print(base64.b64decode(std))           # b'\xfb\xff\xbf' ✓
# print(base64.b64decode(safe))       # binascii.Error ✗

import base64

# 正确做法
text = "你好，世界！"
encoded = base64.b64encode(text.encode('utf-8'))    # 先 UTF-8 编码
decoded = base64.b64decode(encoded).decode('utf-8') # 后 UTF-8 解码
print(decoded)  # 你好，世界！

# 错误做法：直接传 str 给 b64encode
# base64.b64encode("你好")  # TypeError: a bytes-like object is required

import base64
import binascii

data_with_newlines = b"SGVs\nbG8="  # 含换行符

# 默认：忽略换行，正常解码
print(base64.b64decode(data_with_newlines))  # b'Hello'

# 严格模式：报错
try:
    base64.b64decode(data_with_newlines, validate=True)
except binascii.Error as e:
    print(f"验证失败: {e}")  # Non-base64 digit found

import base64

a = base64.b64encode(b"Hello")           # b'SGVsbG8='
b = base64.urlsafe_b64encode(b"Hello")   # b'SGVsbG8='（此例恰好相同）
c = b"SGVsbG8"                           # 无 padding

# 错误：字符串比较
print(a == c)  # False

# 正确：解码后比较
print(base64.b64decode(a) == base64.b64decode(c + b'='))  # True