From 1f0258e9f72de3534bf7d427d69f034d5c6d31f0 Mon Sep 17 00:00:00 2001 From: Alexandre Duret-Lutz Date: Sun, 4 Oct 2015 12:17:06 +0200 Subject: [PATCH] python: docstrings cleanup * wrap/python/spot.py: Better docstrings. * wrap/python/tests/formulas.ipynb: Update. --- wrap/python/spot.py | 70 ++++++++++++++++++++------------ wrap/python/tests/formulas.ipynb | 12 ++++-- 2 files changed, 53 insertions(+), 29 deletions(-) diff --git a/wrap/python/spot.py b/wrap/python/spot.py index 8cea0e7ac..001024720 100644 --- a/wrap/python/spot.py +++ b/wrap/python/spot.py @@ -26,21 +26,24 @@ from functools import lru_cache def setup(**kwargs): """Configure Spot for fancy display. - This is manly useful in IPython. + This is manly useful in Jupyter/IPython. Note that this function needs to be called before any automaton is displayed. Afterwards it will have no effect (you should restart - Python, or the IPython Kernel). + Python, or the Jupyter/IPython Kernel). - Keywords arguments: - bullets -- a Boolean indicating whether to display acceptance conditions - as UTF8 bullets (default: True) - fillcolor -- a string indicating the color to use for states - (default: '#ffffaa') - size -- a string giving the width and height of the GraphViz output - in inches (default: '10.2,5') - font -- the name of the font to use in the GraphViz output - (default: 'Lato') + Parameters + ---------- + bullets : bool + whether to display acceptance conditions as UTF8 bullets + (default: True) + fillcolor : str + the color to use for states (default: '#ffffaa') + size : str + the width and height of the GraphViz output in inches + (default: '10.2,5') + font : str + the font to use in the GraphViz output (default: 'Lato') """ import os @@ -145,12 +148,16 @@ def _formula_to_str(self, format='spot', parenth=False): def _formula_format(self, spec): - """Format the formula according to spec. + """Format the formula according to `spec`. - 'spec' should be a list of letters that select - how the formula should be formatted. + Parameters + ---------- + spec : str, optional + a list of letters that specify how the formula + should be formatted. - Use one of the following letters to select the syntax: + Supported specifiers + -------------------- - 'f': use Spot's syntax (default) - '8': use Spot's syntax in UTF-8 mode @@ -175,6 +182,7 @@ def _formula_format(self, spec): - ':spec': pass the remaining specification to the formating function for strings. + """ syntax = 'f' @@ -282,15 +290,20 @@ twa.save = _twa_save def automata(*filenames): - """Read automata from a list of filenames. + """Read automata from a list of sources. - The automata can be written in the - [HOA format](http://adl.github.io/hoaf/), as - [never claims](http://spinroot.com/spin/Man/never.html), - in [LBTT's format] - (http://www.tcs.hut.fi/Software/lbtt/doc/html/Format-for-automata.html), - or in [ltl2dstar's - format](http://www.ltl2dstar.de/docs/ltl2dstar.html#output-format-dstar) + These sources can be either filenames, commands, or some + textual represantations of automata. + + The automata can be written in the `HOA format`_, as `never + claims`_, in `LBTT's format`_, or in `ltl2dstar's format`_. + + .. _HOA format: http://adl.github.io/hoaf/ + .. _never claims: http://spinroot.com/spin/Man/never.html + .. _LBTT's format: + http://www.tcs.hut.fi/Software/lbtt/doc/html/Format-for-automata.html + .. _ltl2dstar's format: + http://www.ltl2dstar.de/docs/ltl2dstar.html#output-format-dstar If an argument ends with a `|`, then this argument is interpreted as a shell command, and the output of that command (without the `|`) @@ -300,6 +313,13 @@ def automata(*filenames): actual contents to be parsed. Otherwise, the argument is assumed to be a filename. + + The result of this function is a generator on all the automata + objects read from these sources. The typical usage is:: + + for aut in spot.automata(filename): + # do something with aut + """ for filename in filenames: @@ -347,7 +367,7 @@ def automata(*filenames): def automaton(filename): """Read a single automaton from a file. - See `spot.automata()` for a list of supported formats.""" + See `spot.automata` for a list of supported formats.""" try: return next(automata(filename)) except StopIteration: @@ -370,7 +390,7 @@ def translate(formula, *args): - any combination of 'Complete', 'Unambiguous', and 'StateBasedAcceptance' (or 'SBAcc' for short) - The default correspond to 'tgba', 'small' and 'high'. + The default corresponds to 'tgba', 'small' and 'high'. """ type_ = None diff --git a/wrap/python/tests/formulas.ipynb b/wrap/python/tests/formulas.ipynb index 8199091a6..de9d04831 100644 --- a/wrap/python/tests/formulas.ipynb +++ b/wrap/python/tests/formulas.ipynb @@ -246,12 +246,16 @@ "Help on function _formula_format in module spot:\n", "\n", "_formula_format(self, spec)\n", - " Format the formula according to spec.\n", + " Format the formula according to `spec`.\n", " \n", - " 'spec' should be a list of letters that select\n", - " how the formula should be formatted.\n", + " Parameters\n", + " ----------\n", + " spec : str, optional\n", + " a list of letters that specify how the formula\n", + " should be formatted.\n", " \n", - " Use one of the following letters to select the syntax:\n", + " Supported specifiers\n", + " --------------------\n", " \n", " - 'f': use Spot's syntax (default)\n", " - '8': use Spot's syntax in UTF-8 mode\n",