__liquid__ method not called automatically for object property access in templates

[twillis]

Description

The python-liquid library documentation states that objects can implement a __liquid__ method that will be called automatically when the object is accessed in liquid templates. However, this functionality does not work as documented - the __liquid__ method is never called for property access like {{obj.name}}.

Steps to Reproduce

1. Create a class with a __liquid__ method that returns a dictionary
2. Create a liquid template that accesses properties on an instance of this class
3. Render the template with the object
4. Observe that __liquid__ is never called and properties are empty

Reproduction Code

See attached liquid_bug_reproduction.py:

from liquid import Environment

class TestObject:
    def __init__(self, name, value):
        self._name = name
        self._value = value
        self.liquid_called = False
    
    def __liquid__(self):
        print(f"__liquid__ called on {self._name}")
        self.liquid_called = True
        return {
            'name': self._name,
            'value': self._value,
            'computed': f"computed_{self._value}"
        }

env = Environment()
obj = TestObject("test_object", "test_value")

# This should call __liquid__() but doesn't
template = env.from_string("Name: {{obj.name}}, Value: {{obj.value}}")
result = template.render(obj=obj)
print(f"Result: {result}")  # Result: Name: , Value: 
print(f"Was __liquid__ called? {obj.liquid_called}")  # False

Expected Behavior

• {{obj.name}} should call obj.__liquid__()
• The returned dictionary {'name': 'test_object', 'value': 'test_value', 'computed': 'computed_test_value'} should be used for property lookups
• Template should render: Name: test_object, Value: test_value

Actual Behavior

• __liquid__ method is never called
• Property access returns empty values
• Template renders: Name: , Value:

Source Code Analysis

From examining the python-liquid source code, the __liquid__ method is only referenced in the default filter implementation, not in the core property resolution logic. This suggests the feature was partially implemented but not integrated into the main template evaluation system.

Environment

• Python Version: 3.x
• python-liquid Version: Latest
• Operating System: Linux
• Platform: Any

Impact

This bug prevents the intended object serialization workflow, forcing developers to manually convert objects to dictionaries before passing them to templates. This defeats the purpose of the __liquid__ method and breaks the documented API contract.

Suggested Fix

The __liquid__ method should be checked and called in the core property resolution logic, similar to how Django templates handle custom object serialization methods.

Files Attached

1. liquid_bug_reproduction.py - Minimal reproduction script
2. liquid_bug_documentation.md - Detailed analysis and test results

Workaround

Currently, objects must be manually converted:

# Instead of: template.render(obj=my_object)
# Use: template.render(obj=my_object.__liquid__())

[jg-rp]

Hi @twillis,

__liquid__ is called when an object needs to be cast to a Liquid primitive value, not for property access.

For object property access, your class need to implement the Mapping interface (docs).

import collections.abc

from liquid import Environment


class TestObject(collections.abc.Mapping):
    def __init__(self, name, value):
        self._data = {
            "name": name,
            "value": value,
            "computed": f"computed_{value}",
        }

        self.liquid_called = False
        self.getitem_called = False

    def __liquid__(self):
        """Return a Liquid primitive value for this object."""
        print("__liquid__ called")
        self.liquid_called = True
        return 2

    def __getitem__(self, k):
        print(f"__getitem__ called on {k}")
        self.getitem_called = True

        # We're simply wrapping a dictionary in this example.
        # You could delegate to a method or read from a database here.
        return self._data[k]

    def __iter__(self):
        return iter(self._data)

    def __len__(self):
        return len(self._data)


env = Environment()
obj = TestObject("test_object", "test_value")

template = env.from_string(
    "Name: {{obj.name}}, Value: {{obj.value}}, Array Item: {{some_list[obj]}}"
)

result = template.render(obj=obj, some_list=["a", "b", "c"])
print(f"Result: {result}")  # Result: Name: test_object, Value: test_value
print(f"Was __liquid__ called? {obj.liquid_called}")  # True
print(f"Was __getitem__ called? {obj.getitem_called}")  # True

The docs do mention using __liquid__ when "resolving a variable path or segment", but it's also used when an object appears in a Boolean or comparison expression, and some filters use it too. So the docs do need updating.