From ac54d6378238d365cc937d6c2fc3358be6669e21 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Tue, 19 Jun 2012 16:34:16 +0000 Subject: [PATCH] Fixed some documentation issues with the Python Flame classes Docstrings for undocumented methods of child classes are automatically copied from the corresponding method of the parent class. This works both for docstrings as shown in the Python interpreter as well as the Sphinx-generated documentation. Removed manually duplicated docstrings from setProfile(), solve() and setRefineCriteria() methods. --- .../python/Cantera/OneD/BurnerDiffFlame.py | 5 ++- interfaces/python/Cantera/OneD/BurnerFlame.py | 5 ++- .../python/Cantera/OneD/CounterFlame.py | 35 ++---------------- interfaces/python/Cantera/OneD/FreeFlame.py | 5 ++- .../python/Cantera/OneD/StagnationFlow.py | 36 ++----------------- interfaces/python/Cantera/__init__.py | 15 ++++++++ 6 files changed, 25 insertions(+), 76 deletions(-) diff --git a/interfaces/python/Cantera/OneD/BurnerDiffFlame.py b/interfaces/python/Cantera/OneD/BurnerDiffFlame.py index 4418a3a22..9107ccdec 100644 --- a/interfaces/python/Cantera/OneD/BurnerDiffFlame.py +++ b/interfaces/python/Cantera/OneD/BurnerDiffFlame.py @@ -73,20 +73,17 @@ class BurnerDiffFlame(Stack): def solve(self, loglevel = 1, refine_grid = 1): - """Solve the flame. :meth:`.Stack.solve`""" if not self._initialized: self.init() Stack.solve(self, loglevel = loglevel, refine_grid = refine_grid) def setRefineCriteria(self, ratio = 10.0, slope = 0.8, curve = 0.8, prune = 0.0): - """See :meth:`.Stack.setRefineCriteria`""" Stack.setRefineCriteria(self, domain = self.flame, ratio = ratio, slope = slope, curve = curve, prune = prune) def setProfile(self, component, locs, vals): - """Set a profile in the flame""" self._initialized = 1 Stack.setProfile(self, self.flame, component, locs, vals) @@ -134,3 +131,5 @@ class BurnerDiffFlame(Stack): nm = self.gas.speciesName(n) y[n] = self.solution(nm, j) self.gas.setState_TPY(self.T(j), self.pressure, y) + +fix_docs(BurnerDiffFlame) diff --git a/interfaces/python/Cantera/OneD/BurnerFlame.py b/interfaces/python/Cantera/OneD/BurnerFlame.py index 3be575bcc..43007acf4 100644 --- a/interfaces/python/Cantera/OneD/BurnerFlame.py +++ b/interfaces/python/Cantera/OneD/BurnerFlame.py @@ -73,20 +73,17 @@ class BurnerFlame(Stack): def solve(self, loglevel = 1, refine_grid = 1): - """Solve the flame. See :meth:`.Stack.solve`""" if not self._initialized: self.init() Stack.solve(self, loglevel = loglevel, refine_grid = refine_grid) def setRefineCriteria(self, ratio = 10.0, slope = 0.8, curve = 0.8, prune = 0.0): - """See :meth:`.Stack.setRefineCriteria`""" Stack.setRefineCriteria(self, domain = self.flame, ratio = ratio, slope = slope, curve = curve, prune = prune) def setProfile(self, component, locs, vals): - """Set a profile in the flame""" self._initialized = 1 Stack.setProfile(self, self.flame, component, locs, vals) @@ -134,3 +131,5 @@ class BurnerFlame(Stack): nm = self.gas.speciesName(n) y[n] = self.solution(nm, j) self.gas.setState_TPY(self.T(j), self.pressure, y) + +fix_docs(BurnerFlame) diff --git a/interfaces/python/Cantera/OneD/CounterFlame.py b/interfaces/python/Cantera/OneD/CounterFlame.py index 4c9d328f7..3c459f48b 100644 --- a/interfaces/python/Cantera/OneD/CounterFlame.py +++ b/interfaces/python/Cantera/OneD/CounterFlame.py @@ -152,50 +152,17 @@ class CounterFlame(Stack): def solve(self, loglevel = 1, refine_grid = 1): - """Solve the flame. - - :param loglevel: - integer flag controlling the amount of diagnostic output. Zero - suppresses all output, and 5 produces very verbose output. Default: 1 - :param refine_grid: - if non-zero, enable grid refinement. - """ - if not self._initialized: self.init() Stack.solve(self, loglevel = loglevel, refine_grid = refine_grid) def setRefineCriteria(self, ratio = 10.0, slope = 0.8, curve = 0.8, prune = 0.0): - """ - Set the criteria used to refine the flame. - - :param ratio: - additional points will be added if the ratio of the spacing - on either side of a grid point exceeds this value - :param slope: - maximum difference in value between two adjacent points, - scaled by the maximum difference in the profile - (0.0 < slope < 1.0). Adds points in regions of high slope. - :param curve: - maximum difference in slope between two adjacent intervals, scaled - by the maximum difference in the profile (0.0 < curve < 1.0). Adds - points in regions of high curvature. - :param prune: - if the slope or curve criteria are satisfied to the level of - 'prune', the grid point is assumed not to be needed and is removed. - Set prune significantly smaller than 'slope' and 'curve'. Set to - zero to disable pruning the grid. - - >>> f.setRefineCriteria(ratio = 5.0, slope = 0.2, curve = 0.3, - ... prune = 0.03) - """ Stack.setRefineCriteria(self, domain = self.flame, ratio = ratio, slope = slope, curve = curve, prune = prune) def setProfile(self, component, locs, vals): - """Set a profile in the flame""" self._initialized = 1 Stack.setProfile(self, self.flame, component, locs, vals) @@ -245,3 +212,5 @@ class CounterFlame(Stack): nm = self.gas.speciesName(n) y[n] = self.solution(nm, j) self.gas.setState_TPY(self.T(j), self.pressure, y) + +fix_docs(CounterFlame) diff --git a/interfaces/python/Cantera/OneD/FreeFlame.py b/interfaces/python/Cantera/OneD/FreeFlame.py index 238311fb4..bc96558b0 100644 --- a/interfaces/python/Cantera/OneD/FreeFlame.py +++ b/interfaces/python/Cantera/OneD/FreeFlame.py @@ -69,14 +69,12 @@ class FreeFlame(Stack): def solve(self, loglevel = 1, refine_grid = 1): - """Solve the flame. See :meth:`.Stack.solve`""" if not self._initialized: self.init() Stack.solve(self, loglevel = loglevel, refine_grid = refine_grid) def setRefineCriteria(self, ratio = 10.0, slope = 0.8, curve = 0.8, prune = 0.0): - """See :meth:`.Stack.setRefineCriteria`""" Stack.setRefineCriteria(self, domain = self.flame, ratio = ratio, slope = slope, curve = curve, prune = prune) @@ -85,7 +83,6 @@ class FreeFlame(Stack): _cantera.sim1D_setFixedTemperature(self._hndl, temp) def setProfile(self, component, locs, vals): - """Set a profile in the flame""" self._initialized = 1 Stack.setProfile(self, self.flame, component, locs, vals) @@ -132,3 +129,5 @@ class FreeFlame(Stack): nm = self.gas.speciesName(n) y[n] = self.solution(nm, j) self.gas.setState_TPY(self.T(j), self.pressure, y) + +fix_docs(FreeFlame) diff --git a/interfaces/python/Cantera/OneD/StagnationFlow.py b/interfaces/python/Cantera/OneD/StagnationFlow.py index 96f3158fa..5e0f38624 100644 --- a/interfaces/python/Cantera/OneD/StagnationFlow.py +++ b/interfaces/python/Cantera/OneD/StagnationFlow.py @@ -76,51 +76,17 @@ class StagnationFlow(Stack): def solve(self, loglevel = 1, refine_grid = 1): - """Solve the flame. - - :param loglevel: - integer flag controlling the amount of diagnostic output. - Zero suppresses all output, and 5 produces very verbose output. - Default: 1 - :param refine_grid: - if non-zero, enable grid refinement. - """ - if not self._initialized: self.init() Stack.solve(self, loglevel = loglevel, refine_grid = refine_grid) def setRefineCriteria(self, ratio = 10.0, slope = 0.8, curve = 0.8, prune = 0.0): - """ - Set the criteria used to refine the flame. - - :param ratio: - additional points will be added if the ratio of the spacing - on either side of a grid point exceeds this value - :param slope: - maximum difference in value between two adjacent points, scaled by - the maximum difference in the profile (0.0 < slope < 1.0). Adds - points in regions of high slope. - :param curve: - maximum difference in slope between two adjacent intervals, scaled - by the maximum difference in the profile (0.0 < curve < 1.0). Adds - points in regions of high curvature. - :param prune: - if the slope or curve criteria are satisfied to the level of - 'prune', the grid point is assumed not to be needed and is removed. - Set prune significantly smaller than 'slope' and 'curve'. Set to - zero to disable pruning the grid. - - >>> f.setRefineCriteria(ratio = 5.0, slope = 0.2, curve = 0.3, - ... prune = 0.03) - """ Stack.setRefineCriteria(self, domain = self.flow, ratio = ratio, slope = slope, curve = curve, prune = prune) def setProfile(self, component, locs, vals): - """Set a profile in the flame""" self._initialized = 1 Stack.setProfile(self, self.flow, component, locs, vals) @@ -179,3 +145,5 @@ class StagnationFlow(Stack): nm = self.gas.speciesName(n) y[n] = self.solution(nm, j) self.gas.setState_TPY(self.T(j), self.pressure, y) + +fix_docs(StagnationFlow) diff --git a/interfaces/python/Cantera/__init__.py b/interfaces/python/Cantera/__init__.py index 51575c607..46be418fd 100755 --- a/interfaces/python/Cantera/__init__.py +++ b/interfaces/python/Cantera/__init__.py @@ -68,6 +68,21 @@ def reset(): starting a fresh session.""" _cantera.ct_appdelete() +def fix_docs(cls): + """ + Inherit method docstrings from parent class if none is specified on the + child. Usable as a decorator in Python >= 2.6. + """ + for name, func in vars(cls).items(): + if not func.__doc__: + for parent in cls.__bases__: + parfunc = getattr(parent, name) + if parfunc and getattr(parfunc, '__doc__', None): + func.__doc__ = parfunc.__doc__ + break + return cls + + # workaround for case problems in CVS repository file Mixture.py. On some # systems it appears as mixture.py, and on others as Mixture.py try: