paths:                  # 第 0 級
  data_dir: "./data/cifar10"  # 第 1 級（縮進(jìn) 2 空格）
  log_dir: "./logs/experiment_1"
  #如果縮進(jìn)不一致（如一個(gè) 2 空格、一個(gè) 4 空格），解析器會報(bào)錯(cuò)。

use_gpu: true # 布爾值（注釋在行尾）
# 路徑配置（單獨(dú)一行注釋）
paths:
 ...

#YAML 文件的標(biāo)準(zhǔn)規(guī)范允許一個(gè)物理文件中包含多個(gè)獨(dú)立的 YAML 文檔（相當(dāng)于多個(gè)獨(dú)立的配置對象），它們之間用 ---（三個(gè)連字符）來分隔。
# 第一個(gè) YAML 文檔
name: Alice
age: 30
hobbies:
 - reading
 - hiking

---   #用三個(gè)連字符或者三個(gè)點(diǎn)···來顯示結(jié)束一個(gè)文檔，通常不需要。如果在yaml文件中如果有和yaml沒關(guān)系的內(nèi)容，必須有結(jié)束符號。
# 第二個(gè) YAML 文檔
name: Bob
age: 25
hobbies:
 - gaming
 - cooking

---
# 第三個(gè) YAML 文檔
server:
 host: localhost
 port: 8080

msg: 'hello\nworld' #不是換行實(shí)際上結(jié)果是 "hello\\nworld"------Python 用 \\ 來表示“字符串里有一個(gè)反斜杠”
# 單引號 `'...'`（原樣保存） 不做任何的轉(zhuǎn)義。

msg: 'it''s good'

#等價(jià)于
"it's good"

msg: "hello\nworld"

#雙引號支持轉(zhuǎn)義所以結(jié)果是
"hello
world"

description: |
 this is line one
 this is line two
 this is line three


#在python里邊
"this is line one\nthis is line two\nthis is line three\n"

description: >
 this is line one
 this is line two
 this is line three

#實(shí)際上
"this is line one this is line two this is line three\n"

epochs: 100          # 整數(shù)
lr: 0.001            # 小數(shù)
weight_decay: 1.0e-4 # 科學(xué)計(jì)數(shù)法----1e-4 = 1 × 10?? = 0.0001


#其他格式：十六進(jìn)制 0xFF、八進(jìn)制 0o777。

#例如
optional: ~

#縮進(jìn)只能用空格，不能用 Tab
# 對
train:
 batch_size: 64

# 錯(cuò)（Tab）
train:
?batch_size: 64  #不能用tab鍵


#同一層級，縮進(jìn)必須對齊
# 對
train:
 batch_size: 64
 epochs: 100

# 錯(cuò)
train:
 batch_size: 64
   epochs: 100

   
   
#必須唯一（同一層里）
train:
 batch_size: 64
 batch_size: 128   # 覆蓋 / 非法

   
#冒號分左右，縮進(jìn)分里外，對齊是同級，一切都是鍵值對
#YAML 的映射不是“復(fù)雜”，而是“把 Python dict 寫得更好看”

#block風(fēng)格
transform_list:  #transform_list: → 一個(gè)鍵
 - "RandomCrop"   # - → 一個(gè)列表元素，每個(gè) - 表示一項(xiàng)
 - "RandomHorizontalFlip"
 - "Normalize"
#看到 -，就要想到“列表的一項(xiàng)” ，‘-‘后邊一定要有空格

#flow風(fēng)格，行內(nèi)寫法
transform_list: ["RandomCrop", "RandomHorizontalFlip", "Normalize"]
#一般在：列表很短，不嵌套，不需要注釋。時(shí)使用

# config.yaml

project_name: "ResNet_Classification"
use_gpu: true  # 布爾值

# 路徑配置
paths:
  data_dir: "./data/cifar10"
  log_dir: "./logs/experiment_1"

# 模型參數(shù)
model:
  type: "resnet18"
  num_classes: 10
  pretrained: true

# 訓(xùn)練超參數(shù)
train:
  batch_size: 64
  epochs: 100
  learning_rate: 0.001
  weight_decay: 1.0e-4  # 支持科學(xué)計(jì)數(shù)法
  optimizer: "Adam"
  
# 列表/數(shù)組寫法
transform_list:
  - "RandomCrop"
  - "RandomHorizontalFlip"
  - "Normalize"

import yaml

# 讀取函數(shù)
def get_config(path):
    with open(path, 'r', encoding='utf-8') as f:
        return yaml.safe_load(f)     #把yaml文件內(nèi)容轉(zhuǎn)換為python字典。safe_load 推薦用，不會執(zhí)行 YAML 文件里潛在的危險(xiǎn)命令。

  
cfg = get_config("config.yaml")   #輸入路徑

# 使用方式：像查字典一樣
print(cfg['learning_rate'])  # 輸 出結(jié)果
# 缺點(diǎn)：如果層級很深，代碼會變成 config['train']['params']['lr']，很難看且容易寫錯(cuò)字符串

#利用SimpleNamespace實(shí)現(xiàn)---SimpleNamespace 是 Python 標(biāo)準(zhǔn)庫（types 模塊）中的一個(gè)非常輕量的類。它的作用：允許你動態(tài)地給一個(gè)對象添加屬性，并用點(diǎn)號訪問這些屬性。相當(dāng)于一個(gè)“可隨意擴(kuò)展屬性的空對象”。
import yaml   #yaml 是 import 的 PyYAML 庫。
from types import SimpleNamespace

def load_config_as_obj(yaml_path):
    """
    讀取 yaml 并將字典遞歸轉(zhuǎn)換為對象，方便用 . 屬性訪問
    """
    with open(yaml_path, 'r', encoding='utf-8') as f:   #open打開文件，返回一個(gè)文件對象f
        config_dict = yaml.safe_load(f)   #加載為python字典

    # 遞歸轉(zhuǎn)換函數(shù)
    def dict_to_obj(d):
        if not isinstance(d, dict):  
            '''
             #isinstance(object, class_or_tuple):--判斷這個(gè)對象是不是某種類型
             object：你要檢查的變量.
             class_or_tuple：你想檢查的類型（或者類型元組）
             返回值：布爾值 True / False
            '''
            return d
        # 將字典轉(zhuǎn)為 SimpleNamespace 對象
        obj = SimpleNamespace()   #創(chuàng)建一個(gè)空的SimpleNamespace對象。調(diào)用 types.SimpleNamespace 類，創(chuàng)建一個(gè)空的、可動態(tài)加屬性的對象。此時(shí) obj 里面什么屬性都沒有。
        for k, v in d.items():  #d.items返回的是一個(gè)元組，for循環(huán)可以多個(gè)變量，但是要求可迭代對象的每個(gè)元素是元組或列表，元素的長度必須和變量數(shù)一致
            # 遞歸處理嵌套的字典
            setattr(obj, k, dict_to_obj(v))    #這里遞歸調(diào)用dict_to_obj函數(shù)。如果不是字典，則返回d(也就是v)。如果是字典在進(jìn)來再進(jìn)行調(diào)用，直到不是字典未知。----給對象 obj 動態(tài)增加一個(gè)屬性，名字是 k，值是 dict_to_obj(v)。
            #setattr(object, name, value)---把 name 當(dāng)作屬性名，把 value 賦值給對象
            '''
            object：要操作的對象
		   name：屬性名（字符串）
            value：要賦給屬性的值
            '''
        return obj  #可調(diào)用對象

    return dict_to_obj(config_dict)  #返回值

# --- 使用演示 ---
# 假設(shè) yaml 內(nèi)容是：
# train:
#   lr: 0.01
#   device: "cuda"

cfg = load_config_as_obj("config.yaml")  #給一個(gè)yaml文件路徑

# 現(xiàn)在的調(diào)用方式非常優(yōu)雅：
print(cfg.train.lr)      # 0.01
print(cfg.train.device)  # cuda

python train.py --lr 0.001 --epochs 50

parser = argparse.ArgumentParser()

parser.add_argument('--lr', type=float, default=None, help='學(xué)習(xí)率')

parser.add_argument('--epochs', type=int, default=None, help='訓(xùn)練輪數(shù)')
parser.add_argument('--config', type=str, default='./configs/resnet_train.yaml', help='配置文件路徑')

args = parser.parse_args() #`parse_args()` 會讀取運(yùn)行腳本時(shí)的命令行參數(shù)，返回一個(gè)對象 `args`，里面每個(gè)參數(shù)都是 **對象屬性**

python train.py --lr 0.001 --epochs 50

args.lr      # 0.001
args.epochs  # 50
args.config  # './configs/resnet_train.yaml'

#如果命令行不輸入某個(gè)參數(shù)，它就用你定義的 `default` 值。

import argparse  #Python 內(nèi)置模塊，用來解析命令行參數(shù)（命令行參數(shù)也就是python運(yùn)行腳本的時(shí)候輸入的參數(shù)：python train.py --lr 0.001 --epochs 50）。argparse 可以把這些字符串參數(shù)轉(zhuǎn)換成 Python 對象，方便在代碼中使用

