README.md

trinary - A Python implementation of three-valued logic

trinary is a Python library for working with three-valued logic. It allows you to represent and manipulate statements with three possible truth values: true, false, and unknown. Unknown represents the possibility of true and false.

Installing

pip install trinary

Usage

To use trinary, import Unknown into your Python project. You can then use Unknown alongside True and False.

from trinary import Unknown

# Logical AND
print(Unknown & True)      # Unknown
print(Unknown & False)     # False
print(Unknown & Unknown)   # Unknown

# Logical OR
print(Unknown | True)      # True
print(Unknown | False)     # Unknown
print(Unknown | Unknown)   # Unknown

# Logical XOR
print(Unknown ^ True)      # Unknown
print(Unknown ^ False)     # Unknown
print(Unknown | Unknown)   # Unknown

# Logical NOT
print(~Unknown)            # Unknown

# Comparisons
print(Unknown == True)     # Unknown
print(Unknown == False)    # Unknown
print(Unknown == Unknown)  # Unknown   
print(Unknown != True)     # Unknown
print(Unknown != False)    # Unknown
print(Unknown != Unknown)  # Unknown
print(Unknown < True)      # Unknown
print(Unknown < False)     # False
print(Unknown < Unknown)   # Unknown   
print(Unknown <= True)     # True
print(Unknown <= False)    # Unknown
print(Unknown <= Unknown)  # Unknown   
print(Unknown > True)      # False
print(Unknown > False)     # Unknown
print(Unknown > Unknown)   # Unknown   
print(Unknown >= True)     # Unknown
print(Unknown >= False)    # True
print(Unknown >= Unknown)  # Unknown

To cast to a bool, use strictly or weakly to decide how Unknown is cast.

from trinary import Unknown, strictly, weakly

correct = Unknown
print(strictly(correct))  # False
print(weakly(correct))    # True
# anything else is the same as calling bool()
print(weakly(''))         # False

Examples

Use trinary to represent the truth value of a statement with uncertain information.

from trinary import Trinary, Unknown, strictly, weakly

test_a = Unknown
test_b = True

passed_both = test_a & test_b
print(passed_both)            # Unknown
print(strictly(passed_both))  # False
passed_at_least_one = test_a | test_b
print(passed_at_least_one)    # True
maybe_failed_both = weakly(~test_a & ~test_b)
print(maybe_failed_both)      # True


# Example with functions and type hints
def hot_out(weather: str) -> Trinary:
    if weather == "sunny":
        return True
    elif weather == "cloudy":
        return Unknown
    else:
        return False


def going_to_the_beach(weather: str, off_work: Trinary) -> Trinary:
    return hot_out(weather) & off_work


monday_beach = going_to_the_beach(weather="cloudy", off_work=False)
print(monday_beach)              # False
saturday_beach = going_to_the_beach(weather="cloudy", off_work=True)
print(saturday_beach)            # Unknown
definitely_free_saturday = strictly(~saturday_beach)
print(definitely_free_saturday)  # False

Theory

trinary implements Stephen Cole Kleene's "strong logic of indeterminacy", also called K3. This is equivalent to SQL logic with NULL.

Truth Table

p	q	p AND q	p OR q	p XOR q	p IMP q	NOT p
T	T	T	T	F	T	F
T	F	F	T	T	F	F
T	U	U	T	U	U	F
F	T	F	T	T	T	T
F	F	F	F	F	T	T
F	U	U	F	U	U	T
U	T	U	T	U	U	U
U	F	U	U	U	U	U
U	U	U	U	U	U	U

License

trinary is licensed under the MIT License.