Skip to content

Commit

Permalink
Update docstring code examples for all error types
Browse files Browse the repository at this point in the history
  • Loading branch information
welchbj committed Aug 1, 2017
1 parent 3b68a56 commit c60d066
Show file tree
Hide file tree
Showing 5 changed files with 112 additions and 139 deletions.
66 changes: 32 additions & 34 deletions tt/errors/arguments.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,75 +4,73 @@


class ArgumentError(TtError):
"""An exception type for invalid arguments.
.. note::
This exception type should be sub-classed and is not meant to be raised
explicitly.
"""An exception type for invalid arguments. This exception type should be
sub-classed and is not meant to be raised explicitly.
"""


class ConflictingArgumentsError(ArgumentError):
"""An exception type for two or more conflicting arguments.
.. code-block:: python
This error type can be seen in action by passing both an expression and a
set of values to the :class:`TruthTable <tt.tables.truth_table.TruthTable>`
class::
>>> from tt import TruthTable
>>> try:
... t = TruthTable('A or B', from_values='1111')
... except Exception as e:
... print(type(e))
...
<class 'tt.errors.arguments.ConflictingArgumentsError'>
>>> t = TruthTable('A or B', from_values='1111')
Traceback (most recent call last):
...
tt.errors.arguments.ConflictingArgumentsError: `expr` and \
`from_values` are mutually exclusive arguments
"""


class InvalidArgumentTypeError(ArgumentError):
"""An exception type for invalid argument types.
.. code-block:: python
To illustrate this error type, let's try passing an invalid argument when
creating a :class:`TruthTable <tt.tables.truth_table.TruthTable>`::
>>> from tt import TruthTable
>>> try:
... t = TruthTable(7)
... except Exception as e:
... print(type(e))
...
<class 'tt.errors.arguments.InvalidArgumentTypeError'>
>>> t = TruthTable(7)
Traceback (most recent call last):
...
tt.errors.arguments.InvalidArgumentTypeError: Arg `expr` must be of \
type `str` or `BooleanExpression`
"""


class InvalidArgumentValueError(ArgumentError):
"""An exception type for invalid argument values.
.. code-block:: python
Here's an example where we pass a non-power of 2 number of values when
attempting to create a :class:`TruthTable \
<tt.tables.truth_table.TruthTable>`::
>>> from tt import TruthTable
>>> try:
... t = TruthTable(from_values='01x')
... except Exception as e:
... print(type(e))
...
<class 'tt.errors.arguments.InvalidArgumentValueError'>
>>> t = TruthTable(from_values='01x')
Traceback (most recent call last):
...
tt.errors.arguments.InvalidArgumentValueError: Must specify a number \
of input values that is a power of 2
"""


class RequiredArgumentError(ArgumentError):
"""An exception for when a required argument is missing.
.. code-block:: python
Let's try an example where we omit all arguments when attempting to make
a new :class:`TruthTable <tt.tables.truth_table.TruthTable>` object::
>>> from tt import TruthTable
>>> try:
... t = TruthTable()
... except Exception as e:
... print(type(e))
...
<class 'tt.errors.arguments.RequiredArgumentError'>
>>> t = TruthTable()
Traceback (most recent call last):
...
tt.errors.arguments.RequiredArgumentError: Must specify either `expr` \
or `from_values`
"""
8 changes: 2 additions & 6 deletions tt/errors/base.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,8 @@

class TtError(Exception):

"""Base exception type for tt errors.
.. note::
This exception type should be sub-classed and is not meant to be raised
explicitly.
"""Base exception type for tt errors. This exception type should be
sub-classed and is not meant to be raised explicitly.
"""

Expand Down
43 changes: 21 additions & 22 deletions tt/errors/evaluation.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,44 +4,43 @@


class EvaluationError(TtError):
"""An exception type for errors occurring in expression evaluation.
.. note::
This exception type should be sub-classed and is not meant to be raised
explicitly.
"""An exception type for errors occurring in expression evaluation. This
exception type should be sub-classed and is not meant to be raised
explicitly.
"""


class InvalidBooleanValueError(EvaluationError):
"""An exception for an invalid truth or don't care value passed.
"""An exception for when an invalid truth or don't care value is passed.
.. code-block:: python
Here's an example where we attempt to evaluate a \
:class:`BooleanExpression <tt.expressions.bexpr.BooleanExpression>` with
an invalid value passed through ``kwargs``::
>>> from tt import BooleanExpression
>>> try:
... b = BooleanExpression('A or B')
... b.evaluate(A=1, B='brian')
... except Exception as e:
... print(type(e))
...
<class 'tt.errors.evaluation.InvalidBooleanValueError'>
>>> b = BooleanExpression('A or B')
>>> b.evaluate(A=1, B='brian')
Traceback (most recent call last):
...
tt.errors.evaluation.InvalidBooleanValueError: "brian" passed as \
value for "B" is not a valid Boolean value
"""


