Python 模块与包管理：从 import 语句到私有仓库的完整指南

import sys

# 查看已加载的模块
print(len(sys.modules))   # 通常 200+
print('json' in sys.modules)   # True（已加载）

# 模块的缓存机制
import json
print(id(json))   # 对象地址
import json as j
print(id(j))      # 同一个对象！

import importlib
import mymodule

# 修改 mymodule.py 后重新加载
importlib.reload(mymodule)

import sys

for p in sys.path:
    print(p)
# 典型输出：
# ''                          ← 当前目录
# '/usr/local/lib/python311'  ← 标准库
# '/usr/local/lib/python311/site-packages'  ← 第三方包

# 方式 1：临时添加（当前会话有效）
import sys
sys.path.insert(0, "/path/to/your/modules")

# 方式 2：PYTHONPATH 环境变量
# PYTHONPATH=/path/to/modules python script.py

# 方式 3：.pth 文件（推荐）
# 在 site-packages 目录创建 mypaths.pth
# 内容：/path/to/your/modules

# 方式 4：sitecustomize.py
import site
site.addsitedir("/path/to/modules")

# 项目结构：
# myproject/
# ├── app/
# │   ├── __init__.py
# │   ├── models.py
# │   └── utils.py
# └── tests/

# app/models.py
from app.utils import helper   # 绝对导入
import app.utils               # 另一种写法

# app/models.py
from .utils import helper      # 同级目录
from . import utils            # 导入同级包
from ..config import settings  # 上级目录
from .auth.password import hash_password   # 子目录

# 注意：相对导入只能在包内使用，不能直接运行！
# python app/models.py   # ❌ ModuleNotFoundError
# python -m app.models   # ✅ 作为模块运行

# mypackage/__init__.py

# 控制 from mypackage import * 的行为
__all__ = ['module1', 'module2']

# 包级别的初始化代码
print("mypackage 被加载")

# 简化导入路径
from .module1 import MyClass
from .module2 import helper
# 用户可以直接 from mypackage import MyClass

# a.py
from b import func_b

def func_a():
    return "A"

# b.py
from a import func_a

def func_b():
    return "B"

# 运行：python a.py
# → ImportError: cannot import name 'func_a' from partially initialized module 'a'

# common.py
def func_a():
    return "A"

def func_b():
    return "B"

# a.py
from common import func_a, func_b

# a.py
def func_a():
    from b import func_b    # 函数调用时才导入
    return f"A calls {func_b()}"

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from .b import B        # 只在类型检查时导入

class A:
    def method(self, b: "B"):   # 字符串前向引用
        pass

# 在 pyproject.toml 所在目录
pip install -e .           # 可编辑安装（修改代码立即生效）
pip install -e ".[dev]"    # 带 dev 依赖

# 使用 devpi 搭建私有 PyPI
pip install devpi-server
devpi-init
devpi-server --start

# 上传包
devpi upload

# 安装时指定索引
pip install --index-url http://your-devpi/simple mypackage

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

[project]
name = "myproject"
dynamic = ["version"]
description = "A short description"
readme = "README.md"
requires-python = ">=3.9"
license = {text = "MIT"}
authors = [
    {name = "Alice", email = "alice@example.com"}
]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
]
dependencies = [
    "requests>=2.28.0",
    "pydantic>=2.0",
]

[project.optional-dependencies]
dev = ["pytest", "black", "mypy"]
docs = ["mkdocs-material"]

[project.scripts]
mycli = "myproject.cli:main"

# 可编辑安装（现代方式）
pip install -e .

# 带 dev 依赖的完整开发环境
pip install -e ".[dev,test]"

# 使用 pdm（无需虚拟环境切换）
pdm install --dev

from importlib.metadata import version, entry_points, requires

# 获取已安装包的版本
print(version("requests"))          # 2.31.0

# 列出项目的依赖
for req in requires("requests"):
    print(req)

# 遍历所有入口点（console_scripts）
eps = entry_points()
for ep in eps.select(group="console_scripts"):
    print(f"{ep.name} = {ep.value}")

# 获取包的文件列表
from importlib.metadata import files
for file in files("requests"):
    print(file)

# 1. 检查包是否安装
pip list | grep mypackage

# 2. 检查 Python 路径
python -c "import sys; print(sys.path)"

# 3. 检查模块名拼写

# 4. 检查是否在虚拟环境中
which python

# 错误原因：直接运行了包内的文件
python app/models.py          # ❌

# 正确做法
python -m app.models          # ✅
# 或者从项目根目录运行
python -m myproject.app.models