✨ feat(vscode): 代码阅读类块改成属性表并默认折叠，类的说明进「说明」行

vscode/src/codeReader/languages/python.test.ts

@@ -90,7 +90,7 @@ describe('python 代码块树', () => {
   })
 })
 
-describe('python 函数的 docstring', () => {
+describe('python 函数、类的 docstring', () => {
   const source = [
     'class K:',
     '    """类说明"""',
@@ -105,10 +105,9 @@ describe('python 函数的 docstring', () => {
     'def g(): "单行"',
   ].join('\n')
 
-  it('算进函数头部、不单独成块，它前面的注释也在头部里；后面的注释照旧成块；类的 docstring 照旧是注释块', async () => {
+  it('算进函数、类头部、不单独成块，它前面的注释也在头部里；后面的注释照旧成块', async () => {
     expect(await tree(source)).toEqual([
-      { at: 1, kind: 'class', kids: [
-        { at: 2, kind: 'comment' },
+      { at: [1, 2], kind: 'class', kids: [
         { at: [3, 8], kind: 'function', kids: [
           { at: 9, kind: 'comment' },
           { at: 10, kind: 'return' },
@@ -118,9 +117,11 @@ describe('python 函数的 docstring', () => {
     ])
   })
 
-  it('进 facts.doc：是那个字符串节点；没有 docstring 的函数没有', async () => {
+  it('进 facts.doc：是那个字符串节点；没有 docstring 的函数没有；模块开头的 docstring 照旧是注释块', async () => {
     const found = await facts(source)
+    expect(found[1]).toMatchObject({ name: 'K', doc: '"""类说明"""' })
     expect(found[3]).toMatchObject({ name: 'run', doc: '"""跑一遍。\n\n        细节。\n        """' })
+    expect(await tree('"""模块说明"""\nclass K:\n    pass')).toEqual([{ at: 1, kind: 'comment' }, { at: 2, kind: 'class', kids: [{ at: 3, kind: 'statement' }] }])
     expect(found[11]).toMatchObject({ name: 'g', doc: '"单行"' })
     expect(await facts('def f():\n    x = 1\n    """not a docstring"""')).not.toHaveProperty('1.doc')
   })
@@ -236,3 +237,63 @@ describe('python 属性表信息（facts）', () => {
     expect(found[10]).not.toHaveProperty('access')
   })
 })
+
+describe('python 类', () => {
+  it('classes.py：docstring（连同它前面的注释）算进类头部，类里的类、函数里的类照常成块', async () => {
+    expect(await tree(readFixture('classes.py'))).toEqual([
+      { at: 1, kind: 'comment' },
+      { at: 3, kind: 'import' },
+      { at: [6, 10], kind: 'class', kids: [
+        { at: 12, kind: 'field' },
+        { at: 14, kind: 'function', kids: [{ at: 15, kind: 'variable' }] },
+      ] },
+      { at: [18, 20], kind: 'class', kids: [{ at: 21, kind: 'variable' }] },
+      { at: [24, 25], kind: 'class', kids: [
+        { at: 26, kind: 'class', kids: [{ at: 27, kind: 'variable' }] },
+        { at: 29, kind: 'class', kids: [{ at: 30, kind: 'statement' }] },
+      ] },
+      { at: 33, kind: 'class', kids: [{ at: 34, kind: 'statement' }] },
+      { at: 37, kind: 'function', kids: [
+        { at: [38, 39], kind: 'class' },
+        { at: 40, kind: 'return' },
+      ] },
+    ])
+  })
+
+  it('classes.py：名称、说明、访问级别（同函数的下划线规则，类里的类也按它，函数里的没有）、装饰器、父类（参数列表照写的顺序，关键字参数也算）', async () => {
+    const found = await facts(readFixture('classes.py'))
+    expect(found[6]).toEqual({
+      name: 'AppException',
+      doc: '"""应用异常的基类。\n\n    带上 HTTP 状态码。\n    """',
+      access: 'public',
+      decorators: [],
+      typeParameters: [],
+      bases: [{ value: 'Exception' }],
+      implements: [],
+    })
+    expect(found[18]).toMatchObject({ name: 'NotFound', doc: '"""找不到资源。"""', bases: [{ value: 'AppException' }] })
+    expect(found[24]).toEqual({
+      name: 'Meta',
+      access: 'public',
+      decorators: ['@dataclass(frozen=True)'],
+      typeParameters: [],
+      bases: [{ value: 'Base' }, { value: 'metaclass=ABCMeta' }],
+      implements: [],
+    })
+    expect(found[26]).toMatchObject({ name: 'Config', access: 'public', bases: [] })
+    expect(found[29]).toMatchObject({ name: '_Hidden', access: 'private' })
+    expect(found[33]).toMatchObject({ name: '_Private', access: 'private' })
+    expect(found[38]).toEqual({ name: 'Local', doc: '"""局部类。"""', decorators: [], typeParameters: [], bases: [], implements: [] })
+  })
+
+  it('没有「抽象」这个概念；Python 3.12 的泛型参数进 typeParameters；*bases、**kw 也是父类里的一项', async () => {
+    expect((await facts('class G[T](Generic[T], *mixins, **kw):\n    pass'))[1]).toEqual({
+      name: 'G',
+      access: 'public',
+      decorators: [],
+      typeParameters: ['T'],
+      bases: [{ value: 'Generic[T]' }, { value: '*mixins' }, { value: '**kw' }],
+      implements: [],
+    })
+  })
+})