Skip to content

Commit 7d2a466

Browse files
alexcjohnsonalexcjohnson
authored
Merge pull request #950 from jbampton/fix-docstrings
Attempt to standardize Python Docstrings to PEP 257.
2 parents 95e589e + a16e5c3 commit 7d2a466

23 files changed

+149
-195
lines changed

‎.pylintrc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -272,7 +272,7 @@ ignore-docstrings=yes
272272
ignore-imports=no
273273

274274
# Minimum lines number of a similarity.
275-
min-similarity-lines=4
275+
min-similarity-lines=10
276276

277277

278278
[SPELLING]

‎.pylintrc37

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -367,7 +367,7 @@ ignore-docstrings=yes
367367
ignore-imports=no
368368

369369
# Minimum lines number of a similarity.
370-
min-similarity-lines=4
370+
min-similarity-lines=10
371371

372372

373373
[SPELLING]

‎dash/_configs.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@ def load_dash_env_vars():
3838

3939

4040
def get_combined_config(name, val, default=None):
41-
'''consolidate the config with priority from high to low
42-
provided init value > OS environ > default
43-
'''
41+
"""Consolidate the config with priority from high to low provided init
42+
value > OS environ > default."""
43+
4444
if val is not None:
4545
return val
4646

‎dash/_utils.py

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,7 @@ def patch_collections_abc(member):
6060

6161

6262
class AttributeDict(dict):
63-
"""
64-
Dictionary subclass enabling attribute lookup/assignment of keys/values.
63+
"""Dictionary subclass enabling attribute lookup/assignment of keys/values.
6564
6665
For example::
6766
>>> m = AttributeDict({'foo': 'bar'})
@@ -95,7 +94,7 @@ def set_read_only(self, names, msg="Attribute is read-only"):
9594
object.__setattr__(self, "_read_only_msg", msg)
9695

9796
def finalize(self, msg="Object is final: No new keys may be added."):
98-
"""Prevent any new keys being set"""
97+
"""Prevent any new keys being set."""
9998
object.__setattr__(self, "_final", msg)
10099

101100
def __setitem__(self, key, val):

‎dash/dash.py

