py2be

Simple Python library determining whether strings indicate truey or falsey values.

Table of Contents

• Introduction
• Installation & usage
  • Python version compatibility
  • Text string inputs (unicode / bytes)
• Terminology
• Components
  • Functions
• Benchmarks
• Examples
• Project Information
  • Where to get help
  • Contribution guidelines
  • Dependencies
    • Efferent (fan-out)
    • Development Dependencies
    • Afferent (fan-in)
  • Related projects
  • License

Introduction

to-be is a library providing facilities for determining whether the truthiness of strings. It is implemented in several languages: py2be is the Python implementation.

py2be explicitly supports Python 2.7 — not other Python 2.x releases — and Python 3.8+. This is enforced at install time via python_requires in setup.py and exercised in GitHub Actions on Python 2.7 and Python 3.8–3.14.

Installation & usage

Install via pip or pip3, as in:

$ pip3 install py2be

Use via import:

import py2be

or import the functions you need:

from py2be import (
    str2bool,
    string_is_falsey,
    string_is_truey,
    string_is_truthy,
)

Python version compatibility

py2be is intended to run on Python 2.7 and Python 3.8+ only. Versions in the Python 3.0–3.7 range are excluded by python_requires.

Python version	Support
2.7	Supported (the only Python 2 release supported)
3.0 – 3.7	Not supported
3.8+	Supported

Requirement	Applies to
Python 2.7 or 3.8+	All public APIs (str2bool, string_is_falsey, string_is_truey, string_is_truthy)

The public API surface is listed in py2be.__all__.

Text string inputs (unicode / bytes)

All public functions take a single string argument s. The library classifies text only; binary buffers are not accepted.

Input	Python 2.7	Python 3.8+
unicode / text str	Supported	Supported (str)
str (byte string)	Supported for ASCII stock terms (e.g. "true", "no")	N/A — str is text
bytes, bytearray, and other non-text types	Not supported — behaviour is undefined; decode to text first	Not supported — behaviour is undefined; decode to text first
None	str2bool(None) returns None; the boolean predicates return False	Same

On Python 3, passing bytes (for example b"true") will not match stock terms and is not a supported use case. Decode explicitly before calling, for example s.decode("utf-8") or s.decode("ascii").

On Python 2.7, prefer unicode literals (e.g. u"true") for non-ASCII configuration values. ASCII str literals work for the stock vocabulary because they match the internal comparison tables directly.

Trimming uses str.strip() / unicode.strip(); only leading and trailing whitespace is removed before lower-case matching.

Terminology

The term "truthy" is an unhelpfully overloaded term in the programming world, insofar as it is used to refer to the notion of "truthiness" - whether something can be deemed to be interpretable as truth - and also the true side of that interpretation. In this library, the former interpretation is used, leaving us with the following terms:

• "truthy" - whether something can be deemed to be interpretable as having truth (and, thus, will be falsey or truey);
• "falsey" - whether an object can be deemed to be interpretable as being false;
• "truey" - whether an object can be deemed to be interpretable as being true;

For example, consider the following Python program:

from py2be import (
    string_is_falsey,
    string_is_truey,
    string_is_truthy,
)

s1 = "no"
s2 = "True"
s3 = "orange"

# "no" is validly truthy, and is falsey
assert string_is_falsey(s1)
assert not string_is_truey(s1)
assert string_is_truthy(s1)

# "True" is validly truthy, and is truey
assert not string_is_falsey(s2)
assert string_is_truey(s2)
assert string_is_truthy(s2)

# "orange" is not validly truthy, and is neither falsey nor truey
assert not string_is_falsey(s3)
assert not string_is_truey(s3)
assert not string_is_truthy(s3)

Components

Functions

The following public functions are defined in the current version:

Function	Purpose
str2bool(s)	Classifies s as unrecognised (None), falsey (False), or truey (True).
string_is_falsey(s)	Indicates that s, when trimmed, is classified as truthy and is deemed falsey.
string_is_truey(s)	Indicates that s, when trimmed, is classified as truthy and is deemed truey.
string_is_truthy(s)	Indicates that s, when trimmed, is classified as truthy (and is deemed either falsey or truey).

NOTE: string_is_falsey(x) == not string_is_truey(x) is not guaranteed (for example, when x is not classified as truthy, both predicates return False).

Stock falsey terms (after optional trimming and case folding) include 0, false, no, and off. Stock truey terms include 1, true, yes, and on. Several common capitalisations and mixtures of case are recognised without lower-casing first.

Benchmarks

Benchmark scripts are provided under benchmarks/, modelled on to-be.Rust's string_truthy Criterion suite.

Install the package (or set PYTHONPATH=. from the repository root), then run:

$ pip install -e .
$ ./benchmarks/run_all_benchmarks.sh

To run a subset of groups:

$ python benchmarks/string_truthy.py string_is_truthy
$ python benchmarks/string_truthy.py mixed_batch

Run benchmarks on mains power for stable timings. On AC power (Apple Silicon, CPython 3.9, number=200000, repeat=5), one-sided string_is_falsey() / string_is_truey() paths are roughly 30–40% faster on matching stock terms and ~12% faster on unrecognised inputs versus routing both through full _str2bool(); string_is_truthy() is unchanged. Cross-polarity use (e.g. string_is_truey("false")) may be slower — use str2bool() or string_is_truthy() when full classification is needed.

Examples

Examples are provided in the examples directory. A detailed list of them is provided in EXAMPLES.md.

To run the stock string classification example (after pip install -e .):

$ python examples/truthy_strings.py

Project Information

Where to get help

GitHub Page

Contribution guidelines

Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/py2be.

Dependencies

Efferent (fan-out)

None.

Development Dependencies

None (currently).

Afferent (fan-in)

None (currently).

Related projects

• 2be (C);
• to_be.Ruby;
• to-be.Rust;

License

py2be is released under the 3-clause BSD license. See LICENSE for details.