1CTAGS-LANG-PYTHON(7)            Universal Ctags           CTAGS-LANG-PYTHON(7)
2
3
4

NAME

6       ctags-lang-python  - Random notes about tagging python source code with
7       Universal Ctags
8

SYNOPSIS

10       ctags ... --languages=+Python ...
11       ctags ... --language-force=Python ...
12       ctags ... --map-Python=+.py ...
13
14

DESCRIPTION

16       This man page gathers random notes about tagging python source code.
17

TAGGING IMPORT STATEMENTS

19   Summary
20       import X
21
22                     ┌─────┬────────┬──────────┬──────────────────┐
23                     │name │ kind   │ role     │ other noticeable │
24                     │     │        │          │ fields           │
25                     ├─────┼────────┼──────────┼──────────────────┤
26                     │X    │ module │ imported │ N/A              │
27                     └─────┴────────┴──────────┴──────────────────┘
28
29       import X as Y
30
31                 ┌─────┬───────────┬───────────────┬──────────────────┐
32                 │name │ kind      │ role          │ other noticeable │
33                 │     │           │               │ fields           │
34                 ├─────┼───────────┼───────────────┼──────────────────┤
35                 │X    │ module    │ indirectlyIm‐ │ N/A              │
36                 │     │           │ ported        │                  │
37                 ├─────┼───────────┼───────────────┼──────────────────┤
38                 │Y    │ namespace │ definition    │ nameref:module:X │
39                 └─────┴───────────┴───────────────┴──────────────────┘
40
41       from X import *
42
43                     ┌─────┬────────┬───────────┬──────────────────┐
44                     │name │ kind   │ role      │ other noticeable │
45                     │     │        │           │ fields           │
46                     ├─────┼────────┼───────────┼──────────────────┤
47X    │ module │ namespace │ N/A              │
48                     └─────┴────────┴───────────┴──────────────────┘
49
50       from X import Y
51
52                    ┌─────┬─────────┬───────────┬──────────────────┐
53                    │name │ kind    │ role      │ other noticeable │
54                    │     │         │           │ fields           │
55                    ├─────┼─────────┼───────────┼──────────────────┤
56X    │ module  │ namespace │ N/A              │
57                    ├─────┼─────────┼───────────┼──────────────────┤
58Y    │ unknown │ imported  │ scope:module:X
59                    └─────┴─────────┴───────────┴──────────────────┘
60
61       from X import Y as Z
62
63
64
65
66
67                  ┌─────┬─────────┬───────────────┬──────────────────┐
68                  │name │ kind    │ role          │ other noticeable │
69                  │     │         │               │ fields           │
70                  ├─────┼─────────┼───────────────┼──────────────────┤
71X    │ module  │ namespace     │ N/A              │
72                  ├─────┼─────────┼───────────────┼──────────────────┤
73Y    │ unknown │ indirectlyIm‐ │ scope:module:X
74                  │     │         │ ported        │                  │
75                  ├─────┼─────────┼───────────────┼──────────────────┤
76Z    │ unknown │ definition    │ nameref:un‐      │
77                  │     │         │               │ known:X
78                  └─────┴─────────┴───────────────┴──────────────────┘
79
80   Examples
81       "input.py"
82
83          import X0
84
85       "output.tags" with "--options=NONE -o - --extras=+r  --fields=+rzK  in‐
86       put.py"
87
88          X0      input.py        /^import X0$/;" kind:module     roles:imported
89
90       A  tag  for an imported module has module kind with imported role.  The
91       module is not defined here; it is defined in another file. So  the  tag
92       for  the  imported  module  is a reference tag; specify --extras=+r (or
93       --extras=+{reference}) option for tagging it.  "roles:"  field  enabled
94       with  --fields=+r  is for recording the module is "imported" to the tag
95       file.
96
97       "input.py"
98
99          import X1 as Y1
100
101       "output.tags"  with  "--options=NONE  -o  -  --extras=+r  --fields=+rzK
102       --fields-Python=+{nameref} input.py"
103
104          X1      input.py        /^import X1 as Y1$/;"   kind:module     roles:indirectlyImported
105          Y1      input.py        /^import X1 as Y1$/;"   kind:namespace  roles:def       nameref:module:X1
106
107       "Y1"  introduces a new name and is defined here. So "Y1" is tagged as a
108       definition tag.  "X1" is imported in a way that its name cannot be used
109       in this source file. For letting client tools know that the name cannot
110       be used, indirectlyImported role is assigned for  "X1".   "Y1"  is  the
111       name  for  accessing  objects  defined in the module imported via "X1".
112       For recording this relationship, nameref: field is attached to the  tag
113       of  "Y1".   Instead  of module kind, namespace kind is assigned to "Y1"
114       because "Y1" itself isn't a module.
115
116       "input.py"
117
118          from X2 import *
119
120       "output.tags" with "--options=NONE -o - --extras=+r  --fields=+rzK  in‐
121       put.py"
122
123          X2      input.py        /^from X2 import *$/;"  kind:module     roles:namespace
124
125       The  module  is not defined here; it is defined in another file. So the
126       tag for the imported module is a reference tag. Unlike "X0" in  "import
127       X0", "X2" may not be used because the names defined in "X2" can be used
128       in this source file. To represent the difference namespace role is  at‐
129       tached to "X2" instead of imported.
130
131       "input.py"
132
133          from X3 import Y3
134
135       "output.tags"  with "--options=NONE -o - --extras=+r --fields=+rzKZ in‐
136       put.py"
137
138          X3      input.py        /^from X3 import Y3$/;" kind:module     roles:namespace
139          Y3      input.py        /^from X3 import Y3$/;" kind:unknown    scope:module:X3 roles:imported
140
141       "Y3"  is  a  name  for  a  language  object  defined  in  "X3"  module.
142       "scope:module:X3"  attached  to  "Y3"  represents this relation between
143       "Y3" and "X3". ctags assigns unknown kind to "Y3" because ctags  cannot
144       know  whether "Y3" is a class, a variable, or a function from the input
145       file.
146
147       "input.py"
148
149          from X4 import Y4 as Z4
150
151       "output.tags" with "--options=NONE -o - --extras=+r --fields=+rzKZ  in‐
152       put.py"
153
154          X4      input.py        /^from X4 import Y4 as Z4$/;"   kind:module     roles:namespace
155          Y4      input.py        /^from X4 import Y4 as Z4$/;"   kind:unknown    scope:module:X4 roles:indirectlyImported
156          Z4      input.py        /^from X4 import Y4 as Z4$/;"   kind:unknown    roles:def       nameref:unknown:Y4
157
158       "Y4"  is  similar to "Y3" of "from X3 import Y3" but the name cannot be
159       used here.  indirectlyImported role assigned to "Y4" representing this.
160       "Z4"  is  the  name  for accessing the language object named in "Y4" in
161       "X4" module. "nameref:unknown:Y4"  attached  to  "Z4"  and  "scope:mod‐
162       ule:X4" attached to "Y4" represent the relations.
163

