POOP 💩

POOP — Python Object Oriented Programming. A Python 3.14 interpreter that enforces Smalltalk-style message passing by rejecting if/for/print/isinstance and rewriting Python literals (1, "hi", True, […], {…}) into POOP types where every operation is a message to a receiver.

POOP is for educational exploration of message-passing semantics inside the Python ecosystem, not for production. POOP is not distributed via PyPI by design, and there are no tagged releases; clone and run it locally.

Install

git clone https://github.com/cassiobotaro/poop.git
cd poop
uv sync
uv run poop examples/basics/hello_world.py

Contributor / development setup lives in CONTRIBUTING.md.

Hello, POOP

"Hello, World!".print()

Run it:

poop hello.py            # run a file
poop                     # interactive REPL (Ctrl+D to exit)

Inside the REPL, colon-prefixed meta-commands help you explore, Smalltalk-browser style:

>>> :methods "abc"       # the messages an object understands
>>> :explain if          # why a construct is forbidden + the substitute
>>> :help                # list the meta-commands

The ten essentials

Python	POOP
print(x)	x.print()
if cond: … / else:	cond.if_true(lambda: …) / cond.if_true_if_false(lambda: …, lambda: …)
for x in col: …	col.do(lambda x: …)
while cond: …	(lambda: cond).while_true(lambda: …)
len(x)	x.len()
x[i]	x.at(i)
x[a:b]	x.slice(a, b)
not x	x.not_()
x and y / x or y	x.and_(lambda: y) / x.or_(lambda: y)
-x	x.negated()

Full Python → POOP recipe book: MIGRATION.md. Design rationale: INFECTIONS.md.

What's banned (and what to use instead)

POOP runs 71 validators on every program. Grouped by theme:

Control flow — messages on a Boolean, not statements.

• if / else / ternary → cond.if_true(lambda: …) / cond.if_true_if_false(lambda: …, lambda: …)
• for / while / match → col.do(…) / (lambda: cond).while_true(…) / polymorphism
• with / try / raise / assert → With(lambda: cm()).do(…) / Try(lambda: …).except_(ExcType, lambda e: …).run() / ValueError.raise_("msg") / obj.assert_("msg")

Free functions — call as a method on the receiver.

• print / len / abs / hash / round / pow / divmod / min / max / sum / sorted / reversed → x.print(), x.len(), x.abs(), x.hash(), …
• map / filter → col.map(lambda x: …) / col.filter(lambda x: …)
• ascii / bin / chr / repr / format → corresponding methods on Int / Str
• input → "prompt".input() (open is banned outright — POOP has no file I/O)
• iter(col) → col.iter() returns an iterator; it.next() advances it and it.has_next() asks whether it can, so (lambda: it.has_next()).while_true(…) walks it without running off the end

Introspection — call the method on the receiver, or use polymorphism.

• isinstance(x, T) / issubclass(C, P) → x.is_instance(T) / C.is_subclass(P)
• callable(x) / dir(x) → x.callable() / x.dir(); id(x) → a.is_identical(b) (POOP answers the identity question, never an address)
• hasattr(x, n) / getattr(x, n) / setattr(x, n, v) → x.has_attr(n) / x.get_attr(n) / x.set_attr(n, v)
• type(x) / x.__class__ / xs.__len__() → x.class_() / x.class_name() / xs.len() — dunder attribute access is banned outright

Operator sugar — methods on the receiver.

• x[i] / x[a:b] → x.at(i) / x.slice(a, b)
• not x / x and y / x or y → x.not_() / x.and_(lambda: y) / x.or_(lambda: y)
• -x / +x / ~x → x.negated() / drop the + / x.bit_invert()
• x is None / x in y → x.is_none() / y.includes(x) (identity via x.is_identical(y))

Syntax shortcuts that hide behaviour.

• comprehensions ([x for x in …], {…}, generator exprs) → explicit .map / .filter / .do
• top-level def (free functions) → define as a method inside a class
• yield / walrus := / del / global → out of scope
• @decorator → send the message; only @staticmethod / @classmethod / @property are allowed, being class-definition machinery rather than runtime operations