def get_args_and_config():   #讀取 YAML 配置 + 解析命令行參數(shù) + 覆蓋默認(rèn)值。返回最終的 cfg 對象，用于訓(xùn)練腳本中直接訪問參數(shù)
    parser = argparse.ArgumentParser()  #ArgumentParser() 創(chuàng)建一個(gè)解析器對象，知道你程序允許哪些命令行參數(shù)，并解析這些參數(shù)
    parser.add_argument('--config', type=str, default='./configs/resnet_train.yaml', help='配置文件路徑')  #拿到y(tǒng)aml文件的路徑。
    parser.add_argument('--lr', type=float, default=None, help='臨時(shí)修改學(xué)習(xí)率')
    parser.add_argument('--epochs', type=int, default=None, help='臨時(shí)修改輪數(shù)')  #help是提示信息用于--help的時(shí)候顯示
    args = parser.parse_args()   #當(dāng)運(yùn)行python train.py --lr 0.001 --epochs 50之后，可以用args.lr調(diào)取這個(gè)值是多少。
    
    # 1. 先加載 yaml 為對象
    cfg = load_config_as_obj(args.config)   #還是之前的SimpleNamespace。變?yōu)橐粋€(gè)對象，可以用 點(diǎn) 調(diào)用。
    
    # 2. 如果命令行有指定參數(shù)，覆蓋 yaml 中的值
    if args.lr is not None:  #如果通過命令行傳遞進(jìn)來參數(shù)了。
        cfg.training.lr = args.lr   #重新賦值，進(jìn)而覆蓋Yaml的默認(rèn)值。-這里不會修改yaml文件，只是會修改內(nèi)存里的配置對象cfg
        print(f"注意：學(xué)習(xí)率被命令行參數(shù)覆蓋為 {cfg.training.lr}")
        
    if args.epochs is not None:
        cfg.training.epochs = args.epochs

    return cfg

# 在 main 中調(diào)用：
# cfg = get_args_and_config()

{
    "experiment_id": "exp_2024",
    "metrics": {
        "accuracy": 0.95,
        "loss": 0.045
    },
    "classes": ["cat", "dog", "car"],  
    "is_finished": true
}

import json
from types import SimpleNamespace  # 可選：用來轉(zhuǎn)成點(diǎn)號訪問對象

def load_json_config(path="config.json"):
    with open(path, "r", encoding="utf-8") as f:
        config_dict = json.load(f)  # 注意：是 json.load(f)，不是 json.loads()------返回對象也是一個(gè)字典
    
    return config_dict  #一個(gè)字典

# 使用
cfg = load_json_config("config.json")

# 字典方式訪問
print(cfg["data"]["batch_size"])      # 128
print(cfg["optimizer"]["lr"])         # 0.001

#轉(zhuǎn)化為對象訪問
def load_json_as_obj(path="config.json"):  #給一個(gè)默認(rèn)值config.json，不傳參數(shù)的時(shí)候就用默認(rèn)值。
    with open(path, "r", encoding="utf-8") as f:
        data = json.load(f)
    
    def dict_to_obj(d):
        if isinstance(d, dict):  #判斷是不是字典類型
            return SimpleNamespace(**{k: dict_to_obj(v) for k, v in d.items()}) #**字典 的意思是：把字典“拆開”成關(guān)鍵字參數(shù)
        '''
       { key_expression : value_expression  for 變量 in 可迭代對象 } --- {k : dict_to_obj(v)  for k, v in d.items()}
       d 是一個(gè)字典（比如 {'lr': 0.001, 'device': 'cuda'}）
      d.items() 返回所有鍵值對：[('lr', 0.001), ('device', 'cuda')]
	for k, v in d.items()：依次取出鍵（k）和值（v）
	k : dict_to_obj(v)：新字典的鍵還是原來的 k，但值要先經(jīng)過 dict_to_obj(v) 處理（如果 v 是字典，就遞歸轉(zhuǎn)成對象；如果不是，就原樣返回）
       ---------------------------
        {k: dict_to_obj(v) for k, v in d.items()}-一個(gè)經(jīng)典的字典推導(dǎo)式。它本身就等價(jià)于“先創(chuàng)建一個(gè)空字典，再用 for 循環(huán)往里塞數(shù)據(jù)”。
        等價(jià)于：
        new_dict = {}              # 1 先創(chuàng)建空字典
	   for k, v in d.items():     # 2 遍歷原字典
          new_dict[k] = dict_to_obj(v)   # 3 賦值
        '''
        elif isinstance(d, list):  #json可以做嵌套，因此可能包含列表的情況。"classes": ["cat", "dog", "car"],  
            return [dict_to_obj(i) if isinstance(i, dict) else i for i in d]
        '''
        new_list = []
        for i in d:
            if isinstance(i, dict):
                new_list.append(dict_to_obj(i))
            else:
                new_list.append(i)	
        '''
        '''
        [表達(dá)式 for 變量 in 可迭代對象 if 條件]
        表達(dá)式 → 每次循環(huán)計(jì)算出的值，會成為新列表的元素
		變量 → 循環(huán)中取出的每個(gè)元素
		可迭代對象 → 任何可遍歷的對象，如列表、字典的 keys、range() 等
		if 條件 → 可選，對循環(huán)元素做過濾
        '''
        else:
            return d  #普通值
    
    return dict_to_obj(data)

