Comparables

class nettlesome.terms.Comparable

Objects that can be compared for implication, same meaning, contradiction, and consistency.

Attr generic: Whether the object is referred to in a generic sense. If True, substituting this object for another generic object of the same class does not change the meaning of other Comparable objects that incorporate this one as a term.
Attr absent: Indicates the absence of the described object. The absence of two contradictory objects is not contradictory.
Attr name: An identifier for this object. May be used as a shorthand way of referring to this object when replacing another Comparable object’s generic terms.
Attr plural: Indicates whether the object refers to multiple things.

__ge__(other)

Call implies() as an alias.

Return type: bool
Returns: bool indicating whether self implies other

__gt__(other)

Test whether self implies other and self != other.

Return type: bool

__str__(): Return str(self).

__weakref__: list of weak references to the object (if defined)

compare_keys(other)

Test if self and other would be considered identical in a ContextRegister.

May return True even if Python’s == operation would return False.

May return False even if the .means() method would return True because self and other have generic terms.

Return type: bool

compare_ordering_of_terms(other, relation, ordering)

Determine whether one ordering of self’s terms matches other’s terms.

Multiple term orderings exist where the terms can be rearranged without changing the Fact’s meaning.

For instance, “<Ann> and <Bob> both were members of the same family” has a second ordering “<Bob> and <Ann> both were members of the same family”.

Return type: bool

compare_terms(other, relation)

Test if relation holds for corresponding context factors of self and other.

This doesn’t track a persistent ContextRegister as it goes down the sequence of Factor pairs. Perhaps(?) this simpler process can weed out Factors that clearly don’t satisfy a comparison before moving on to the more costly Analogy process. Or maybe it’s useful for testing.

Return type: bool

consistent_with(other, context=None)

Check if self and other can be non-contradictory.

Return type: bool
Returns: a bool indicating whether there’s at least one way to match the terms of self and other, such that they fit the relationship comparison.

contradicts(other, context=None)

Test whether self implies the absence of other.

Return type: bool
Returns: True if self and other can’t both be true at the same time. Otherwise returns False.

contradicts_same_context(other)

Check if self contradicts other if Terms with the same name always match.

Used to check consistency of FactorGroups.

Return type: bool

explain_consistent_with(other, context=None)

Get one explanation of why self and other need not contradict.

Return type: Optional[Explanation]

explain_contradiction(other, context=None)

Get one explanation of why self and other contradict.

Using the explanations_contradiction() method, generates one Explanation of how an analogy between the generic terms of the two objects can make them contradictory.

In this example using two FactorGroups, if the three Statements in brexit were asserted about the three Entity terms in nafta, there would be an inconsistency as to whether one pair of Entities signed a treaty with each other.

>>> from nettlesome import Statement, Entity, FactorGroup
>>> nafta = FactorGroup([
...     Statement(predicate="$country1 signed a treaty with $country2",
...               terms=[Entity(name="Mexico"), Entity(name="USA")]),
...     Statement(predicate="$country2 signed a treaty with $country3",
...               terms=[Entity(name="USA"), Entity(name="Canada")]),
...     Statement(predicate="$country3 signed a treaty with $country1",
...           terms=[Entity(name="USA"), Entity(name="Canada")])])
>>> brexit = FactorGroup([
...     Statement(predicate="$country1 signed a treaty with $country2",
...               terms=[Entity(name="UK"), Entity(name="European Union")]),
...     Statement(predicate="$country2 signed a treaty with $country3",
...               terms=[Entity(name="European Union"), Entity(name="Germany")]),
...     Statement(predicate="$country3 signed a treaty with $country1",
...          terms=[Entity(name="Germany"), Entity(name="UK")], truth=False)])
>>> print(nafta.explain_contradiction(brexit))
Because <Mexico> is like <Germany>, and <USA> is like <UK>,
  the statement that <Mexico> signed a treaty with <USA>
CONTRADICTS
  the statement it was false that <Germany> signed a treaty with <UK>

Return type: Optional[Explanation]

explain_implication(other, context=None)

Get one explanation of why self implies other.

Return type: Optional[Explanation]

explain_implied_by(other, context=None)

Get one explanation of why self implies other.

Return type: Optional[Explanation]

explain_same_meaning(other, context=None)

Get one explanation of why self and other have the same meaning.

