Skip to content

Commit 4719499

Browse files
committed
STY: Black for tools/
1 parent b35db57 commit 4719499

11 files changed

+607
-509
lines changed

tools/apigen.py

Lines changed: 98 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -26,20 +26,20 @@
2626

2727
# Functions and classes
2828
class ApiDocWriter(object):
29-
''' Class for automatic detection and parsing of API docs
30-
to Sphinx-parsable reST format'''
29+
""" Class for automatic detection and parsing of API docs
30+
to Sphinx-parsable reST format"""
3131

3232
# only separating first two levels
33-
rst_section_levels = ['*', '=', '-', '~', '^']
33+
rst_section_levels = ["*", "=", "-", "~", "^"]
3434

3535
def __init__(
36-
self,
37-
package_name,
38-
rst_extension='.rst',
39-
package_skip_patterns=None,
40-
module_skip_patterns=None,
36+
self,
37+
package_name,
38+
rst_extension=".rst",
39+
package_skip_patterns=None,
40+
module_skip_patterns=None,
4141
):
42-
''' Initialize package for parsing
42+
""" Initialize package for parsing
4343
4444
Parameters
4545
----------
@@ -64,11 +64,11 @@ def __init__(
6464
``.util.console``
6565
If is None, gives default. Default is:
6666
['\.setup$', '\._']
67-
'''
67+
"""
6868
if package_skip_patterns is None:
69-
package_skip_patterns = ['\\.tests$']
69+
package_skip_patterns = ["\\.tests$"]
7070
if module_skip_patterns is None:
71-
module_skip_patterns = ['\\.setup$', '\\._']
71+
module_skip_patterns = ["\\.setup$", "\\._"]
7272
self.package_name = package_name
7373
self.rst_extension = rst_extension
7474
self.package_skip_patterns = package_skip_patterns
@@ -78,7 +78,7 @@ def get_package_name(self):
7878
return self._package_name
7979

8080
def set_package_name(self, package_name):
81-
''' Set package_name
81+
""" Set package_name
8282
8383
>>> docwriter = ApiDocWriter('sphinx')
8484
>>> import sphinx
@@ -88,33 +88,34 @@ def set_package_name(self, package_name):
8888
>>> import docutils
8989
>>> docwriter.root_path == docutils.__path__[0]
9090
True
91-
'''
91+
"""
9292
# It's also possible to imagine caching the module parsing here
9393
self._package_name = package_name
9494
self.root_module = __import__(package_name)
9595
self.root_path = self.root_module.__path__[0]
9696
self.written_modules = None
9797

98-
package_name = property(get_package_name, set_package_name, None,
99-
'get/set package_name')
98+
package_name = property(
99+
get_package_name, set_package_name, None, "get/set package_name"
100+
)
100101

101102
def _get_object_name(self, line):
102-
''' Get second token in line
103+
""" Get second token in line
103104
>>> docwriter = ApiDocWriter('sphinx')
104105
>>> docwriter._get_object_name(" def func(): ")
105106
u'func'
106107
>>> docwriter._get_object_name(" class Klass(object): ")
107108
'Klass'
108109
>>> docwriter._get_object_name(" class Klass: ")
109110
'Klass'
110-
'''
111-
name = line.split()[1].split('(')[0].strip()
111+
"""
112+
name = line.split()[1].split("(")[0].strip()
112113
# in case we have classes which are not derived from object
113114
# ie. old style classes
114-
return name.rstrip(':')
115+
return name.rstrip(":")
115116

