时间戳

首页 > 技术文章 > 15. 包与软件开发目录规范

15. 包与软件开发目录规范

superpoint 2021-11-05 21:48 原文

包

包是模块的一种形式，使用来被导入的，所以模块得导入方式对包适用

包就是一个含有__init__.py文件的文件夹，里面有若干模块文件

  1. 产生一个名称空间
  2. 调用文件夹中的init文件，将运行过程中产生的名称放到产生的名称空间中
  3. 在当前文件中产生一个m（包的名称）的指针，指向1的名称空间

注意：python3中init文件即使不存在也不会报错，但是python2中必须有

两种导入方式：将子文件中的功能导入到init文件中

假设包名称是m，子文件分别是m1（包含函数f1），m2（包含函数f2），m3（包含函数f3）

下面进行的操作都是在init文件中进行的

​ 绝对导入：

# 绝对导入：以包的文件夹作为起始来进行导入
import sys
sys.path.append(r'绝对路径，从根目录开始')
from m.m1 import f1
from m.m2 import f2
from m.m3 import f3

强调三点：

  1. 关于包相关的导入语句也分为import和from ... import ...两种，但是无论哪种，无论在什么位置，在导入时都必须遵循一个原则：凡是在导入时带点的，点的左边都必须是一个包，否则非法。可以带有一连串的点，如import 顶级包.子包.子模块,但都必须遵循这个原则。但对于导入后，在使用时就没有这种限制了，点的左边可以是包,模块，函数，类(它们都可以用点的方式调用自己的属性)。

  2. 包A和包B下有同名模块也不会冲突，如A.a与B.a来自俩个命名空间

  3. import导入文件时，产生名称空间中的名字来源于文件，import 包，产生的名称空间的名字同样来源于文件，即包下的__init__.py，导入包本质就是在导入该文件

    ​ 相对导入：

# 相对导入：仅限于包内使用，尽量不要跨出包的范围使用
# .代表当前文件夹   ..代表上一级文件夹
from . import f1  # 这个点的位置指的就是m这个包

from 包 import *

在使用包时同样支持from m import * ，代表的是futures下__init__.py中所有的名字，通用是用属性__all__来控制

# m下的__init__.py
__all__=['process','thread']

最后说明一点，包内部的目录结构通常是包的开发者为了方便自己管理和维护代码而创建的（结构清晰，方便查找），对包的用户这种结构没有意义，通过操作__init__.py可以“隐藏”包内部的目录结构，降低使用难度，比如想要让用户直接使用

import pool
pool.check()
pool.ProcessPoolExecutor(3)
pool.ThreadPoolExecutor(3)

需要操作pool下的__init__.py

from .versions import check
from .futures.process import ProcessPoolExecutor
from .futures.thread import ThreadPoolExecutor

绝对导入和相对导入总结：

# 绝对导入: 以执行文件的sys.path为起始点开始导入,称之为绝对导入
#        优点: 执行文件与被导入的模块中都可以使用
#        缺点: 所有导入都是以sys.path为起始点,导入麻烦

# 相对导入: 参照当前所在文件的文件夹为起始开始查找,称之为相对导入
#        符号: .代表当前所在文件的文件加,..代表上一级文件夹,...代表上一级的上一级文件夹
#        优点: 导入更加简单
#        缺点: 只能在导入包中的模块时才能使用
　　　　  #注意:
　　　　　　　　1. 相对导入只能用于包内部模块之间的相互导入,导入者与被导入者都必须存在于一个包内
　　　　　　　　2. attempted relative import beyond top-level package # 试图在顶级包之外使用相对导入是错误的,言外之意,必须在顶级包内使用相对导入,每增加一个.代表跳到上一级文件夹,而上一级不应该超出顶级包

软件开发的目录规范

包名一般是和项目相关联，如ATM等等