cfg = load_json_as_obj("config.json")

# 現(xiàn)在可以用點(diǎn)號訪問了！
print(cfg.data.batch_size)      # 128
print(cfg.optimizer.lr)         # 0.001
print(cfg.model.name)           # resnet18

#寫入json文件
import json

config = {                                  #創(chuàng)建一個(gè)字典
    "project_name": "MyExperiment",
    "final_accuracy": 92.5,
    "best_epoch": 87
}

with open("result.json", "w", encoding="utf-8") as f:  #with open自動打卡文件，用w 模式，with打開不用手動 f.close。with當(dāng)代碼結(jié)束會自動調(diào)用f.close（）
    json.dump(config, f, indent=4, ensure_ascii=False)
    # indent=4：美化輸出，方便閱讀
    # ensure_ascii=False：支持中文等非ASCII字符

json.dump(obj, fp, *, skipkeys=False, ensure_ascii=True, check_circular=True,     
   allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False)

# config.py - 所有配置和邏輯集中在這里

import torch
import torch.nn as nn
from torchvision import models, transforms

# ================== 數(shù)據(jù)配置 ==================
DATA_DIR = "./data"
BATCH_SIZE = 128
NUM_WORKERS = 4

# ================== 模型配置 ==================
MODEL_NAME = "resnet18"   # 改這里就能換模型
NUM_CLASSES = 10
PRETRAINED = True

def get_model():
    if MODEL_NAME == "resnet18":
        base = models.resnet18(pretrained=PRETRAINED)
    elif MODEL_NAME == "resnet50":
        base = models.resnet50(pretrained=PRETRAINED)
    elif MODEL_NAME == "mobilenet_v2":
        base = models.mobilenet_v2(pretrained=PRETRAINED)
    else:
        raise ValueError(f"Unknown model: {MODEL_NAME}")
    
    # 統(tǒng)一修改最后一層
    if hasattr(base, 'fc'):  # ResNet 系列
        base.fc = nn.Linear(base.fc.in_features, NUM_CLASSES)
    elif hasattr(base, 'classifier'):  # MobileNet
        base.classifier[1] = nn.Linear(base.classifier[1].in_features, NUM_CLASSES)
    
    return base

# ================== 訓(xùn)練配置 ==================
LR = 0.001
EPOCHS = 100
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"

# ================== 數(shù)據(jù)增強(qiáng) ==================
def get_transforms():
    return transforms.Compose([
        transforms.RandomCrop(32, padding=4),
        transforms.RandomHorizontalFlip(),
        transforms.ToTensor(),
        transforms.Normalize((0.4914, 0.4822, 0.4465), (0.2023, 0.1994, 0.2010)),
    ])

# train.py
from config import get_model, get_transforms, BATCH_SIZE, NUM_WORKERS, LR, EPOCHS, DEVICE, DATA_DIR

model = get_model().to(DEVICE)
transform = get_transforms()

# 數(shù)據(jù)加載、優(yōu)化器、訓(xùn)練循環(huán)...

<?xml version="1.0" encoding="UTF-8"?>
<config>
    <project_name>MyExperiment</project_name>
    <model>
        <type>resnet18</type>
        <num_classes>10</num_classes>
        <pretrained>true</pretrained>
    </model>
    <training>
        <batch_size>64</batch_size>
        <epochs>100</epochs>
        <learning_rate>0.001</learning_rate>
        <optimizer>Adam</optimizer>
    </training>
</config>

#Python 內(nèi)置庫 xml.etree.ElementTree 可以解析 XML。解析、創(chuàng)建、操作 XML 文件
import xml.etree.ElementTree as ET

