add demo for type annotation

docs/requirements.txt

@@ -4,6 +4,7 @@ joblib==1.2.0
 setuptools==58.0.4
 astropy==5.1
 pycodestyle==2.9.1
+nbsphinx
 #sphinx_copybutton==0.5.0 # this does not exclude linenos
 git+https://github.com/executablebooks/sphinx-copybutton.git
 git+https://csst-tb.bao.ac.cn/code/csst-l1/csst_common.git

docs/source/demo_type_annotation.ipynb

+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "source": [
+    "# How to do Python type annotation"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "697384beaffb53a3"
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## built-in types"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "4313baabbbf2ecb"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "outputs": [],
+   "source": [
+    "a: int = 8 # 整数型标注\n",
+    "b: float = 1.23 # 浮点型标注\n",
+    "c: bool = True # 布尔型标注\n",
+    "d: tuple = (1, 2) # 元组型标注\n",
+    "e: tuple[int, float] = (1, 2.34) # 限定类型和元素个数的元组标注\n",
+    "f: tuple[int, ...] = (1, 2, 3, 4, 5., \"abc\") # 限定类型但不定元素个数的元组型标注\n",
+    "g: list = [1, 2, 3] # 一般的列表型标注\n",
+    "h: list[int] = [1, 2, 3] # 对列表型来说不需要标元素个数，但可以明确要求元素类型"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "ExecuteTime": {
+     "end_time": "2023-09-16T11:21:28.779243Z",
+     "start_time": "2023-09-16T11:21:28.772041Z"
+    }
+   },
+   "id": "5fbe06f15bbcd630"
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## `typing` 模块\n",
+    "对于一些内建类型来说是可以直接用内建类型来标注的，例如以下两句是相等的"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "a06987fbe46de9e4"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "outputs": [],
+   "source": [
+    "l1: list[int] = [1, 2, 3]\n",
+    "\n",
+    "from typing import List\n",
+    "l2: List[int] = [1, 2, 3]"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "ExecuteTime": {
+     "end_time": "2023-09-16T11:24:33.997164Z",
+     "start_time": "2023-09-16T11:24:33.993038Z"
+    }
+   },
+   "id": "c9d78355e0521512"
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## Union, Optional和Any\n",
+    "\n",
+    "- Union表示并集，Union[float, int]表示可以是float也可以是int\n",
+    "- Optional表示可选，Optional[int]表示可以是None也可以是int\n",
+    "- Any表示任意类型"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "8cab70562a62c99"
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## numpy.typing\n",
+    "我们经常会用到numpy.ndarray进行科学计算，可以有以下几种标注方式:\n",
+    "\n",
+    "1. 直接用np.ndarray进行标注, 此时不限定类型(dtype)"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "ca8b1d813d84ad8c"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "\n",
+    "x1: np.ndarray = np.arange(10)"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "ExecuteTime": {
+     "end_time": "2023-09-16T11:30:37.052436Z",
+     "start_time": "2023-09-16T11:30:37.044Z"
+    }
+   },
+   "id": "6ebd28b4f4c84ab4"
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "2. 限定类型时不能使用np.ndarray而必须用numpy.typing模块"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "622cde4d8d3fb34a"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "outputs": [],
+   "source": [
+    "import numpy.typing as npt\n",
+    "\n",
+    "x2: npt.NDArray = np.arange(10, dtype=float)\n",
+    "x3: npt.NDArray[np.int_] = np.arange(10, dtype=int)\n",
+    "x4: npt.NDArray[np.float_] = np.arange(10, dtype=float)\n",
+    "x5: npt.NDArray[np.float32] = np.arange(10, dtype=np.float32)\n",
+    "x6: npt.NDArray[np.bool_] = np.ones(10, dtype=bool)\n",
+    "x7: npt.NDArray[np.complex_] = np.ones(10, dtype=np.complex_)"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "ExecuteTime": {
+     "end_time": "2023-09-16T11:33:56.755287Z",
+     "start_time": "2023-09-16T11:33:56.739805Z"
+    }
+   },
+   "id": "36d4e0be053bbd1a"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "47b6d72d76ee84a1"
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/source/index.rst

@@ -71,6 +71,7 @@ The guide for LSST developers
    :caption: TEAM
 
    ch01_team.rst
+   demo_type_annotation.ipynb
 
 
 .. toctree::