Foo/
|-- core/
|   |-- core.py
|
|-- api/
|   |-- api.py
|
|-- db/
|   |-- db_handle.py
|
|-- lib/
|   |-- common.py
|
|-- conf/
|   |-- settings.py
|
|-- run.py
|-- setup.py
|-- requirements.txt
|-- README
  • core/: 存放业务逻辑相关代码
  • api/: 存放接口文件，接口主要用于为业务逻辑提供数据操作。
  • db/: 存放操作数据库相关文件，主要用于与数据库交互
  • lib/: 存放程序中常用的自定义模块
  • conf/: 存放配置文件
  • run.py: 程序的启动文件，一般放在项目的根目录下，因为在运行时会默认将运行文件所在的文件夹作为sys.path的第一个路径，这样就省去了处理环境变量的步骤
  • setup.py: 安装、部署、打包的脚本
  • requirements.txt: 存放软件依赖的外部Python包列表
  • README: 项目说明文件

除此之外，有一些方案给出了更加多的内容，比如LICENSE.txt,ChangeLog.txt文件等，主要是在项目需要开源时才会用到

关于README的内容，这个应该是每个项目都应该有的一个文件，目的是能简要描述该项目的信息，让读者快速了解这个项目。它需要说明以下几个事项:

# 1、软件定位，软件的基本功能；# 2、运行代码的方法: 安装环境、启动命令等；# 3、简要的使用说明；# 4、代码目录结构说明，更详细点可以说明软件的基本原理；# 5、常见问题说明。

关于setup.py和requirements.txt：

​ 一般来说，用setup.py来管理代码的打包、安装、部署问题。业界标准的写法是用Python流行的打包工具setuptools来管理这些事情，这种方式普遍应用于开源项目中。不过这里的核心思想不是用标准化的工具来解决这些问题，而是说，一个项目一定要有一个安装部署工具，能快速便捷的在一台新机器上将环境装好、代码部署好和将程序运行起来

requirements.txt文件的存在是为了方便开发者维护软件的依赖库。我们需要将开发过程中依赖库的信息添加进该文件中，避免在 setup.py安装依赖时漏掉软件包，同时也方便了使用者明确项目引用了哪些Python包

这个文件的格式是每一行包含一个包依赖的说明，通常是flask>=0.10这种格式，要求是这个格式能被pip识别，这样就可以简单的通过 pip install -r requirements.txt来把所有Python依赖库都装好了

举例介绍

#===============>star.py
import sys,os
BASE_DIR=os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
sys.path.append(BASE_DIR)

from core import src

if __name__ == '__main__':
    src.run()
#===============>settings.py
import os

BASE_DIR=os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
DB_PATH=os.path.join(BASE_DIR,'db','db.json')
LOG_PATH=os.path.join(BASE_DIR,'log','access.log')
LOGIN_TIMEOUT=5

"""
logging配置
"""
# 定义三种日志输出格式
standard_format = '[%(asctime)s][%(threadName)s:%(thread)d][task_id:%(name)s][%(filename)s:%(lineno)d]' \
                  '[%(levelname)s][%(message)s]' #其中name为getlogger指定的名字
simple_format = '[%(levelname)s][%(asctime)s][%(filename)s:%(lineno)d]%(message)s'
id_simple_format = '[%(levelname)s][%(asctime)s] %(message)s'

# log配置字典
LOGGING_DIC = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'standard': {
            'format': standard_format
        },
        'simple': {
            'format': simple_format
        },
    },
    'filters': {},
    'handlers': {
        #打印到终端的日志
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',  # 打印到屏幕
            'formatter': 'simple'
        },
        #打印到文件的日志,收集info及以上的日志
        'default': {
            'level': 'DEBUG',
            'class': 'logging.handlers.RotatingFileHandler',  # 保存到文件
            'formatter': 'standard',
            'filename': LOG_PATH,  # 日志文件
            'maxBytes': 1024*1024*5,  # 日志大小 5M
            'backupCount': 5,
            'encoding': 'utf-8',  # 日志文件的编码，再也不用担心中文log乱码了
        },
    },
    'loggers': {
        #logging.getLogger(__name__)拿到的logger配置
        '': {
            'handlers': ['default', 'console'],  # 这里把上面定义的两个handler都加上，即log数据既写入文件又打印到屏幕
            'level': 'DEBUG',
            'propagate': True,  # 向上（更高level的logger）传递
        },
    },
}