LAMBDA EXPRESSION AND TYPE HINT

165   Summary
166       id = lambda var0: var0
167
168                   ┌─────┬──────────┬────────────┬──────────────────┐
169                   │name │ kind     │ role       │ other noticeable │
170                   │     │          │            │ fields           │
171                   ├─────┼──────────┼────────────┼──────────────────┤
172id   │ function │ definition │ signature:(var0) │
173                   └─────┴──────────┴────────────┴──────────────────┘
174
175       id_t: Callable[[int], int] = lambda var1: var1
176
177               ┌──────────┬──────────┬────────────┬──────────────────────┐
178               │name      │ kind     │ role       │ other noticeable     │
179               │          │          │            │ fields               │
180               ├──────────┼──────────┼────────────┼──────────────────────┤
181id_t      │ variable │ definition │ typeref:type‐        │
182               │          │          │            │ name:Callable[[int],
183               │          │          │            │ int]
184               │          │          │            │ nameref:func‐        │
185               │          │          │            │ tion:anonFuncN       │
186               ├──────────┼──────────┼────────────┼──────────────────────┤
187               │anonFuncN │ function │ definition │ signature:(var1)     │
188               └──────────┴──────────┴────────────┴──────────────────────┘
189
190   Examples
191       "input.py"
192
193          from typing import Callable
194          id = lambda var0: var0
195          id_t: Callable[[int], int] = lambda var1: var1
196
197       "output.tags"   with   "--options=NONE   -o  -  --sort=no  --fields=+KS
198       --fields-Python=+{nameref} --extras=+{anonymous} input.py"
199
200          id      input.py        /^id = lambda var0: var0$/;"    function        signature:(var0)
201          id_t    input.py        /^id_t: Callable[[int], int] = lambda var1: var1$/;"\
202                  variable        typeref:typename:Callable[[int], int]   nameref:function:anonFunc84011d2c0101
203          anonFunc84011d2c0101    input.py        /^id_t: Callable[[int], int] = lambda var1: var1$/;"\
204                  function        signature:(var1)
205
206       If a variable ("id") with no type hint is initialized with a lambda ex‐
207       pression, ctags assigns function kind for the tag of "id".
208
209       If  a  variable  ("id_t") with a type hint is initialized with a lambda
210       expression, ctags assigns variable kind for  the  tag  of  "id_t"  with
211       typeref: and nameref: fields. ctags fills typeref: field with the value
212       of the type hint. The way of filling nameref: is a bit complicated.
213
214       For the lambda expression used in initializing the  type-hint'ed  vari‐
215       able, ctags creates anonymous extra tag ("anonFunc84011d2c0101"). ctags
216       fills the nameref: field of "id_t" with the  name  of  anonymous  extra
217       tag: "nameref:function:anonFunc84011d2c0101".
218
219       You may think why ctags does so complicated, and why ctags doesn't emit
220       following tags output for the input:
221
222          id      input.py        /^id = \\$/;"   function        signature:(var0)
223          id_t    input.py        /^id_t: \\$/;"  function        typeref:typename:Callable[[int], int]   signature:(var1)
224
225       There is a reason. The other languages  of  ctags  obey  the  following
226       rule:  ctags  fills typeref: field for a tag of a callable object (like
227       function) with the type of its return value. If we consider "id_t" is a
228       function,  its  typeref: field should have "typename:int". However, for
229       filling  typeref:   with   "typename:int",   ctags   has   to   analyze
230       "Callable[[int], int]" deeper. We don't want to do so.
231

SEE ALSO

233       ctags(1), ctags-client-tools(7), ctags-lang-iPythonCell(7)
234
235
236
237
2385.9.0                                                     CTAGS-LANG-PYTHON(7)
Impressum