Lines changed: 13 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -87,8 +87,7 @@ class _NoUpdate(object):
8787
# pylint: disable=too-many-instance-attributes
8888
# pylint: disable=too-many-arguments, too-many-locals
8989
class Dash(object):
90-
"""
91-
Dash is a framework for building analytical web applications.
90+
"""Dash is a framework for building analytical web applications.
9291
No JavaScript required.
9392
9493
If a parameter can be set by an environment variable, that is listed as:
@@ -347,9 +346,7 @@ def __init__(
347346
self.init_app()
348347

349348
def init_app(self, app=None):
350-
"""
351-
Initialize the parts of Dash that require a flask app
352-
"""
349+
"""Initialize the parts of Dash that require a flask app."""
353350
config = self.config
354351

355352
if app is not None:
@@ -377,7 +374,7 @@ def init_app(self, app=None):
377374

378375
@self.server.errorhandler(exceptions.PreventUpdate)
379376
def _handle_error(_):
380-
"""Handle a halted callback and return an empty 204 response"""
377+
"""Handle a halted callback and return an empty 204 response."""
381378
return "", 204
382379

383380
prefix = config.routes_pathname_prefix
@@ -774,16 +771,14 @@ def interpolate_index(
774771
favicon="",
775772
renderer="",
776773
):
777-
"""
778-
Called to create the initial HTML string that is loaded on page.
774+
"""Called to create the initial HTML string that is loaded on page.
779775
Override this method to provide you own custom HTML.
780776
781777
:Example:
782778
783779
class MyDash(dash.Dash):
784780
def interpolate_index(self, **kwargs):
785-
return '''
786-
<!DOCTYPE html>
781+
return '''<!DOCTYPE html>
787782
<html>
788783
<head>
789784
<title>My App</title>
@@ -796,12 +791,10 @@ def interpolate_index(self, **kwargs):
796791
{renderer}
797792
<div id="custom-footer">My custom footer</div>
798793
</body>
799-
</html>
800-
'''.format(
801-
app_entry=kwargs.get('app_entry'),
802-
config=kwargs.get('config'),
803-
scripts=kwargs.get('scripts'),
804-
renderer=kwargs.get('renderer'))
794+
</html>'''.format(app_entry=kwargs.get('app_entry'),
795+
config=kwargs.get('config'),
796+
scripts=kwargs.get('scripts'),
797+
renderer=kwargs.get('renderer'))
805798
806799
:param metas: Collected & formatted meta tags.
807800
:param title: The title of the app.
@@ -1164,8 +1157,7 @@ def _validate_value(val, index=None):
11641157
def clientside_callback(
11651158
self, clientside_function, output, inputs=[], state=[]
11661159
):
1167-
"""
1168-
Create a callback that updates the output by calling a clientside
1160+
"""Create a callback that updates the output by calling a clientside
11691161
(JavaScript) function instead of a Python function.
11701162
11711163
Unlike `@app.calllback`, `clientside_callback` is not a decorator:
@@ -1518,9 +1510,8 @@ def enable_dev_tools(
15181510
dev_tools_silence_routes_logging=None,
15191511
dev_tools_prune_errors=None,
15201512
):
1521-
"""
1522-
Activate the dev tools, called by `run_server`. If your application is
1523-
served by wsgi and you want to activate the dev tools, you can call
1513+
"""Activate the dev tools, called by `run_server`. If your application
1514+
is served by wsgi and you want to activate the dev tools, you can call
15241515
this method out of `__main__`.
15251516
15261517
All parameters can be set by environment variables as listed.
@@ -1734,8 +1725,7 @@ def run_server(
17341725
dev_tools_prune_errors=None,
17351726
**flask_run_options
17361727
):
1737-
"""
1738-
Start the flask server in local mode, you should not run this on a
1728+
"""Start the flask server in local mode, you should not run this on a
17391729
production server, use gunicorn/waitress instead.
17401730
17411731
If a parameter can be set by an environment variable, that is listed

‎dash/development/_py_components_generation.py

Lines changed: 18 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,8 @@
1010

1111
# pylint: disable=unused-argument
1212
def generate_class_string(typename, props, description, namespace):
13-
"""
14-
Dynamically generate class strings to have nicely formatted docstrings,
15-
keyword arguments, and repr
13+
"""Dynamically generate class strings to have nicely formatted docstrings,
14+
keyword arguments, and repr.
1615
1716
Inspired by http://jameso.be/2013/08/06/namedtuple.html
1817
@@ -26,7 +25,6 @@ def generate_class_string(typename, props, description, namespace):
2625
Returns
2726
-------
2827
string
29-
3028
"""
3129
# TODO _prop_names, _type, _namespace, and available_properties
3230
# can be modified by a Dash JS developer via setattr
@@ -111,8 +109,7 @@ def __init__(self, {default_argtext}):
111109

112110

113111
def generate_class_file(typename, props, description, namespace):
114-
"""
115-
Generate a python class file (.py) given a class string
112+
"""Generate a python class file (.py) given a class string.
116113
117114
Parameters
118115
----------
@@ -123,7 +120,6 @@ def generate_class_file(typename, props, description, namespace):
123120
124121
Returns
125122
-------
126-
127123
"""
128124
import_string =\
129125
"# AUTO GENERATED FILE - DO NOT EDIT\n\n" + \
@@ -175,8 +171,7 @@ def generate_classes_files(project_shortname, metadata, *component_generators):
175171

176172

177173
def generate_class(typename, props, description, namespace):
178-
"""
179-
Generate a python class object given a class string
174+
"""Generate a python class object given a class string.
180175
181176
Parameters
182177
----------
@@ -187,7 +182,6 @@ def generate_class(typename, props, description, namespace):
187182
188183
Returns
189184
-------
190-
191185
"""
192186
string = generate_class_string(typename, props, description, namespace)
193187
scope = {'Component': Component, '_explicitize_args': _explicitize_args}
@@ -198,8 +192,7 @@ def generate_class(typename, props, description, namespace):
198192

199193

200194
def required_props(props):
201-
"""
202-
Pull names of required props from the props object
195+
"""Pull names of required props from the props object.
203196
204197
Parameters
205198
----------
@@ -215,8 +208,7 @@ def required_props(props):
215208

216209

217210
def create_docstring(component_name, props, description):
218-
"""
219-
Create the Dash component docstring
211+
"""Create the Dash component docstring.
220212
221213
Parameters
222214
----------
@@ -258,8 +250,8 @@ def create_docstring(component_name, props, description):
258250

259251

260252
def prohibit_events(props):
261-
"""
262-
Events have been removed. Raise an error if we see dashEvents or fireEvents
253+
"""Events have been removed. Raise an error if we see dashEvents or
254+
fireEvents.
263255
264256
Parameters
265257
----------
@@ -277,8 +269,7 @@ def prohibit_events(props):
277269

278270

279271
def parse_wildcards(props):
280-
"""
281-
Pull out the wildcard attributes from the Component props
272+
"""Pull out the wildcard attributes from the Component props.
282273
283274
Parameters
284275
----------
@@ -298,9 +289,8 @@ def parse_wildcards(props):
298289

299290

300291
def reorder_props(props):
301-
"""
302-
If "children" is in props, then move it to the
303-
front to respect dash convention
292+
"""If "children" is in props, then move it to the front to respect dash
293+
convention.
304294
305295
Parameters
306296
----------
@@ -322,8 +312,8 @@ def reorder_props(props):
322312

323313

324314
def filter_props(props):
325-
"""
326-
Filter props from the Component arguments to exclude:
315+
"""Filter props from the Component arguments to exclude:
316+
327317
- Those without a "type" or a "flowType" field
328318
- Those with arg.type.name in {'func', 'symbol', 'instanceOf'}
329319
@@ -397,8 +387,7 @@ def filter_props(props):
397387
# pylint: disable=too-many-arguments
398388
def create_prop_docstring(prop_name, type_object, required, description,
399389
default, indent_num, is_flow_type=False):
400-
"""
401-
Create the Dash component prop docstring
390+
"""Create the Dash component prop docstring.
402391
403392
Parameters
404393
----------
@@ -469,7 +458,7 @@ def create_prop_docstring(prop_name, type_object, required, description,
469458

470459

471460
def map_js_to_py_types_prop_types(type_object):
472-
"""Mapping from the PropTypes js type object to the Python type"""
461+
"""Mapping from the PropTypes js type object to the Python type."""
473462

474463
def shape_or_exact():
475464
return 'dict containing keys {}.\n{}'.format(
@@ -515,7 +504,7 @@ def shape_or_exact():
515504

516505
# React's PropTypes.arrayOf
517506
arrayOf=lambda: (
518-
"list" + ((" of {}").format(
507+
"list" + (" of {}".format(
519508
js_to_py_type(type_object["value"]) + 's'
520509
if js_to_py_type(type_object["value"]).split(' ')[0] != 'dict'
521510
else js_to_py_type(type_object["value"]).replace(
@@ -540,7 +529,7 @@ def shape_or_exact():
540529

541530

542531
def map_js_to_py_types_flow_types(type_object):
543-
"""Mapping from the Flow js types to the Python type"""
532+
"""Mapping from the Flow js types to the Python type."""
544533

545534
return dict(
546535
array=lambda: 'list',
@@ -587,8 +576,7 @@ def map_js_to_py_types_flow_types(type_object):
587576

588577

589578
def js_to_py_type(type_object, is_flow_type=False, indent_num=0):
590-
"""
591-
Convert JS types to Python types for the component definition
579+
"""Convert JS types to Python types for the component definition.
592580
593581
Parameters
594582
----------

0 commit comments

Comments
 (0)