Merge pull request #73 from Alinvor/kernel

[DONE]合并分支

Author: DovSnier

.rmcache.ps1

@@ -4,9 +4,17 @@
 #   1. https://docs.microsoft.com/zh-cn/powershell/scripting/samples/working-with-files-and-folders?view=powershell-7.1
 #   2. https://docs.microsoft.com/zh-cn/powershell/scripting/samples/working-with-registry-keys?view=powershell-7.1
 #
-# the delete files
+## THE DELETE FILES
 Get-ChildItem -Path . -include *.pyc -Recurse | Remove-Item
-# the delete directory
-Get-ChildItem -Path . -include __pycache__ -Recurse | Remove-Item
+## THE DELETE DIRECTORY
+# ./build/*
 Remove-Item -Path .\build\* -Recurse
+# ./src/com.dvsnier.*.egg-info
+Remove-Item -Path .\src\com.dvsnier.*.egg-info -Recurse
+# Get-ChildItem -Path .\src\com.dvsnier.*.egg-info -Recurse
+# ./dist/*
+Remove-Item -Path .\dist\* -Recurse
+# ./out/log/*
 Remove-Item -Path .\out\log\* -Recurse
+# __pycache__
+Get-ChildItem -Path . -include __pycache__ -Recurse | Remove-Item

README.md