class NoEvaluationVariationError(EvaluationError):
"""An exception type for when evaluation of an expression will not vary.
.. code-block:: python
Let's see an example where we attempt to make a :class:`TruthTable \
<tt.tables.truth_table.TruthTable>` from an expression that has no
symbols nor variation in its results::
>>> from tt import TruthTable
>>> try:
... t = TruthTable('1 or 0')
... except Exception as e:
... print(type(e))
...
<class 'tt.errors.evaluation.NoEvaluationVariationError'>
>>> t = TruthTable('1 or 0')
Traceback (most recent call last):
...
tt.errors.evaluation.NoEvaluationVariationError: This expression is \
composed only of constant values
"""
87 changes: 37 additions & 50 deletions tt/errors/grammar.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,9 @@

class GrammarError(TtError):

"""Base type for errors that occur in the handling of expression.
.. note::
This exception type should be sub-classed and is not meant to be raised
explicitly.
"""Base type for errors that occur in the handling of expression. This
exception type should be sub-classed and is not meant to be raised
explicitly.
"""

Expand All @@ -23,10 +20,8 @@ def __init__(self, message, expr_str=None, error_pos=None, *args):
def expr_str(self):
"""The expression in which the exception occurred.
.. note::
This may be left as ``None``, in which case the expression will not
be propagated with the exception.
If this property is left as ``None``, the expression will not be
propagated with the exception.
:type: :class:`str <python:str>`
Expand All @@ -37,10 +32,8 @@ def expr_str(self):
def error_pos(self):
"""The position in the expression where the error occurred.
.. note::
This may be left as ``None``, in which case there is no specific
location in the expression causing the exception.
If this property is left as ``None``, it can be assumed that there is
no specific location in the expression causing the exception.
:type: :class:`int <python:int>`
Expand All @@ -51,81 +44,75 @@ def error_pos(self):
class BadParenPositionError(GrammarError):
"""An exception type for unexpected parentheses.
.. code-block:: python
Here's a quick and dirty example::
>>> from tt import BooleanExpression
>>> try:
... b = BooleanExpression(') A or B')
... except Exception as e:
... print(type(e))
...
<class 'tt.errors.grammar.BadParenPositionError'>
>>> b = BooleanExpression('A or B (')
Traceback (most recent call last):
...
tt.errors.grammar.BadParenPositionError: Unexpected parenthesis
"""


class EmptyExpressionError(GrammarError):
"""An exception type for when an empty expression is received.
.. code-block:: python
Let's take a brief look::
>>> from tt import BooleanExpression
>>> try:
... b = BooleanExpression('')
... except Exception as e:
... print(type(e))
...
<class 'tt.errors.grammar.EmptyExpressionError'>
>>> b = BooleanExpression('')
Traceback (most recent call last):
...
tt.errors.grammar.EmptyExpressionError: Empty expression is invalid
"""


class ExpressionOrderError(GrammarError):
"""An exception type for unexpected operands or operators.
.. code-block:: python
Here's an example with an unexpected operator::
>>> from tt import BooleanExpression
>>> try:
... b = BooleanExpression('A or or B')
... except Exception as e:
... print(type(e))
...
<class 'tt.errors.grammar.ExpressionOrderError'>
>>> b = BooleanExpression('A or or B')
Traceback (most recent call last):
...
tt.errors.grammar.ExpressionOrderError: Unexpected binary operator "or"
"""


class InvalidIdentifierError(GrammarError):
"""An exception type for invalid operand names.
.. code-block:: python
"""An exception type for invalid operand names. Invalid operand names are
determined via the :func:`is_valid_identifier \
<tt.definitions.operands.is_valid_identifier>` function.
Here are a couple of examples, for both expressions and tables::
BooleanExpression
>>> from tt import BooleanExpression, TruthTable
>>> b = BooleanExpression('%A or B')
>>> b = BooleanExpression('__A xor B')
Traceback (most recent call last):
...
tt.errors.grammar.InvalidIdentifierError: Invalid operand name "%A"
>>> t = TruthTable(from_values='0x11', ordering=['A', 'while'])
tt.errors.grammar.InvalidIdentifierError: Invalid operand name "__A"
>>> t = TruthTable(from_values='0x11', ordering=['for', 'operand'])
Traceback (most recent call last):
...
tt.errors.grammar.InvalidIdentifierError: "while" in ordering is not \
a valid symbol name
tt.errors.grammar.InvalidIdentifierError: "for" in ordering is not a \
valid symbol name
"""


class UnbalancedParenError(GrammarError):
"""An exception type for unbalanced parentheses.
.. code-block:: python
Here's a short example::
>>> from tt import BooleanExpression
>>> try:
... b = BooleanExpression('A or ((B)')
... except Exception as e:
... print(type(e))
...
<class 'tt.errors.grammar.UnbalancedParenError'>
>>> b = BooleanExpression('A or B or C)')
Traceback (most recent call last):
...
tt.errors.grammar.UnbalancedParenError: Unbalanced parenthesis
"""
Loading

0 comments on commit c60d066

Please sign in to comment.