#===============>src.py
from conf import settings
from lib import common
import time

logger=common.get_logger(__name__)

current_user={'user':None,'login_time':None,'timeout':int(settings.LOGIN_TIMEOUT)}
def auth(func):
    def wrapper(*args,**kwargs):
        if current_user['user']:
            interval=time.time()-current_user['login_time']
            if interval < current_user['timeout']:
                return func(*args,**kwargs)
        name = input('name>>: ')
        password = input('password>>: ')
        db=common.conn_db()
        if db.get(name):
            if password == db.get(name).get('password'):
                logger.info('登录成功')
                current_user['user']=name
                current_user['login_time']=time.time()
                return func(*args,**kwargs)
        else:
            logger.error('用户名不存在')

    return wrapper

@auth
def buy():
    print('buy...')

@auth
def run():

    print('''
    1 购物
    2 查看余额
    3 转账
    ''')
    while True:
        choice = input('>>: ').strip()
        if not choice:continue
        if choice == '1':
            buy()



#===============>db.json
{"egon": {"password": "123", "money": 3000}, "alex": {"password": "alex3714", "money": 30000}, "wsb": {"password": "3714", "money": 20000}}

#===============>common.py
from conf import settings
import logging
import logging.config
import json

def get_logger(name):
    logging.config.dictConfig(settings.LOGGING_DIC)  # 导入上面定义的logging配置
    logger = logging.getLogger(name)  # 生成一个log实例
    return logger


def conn_db():
    db_path=settings.DB_PATH
    dic=json.load(open(db_path,'r',encoding='utf-8'))
    return dic


#===============>access.log
[2017-10-21 19:08:20,285][MainThread:10900][task_id:core.src][src.py:19][INFO][登录成功]
[2017-10-21 19:08:32,206][MainThread:10900][task_id:core.src][src.py:19][INFO][登录成功]
[2017-10-21 19:08:37,166][MainThread:10900][task_id:core.src][src.py:24][ERROR][用户名不存在]
[2017-10-21 19:08:39,535][MainThread:10900][task_id:core.src][src.py:24][ERROR][用户名不存在]
[2017-10-21 19:08:40,797][MainThread:10900][task_id:core.src][src.py:24][ERROR][用户名不存在]
[2017-10-21 19:08:47,093][MainThread:10900][task_id:core.src][src.py:24][ERROR][用户名不存在]
[2017-10-21 19:09:01,997][MainThread:10900][task_id:core.src][src.py:19][INFO][登录成功]
[2017-10-21 19:09:05,781][MainThread:10900][task_id:core.src][src.py:24][ERROR][用户名不存在]
[2017-10-21 19:09:29,878][MainThread:8812][task_id:core.src][src.py:19][INFO][登录成功]
[2017-10-21 19:09:54,117][MainThread:9884][task_id:core.src][src.py:19][INFO][登录成功]

补充

# 在进行开发的时候，尽量将路径变成动态的，可根据环境改变的路径，方便用户使用，下面介绍一些方法帮助实现动态的路径
import os  # 文件操作相关的模块
os.path.dirname(path)  # 显示当前路径的父文件夹
os.getcwd()  # 显示当前文件的位置，返回一个文件路径
os.chdir(path)  # 改变当前文件的位置，就是文件的移动
__file__  # 显示当前文件的绝对路径
os.path.dirname(__file__)  # 显示当前文件的父级文件夹

推荐阅读