@@ -45,7 +45,13 @@
     - [5.3.1 注册账号](#531-注册账号)
     - [5.3.2 检查软件包](#532-检查软件包)
     - [5.3.3 上传软件包](#533-上传软件包)
-- [六. 参考](#六-参考)
+- [六. WiKi](#六-wiki)
+  - [6.1 规约与守则](#61-规约与守则)
+  - [6.2 文档与源码](#62-文档与源码)
+  - [6.3 配置与模板](#63-配置与模板)
+  - [6.4 调试与构建](#64-调试与构建)
+  - [6.5 日志与清理](#65-日志与清理)
+- [七. 参考](#七-参考)
 
 ## 一. 构建`venv`环境
 
@@ -948,7 +954,46 @@ twine check dist/*
 twine upload dist/*
 ```
 
-## 六. 参考
+## 六. WiKi
+
+### 6.1 规约与守则
+
+1. [【Contract: 规约守则】](./doc/project_help/the_global_rules.md)
+
+### 6.2 文档与源码
+
+1. [【Document: Python 环境查看函数】](./doc/README.md)
+2. [【Source: Recommended Source Websites】](./doc/SOURCE.md)
+
+### 6.3 配置与模板
+
+1. [【Config: The `LICENSE` File】](./LICENSE.txt)
+2. [【Config: The `MANIFEST` File】](./MANIFEST.in)
+3. [【Config: The `pyproject` File】](./pyproject.toml)
+4. [【Config: The `requirements` File】](./requirements.txt)
+5. [【Config: The `setup` File】](./setup.cfg)
+6. [【Config: The `tox` File】](./tox.ini)
+7. [【Template: The `__init__` File】](./template/__init__.py)
+8. [【Template: The `__init__with_pkgutil` File】](./template/__init__with_pkgutil.py)
+9. [【Template: The `template` File】](./template/template.py)
+10. [【Template: The `template_class` File】](./template/template_class.py)
+11. [【Template: The `test_template` File】](./template/test_template.py)
+
+### 6.4 调试与构建
+
+1. [【Debug: Bash_or_Ps1】](./Temp/bash/bash_or_ps1.md)
+2. [【Debug: Python Command】](./Temp/bash/python_command.md)
+3. [【Debug: Environment Variable Information(The Necessities)】](./Temp/debug/env/interpreterInfo.py)
+4. [【Debug: Environment Variable Information(An Generals)】](./Temp/debug/env/interpreterInfo.py)
+5. [【Build: The `Requirements` Text】](./Temp/archives/material/requirements.txt)
+6. [【Build: The `Setup` Script】](./Temp/archives/material/setup.py)
+
+### 6.5 日志与清理
+
+1. [【Clean: darwin】](./.rmcache.bash)
+2. [【Clean: win】](./.rmcache.ps1)
+
+## 七. 参考
 
 1. https://packaging.python.org/tutorials/packaging-projects/
 2. https://packaging.python.org/guides/distributing-packages-using-setuptools/

Temp/bash/python_command.md

@@ -3,6 +3,9 @@
 - [一. pip](#一-pip)
   - [1.1. pip --editable](#11-pip---editable)
   - [1.2. pip list or freeze](#12-pip-list-or-freeze)
+  - [1.3. pip install](#13-pip-install)
+    - [1.3.1. pip install -r requirements.txt](#131-pip-install--r-requirementstxt)
+    - [1.3.2. pip install xxx](#132-pip-install-xxx)
 - [二. flake8](#二-flake8)
 
 ## 一. pip
@@ -29,6 +32,27 @@ pip2 freeze > ./Temp/txt/2021_pip2_freeze.txt
 pip3 freeze > ./Temp/txt/2021_pip3_freeze.txt
 ```
 
+### 1.3. pip install
+
+#### 1.3.1. pip install -r requirements.txt
+
+```bash
+# the base component requirements
+pip2 install -r ./requirements.txt
+pip3 install -r ./requirements.txt
+
+# the base chain component requirements
+pip2 install -r ./Temp/archives/material/requirements.txt
+pip3 install -r ./Temp/archives/material/requirements.txt
+```
+
+#### 1.3.2. pip install xxx
+
+```bash
+pip2 install xxx
+pip3 install xxx
+```
+
 ## 二. flake8
 
 ```bash

doc/SOURCE.md

@@ -0,0 +1,17 @@
+# 阅读
+
+尝试去一些网站读源码:
+
+- https://github.com/
+- https://launchpad.net/
+- https://koders.com/
+- https://bitbucket.org/
+- https://www.python.org/dev/peps/
+- https://pypi.org/
+- https://docs.python.org/zh-cn/2.7/index.html
+- https://docs.python.org/zh-cn/3.8/
+- https://stackoverflow.com/
+- https://github.com/Alinvor/Python-DeMo
+- https://gitee.com/dovsnier/Python-Test
+- https://blog.csdn.net/dovsnier/category_9322292.html?spm=1001.2014.3001.5482
+- https://blog.csdn.net/dovsnier/category_3041641.html?spm=1001.2014.3001.5482

doc/project_help/the_global_rules.md

@@ -2,7 +2,11 @@
 
 - [一. 说明](#一-说明)
 - [二. 源码](#二-源码)
-- [三. 测试](#三-测试)
+- [三. 调试](#三-调试)
+  - [3.1. System 环境变量](#31-system-环境变量)
+  - [3.2. VSCode PYTHONPATH](#32-vscode-pythonpath)
+  - [3.3. inline import](#33-inline-import)
+- [四. 测试](#四-测试)
 
 ## 一. 说明
 
@@ -13,6 +17,88 @@
 1. 统一采用`com.dvsnier` 命名空间;
 2. 包结构，统一定义: `com.dvsnier.xxx`, 且`xxx` 包名称一定要和目录层次一一对应, 可以避免潜在无关紧要问题;
 
-## 三. 测试
+## 三. 调试
+
+### 3.1. System 环境变量
+
+目前我们规定如下可选全局变量:
+
+- `PYTHONPATH`: 【可选项】, Python 环境变量;
+- `BASE_PROJECT_PREFIX`: 【必选项】, 当前工作区目录前缀;
+
+> 1. `工作区`: 当前程序被系统`调用并执行`的区间点;
+> 2. `运行区`: 当前程序被系统`执行`的区间点;
+>
+> > - `工作目录`: 当前进程的`静态执行` 符号载体;
+> > - `运行目录`: 当前进程的`动态执行` 驻留载体;
+
+```bash
+# darwin Python
+# export PYTHONPATH=.
+export BASE_PROJECT_PREFIX="/Users/.../Python-DeMo"
+
+# win Python
+# PYTHONPATH=.
+BASE_PROJECT_PREFIX="D:\\...\\Python-DeMo"
+```
+
+### 3.2. VSCode PYTHONPATH
+
+VSCode 环境变量指定的默认配置选项为:
+
+```json
+{
+    "python.envFile": "${workspaceFolder}/.env"
+}
+```
+
+**注意**:
+
+1. 在`${workspaceFolder}/.env` 文件中所指定 `PYTHONPATH` 请使用`绝对路径`, 因为使用相对路径目前的版本不受支持;
+2. 目前无需在 VSCode 中使用`.` 操作符指定当前目录, 从而被重复加入到VSCode `PYTHONPATH` 中, VSCode 默认具有当前功能(隐含默认将当前执行目录加入`PYTHONPATH` 环境变量);
+3. 加载环境变量顺序需要注意, VSCode 默认加载位置为: `["VSCode DEFAULT RULES(stdlib)", "VSCode DEFAULT INLINE RULUES WITH PYTHON PATH . AND SRC", "VSCode PYTHONPATH WITH ENV", "SYSTEM DEFAULT PYTHON PATH LIST", "virtual environment list"]`
+4. `.` 操作符在VSCode `PYTHONPATH` 中单独使用是起作用的, 联合使用不起作用, 是 VSCode 的一个 Bug, 同时不支持 `${workspaceFolder}` 变量替换;
+
+具体 `PYTHONPATH` 添加规则如下:
+
+```bash
+"VSCode STD LIBRARY" ↔ "VSCode DEFAULT RULES(stdlib)"
+        ↓                               ↓
+"VSCode CURRENT RULES" ↔ "VSCode DEFAULT INLINE RULES WITH PYTHON PATH . AND SRC"
+        ↓                     ↓
+"VSCode ENV" ↔ "VSCode PYTHONPATH WITH ENV"
+        ↓                   ↓
+"SYSTEM" ↔ "SYSTEM DEFAULT PYTHON PATH LIST"
+        ↓                           ↓
+"VIRTUAL ENVIRONMENT" ↔ "virtual environment list"
+```
+
+举例如下:
+
+```bash
+# darwin
+PYTHONPATH=/Users/.../Python-DeMo:/Users/.../Python-DeMo/tests:${PYTHONPATH}
+
+# win32
+PYTHONPATH=D:\\WorkSpace\\...\\Python-DeMo;D:\\WorkSpace\\...\\Python-DeMo\\tests;%PYTHONPATH%
+```
+
+### 3.3. inline import
+
+**内联导入**:
+
+在 VSCode 中, 如果需要在 `tests` 写测试用例, 调用 `src` 中代码, 由于 Python 或 VSCode 机制的原因, 实际上不指明 `PYTHONPATH` 的情况下, 是无法进行调用的; 因此我们采用如下方式:
+
+1. `PYTHONPATH` 指定绝对路径方式【不推荐】;
+2. 将 `src` 调试安装到当前虚拟环境下(需要 `setup.py` 文件参与)**【推荐】**;
+
+举例如下:
+
+```bash
+pip2 install -e .
+pip3 install -e .
+```
+
+## 四. 测试
 
 1. 统一采用和源码空间统一的目录结构和命名空间形式;

doc/source.md

@@ -7,6 +7,3 @@
 #
 [bdist_wheel]
 universal = 1
-
-[flake8]
-max-line-length = 120