116117
def _uri2path(self, uri):
117-
''' Convert uri to absolute filepath
118+
""" Convert uri to absolute filepath
118119
119120
Parameters
120121
----------
@@ -140,53 +141,53 @@ def _uri2path(self, uri):
140141
True
141142
>>> docwriter._uri2path('sphinx.does_not_exist')
142143
143-
'''
144+
"""
144145
if uri == self.package_name:
145-
return os.path.join(self.root_path, '__init__.py')
146-
path = uri.replace('.', os.path.sep)
147-
path = path.replace(self.package_name + os.path.sep, '')
146+
return os.path.join(self.root_path, "__init__.py")
147+
path = uri.replace(".", os.path.sep)
148+
path = path.replace(self.package_name + os.path.sep, "")
148149
path = os.path.join(self.root_path, path)
149150
# XXX maybe check for extensions as well?
150-
if os.path.exists(path + '.py'): # file
151-
path += '.py'
152-
elif os.path.exists(os.path.join(path, '__init__.py')):
153-
path = os.path.join(path, '__init__.py')
151+
if os.path.exists(path + ".py"): # file
152+
path += ".py"
153+
elif os.path.exists(os.path.join(path, "__init__.py")):
154+
path = os.path.join(path, "__init__.py")
154155
else:
155156
return None
156157
return path
157158

158159
def _path2uri(self, dirpath):
159-
''' Convert directory path to uri '''
160+
""" Convert directory path to uri """
160161
relpath = dirpath.replace(self.root_path, self.package_name)
161162
if relpath.startswith(os.path.sep):
162163
relpath = relpath[1:]
163-
return relpath.replace(os.path.sep, '.')
164+
return relpath.replace(os.path.sep, ".")
164165

165166
def _parse_module(self, uri):
166-
''' Parse module defined in *uri* '''
167+
""" Parse module defined in *uri* """
167168
filename = self._uri2path(uri)
168169
if filename is None:
169170
# nothing that we could handle here.
170171
return ([], [])
171-
f = open(filename, 'rt')
172+
f = open(filename, "rt")
172173
functions, classes = self._parse_lines(f)
173174
f.close()
174175
return functions, classes
175176

176177
def _parse_lines(self, linesource):
177-
''' Parse lines of text for functions and classes '''
178+
""" Parse lines of text for functions and classes """
178179
functions = []
179180
classes = []
180181
for line in linesource:
181-
if line.startswith('def ') and line.count('('):
182+
if line.startswith("def ") and line.count("("):
182183
# exclude private stuff
183184
name = self._get_object_name(line)
184-
if not name.startswith('_'):
185+
if not name.startswith("_"):
185186
functions.append(name)
186-
elif line.startswith('class '):
187+
elif line.startswith("class "):
187188
# exclude private stuff
188189
name = self._get_object_name(line)
189-
if not name.startswith('_'):
190+
if not name.startswith("_"):
190191
classes.append(name)
191192
else:
192193
pass
@@ -195,7 +196,7 @@ def _parse_lines(self, linesource):
195196
return functions, classes
196197

197198
def generate_api_doc(self, uri):
198-
'''Make autodoc documentation template string for a module
199+
"""Make autodoc documentation template string for a module
199200
200201
Parameters
201202
----------
@@ -206,71 +207,72 @@ def generate_api_doc(self, uri):
206207
-------
207208
S : string
208209
Contents of API doc
209-
'''
210+
"""
210211
# get the names of all classes and functions
211212
functions, classes = self._parse_module(uri)
212213
if not len(functions) and not len(classes):
213-
print(('WARNING: Empty -', uri)) # dbg
214-
return ''
214+
print(("WARNING: Empty -", uri)) # dbg
215+
return ""
215216

216217
# Make a shorter version of the uri that omits the package name for
217218
# titles
218-
uri_short = re.sub(r'^%s\.' % self.package_name, '', uri)
219+
uri_short = re.sub(r"^%s\." % self.package_name, "", uri)
219220

220-
ad = '.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n'
221+
ad = ".. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n"
221222

222223
chap_title = uri_short
223-
ad += (chap_title + '\n' +
224-
self.rst_section_levels[1] * len(chap_title) + '\n\n')
224+
ad += chap_title + "\n" + self.rst_section_levels[1] * len(chap_title) + "\n\n"
225225

226226
# Set the chapter title to read 'module' for all modules except for the
227227
# main packages
228-
if '.' in uri:
229-
title = 'Module: :mod:`' + uri_short + '`'
228+
if "." in uri:
229+
title = "Module: :mod:`" + uri_short + "`"
230230
else:
231-
title = ':mod:`' + uri_short + '`'
232-
ad += title + '\n' + self.rst_section_levels[2] * len(title)
231+
title = ":mod:`" + uri_short + "`"
232+
ad += title + "\n" + self.rst_section_levels[2] * len(title)
233233

234234
if len(classes):
235-
ad += '\nInheritance diagram for ``%s``:\n\n' % uri
236-
ad += '.. inheritance-diagram:: %s \n' % uri
237-
ad += ' :parts: 2\n'
235+
ad += "\nInheritance diagram for ``%s``:\n\n" % uri
236+
ad += ".. inheritance-diagram:: %s \n" % uri
237+
ad += " :parts: 2\n"
238238

239-
ad += '\n.. automodule:: ' + uri + '\n'
240-
ad += '\n.. currentmodule:: ' + uri + '\n'
239+
ad += "\n.. automodule:: " + uri + "\n"
240+
ad += "\n.. currentmodule:: " + uri + "\n"
241241
multi_class = len(classes) > 1
242242
multi_fx = len(functions) > 1
243243
if multi_class:
244-
ad += '\n' + 'Classes' + '\n' + \
245-
self.rst_section_levels[2] * 7 + '\n'
244+
ad += "\n" + "Classes" + "\n" + self.rst_section_levels[2] * 7 + "\n"
246245
elif len(classes) and multi_fx:
247-
ad += '\n' + 'Class' + '\n' + \
248-
self.rst_section_levels[2] * 5 + '\n'
246+
ad += "\n" + "Class" + "\n" + self.rst_section_levels[2] * 5 + "\n"
249247
for c in classes:
250-
ad += '\n:class:`' + c + '`\n' \
251-
+ self.rst_section_levels[multi_class + 2] * \
252-
(len(c) + 9) + '\n\n'
253-
ad += '\n.. autoclass:: ' + c + '\n'
248+
ad += (
249+
"\n:class:`"
250+
+ c
251+
+ "`\n"
252+
+ self.rst_section_levels[multi_class + 2] * (len(c) + 9)
253+
+ "\n\n"
254+
)
255+
ad += "\n.. autoclass:: " + c + "\n"
254256
# must NOT exclude from index to keep cross-refs working
255-
ad += ' :members:\n' \
256-
' :undoc-members:\n' \
257-
' :show-inheritance:\n' \
258-
' :inherited-members:\n' \
259-
'\n' \
260-
' .. automethod:: __init__\n'
257+
ad += (
258+
" :members:\n"
259+
" :undoc-members:\n"
260+
" :show-inheritance:\n"
261+
" :inherited-members:\n"
262+
"\n"
263+
" .. automethod:: __init__\n"
264+
)
261265
if multi_fx:
262-
ad += '\n' + 'Functions' + '\n' + \
263-
self.rst_section_levels[2] * 9 + '\n\n'
266+
ad += "\n" + "Functions" + "\n" + self.rst_section_levels[2] * 9 + "\n\n"
264267
elif len(functions) and multi_class:
265-
ad += '\n' + 'Function' + '\n' + \
266-
self.rst_section_levels[2] * 8 + '\n\n'
268+
ad += "\n" + "Function" + "\n" + self.rst_section_levels[2] * 8 + "\n\n"
267269
for f in functions:
268270
# must NOT exclude from index to keep cross-refs working
269-
ad += '\n.. autofunction:: ' + uri + '.' + f + '\n\n'
271+
ad += "\n.. autofunction:: " + uri + "." + f + "\n\n"
270272
return ad
271273

272274
def _survives_exclude(self, matchstr, match_type):
273-
''' Returns True if *matchstr* does not match patterns
275+
""" Returns True if *matchstr* does not match patterns
274276
275277
``self.package_name`` removed from front of string if present
276278
@@ -289,10 +291,10 @@ def _survives_exclude(self, matchstr, match_type):
289291
>>> dw.module_skip_patterns.append('^\\.badmod$')
290292
>>> dw._survives_exclude('sphinx.badmod', 'module')
291293
False
292-
'''
293-
if match_type == 'module':
294+
"""
295+
if match_type == "module":
294296
patterns = self.module_skip_patterns
295-
elif match_type == 'package':
297+
elif match_type == "package":
296298
patterns = self.package_skip_patterns
297299
else:
298300
raise ValueError('Cannot interpret match type "%s"' % match_type)
@@ -312,7 +314,7 @@ def _survives_exclude(self, matchstr, match_type):
312314
return True
313315