>>> from nettlesome import Statement, Entity
>>> hades_curse = Statement(
...    predicate="$deity cursed $target",
...    terms=[Entity(name="Hades"), Entity(name="Persephone")])
>>> aphrodite_curse = Statement(
...    predicate="$deity cursed $target",
...    terms=[Entity(name="Aphrodite"), Entity(name="Narcissus")])
>>> print(hades_curse.explain_same_meaning(aphrodite_curse))
Because <Hades> is like <Aphrodite>, and <Persephone> is like <Narcissus>,
  the statement that <Hades> cursed <Persephone>
MEANS
  the statement that <Aphrodite> cursed <Narcissus>

Return type: Optional[Explanation]

explanations_consistent_with(other, context=None)

Test whether self does not contradict other.

This should only be called after confirming that other is not None.

Return type: Iterator[Explanation]
Returns: True if self and other can’t both be true at the same time. Otherwise returns False.

explanations_contradiction(other, context=None)

Test whether self implies() the absence of other.

This should only be called after confirming that other is not None.

Return type: Iterator[Explanation]
Returns: True if self and other can’t both be true at the same time. Otherwise returns False.

explanations_implication(other, context=None)

Generate ContextRegisters that cause self to imply other.

If self is absent, then generate a ContextRegister from other’s point of view and then swap the keys and values.

Return type: Iterator[Explanation]

explanations_implied_by(other, context=None)

Generate explanations for how other may imply self.

Return type: Iterator[Explanation]

explanations_same_meaning(other, context=None)

Generate ways to match contexts of self and other so they mean the same.

Return type: Iterator[Explanation]

generic_terms()

Get Terms that can be replaced without changing self’s meaning.

Return type: List[Term]

generic_terms_by_str()

Index Terms that can be replaced without changing self’s meaning.

Return type: Dict[str, Term]
Returns: a dict with the names of self's generic Factors as keys and the Factors themselves as values.

get_factor(query)

Search for Comparable with str or name matching query.

Parameters: query (str) – a string that matches the desired Comparable’s name or the output of its __str__ method.
Return type: Optional[Term]

get_factor_by_name(name)

Search of self and self’s attributes for Factor with specified name.

Return type: Optional[Term]
Returns: a Comparable with the specified name attribute if it exists, otherwise None.

get_factor_by_str(query)

Search of self and self’s attributes for Factor with specified string.

Return type: Optional[Term]
Returns: a Factor with the specified string if it exists, otherwise None.

implied_by(other, context=None)

Find whether other implies self.

Parameters

other (Optional[Comparable]) – a second Comparable to compare with self
context (Optional[ContextRegister]) – correspondences between Terms in self and other

Returns

whether other implies self.

implies(other, context=None)

Test whether self implies other.

When inherited by FactorGroup, this method will check whether every Statement in other is implied by some Statement in self.

>>> from nettlesome import Entity, Comparison, Statement, FactorGroup
>>> over_100y = Comparison(content="the distance between $site1 and $site2 was", sign=">", expression="100 yards")
>>> under_1mi = Comparison(content="the distance between $site1 and $site2 was", sign="<", expression="1 mile")
>>> protest_facts = FactorGroup(
...     [Statement(predicate=over_100y, terms=[Entity(name="the political convention"), Entity(name="the police cordon")]),
...      Statement(predicate=under_1mi, terms=[Entity(name="the police cordon"), Entity(name="the political convention")])])
>>> over_50m = Comparison(content="the distance between $site1 and $site2 was", sign=">", expression="50 meters")
>>> under_2km = Comparison(content="the distance between $site1 and $site2 was", sign="<=", expression="2 km")
>>> speech_zone_facts = FactorGroup(
...     [Statement(predicate=over_50m, terms=[Entity(name="the free speech zone"), Entity(name="the courthouse")]),
...      Statement(predicate=under_2km, terms=[Entity(name="the free speech zone"), Entity(name="the courthouse")])])
>>> protest_facts.implies(speech_zone_facts)
True

Return type: bool

implies_same_context(other)

Check if self would imply other if their generic terms are matched in order.

Return type: bool

property key: str

Return string representation of self for use as a key in a ContextRegister.

Return type: str

likely_contexts(other, context=None)

Generate contexts that match Terms from Factors with corresponding meanings.

Parameters

other (Comparable) – an object being compared to self
context (Optional[ContextRegister]) – pairs of terms that must remain matched when yielding new contexts

Yields

ContextRegisters matching all Terms of self and other.

Return type

Iterator[ContextRegister]

make_generic()

Get a copy of self except ensure generic is True.

Note

The new object created with this method will still have all the attributes of self except generic=False.

Return type: Comparable
Returns: a new object changing generic to True.

make_same_context(other): Make ContextRegister assuming all terms in self correspond to the same terms in other.

means(other, context=None)

Test whether self and other have identical meanings.

Return type: bool
Returns: whether other is another Factor with the same meaning as self.

Not the same as an equality comparison with the == symbol, which simply converts self's and other's fields to tuples and compares them.

>>> from nettlesome import Statement, Entity
>>> hades_curse = Statement(predicate="$deity cursed $target",
...    terms=[Entity(name="Hades"), Entity(name="Persephone")])
>>> aphrodite_curse = Statement(predicate="$deity cursed $target",
...    terms=[Entity(name="Aphrodite"), Entity(name="Narcissus")])
>>> hades_curse.means(aphrodite_curse)
True

new_context(changes)

Create new Comparable, replacing keys of changes with values.

Parameters: changes (ContextRegister) – has Comparables to replace as keys, and has their replacements as the corresponding values.
Return type: Comparable
Returns: a new Comparable object with the replacements made.

own_attributes()

Return attributes of self that aren’t inherited from another class.

Used for getting parameters to pass to __init__() when generating a new object.

Return type: Dict[str, Any]

possible_contexts(other, context=None)

Get permutations of generic Factor assignments not ruled out by the known context.

Parameters: other (Comparable) – another Comparable object with generic Factors
Yields: all possible ContextRegisters linking the two Comparables
Return type: Iterator[ContextRegister]

property recursive_terms: Dict[str, nettlesome.terms.Term]

Collect self’s terms, and their terms, recursively.

Return type: Dict[str, Term]
Returns: a dict (instead of a set, to preserve order) of Terms.

property short_string: str

Summarize self without line breaks.

Return type: str

term_permutations()

Generate permutations of context factors that preserve same meaning.

Return type: Iterator[TermSequence]

property term_sequence: nettlesome.terms.TermSequence

Get Factors used in comparisons with other Factors.

Return type: TermSequence
Returns: a tuple of attributes that are designated as the terms for whichever subclass of Factor calls this method. These can be used for comparing objects using consistent_with()

update_context_register(other, context, comparison)

Find ways to update self_mapping to allow relationship comparison.

Parameters

other (Optional[Comparable]) – another Comparable being compared to self
register – keys representing Comparables from self’s context and values representing Comparables in other’s context.
comparison (Callable) – a function defining the comparison that must be True between self and other. Could be Comparable.means() or Comparable.__ge__().

Yields

every way that self_mapping can be updated to be consistent with self and other having the relationship comparison.

Return type

Iterator[ContextRegister]

property wrapped_string: str

Return string representation with line breaks.

Return type: str

class nettlesome.terms.TermSequence(value: Union[nettlesome.terms.Term, Sequence[Optional[nettlesome.terms.Term]]] = ())

A sequence of Terms that can be compared in order.

static __new__(cls, value=()): Convert Sequence of Terms to a subclass of Tuple.

ordered_comparison(other, operation, context=None)

Find ways for a series of pairs of Terms terms to satisfy a comparison.

Parameters: context (Optional[ContextRegister]) – keys representing terms in self and values representing terms in other. The keys and values have been found in corresponding positions in self and other.
Yields: every way that matches can be updated to be consistent with each element of self.need_matches having the relationship self.comparison with the item at the corresponding index of self.available.
Return type: Iterator[ContextRegister]

nettlesome.terms.consistent_with(left, right, context=None)

Call Factor.consistent_with() as function alias.

This exists because Factor._context_registers() needs a function rather than a method for the comparison variable.

Return type: bool
Returns: whether other is consistent with self.

nettlesome.terms.means(left, right)

Call Factor.means() as function alias.

This exists because Explanation objects expect a function rather than a method

Return type: bool
Returns: whether other is another Factor with the same meaning as self.

nettlesome.terms.contradicts(left, right)

Call Factor.contradicts() as function alias.

This exists because Explanation objects expect a function rather than a method

Return type: bool
Returns: whether other is another Factor that can contradict self, assuming relevant context factors

@nettlesome.terms.new_context_helper(func)

Search Factor for generic Factors to use in new context.

Decorators for memoizing generic Factors. Used when changing an abstract Rule from one concrete context to another.

If a list has been passed in rather than a dict, uses the input as a series of Factors to replace the generic_terms from the calling object.

Also, if changes contains a replacement for the calling object, the decorator returns the replacement and never calls the decorated function.

Parameters

factor – a Factor that is having its generic Factors replaced to change context (for instance, to change to the context of a different case involving parties represented by different Entity objects).
changes – indicates which generic Factors within factor should be replaced and what they should be replaced with.

Returns

a new Factor object in the new context.