Side-channels.

• exec / breakpoint / exit — interpreter escape hatches forbidden
• __builtins__ / __loader__ / __spec__ / __name__ — dunder globals are raw Python natives (and __builtins__ is mutable), so bare dunder names are banned alongside dunder attributes
• obj._value / obj._items — a leading underscore is another object's own state → obj.get_attr(name), which refuses it by saying so. self, cls and the enclosing class by name stay legal: reaching your own state is not reaching into anything

No library. POOP is the language, not the library — it mirrors no stdlib module.

• import — if Python needs an import to reach something, POOP does not offer it. There is no math, no json, no os.
• The only names injected are Try and With — the two constructs replacing try/except and with, which are Python keywords rather than modules.
• Python's builtins are not there either: user code runs against an allow-list (super, classmethod, staticmethod, property, plus what the class statement needs), so OSError, copyright and the rest answer NameError rather than handing back a live Python object.
• async def / await follow from this: asyncio was the only way to drive a coroutine, so async has no substitute and is banned outright. So is open — there is no file I/O; a program talks through "prompt".input() and obj.print().

The full catalog with one row per validator and the substitute recipe lives in INFECTIONS.md.

Learn by example

examples/ ships 44 programs across three subfolders, grouped by what they teach.

Language basics (examples/basics/)

• hello_world.py — the smallest POOP program
• greet.py — string input + concatenation
• fizzbuzz.py — control flow via if_true_if_false
• leap_year.py — and_ / or_ / not_
• collatz.py — while-style recursion
• grades.py — collection processing
• string_iteration.py — a string is a collection too
• slicing.py — Slice as a reusable value object
• bank_account.py — encapsulation

Idiomatic POOP (examples/idiomatic/)

• pipeline.py — filter / filter_false / map / do chain
• safe_config.py — if_none / if_not_none cascade
• common_interests.py — set operations
• statistics.py — number aggregation
• rpn_calculator.py — stack as a POOP List
• roman_numerals.py — string mapping
• managed_resource.py — With and the __exit__ protocol

Classic OO patterns (Sandi Metz / GoF) (examples/patterns/)

Creational

• abstract_factory.py — Abstract Factory
• builder.py — Builder
• factory_method.py — Factory Method
• prototype.py — Prototype (cloning a configured example)
• singleton.py — Singleton (class-side cached instance)

Structural

• adapter.py — Adapter
• bridge.py — Bridge
• tree.py — Composite (replacing isinstance)
• decorators.py — Decorator (composition by delegation)
• facade.py — Facade
• flyweight.py — Flyweight (shared intrinsic state)
• proxy.py — Proxy (lazy-loading virtual proxy)

Behavioral

• chain_of_responsibility.py — Chain of Responsibility
• command.py — Command (with undo)
• interpreter.py — Interpreter
• iterator.py — Iterator
• mediator.py — Mediator
• memento.py — Memento
• observer.py — Observer
• door.py — State
• discounts.py — Strategy
• template_method.py — Template Method
• visitor.py — Visitor

Other OO patterns (Fowler / Beck / Evans / Metz)

• null_customer.py — Null Object
• payroll.py — polymorphism replacing if employee.type == ...
• specification.py — Specification (composable rules replacing and/or/not)
• money.py — Money value object
• execute_around.py — Execute Around Method

Type annotations

Annotations (x: int, def f(x: int) -> str:) are not evaluated at runtime in Python and do not cause errors in POOP programs, but they are misleading: POOP transforms every literal to its own types (Int, Str, …), so a variable annotated as int holds an Int at runtime. Avoid annotations in POOP code. type X = int is explicitly banned by the validator pipeline.

Where to next

• MIGRATION.md — full Python → POOP recipe book
• INFECTIONS.md — every validator / transformer / type, with rationale
• proposals.md — open design backlog
• CONTRIBUTING.md — dev setup, atomic-commit conventions, versioning
• Issues — bugs and feature requests