Vega strike Python Modules doc  0.5.1
Documentation of the " Modules " folder of Vega strike
 All Data Structures Namespaces Files Functions Variables
Public Member Functions | Data Fields
Tester Class Reference

Public Member Functions

def __init__
 
def runstring
 
def rundoc
 
def rundict
 
def run__test__
 
def summarize
 
def merge
 

Data Fields

 globs
 
 verbose
 
 isprivate
 
 name2ft
 
 compileflags
 

Detailed Description

Class Tester -- runs docstring examples and accumulates stats.

In normal use, function doctest.testmod() hides all this from you,
so use that if you can.  Create your own instances of Tester to do
fancier things.

Methods:
runstring(s, name)
    Search string s for examples to run; use name for logging.
    Return (#failures, #tries).

rundoc(object, name=None)
    Search object.__doc__ for examples to run; use name (or
    object.__name__) for logging.  Return (#failures, #tries).

rundict(d, name, module=None)
    Search for examples in docstrings in all of d.values(); use name
    for logging.  Exclude functions and classes not defined in module
    if specified.  Return (#failures, #tries).

run__test__(d, name)
    Treat dict d like module.__test__.  Return (#failures, #tries).

summarize(verbose=None)
    Display summary of testing results, to stdout.  Return
    (#failures, #tries).

merge(other)
    Merge in the test results from Tester instance "other".

>>> from doctest import Tester
>>> t = Tester(globs={'x': 42}, verbose=0)
>>> t.runstring(r'''
...      >>> x = x * 2
...      >>> print x
...      42
... ''', 'XYZ')
*****************************************************************
Failure in example: print x
from line #2 of XYZ
Expected: 42
Got: 84
(1, 2)
>>> t.runstring(">>> x = x * 2\\n>>> print x\\n84\\n", 'example2')
(0, 2)
>>> t.summarize()
*****************************************************************
1 items had failures:
   1 of   2 in XYZ
***Test Failed*** 1 failures.
(1, 4)
>>> t.summarize(verbose=1)
1 items passed all tests:
   2 tests in example2
*****************************************************************
1 items had failures:
   1 of   2 in XYZ
4 tests in 2 items.
3 passed and 1 failed.
***Test Failed*** 1 failures.
(1, 4)
>>>

Definition at line 570 of file doctest.py.

Constructor & Destructor Documentation

def __init__ (   self,
  mod = None,
  globs = None,
  verbose = None,
  isprivate = None 
) 
mod=None, globs=None, verbose=None, isprivate=None

See doctest.__doc__ for an overview.

Optional keyword arg "mod" is a module, whose globals are used for
executing examples.  If not specified, globs must be specified.

Optional keyword arg "globs" gives a dict to be used as the globals
when executing examples; if not specified, use the globals from
module mod.

In either case, a copy of the dict is used for each docstring
examined.

Optional keyword arg "verbose" prints lots of stuff if true, only
failures if false; by default, it's true iff "-v" is in sys.argv.

Optional keyword arg "isprivate" specifies a function used to determine
whether a name is private.  The default function is doctest.is_private;
see its docs for details.

Definition at line 636 of file doctest.py.

636 
637  isprivate=None):
638  """mod=None, globs=None, verbose=None, isprivate=None
639 
640 See doctest.__doc__ for an overview.
641 
642 Optional keyword arg "mod" is a module, whose globals are used for
643 executing examples. If not specified, globs must be specified.
644 
645 Optional keyword arg "globs" gives a dict to be used as the globals
646 when executing examples; if not specified, use the globals from
647 module mod.
648 
649 In either case, a copy of the dict is used for each docstring
650 examined.
651 
652 Optional keyword arg "verbose" prints lots of stuff if true, only
653 failures if false; by default, it's true iff "-v" is in sys.argv.
654 
655 Optional keyword arg "isprivate" specifies a function used to determine
656 whether a name is private. The default function is doctest.is_private;
657 see its docs for details.
658 """
659 
660  if mod is None and globs is None:
661  raise TypeError("Tester.__init__: must specify mod or globs")
662  if mod is not None and not _ismodule(mod):
663  raise TypeError("Tester.__init__: mod must be a module; " +
664  `mod`)
665  if globs is None:
666  globs = mod.__dict__
667  self.globs = globs
668 
669  if verbose is None:
670  import sys
671  verbose = "-v" in sys.argv
672  self.verbose = verbose
673 
674  if isprivate is None:
675  isprivate = is_private
676  self.isprivate = isprivate
677 
678  self.name2ft = {} # map name to (#failures, #trials) pair
679 
680  self.compileflags = _extract_future_flags(globs)

Member Function Documentation

def merge (   self,
  other 
) 
other -> merge in test results from the other Tester instance.

If self and other both have a test result for something
with the same name, the (#failures, #tests) results are
summed, and a warning is printed to stdout.

>>> from doctest import Tester
>>> t1 = Tester(globs={}, verbose=0)
>>> t1.runstring('''
... >>> x = 12
... >>> print x
... 12
... ''', "t1example")
(0, 2)
>>>
>>> t2 = Tester(globs={}, verbose=0)
>>> t2.runstring('''
... >>> x = 13
... >>> print x
... 13
... ''', "t2example")
(0, 2)
>>> common = ">>> assert 1 + 2 == 3\\n"
>>> t1.runstring(common, "common")
(0, 1)
>>> t2.runstring(common, "common")
(0, 1)
>>> t1.merge(t2)
*** Tester.merge: 'common' in both testers; summing outcomes.
>>> t1.summarize(1)
3 items passed all tests:
   2 tests in common
   2 tests in t1example
   2 tests in t2example
6 tests in 3 items.
6 passed and 0 failed.
Test passed.
(0, 6)
>>>

Definition at line 969 of file doctest.py.

References Tester.isprivate, Tester.name2ft, and Tester.rundoc().

969 
970  def merge(self, other):
971  """
972  other -> merge in test results from the other Tester instance.
973 
974  If self and other both have a test result for something
975  with the same name, the (#failures, #tests) results are
976  summed, and a warning is printed to stdout.
977 
978  >>> from doctest import Tester
979  >>> t1 = Tester(globs={}, verbose=0)
980  >>> t1.runstring('''
981  ... >>> x = 12
982  ... >>> print x
983  ... 12
984  ... ''', "t1example")
985  (0, 2)
986  >>>
987  >>> t2 = Tester(globs={}, verbose=0)
988  >>> t2.runstring('''
989  ... >>> x = 13
990  ... >>> print x
991  ... 13
992  ... ''', "t2example")
993  (0, 2)
994  >>> common = ">>> assert 1 + 2 == 3\\n"
995  >>> t1.runstring(common, "common")
996  (0, 1)
997  >>> t2.runstring(common, "common")
998  (0, 1)
999  >>> t1.merge(t2)
1000  *** Tester.merge: 'common' in both testers; summing outcomes.
1001  >>> t1.summarize(1)
1002  3 items passed all tests:
1003  2 tests in common
1004  2 tests in t1example
1005  2 tests in t2example
1006  6 tests in 3 items.
1007  6 passed and 0 failed.
1008  Test passed.
1009  (0, 6)
1010  >>>
1011  """
1012 
1013  d = self.name2ft
1014  for name, (f, t) in other.name2ft.items():
1015  if d.has_key(name):
1016  print "*** Tester.merge: '" + name + "' in both" \
1017  " testers; summing outcomes."
1018  f2, t2 = d[name]
1019  f = f + f2
1020  t = t + t2
1021  d[name] = f, t
def run__test__ (   self,
  d,
  name 
) 
d, name -> Treat dict d like module.__test__.

Return (#failures, #tries).
See testmod.__doc__ for details.

Definition at line 883 of file doctest.py.

References Tester.isprivate, Tester.rundoc(), and Tester.runstring().

883 
884  def run__test__(self, d, name):
885  """d, name -> Treat dict d like module.__test__.
886 
887  Return (#failures, #tries).
888  See testmod.__doc__ for details.
889  """
890 
891  failures = tries = 0
892  prefix = name + "."
893  savepvt = self.isprivate
894  try:
895  self.isprivate = lambda *args: 0
896  # Run the tests by alpha order of names, for consistency in
897  # verbose-mode output.
898  keys = d.keys()
899  keys.sort()
900  for k in keys:
901  v = d[k]
902  thisname = prefix + k
903  if type(v) in _StringTypes:
904  f, t = self.runstring(v, thisname)
905  elif _isfunction(v) or _isclass(v):
906  f, t = self.rundoc(v, thisname)
907  else:
908  raise TypeError("Tester.run__test__: values in "
909  "dict must be strings, functions "
910  "or classes; " + `v`)
911  failures = failures + f
912  tries = tries + t
913  finally:
914  self.isprivate = savepvt
915  return failures, tries
def rundict (   self,
  d,
  name,
  module = None 
) 
d, name, module=None -> search for docstring examples in d.values().

For k, v in d.items() such that v is a function or class,
do self.rundoc(v, name + "." + k).  Whether this includes
objects with private names depends on the constructor's
"isprivate" argument.  If module is specified, functions and
classes that are not defined in module are excluded.
Return aggregate (#failures, #examples).

Build and populate two modules with sample functions to test that
exclusion of external functions and classes works.

>>> import new
>>> m1 = new.module('_m1')
>>> m2 = new.module('_m2')
>>> test_data = \

Definition at line 804 of file doctest.py.

References Tester.__runone().

804 
805  def rundict(self, d, name, module=None):
806  """
807  d, name, module=None -> search for docstring examples in d.values().
808 
809  For k, v in d.items() such that v is a function or class,
810  do self.rundoc(v, name + "." + k). Whether this includes
811  objects with private names depends on the constructor's
812  "isprivate" argument. If module is specified, functions and
813  classes that are not defined in module are excluded.
814  Return aggregate (#failures, #examples).
815 
816  Build and populate two modules with sample functions to test that
817  exclusion of external functions and classes works.
818 
819  >>> import new
820  >>> m1 = new.module('_m1')
821  >>> m2 = new.module('_m2')
822  >>> test_data = \"""
823  ... def _f():
824  ... '''>>> assert 1 == 1
825  ... '''
826  ... def g():
827  ... '''>>> assert 2 != 1
828  ... '''
829  ... class H:
830  ... '''>>> assert 2 > 1
831  ... '''
832  ... def bar(self):
833  ... '''>>> assert 1 < 2
834  ... '''
835  ... \"""
836  >>> exec test_data in m1.__dict__
837  >>> exec test_data in m2.__dict__
838  >>> m1.__dict__.update({"f2": m2._f, "g2": m2.g, "h2": m2.H})
839 
840  Tests that objects outside m1 are excluded:
841 
842  >>> t = Tester(globs={}, verbose=0)
843  >>> t.rundict(m1.__dict__, "rundict_test", m1) # _f, f2 and g2 and h2 skipped
844  (0, 3)
845 
846  Again, but with a custom isprivate function allowing _f:
847 
848  >>> t = Tester(globs={}, verbose=0, isprivate=lambda x,y: 0)
849  >>> t.rundict(m1.__dict__, "rundict_test_pvt", m1) # Only f2, g2 and h2 skipped
850  (0, 4)
851 
852  And once more, not excluding stuff outside m1:
853 
854  >>> t = Tester(globs={}, verbose=0, isprivate=lambda x,y: 0)
855  >>> t.rundict(m1.__dict__, "rundict_test_pvt") # None are skipped.
856  (0, 8)
857 
858  The exclusion of objects from outside the designated module is
859  meant to be invoked automagically by testmod.
860 
861  >>> testmod(m1)
862  (0, 3)
863 
864  """
865 
866  if not hasattr(d, "items"):
867  raise TypeError("Tester.rundict: d must support .items(); " +
868  `d`)
869  f = t = 0
870  # Run the tests by alpha order of names, for consistency in
871  # verbose-mode output.
872  names = d.keys()
873  names.sort()
874  for thisname in names:
875  value = d[thisname]
876  if _isfunction(value) or _isclass(value):
877  if module and not _from_module(module, value):
878  continue
879  f2, t2 = self.__runone(value, name + "." + thisname)
880  f = f + f2
881  t = t + t2
882  return f, t
def rundoc (   self,
  object,
  name = None 
) 
object, name=None -> search object.__doc__ for examples to run.

Use optional string name as the key for logging the outcome;
by default use object.__name__.
Return (#failures, #examples).
If object is a class object, search recursively for method
docstrings too.
object.__doc__ is examined regardless of name, but if object is
a class, whether private names reached from object are searched
depends on the constructor's "isprivate" argument.

>>> t = Tester(globs={}, verbose=0)
>>> def _f():
...     '''Trivial docstring example.
...     >>> assert 2 == 2
...     '''
...     return 32
...
>>> t.rundoc(_f)  # expect 0 failures in 1 example
(0, 1)

Definition at line 719 of file doctest.py.

References Tester.__record_outcome(), Tester.compileflags, Tester.globs, Tester.isprivate, Tester.run__test__(), doctest.run_docstring_examples(), locale.str(), and Tester.verbose.

719 
720  def rundoc(self, object, name=None):
721  """
722  object, name=None -> search object.__doc__ for examples to run.
723 
724  Use optional string name as the key for logging the outcome;
725  by default use object.__name__.
726  Return (#failures, #examples).
727  If object is a class object, search recursively for method
728  docstrings too.
729  object.__doc__ is examined regardless of name, but if object is
730  a class, whether private names reached from object are searched
731  depends on the constructor's "isprivate" argument.
732 
733  >>> t = Tester(globs={}, verbose=0)
734  >>> def _f():
735  ... '''Trivial docstring example.
736  ... >>> assert 2 == 2
737  ... '''
738  ... return 32
739  ...
740  >>> t.rundoc(_f) # expect 0 failures in 1 example
741  (0, 1)
742  """
743 
744  if name is None:
745  try:
746  name = object.__name__
747  except AttributeError:
748  raise ValueError("Tester.rundoc: name must be given "
749  "when object.__name__ doesn't exist; " + `object`)
750  if self.verbose:
751  print "Running", name + ".__doc__"
752  f, t = run_docstring_examples(object, self.globs, self.verbose, name,
753  self.compileflags)
754  if self.verbose:
755  print f, "of", t, "examples failed in", name + ".__doc__"
756  self.__record_outcome(name, f, t)
757  if _isclass(object):
758  # In 2.2, class and static methods complicate life. Build
759  # a dict "that works", by hook or by crook.
760  d = {}
761  for tag, kind, homecls, value in _classify_class_attrs(object):
762 
763  if homecls is not object:
764  # Only look at names defined immediately by the class.
765  continue
766 
767  elif self.isprivate(name, tag):
768  continue
769 
770  elif kind == "method":
771  # value is already a function
772  d[tag] = value
773 
774  elif kind == "static method":
775  # value isn't a function, but getattr reveals one
776  d[tag] = getattr(object, tag)
777 
778  elif kind == "class method":
779  # Hmm. A classmethod object doesn't seem to reveal
780  # enough. But getattr turns it into a bound method,
781  # and from there .im_func retrieves the underlying
782  # function.
783  d[tag] = getattr(object, tag).im_func
784 
785  elif kind == "property":
786  # The methods implementing the property have their
787  # own docstrings -- but the property may have one too.
788  if value.__doc__ is not None:
789  d[tag] = str(value.__doc__)
790 
791  elif kind == "data":
792  # Grab nested classes.
793  if _isclass(value):
794  d[tag] = value
795 
796  else:
797  raise ValueError("teach doctest about %r" % kind)
798 
799  f2, t2 = self.run__test__(d, name)
800  f += f2
801  t += t2
802 
803  return f, t
def runstring (   self,
  s,
  name 
) 
s, name -> search string s for examples to run, logging as name.

Use string name as the key for logging the outcome.
Return (#failures, #examples).

>>> t = Tester(globs={}, verbose=1)
>>> test = r'''
...    # just an example
...    >>> x = 1 + 2
...    >>> x
...    3
... '''
>>> t.runstring(test, "Example")
Running string Example
Trying: x = 1 + 2
Expecting: nothing
ok
Trying: x
Expecting: 3
ok
0 of 2 examples failed in string Example
(0, 2)

Definition at line 681 of file doctest.py.

References Tester.__record_outcome(), Tester.compileflags, Tester.globs, and Tester.verbose.

681 
682  def runstring(self, s, name):
683  """
684  s, name -> search string s for examples to run, logging as name.
685 
686  Use string name as the key for logging the outcome.
687  Return (#failures, #examples).
688 
689  >>> t = Tester(globs={}, verbose=1)
690  >>> test = r'''
691  ... # just an example
692  ... >>> x = 1 + 2
693  ... >>> x
694  ... 3
695  ... '''
696  >>> t.runstring(test, "Example")
697  Running string Example
698  Trying: x = 1 + 2
699  Expecting: nothing
700  ok
701  Trying: x
702  Expecting: 3
703  ok
704  0 of 2 examples failed in string Example
705  (0, 2)
706  """
707 
708  if self.verbose:
709  print "Running string", name
710  f = t = 0
711  e = _extract_examples(s)
712  if e:
713  f, t = _run_examples(e, self.globs, self.verbose, name,
714  self.compileflags)
715  if self.verbose:
716  print f, "of", t, "examples failed in string", name
717  self.__record_outcome(name, f, t)
718  return f, t
def summarize (   self,
  verbose = None 
) 
verbose=None -> summarize results, return (#failures, #tests).

Print summary of test results to stdout.
Optional arg 'verbose' controls how wordy this is.  By
default, use the verbose setting established by the
constructor.

Definition at line 916 of file doctest.py.

References Tester.name2ft, and Tester.verbose.

916 
917  def summarize(self, verbose=None):
918  """
919  verbose=None -> summarize results, return (#failures, #tests).
920 
921  Print summary of test results to stdout.
922  Optional arg 'verbose' controls how wordy this is. By
923  default, use the verbose setting established by the
924  constructor.
925  """
926 
927  if verbose is None:
928  verbose = self.verbose
929  notests = []
930  passed = []
931  failed = []
932  totalt = totalf = 0
933  for x in self.name2ft.items():
934  name, (f, t) = x
935  assert f <= t
936  totalt = totalt + t
937  totalf = totalf + f
938  if t == 0:
939  notests.append(name)
940  elif f == 0:
941  passed.append( (name, t) )
942  else:
943  failed.append(x)
944  if verbose:
945  if notests:
946  print len(notests), "items had no tests:"
947  notests.sort()
948  for thing in notests:
949  print " ", thing
950  if passed:
951  print len(passed), "items passed all tests:"
952  passed.sort()
953  for thing, count in passed:
954  print " %3d tests in %s" % (count, thing)
955  if failed:
956  print "*" * 65
957  print len(failed), "items had failures:"
958  failed.sort()
959  for thing, (f, t) in failed:
960  print " %3d of %3d in %s" % (f, t, thing)
961  if verbose:
962  print totalt, "tests in", len(self.name2ft), "items."
963  print totalt - totalf, "passed and", totalf, "failed."
964  if totalf:
965  print "***Test Failed***", totalf, "failures."
966  elif verbose:
967  print "Test passed."
968  return totalf, totalt

Field Documentation

compileflags

Definition at line 679 of file doctest.py.

globs

Definition at line 666 of file doctest.py.

isprivate

Definition at line 675 of file doctest.py.

name2ft

Definition at line 677 of file doctest.py.

verbose

Definition at line 671 of file doctest.py.

The documentation for this class was generated from the following file: