1CTAGS-LANG-PYTHON(7) Universal Ctags CTAGS-LANG-PYTHON(7)
2
6 ctags-lang-python - Random notes about tagging python source code with
7 Universal Ctags
8
10 ctags ... --languages=+Python ...
11 ctags ... --language-force=Python ...
12 ctags ... --map-Python=+.py ...
13
16 This man page gathers random notes about tagging python source code.
17
19 Summary
20 import X
21 ┌─────┬────────┬──────────┬──────────────────┐
23 │name │ kind │ role │ other noticeable │
24 │ │ │ │ fields │
25 ├─────┼────────┼──────────┼──────────────────┤
26 │X │ module │ imported │ N/A │
27 └─────┴────────┴──────────┴──────────────────┘
28 import X as Y
30 ┌─────┬───────────┬───────────────┬──────────────────┐
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 from X import *
42 ┌─────┬────────┬───────────┬──────────────────┐
44 │name │ kind │ role │ other noticeable │
45 │ │ │ │ fields │
46 ├─────┼────────┼───────────┼──────────────────┤
47 │X │ module │ namespace │ N/A │
48 └─────┴────────┴───────────┴──────────────────┘
49 from X import Y
51 ┌─────┬─────────┬───────────┬──────────────────┐
53 │name │ kind │ role │ other noticeable │
54 │ │ │ │ fields │
55 ├─────┼─────────┼───────────┼──────────────────┤
56 │X │ module │ namespace │ N/A │
57 ├─────┼─────────┼───────────┼──────────────────┤
58 │Y │ unknown │ imported │ scope:module:X │
59 └─────┴─────────┴───────────┴──────────────────┘
60 from X import Y as Z
62 ┌─────┬─────────┬───────────────┬──────────────────┐
68 │name │ kind │ role │ other noticeable │
69 │ │ │ │ fields │
70 ├─────┼─────────┼───────────────┼──────────────────┤
71 │X │ module │ namespace │ N/A │
72 ├─────┼─────────┼───────────────┼──────────────────┤
73 │Y │ unknown │ indirectlyIm‐ │ scope:module:X │
74 │ │ │ ported │ │
75 ├─────┼─────────┼───────────────┼──────────────────┤
76 │Z │ unknown │ definition │ nameref:un‐ │
77 │ │ │ │ known:X │
78 └─────┴─────────┴───────────────┴──────────────────┘
79 Examples
81 "input.py"
82 import X0
84 "output.tags" with "--options=NONE -o - --extras=+r --fields=+rzK in‐
86 put.py"
87 X0 input.py /^import X0$/;" kind:module roles:imported
89 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 "input.py"
98 import X1 as Y1
100 "output.tags" with "--options=NONE -o - --extras=+r --fields=+rzK
102 --fields-Python=+{nameref} input.py"
103 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 "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 "input.py"
117 from X2 import *
119 "output.tags" with "--options=NONE -o - --extras=+r --fields=+rzK in‐
121 put.py"
122 X2 input.py /^from X2 import *$/;" kind:module roles:namespace
124 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 "input.py"
132 from X3 import Y3
134 "output.tags" with "--options=NONE -o - --extras=+r --fields=+rzKZ in‐
136 put.py"
137 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 "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 "input.py"
148 from X4 import Y4 as Z4
150 "output.tags" with "--options=NONE -o - --extras=+r --fields=+rzKZ in‐
152 put.py"
153 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 "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
165 Summary
166 id = lambda var0: var0
167 ┌─────┬──────────┬────────────┬──────────────────┐
169 │name │ kind │ role │ other noticeable │
170 │ │ │ │ fields │
171 ├─────┼──────────┼────────────┼──────────────────┤
172 │id │ function │ definition │ signature:(var0) │
173 └─────┴──────────┴────────────┴──────────────────┘
174 id_t: Callable[[int], int] = lambda var1: var1
176 ┌──────────┬──────────┬────────────┬──────────────────────┐
178 │name │ kind │ role │ other noticeable │
179 │ │ │ │ fields │
180 ├──────────┼──────────┼────────────┼──────────────────────┤
181 │id_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 Examples
191 "input.py"
192 from typing import Callable
194 id = lambda var0: var0
195 id_t: Callable[[int], int] = lambda var1: var1
196 "output.tags" with "--options=NONE -o - --sort=no --fields=+KS
198 --fields-Python=+{nameref} --extras=+{anonymous} input.py"
199 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 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 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 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 You may think why ctags does so complicated, and why ctags doesn't emit
220 following tags output for the input:
221 id input.py /^id = \\$/;" function signature:(var0)
223 id_t input.py /^id_t: \\$/;" function typeref:typename:Callable[[int], int] signature:(var1)
224 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
233 ctags(1), ctags-client-tools(7), ctags-lang-iPythonCell(7)
2345.9.0 CTAGS-LANG-PYTHON(7)