314316
def discover_modules(self):
315-
''' Return module sequence discovered from ``self.package_name``
317+
""" Return module sequence discovered from ``self.package_name``
316318
317319
318320
Parameters
@@ -334,25 +336,27 @@ def discover_modules(self):
334336
>>> 'sphinx.util' in dw.discover_modules()
335337
False
336338
>>>
337-
'''
339+
"""
338340
modules = []
339341
# raw directory parsing
340342
for dirpath, dirnames, filenames in os.walk(self.root_path):
341343
# Check directory names for packages
342344
root_uri = self._path2uri(os.path.join(self.root_path, dirpath))
343345
for dirname in dirnames[:]: # copy list - we modify inplace
344-
package_uri = '.'.join((root_uri, dirname))
345-
if (self._uri2path(package_uri)
346-
and self._survives_exclude(package_uri, 'package')):
346+
package_uri = ".".join((root_uri, dirname))
347+
if self._uri2path(package_uri) and self._survives_exclude(
348+
package_uri, "package"
349+
):
347350
modules.append(package_uri)
348351
else:
349352
dirnames.remove(dirname)
350353
# Check filenames for modules
351354
for filename in filenames:
352355
module_name = filename[:-3]
353-
module_uri = '.'.join((root_uri, module_name))
354-
if (self._uri2path(module_uri)
355-
and self._survives_exclude(module_uri, 'module')):
356+
module_uri = ".".join((root_uri, module_name))
357+
if self._uri2path(module_uri) and self._survives_exclude(
358+
module_uri, "module"
359+
):
356360
modules.append(module_uri)
357361
# print sorted(modules) #dbg
358362
return sorted(modules)
@@ -366,7 +370,7 @@ def write_modules_api(self, modules, outdir):
366370
continue
367371
# write out to file
368372
outfile = os.path.join(outdir, m + self.rst_extension)
369-
fileobj = open(outfile, 'wt')
373+
fileobj = open(outfile, "wt")
370374
fileobj.write(api_str)
371375
fileobj.close()
372376
written_modules.append(m)
@@ -395,7 +399,7 @@ def write_api_docs(self, outdir):
395399
modules = self.discover_modules()
396400
self.write_modules_api(modules, outdir)
397401

398-
def write_index(self, outdir, froot='gen', relative_to=None):
402+
def write_index(self, outdir, froot="gen", relative_to=None):
399403
"""Make a reST API index file from written files
400404
401405
Parameters
@@ -414,18 +418,18 @@ def write_index(self, outdir, froot='gen', relative_to=None):
414418
leave path as it is.
415419
"""
416420
if self.written_modules is None:
417-
raise ValueError('No modules written')
421+
raise ValueError("No modules written")
418422
# Get full filename path
419423
path = os.path.join(outdir, froot + self.rst_extension)
420424
# Path written into index is relative to rootpath
421425
if relative_to is not None:
422-
relpath = outdir.replace(relative_to + os.path.sep, '')
426+
relpath = outdir.replace(relative_to + os.path.sep, "")
423427
else:
424428
relpath = outdir
425-
idx = open(path, 'wt')
429+
idx = open(path, "wt")
426430
w = idx.write
427-
w('.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n')
428-
w('.. toctree::\n\n')
431+
w(".. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n")
432+
w(".. toctree::\n\n")
429433
for f in self.written_modules:
430-
w(' %s\n' % os.path.join(relpath, f))
434+
w(" %s\n" % os.path.join(relpath, f))
431435
idx.close()

0 commit comments

Comments
 (0)