# 1. 讀取 XML 文件
tree = ET.parse("config.xml")  # 返回 ElementTree 對象 --tree → XML 的整個(gè)樹形結(jié)構(gòu)
root = tree.getroot()          # 根節(jié)點(diǎn) <config>----從 ElementTree 中獲取 根節(jié)點(diǎn)

# 2. 訪問數(shù)據(jù)
project_name = root.find("project_name").text  #root.find--查找 <config> 下的第一個(gè) <project_name> 子節(jié)點(diǎn)，返回一個(gè) Element 對象
										 #.text 獲取該節(jié)點(diǎn)的文本內(nèi)容 "MyExperiment"。
print(project_name)  # MyExperiment---project_name → 字符串類

model_type = root.find("model/type").text
num_classes = int(root.find("model/num_classes").text)
pretrained = root.find("model/pretrained").text == "true"  #== "true" → 轉(zhuǎn)成布爾值

batch_size = int(root.find("training/batch_size").text)
learning_rate = float(root.find("training/learning_rate").text)

print(model_type, num_classes, pretrained, batch_size, learning_rate)

# config.toml
project_name = "CIFAR10_Classification"
seed = 42

[data]
dataset = "CIFAR10"
data_dir = "./data"
batch_size = 128
num_workers = 4

[model]  #TOML 使用 表（table） 來表示 嵌套結(jié)構(gòu)或命名空間,[model] 表示 一個(gè)名為 model 的表,表下面的鍵值對都屬于這個(gè)表的 子空間
name = "resnet18"
pretrained = true
num_classes = 10

[optimizer]
name = "Adam"
lr = 0.001
weight_decay = 1e-4

[train]
epochs = 100
device = "cuda"

#可以做項(xiàng)目依賴管理
'''
TOML 的 最常見用途不是存超參，而是 管理 Python 項(xiàng)目的依賴和構(gòu)建配置
在現(xiàn)代 Python 項(xiàng)目中，它已經(jīng)取代了：
requirements.txt（老式依賴列表）
setup.py（舊版打包配置）
存放位置：項(xiàng)目根目錄
'''

#例如
[project]
name = "cifar10-resnet"
version = "0.1.0"
description = "CIFAR-10 分類實(shí)驗(yàn)"
authors = [{name = "張三", email = "zhangsan@example.com"}]
requires-python = ">=3.9"
dependencies = [
    "torch>=2.0.0",
    "torchvision>=0.15.0",
    "pyyaml>=6.0",
    "matplotlib>=3.5",
    "tqdm"
]

[project.optional-dependencies]
dev = ["black", "flake8", "pytest"]
train = ["wandb", "tensorboard"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"


#可以這么用

# 安裝項(xiàng)目依賴
pip install .

# 安裝開發(fā)依賴
pip install -e ".[dev]"

# 用 poetry 管理
poetry install          # 自動安裝所有依賴
poetry add torch==2.1.0 # 添加新依賴，自動更新 toml


'''
環(huán)境可復(fù)現(xiàn)：別人 clone 你的代碼后，只需 pip install . 就能裝好相同版本的包
版本鎖定：精確控制 torch、torchvision 等版本
現(xiàn)代標(biāo)準(zhǔn)：pip、poetry、pdm 等工具都支持 TOML
分組依賴：區(qū)分運(yùn)行、開發(fā)、訓(xùn)練依賴

在工程中，TOML 最重要的用途是 依賴管理和項(xiàng)目構(gòu)建，而不是超參配置
'''

#作為超參配置--代碼讀取 TOML 作為超參配置
#雖然不常用，但可以把 TOML 當(dāng)作 YAML/JSON 的替代品，存超參。需要安裝toml庫。pip install toml

#讀取toml為對象
import toml
from types import SimpleNamespace

def load_toml_config(path="config.toml"):
    data = toml.load(path)   #返回字典類型
    
    def dict_to_obj(d):
        if isinstance(d, dict):
            return SimpleNamespace(**{k: dict_to_obj(v) for k, v in d.items()})
        elif isinstance(d, list):  #可能有淚飆類型  transforms = ["crop", "flip", "normalize"]   讓列表里的字典也能用 點(diǎn)號訪問。
            return [dict_to_obj(i) for i in d]
        else:
            return d
    
    return dict_to_obj(data)

cfg = load_toml_config("config.toml")
print(cfg.data.batch_size)   # 128
print(cfg.optimizer.lr)      # 0.001



#寫入toml
import toml

config = {"train": {"epochs": 100, "lr": 0.001}}
with open("config.toml", "w") as f:
    toml.dump(config, f)