diff options
author | Ben Reynwar <ben@reynwar.net> | 2012-08-14 10:28:23 -0700 |
---|---|---|
committer | Ben Reynwar <ben@reynwar.net> | 2012-08-14 10:28:23 -0700 |
commit | fc4d37062c46886d3bc1fb0b6c3626d779be4ecd (patch) | |
tree | e69367ce9284b7a91c31899f66d129d2a9bccae6 /grc/python | |
parent | 3e46aef392ba9b2e63bbfefefdb7178cc87049ab (diff) |
docs: Modified argument formating in python docstrings in grc.
Diffstat (limited to 'grc/python')
-rw-r--r-- | grc/python/Block.py | 26 | ||||
-rw-r--r-- | grc/python/FlowGraph.py | 48 | ||||
-rw-r--r-- | grc/python/Generator.py | 14 | ||||
-rw-r--r-- | grc/python/Param.py | 28 | ||||
-rw-r--r-- | grc/python/Port.py | 20 | ||||
-rw-r--r-- | grc/python/expr_utils.py | 56 | ||||
-rw-r--r-- | grc/python/extract_docs.py | 16 |
7 files changed, 151 insertions, 57 deletions
diff --git a/grc/python/Block.py b/grc/python/Block.py index 2c334dfc2c..806de46724 100644 --- a/grc/python/Block.py +++ b/grc/python/Block.py @@ -34,9 +34,13 @@ class Block(_Block, _GUIBlock): def __init__(self, flow_graph, n): """ Make a new block from nested data. - @param flow graph the parent element - @param n the nested odict - @return block a new block + + Args: + flow: graph the parent element + n: the nested odict + + Returns: + block a new block """ #grab the data self._doc = n.find('doc') or '' @@ -128,8 +132,12 @@ class Block(_Block, _GUIBlock): def port_controller_modify(self, direction): """ Change the port controller. - @param direction +1 or -1 - @return true for change + + Args: + direction: +1 or -1 + + Returns: + true for change """ changed = False #concat the nports string from the private nports settings of all ports @@ -161,7 +169,9 @@ class Block(_Block, _GUIBlock): Split each import statement at newlines. Combine all import statments into a list. Filter empty imports. - @return a list of import statements + + Returns: + a list of import statements """ return filter(lambda i: i, sum(map(lambda i: self.resolve_dependencies(i).split('\n'), self._imports), [])) @@ -171,7 +181,9 @@ class Block(_Block, _GUIBlock): def get_callbacks(self): """ Get a list of function callbacks for this block. - @return a list of strings + + Returns: + a list of strings """ def make_callback(callback): callback = self.resolve_dependencies(callback) diff --git a/grc/python/FlowGraph.py b/grc/python/FlowGraph.py index 89a169355b..9d48401ea0 100644 --- a/grc/python/FlowGraph.py +++ b/grc/python/FlowGraph.py @@ -35,10 +35,14 @@ class FlowGraph(_FlowGraph, _GUIFlowGraph): def _eval(self, code, namespace, namespace_hash): """ Evaluate the code with the given namespace. - @param code a string with python code - @param namespace a dict representing the namespace - @param namespace_hash a unique hash for the namespace - @return the resultant object + + Args: + code: a string with python code + namespace: a dict representing the namespace + namespace_hash: a unique hash for the namespace + + Returns: + the resultant object """ if not code: raise Exception, 'Cannot evaluate empty statement.' my_hash = hash(code) ^ namespace_hash @@ -51,8 +55,12 @@ class FlowGraph(_FlowGraph, _GUIFlowGraph): def get_io_signaturev(self, direction): """ Get a list of io signatures for this flow graph. - @param direction a string of 'in' or 'out' - @return a list of dicts with: type, label, vlen, size + + Args: + direction: a string of 'in' or 'out' + + Returns: + a list of dicts with: type, label, vlen, size """ sorted_pads = { 'in': self.get_pad_sources(), @@ -69,7 +77,9 @@ class FlowGraph(_FlowGraph, _GUIFlowGraph): def get_pad_sources(self): """ Get a list of pad source blocks sorted by id order. - @return a list of pad source blocks in this flow graph + + Returns: + a list of pad source blocks in this flow graph """ pads = filter(lambda b: b.get_key() == 'pad_source', self.get_enabled_blocks()) return sorted(pads, lambda x, y: cmp(x.get_id(), y.get_id())) @@ -77,7 +87,9 @@ class FlowGraph(_FlowGraph, _GUIFlowGraph): def get_pad_sinks(self): """ Get a list of pad sink blocks sorted by id order. - @return a list of pad sink blocks in this flow graph + + Returns: + a list of pad sink blocks in this flow graph """ pads = filter(lambda b: b.get_key() == 'pad_sink', self.get_enabled_blocks()) return sorted(pads, lambda x, y: cmp(x.get_id(), y.get_id())) @@ -85,7 +97,9 @@ class FlowGraph(_FlowGraph, _GUIFlowGraph): def get_imports(self): """ Get a set of all import statments in this flow graph namespace. - @return a set of import statements + + Returns: + a set of import statements """ imports = sum([block.get_imports() for block in self.get_enabled_blocks()], []) imports = sorted(set(imports)) @@ -95,7 +109,9 @@ class FlowGraph(_FlowGraph, _GUIFlowGraph): """ Get a list of all variables in this flow graph namespace. Exclude paramterized variables. - @return a sorted list of variable blocks in order of dependency (indep -> dep) + + Returns: + a sorted list of variable blocks in order of dependency (indep -> dep) """ variables = filter(lambda b: _variable_matcher.match(b.get_key()), self.get_enabled_blocks()) return expr_utils.sort_objects(variables, lambda v: v.get_id(), lambda v: v.get_var_make()) @@ -103,7 +119,9 @@ class FlowGraph(_FlowGraph, _GUIFlowGraph): def get_parameters(self): """ Get a list of all paramterized variables in this flow graph namespace. - @return a list of paramterized variables + + Returns: + a list of paramterized variables """ parameters = filter(lambda b: _parameter_matcher.match(b.get_key()), self.get_enabled_blocks()) return parameters @@ -118,9 +136,13 @@ class FlowGraph(_FlowGraph, _GUIFlowGraph): def evaluate(self, expr): """ Evaluate the expression. - @param expr the string expression + + Args: + expr: the string expression @throw Exception bad expression - @return the evaluated data + + Returns: + the evaluated data """ if self._renew_eval_ns: self._renew_eval_ns = False diff --git a/grc/python/Generator.py b/grc/python/Generator.py index 2a6fe51d5d..f8490227a7 100644 --- a/grc/python/Generator.py +++ b/grc/python/Generator.py @@ -35,8 +35,10 @@ class Generator(object): """ Initialize the generator object. Determine the file to generate. - @param flow_graph the flow graph object - @param file_path the path to write the file to + + Args: + flow_graph: the flow graph object + file_path: the path to write the file to """ self._flow_graph = flow_graph self._generate_options = self._flow_graph.get_option('generate_options') @@ -72,7 +74,9 @@ Add a Misc->Throttle block to your flow graph to avoid CPU congestion.''') def get_popen(self): """ Execute this python flow graph. - @return a popen object + + Returns: + a popen object """ #extract the path to the python executable python_exe = sys.executable @@ -95,7 +99,9 @@ Add a Misc->Throttle block to your flow graph to avoid CPU congestion.''') def __str__(self): """ Convert the flow graph to python code. - @return a string of python code + + Returns: + a string of python code """ title = self._flow_graph.get_option('title') or self._flow_graph.get_option('id').replace('_', ' ').title() imports = self._flow_graph.get_imports() diff --git a/grc/python/Param.py b/grc/python/Param.py index 2caca48024..b310468842 100644 --- a/grc/python/Param.py +++ b/grc/python/Param.py @@ -106,7 +106,9 @@ class Param(_Param, _GUIParam): def __repr__(self): """ Get the repr (nice string format) for this param. - @return the string representation + + Returns: + the string representation """ ################################################## # truncate helper method @@ -167,7 +169,9 @@ class Param(_Param, _GUIParam): def get_color(self): """ Get the color that represents this param's type. - @return a hex color code. + + Returns: + a hex color code. """ try: return { @@ -198,7 +202,9 @@ class Param(_Param, _GUIParam): If the parameter controls a port type, vlen, or nports, return part. If the parameter is an empty grid position, return part. These parameters are redundant to display in the flow graph view. - @return hide the hide property string + + Returns: + hide the hide property string """ hide = _Param.get_hide(self) if hide: return hide @@ -234,7 +240,9 @@ class Param(_Param, _GUIParam): def evaluate(self): """ Evaluate the value. - @return evaluated type + + Returns: + evaluated type """ self._init = True self._lisitify_flag = False @@ -435,7 +443,9 @@ class Param(_Param, _GUIParam): Convert the value to code. For string and list types, check the init flag, call evaluate(). This ensures that evaluate() was called to set the xxxify_flags. - @return a string representing the code + + Returns: + a string representing the code """ v = self.get_value() t = self.get_type() @@ -452,7 +462,11 @@ class Param(_Param, _GUIParam): def get_all_params(self, type): """ Get all the params from the flowgraph that have the given type. - @param type the specified type - @return a list of params + + Args: + type: the specified type + + Returns: + a list of params """ return sum([filter(lambda p: p.get_type() == type, block.get_params()) for block in self.get_parent().get_parent().get_enabled_blocks()], []) diff --git a/grc/python/Port.py b/grc/python/Port.py index 9f8b50d052..0e7051c7c0 100644 --- a/grc/python/Port.py +++ b/grc/python/Port.py @@ -84,9 +84,11 @@ class Port(_Port, _GUIPort): def __init__(self, block, n, dir): """ Make a new port from nested data. - @param block the parent element - @param n the nested odict - @param dir the direction + + Args: + block: the parent element + n: the nested odict + dir: the direction """ self._n = n if n['type'] == 'msg': n['key'] = 'msg' @@ -163,7 +165,9 @@ class Port(_Port, _GUIPort): """ Get the vector length. If the evaluation of vlen cannot be cast to an integer, return 1. - @return the vector length or 1 + + Returns: + the vector length or 1 """ vlen = self.get_parent().resolve_dependencies(self._vlen) try: return int(self.get_parent().get_parent().evaluate(vlen)) @@ -174,7 +178,9 @@ class Port(_Port, _GUIPort): Get the number of ports. If already blank, return a blank If the evaluation of nports cannot be cast to an integer, return 1. - @return the number of ports or 1 + + Returns: + the number of ports or 1 """ nports = self.get_parent().resolve_dependencies(self._nports) #return blank if nports is blank @@ -190,7 +196,9 @@ class Port(_Port, _GUIPort): """ Get the color that represents this port's type. Codes differ for ports where the vec length is 1 or greater than 1. - @return a hex color code. + + Returns: + a hex color code. """ try: color = Constants.TYPE_TO_COLOR[self.get_type()] diff --git a/grc/python/expr_utils.py b/grc/python/expr_utils.py index a2e56eedf9..67580f6ffc 100644 --- a/grc/python/expr_utils.py +++ b/grc/python/expr_utils.py @@ -54,8 +54,12 @@ def expr_split(expr): Split up an expression by non alphanumeric characters, including underscore. Leave strings in-tact. #TODO ignore escaped quotes, use raw strings. - @param expr an expression string - @return a list of string tokens that form expr + + Args: + expr: an expression string + + Returns: + a list of string tokens that form expr """ toks = list() tok = '' @@ -78,9 +82,13 @@ def expr_split(expr): def expr_replace(expr, replace_dict): """ Search for vars in the expression and add the prepend. - @param expr an expression string - @param replace_dict a dict of find:replace - @return a new expression with the prepend + + Args: + expr: an expression string + replace_dict: a dict of find:replace + + Returns: + a new expression with the prepend """ expr_splits = expr_split(expr) for i, es in enumerate(expr_splits): @@ -91,9 +99,13 @@ def expr_replace(expr, replace_dict): def get_variable_dependencies(expr, vars): """ Return a set of variables used in this expression. - @param expr an expression string - @param vars a list of variable names - @return a subset of vars used in the expression + + Args: + expr: an expression string + vars: a list of variable names + + Returns: + a subset of vars used in the expression """ expr_toks = expr_split(expr) return set(filter(lambda v: v in expr_toks, vars)) @@ -101,8 +113,12 @@ def get_variable_dependencies(expr, vars): def get_graph(exprs): """ Get a graph representing the variable dependencies - @param exprs a mapping of variable name to expression - @return a graph of variable deps + + Args: + exprs: a mapping of variable name to expression + + Returns: + a graph of variable deps """ vars = exprs.keys() #get dependencies for each expression, load into graph @@ -116,8 +132,12 @@ def get_graph(exprs): def sort_variables(exprs): """ Get a list of variables in order of dependencies. - @param exprs a mapping of variable name to expression - @return a list of variable names + + Args: + exprs: a mapping of variable name to expression + + Returns: + a list of variable names @throws Exception circular dependencies """ var_graph = get_graph(exprs) @@ -136,10 +156,14 @@ def sort_variables(exprs): def sort_objects(objects, get_id, get_expr): """ Sort a list of objects according to their expressions. - @param objects the list of objects to sort - @param get_id the function to extract an id from the object - @param get_expr the function to extract an expression from the object - @return a list of sorted objects + + Args: + objects: the list of objects to sort + get_id: the function to extract an id from the object + get_expr: the function to extract an expression from the object + + Returns: + a list of sorted objects """ id2obj = dict([(get_id(obj), obj) for obj in objects]) #map obj id to expression code diff --git a/grc/python/extract_docs.py b/grc/python/extract_docs.py index a7e945c373..8c151b6e1a 100644 --- a/grc/python/extract_docs.py +++ b/grc/python/extract_docs.py @@ -23,8 +23,12 @@ def _extract(key): """ Extract the documentation from the python __doc__ strings. If multiple modules match, combine the docs. - @param key the block key - @return a string with documentation + + Args: + key: the block key + + Returns: + a string with documentation """ #extract matches try: @@ -48,8 +52,12 @@ _docs_cache = dict() def extract(key): """ Call the private extract and cache the result. - @param key the block key - @return a string with documentation + + Args: + key: the block key + + Returns: + a string with documentation """ if not _docs_cache.has_key(key): _docs_cache[key] = _extract(key) |