Segment value types

These classes are used to represent segment values in Python without needing a model instance.

BaseValue

Source code in wagtail_localize/segments/types.py

class BaseValue:
    def __init__(self, path, order=0):
        self.path = path
        self.order = order

    def clone(self):
        """
        Clones this segment. Must be overridden in subclass.
        """
        raise NotImplementedError

    def with_order(self, order):
        """
        Sets the order of this segment.
        """
        clone = self.clone()
        clone.order = order
        return clone

    def wrap(self, base_path):
        """
        Appends a component to the beginning of the path.

        For example:

        >>> s = StringSegmentValue("field", "foo")
        >>> s.wrap("wrapped")
        StringSegmentValue('wrapped.field', 'foo')
        """
        new_path = base_path

        if self.path:
            new_path += "." + self.path

        clone = self.clone()
        clone.path = new_path
        return clone

    def unwrap(self):
        """
        Pops a component from the beginning of the path. Reversing .wrap().

        For example:

        >>> s = StringSegmentValue("wrapped.field", "foo")
        >>> s.unwrap()
        'wrapped', StringSegmentValue('field', 'foo')
        """
        first_component, *remaining_components = self.path.split(".")
        new_path = ".".join(remaining_components)

        clone = self.clone()
        clone.path = new_path
        return first_component, clone

clone()

Clones this segment. Must be overridden in subclass.

Source code in wagtail_localize/segments/types.py

def clone(self):
    """
    Clones this segment. Must be overridden in subclass.
    """
    raise NotImplementedError

unwrap()

Pops a component from the beginning of the path. Reversing .wrap().

For example:

s = StringSegmentValue("wrapped.field", "foo") s.unwrap() 'wrapped', StringSegmentValue('field', 'foo')

Source code in wagtail_localize/segments/types.py

def unwrap(self):
    """
    Pops a component from the beginning of the path. Reversing .wrap().

    For example:

    >>> s = StringSegmentValue("wrapped.field", "foo")
    >>> s.unwrap()
    'wrapped', StringSegmentValue('field', 'foo')
    """
    first_component, *remaining_components = self.path.split(".")
    new_path = ".".join(remaining_components)

    clone = self.clone()
    clone.path = new_path
    return first_component, clone

with_order(order)

Sets the order of this segment.

Source code in wagtail_localize/segments/types.py

def with_order(self, order):
    """
    Sets the order of this segment.
    """
    clone = self.clone()
    clone.order = order
    return clone

wrap(base_path)

Appends a component to the beginning of the path.

For example:

s = StringSegmentValue("field", "foo") s.wrap("wrapped") StringSegmentValue('wrapped.field', 'foo')

Source code in wagtail_localize/segments/types.py

def wrap(self, base_path):
    """
    Appends a component to the beginning of the path.

    For example:

    >>> s = StringSegmentValue("field", "foo")
    >>> s.wrap("wrapped")
    StringSegmentValue('wrapped.field', 'foo')
    """
    new_path = base_path

    if self.path:
        new_path += "." + self.path

    clone = self.clone()
    clone.path = new_path
    return clone

OverridableSegmentValue

Bases: BaseValue

Represents a field that can be overridden.

Attributes:

Name	Type	Description
path	str	The content path of the segment.
data	any	The value of the field in the source. Must be JSON-serializable.
order	int	The index that this segment appears on a page.

Source code in wagtail_localize/segments/types.py

class OverridableSegmentValue(BaseValue):
    """
    Represents a field that can be overridden.

    Attributes:
        path (str): The content path of the segment.
        data (any): The value of the field in the source. Must be JSON-serializable.
        order (int): The index that this segment appears on a page.
    """

    def __init__(self, path, data, **kwargs):
        """
        Initialises a new RelatedObjectSegmentValue.

        Args:
            path (str): The content path of the segment.
            data (any): The value of the field in the source. Must be JSON-serializable.
            order (int, optional): The index that this segment appears on a page.
        """
        self.data = data

        super().__init__(path, **kwargs)

    def clone(self):
        """
        Makes an exact copy of this OverridableSegmentValue.

        Instead of mutating SegmentValue classes in place, it's recommended to clone them first.

        Returns:
            OverridableSegmentValue: The new segment value that's a copy of this one.
        """
        return OverridableSegmentValue(self.path, self.data, order=self.order)

    def is_empty(self):
        """
        Returns True if the data is empty.

        Returns:
            boolean: True if the data is empty.
        """
        return self.data in ["", None]

    def __eq__(self, other):
        return (
            isinstance(other, OverridableSegmentValue)
            and self.path == other.path
            and self.data == other.data
        )

    def __repr__(self):
        return f"<OverridableSegmentValue {self.path} '{self.data}'>"

__init__(path, data, **kwargs)

Initialises a new RelatedObjectSegmentValue.

Parameters:

Name	Type	Description	Default
path	str	The content path of the segment.	required
data	any	The value of the field in the source. Must be JSON-serializable.	required
order	int	The index that this segment appears on a page.	required

Source code in wagtail_localize/segments/types.py

def __init__(self, path, data, **kwargs):
    """
    Initialises a new RelatedObjectSegmentValue.

    Args:
        path (str): The content path of the segment.
        data (any): The value of the field in the source. Must be JSON-serializable.
        order (int, optional): The index that this segment appears on a page.
    """
    self.data = data

    super().__init__(path, **kwargs)

clone()

Makes an exact copy of this OverridableSegmentValue.

Instead of mutating SegmentValue classes in place, it's recommended to clone them first.

Returns:

Name	Type	Description
OverridableSegmentValue		The new segment value that's a copy of this one.

Source code in wagtail_localize/segments/types.py

def clone(self):
    """
    Makes an exact copy of this OverridableSegmentValue.

    Instead of mutating SegmentValue classes in place, it's recommended to clone them first.

    Returns:
        OverridableSegmentValue: The new segment value that's a copy of this one.
    """
    return OverridableSegmentValue(self.path, self.data, order=self.order)

is_empty()

Returns True if the data is empty.

Returns:

Name	Type	Description
boolean		True if the data is empty.

Source code in wagtail_localize/segments/types.py

def is_empty(self):
    """
    Returns True if the data is empty.

    Returns:
        boolean: True if the data is empty.
    """
    return self.data in ["", None]

RelatedObjectSegmentValue

Bases: BaseValue

Represents a reference to a foreign translatable object.

Attributes:

Name	Type	Description
path	str	The content path of the segment.
content_type	ContentType	The content type of the base model of the foreign object.
translation_key	UUID	The value of the foreign object's translation_key field.
order	int	The index that this segment appears on a page.

Source code in wagtail_localize/segments/types.py

class RelatedObjectSegmentValue(BaseValue):
    """
    Represents a reference to a foreign translatable object.

    Attributes:
        path (str): The content path of the segment.
        content_type (ContentType): The content type of the base model of the foreign object.
        translation_key (UUID): The value of the foreign object's `translation_key` field.
        order (int): The index that this segment appears on a page.
    """

    def __init__(self, path, content_type, translation_key, **kwargs):
        """
        Initialises a new RelatedObjectSegmentValue.

        Args:
            path (str): The content path of the segment.
            content_type (ContentType): The content type of the base model of the foreign object.
            translation_key (UUID): The value of the foreign object's `translation_key` field.
            order (int, optional): The index that this segment appears on a page.
        """
        self.content_type = content_type
        self.translation_key = translation_key

        super().__init__(path, **kwargs)

    @classmethod
    def from_instance(cls, path, instance):
        """
        Initialises a new RelatedObjectSegmentValue from a model instance.

        Note: This class only records the type and translation key of the instance. So you will need to save the
        locale separately if you need to get this same instance back later.

        Args:
            path (str): The content path of the segment.
            instance (Model): An instance of the translatable object that needs to be referenced.

        Raises:
            AttributeError: If the instance is not translatable.

        Returns:
            RelatedObjectSegmentValue: The new segment value.
        """
        model = instance.get_translation_model()
        return cls(
            path, ContentType.objects.get_for_model(model), instance.translation_key
        )

    def get_instance(self, locale):
        """
        Gets an instance of the referenced translatable object for the given locale.

        Raises:
            Model.DoesNotExist: If there isn't an instance of the translatable object in the given locale.

        Returns:
            Model: The instance.
        """
        from ..models import pk

        return self.content_type.get_object_for_this_type(
            translation_key=self.translation_key, locale_id=pk(locale)
        )

    def clone(self):
        """
        Makes an exact copy of this RelatedObjectSegmentValue.

        Instead of mutating SegmentValue classes in place, it's recommended to clone them first.

        Returns:
            RelatedObjectSegmentValue: The new segment value that's a copy of this one.
        """
        return RelatedObjectSegmentValue(
            self.path, self.content_type, self.translation_key, order=self.order
        )

    def is_empty(self):
        """
        Returns True if the related object is null.

        Returns:
            boolean: True if the related object is null.
        """
        return self.content_type is None and self.translation_key is None

    def __eq__(self, other):
        return (
            isinstance(other, RelatedObjectSegmentValue)
            and self.path == other.path
            and self.content_type == other.content_type
            and self.translation_key == other.translation_key
        )

    def __repr__(self):
        return f"<RelatedObjectSegmentValue {self.path} {self.content_type} {self.translation_key}>"

__init__(path, content_type, translation_key, **kwargs)

Initialises a new RelatedObjectSegmentValue.

Parameters:

Name	Type	Description	Default
path	str	The content path of the segment.	required
content_type	ContentType	The content type of the base model of the foreign object.	required
translation_key	UUID	The value of the foreign object's translation_key field.	required
order	int	The index that this segment appears on a page.	required

Source code in wagtail_localize/segments/types.py

def __init__(self, path, content_type, translation_key, **kwargs):
    """
    Initialises a new RelatedObjectSegmentValue.

    Args:
        path (str): The content path of the segment.
        content_type (ContentType): The content type of the base model of the foreign object.
        translation_key (UUID): The value of the foreign object's `translation_key` field.
        order (int, optional): The index that this segment appears on a page.
    """
    self.content_type = content_type
    self.translation_key = translation_key

    super().__init__(path, **kwargs)

clone()

Makes an exact copy of this RelatedObjectSegmentValue.

Instead of mutating SegmentValue classes in place, it's recommended to clone them first.

Returns:

Name	Type	Description
RelatedObjectSegmentValue		The new segment value that's a copy of this one.

Source code in wagtail_localize/segments/types.py

def clone(self):
    """
    Makes an exact copy of this RelatedObjectSegmentValue.

    Instead of mutating SegmentValue classes in place, it's recommended to clone them first.

    Returns:
        RelatedObjectSegmentValue: The new segment value that's a copy of this one.
    """
    return RelatedObjectSegmentValue(
        self.path, self.content_type, self.translation_key, order=self.order
    )

from_instance(path, instance) classmethod

Initialises a new RelatedObjectSegmentValue from a model instance.

Note: This class only records the type and translation key of the instance. So you will need to save the locale separately if you need to get this same instance back later.

Parameters:

Name	Type	Description	Default
path	str	The content path of the segment.	required
instance	Model	An instance of the translatable object that needs to be referenced.	required

Raises:

Type	Description
AttributeError	If the instance is not translatable.

Returns:

Name	Type	Description
RelatedObjectSegmentValue		The new segment value.

Source code in wagtail_localize/segments/types.py

@classmethod
def from_instance(cls, path, instance):
    """
    Initialises a new RelatedObjectSegmentValue from a model instance.

    Note: This class only records the type and translation key of the instance. So you will need to save the
    locale separately if you need to get this same instance back later.

    Args:
        path (str): The content path of the segment.
        instance (Model): An instance of the translatable object that needs to be referenced.

    Raises:
        AttributeError: If the instance is not translatable.

    Returns:
        RelatedObjectSegmentValue: The new segment value.
    """
    model = instance.get_translation_model()
    return cls(
        path, ContentType.objects.get_for_model(model), instance.translation_key
    )

get_instance(locale)

Gets an instance of the referenced translatable object for the given locale.

Raises:

Type	Description
DoesNotExist	If there isn't an instance of the translatable object in the given locale.

Returns:

Name	Type	Description
Model		The instance.

Source code in wagtail_localize/segments/types.py

def get_instance(self, locale):
    """
    Gets an instance of the referenced translatable object for the given locale.

    Raises:
        Model.DoesNotExist: If there isn't an instance of the translatable object in the given locale.

    Returns:
        Model: The instance.
    """
    from ..models import pk

    return self.content_type.get_object_for_this_type(
        translation_key=self.translation_key, locale_id=pk(locale)
    )

is_empty()

Returns True if the related object is null.

Returns:

Name	Type	Description
boolean		True if the related object is null.

Source code in wagtail_localize/segments/types.py

def is_empty(self):
    """
    Returns True if the related object is null.

    Returns:
        boolean: True if the related object is null.
    """
    return self.content_type is None and self.translation_key is None

StringSegmentValue

Bases: BaseValue

Represents a translatable string segment.

Attributes:

Name	Type	Description
path	str	The content path of the segment.
string	StringValue	the value of the segment.
attrs	dict	A dict of HTML attributes that were stripped out of the string.
order	int	The index that this segment appears on a page.

Source code in wagtail_localize/segments/types.py

class StringSegmentValue(BaseValue):
    """
    Represents a translatable string segment.

    Attributes:
        path (str): The content path of the segment.
        string (StringValue): the value of the segment.
        attrs (dict): A dict of HTML attributes that were stripped out of the string.
        order (int): The index that this segment appears on a page.
    """

    def __init__(self, path, string, attrs=None, **kwargs):
        """
        Initialises a new StringSegmentValue.

        Args:
            path (str): The content path of the segment.
            string (StringValue): the value of the segment.
            attrs (dict, optional): A dict of HTML attributes that were stripped out of the string.
            order (int, optional): The index that this segment appears on a page.
        """
        if isinstance(string, str):
            string = StringValue.from_plaintext(string)

        elif isinstance(string, StringValue):
            pass

        else:
            raise TypeError(
                f"`string` must be either a `StringValue` or a `str`. Got `{type(string).__name__}`"
            )

        self.string = string
        self.attrs = attrs or None

        super().__init__(path, **kwargs)

    def clone(self):
        """
        Makes an exact copy of this StringSegmentValue.

        Instead of mutating SegmentValue classes in place, it's recommended to clone them first.

        Returns:
            StringSegmentValue: The new segment value that's a copy of this one.
        """
        return StringSegmentValue(
            self.path, self.string, attrs=self.attrs, order=self.order
        )

    @classmethod
    def from_source_html(cls, path, html, **kwargs):
        """
        Initialises a StringSegmentValue from a HTML string.

        Args:
            path (str): The content path of the segment.
            html (str): The HTML value of the segment.
            order (int, optional): The index that this segment appears on a page.
        """
        string, attrs = StringValue.from_source_html(html)
        return cls(path, string, attrs=attrs, **kwargs)

    def render_text(self):
        """
        Returns a plain text representation of the segment value.

        Note: If the segment value was created from HTML, this strips out HTML tags.

        Returns:
            str: The text representation of the segment value.
        """
        return self.string.render_text()

    def render_html(self):
        """
        Returns a HTML representation of the segment value.

        Note: If the segment value was created from plain text, this escapes special characters.

        Returns:
            str: The HTML representation of the segment value.
        """
        return self.string.render_html(self.attrs)

    def is_empty(self):
        """
        Returns True if the StringValue is blank.

        Returns:
            boolean: True if the StringValue is blank.
        """
        return self.string.data in ["", None]

    def __eq__(self, other):
        return (
            isinstance(other, StringSegmentValue)
            and self.path == other.path
            and self.string == other.string
            and self.attrs == other.attrs
        )

    def __repr__(self):
        return f"<StringSegmentValue {self.path} '{self.render_html()}'>"

__init__(path, string, attrs=None, **kwargs)

Initialises a new StringSegmentValue.

Parameters:

Name	Type	Description	Default
path	str	The content path of the segment.	required
string	StringValue	the value of the segment.	required
attrs	dict	A dict of HTML attributes that were stripped out of the string.	None
order	int	The index that this segment appears on a page.	required

Source code in wagtail_localize/segments/types.py

def __init__(self, path, string, attrs=None, **kwargs):
    """
    Initialises a new StringSegmentValue.

    Args:
        path (str): The content path of the segment.
        string (StringValue): the value of the segment.
        attrs (dict, optional): A dict of HTML attributes that were stripped out of the string.
        order (int, optional): The index that this segment appears on a page.
    """
    if isinstance(string, str):
        string = StringValue.from_plaintext(string)

    elif isinstance(string, StringValue):
        pass

    else:
        raise TypeError(
            f"`string` must be either a `StringValue` or a `str`. Got `{type(string).__name__}`"
        )

    self.string = string
    self.attrs = attrs or None

    super().__init__(path, **kwargs)

clone()

Makes an exact copy of this StringSegmentValue.

Instead of mutating SegmentValue classes in place, it's recommended to clone them first.

Returns:

Name	Type	Description
StringSegmentValue		The new segment value that's a copy of this one.

Source code in wagtail_localize/segments/types.py

def clone(self):
    """
    Makes an exact copy of this StringSegmentValue.

    Instead of mutating SegmentValue classes in place, it's recommended to clone them first.

    Returns:
        StringSegmentValue: The new segment value that's a copy of this one.
    """
    return StringSegmentValue(
        self.path, self.string, attrs=self.attrs, order=self.order
    )

from_source_html(path, html, **kwargs) classmethod

Initialises a StringSegmentValue from a HTML string.

Parameters:

Name	Type	Description	Default
path	str	The content path of the segment.	required
html	str	The HTML value of the segment.	required
order	int	The index that this segment appears on a page.	required

Source code in wagtail_localize/segments/types.py

@classmethod
def from_source_html(cls, path, html, **kwargs):
    """
    Initialises a StringSegmentValue from a HTML string.

    Args:
        path (str): The content path of the segment.
        html (str): The HTML value of the segment.
        order (int, optional): The index that this segment appears on a page.
    """
    string, attrs = StringValue.from_source_html(html)
    return cls(path, string, attrs=attrs, **kwargs)

is_empty()

Returns True if the StringValue is blank.

Returns:

Name	Type	Description
boolean		True if the StringValue is blank.

Source code in wagtail_localize/segments/types.py

def is_empty(self):
    """
    Returns True if the StringValue is blank.

    Returns:
        boolean: True if the StringValue is blank.
    """
    return self.string.data in ["", None]

render_html()

Returns a HTML representation of the segment value.

Note: If the segment value was created from plain text, this escapes special characters.

Returns:

Name	Type	Description
str		The HTML representation of the segment value.

Source code in wagtail_localize/segments/types.py

def render_html(self):
    """
    Returns a HTML representation of the segment value.

    Note: If the segment value was created from plain text, this escapes special characters.

    Returns:
        str: The HTML representation of the segment value.
    """
    return self.string.render_html(self.attrs)

render_text()

Returns a plain text representation of the segment value.

Note: If the segment value was created from HTML, this strips out HTML tags.

Returns:

Name	Type	Description
str		The text representation of the segment value.

Source code in wagtail_localize/segments/types.py

def render_text(self):
    """
    Returns a plain text representation of the segment value.

    Note: If the segment value was created from HTML, this strips out HTML tags.

    Returns:
        str: The text representation of the segment value.
    """
    return self.string.render_text()

TemplateSegmentValue

Bases: BaseValue

Represents an HTML template used to recombine the values of RichTextField/Blocks.

Attributes:

Name	Type	Description
path	str	The content path of the segment.
format	str	The format of the template (eg, 'html').
template	str	The template.
string_count	int	The number of translatablle string segments that were extracted from the template.
order	int	The index that this segment appears on a page.

Source code in wagtail_localize/segments/types.py

class TemplateSegmentValue(BaseValue):
    """
    Represents an HTML template used to recombine the values of RichTextField/Blocks.

    Attributes:
        path (str): The content path of the segment.
        format (str): The format of the template (eg, 'html').
        template (str): The template.
        string_count (int): The number of translatablle string segments that were extracted from the template.
        order (int): The index that this segment appears on a page.
    """

    def __init__(self, path, format, template, string_count, **kwargs):
        """
        Initialises a new TemplateSegmentValue.

        Args:
            path (str): The content path of the segment.
            format (str): The format of the template (eg, 'html').
            template (str): The template.
            string_count (int): The number of translatablle string segments that were extracted from the template.
            order (int, optional): The index that this segment appears on a page.
        """
        self.format = format
        self.template = template
        self.string_count = string_count

        super().__init__(path, **kwargs)

    def clone(self):
        """
        Makes an exact copy of this TemplateSegmentValue.

        Instead of mutating SegmentValue classes in place, it's recommended to clone them first.

        Returns:
            TemplateSegmentValue: The new segment value that's a copy of this one.
        """
        return TemplateSegmentValue(
            self.path, self.format, self.template, self.string_count, order=self.order
        )

    def is_empty(self):
        """
        Returns True if the template is blank.

        Returns:
            boolean: True if the template is blank.
        """
        return self.template in ["", None]

    def __eq__(self, other):
        return (
            isinstance(other, TemplateSegmentValue)
            and self.path == other.path
            and self.format == other.format
            and self.template == other.template
            and self.string_count == other.string_count
        )

    def __repr__(self):
        return f"<TemplateSegmentValue {self.path} format:{self.format} {self.string_count} segments>"

__init__(path, format, template, string_count, **kwargs)

Initialises a new TemplateSegmentValue.

Parameters:

Name	Type	Description	Default
path	str	The content path of the segment.	required
format	str	The format of the template (eg, 'html').	required
template	str	The template.	required
string_count	int	The number of translatablle string segments that were extracted from the template.	required
order	int	The index that this segment appears on a page.	required

Source code in wagtail_localize/segments/types.py

def __init__(self, path, format, template, string_count, **kwargs):
    """
    Initialises a new TemplateSegmentValue.

    Args:
        path (str): The content path of the segment.
        format (str): The format of the template (eg, 'html').
        template (str): The template.
        string_count (int): The number of translatablle string segments that were extracted from the template.
        order (int, optional): The index that this segment appears on a page.
    """
    self.format = format
    self.template = template
    self.string_count = string_count

    super().__init__(path, **kwargs)

clone()

Makes an exact copy of this TemplateSegmentValue.

Instead of mutating SegmentValue classes in place, it's recommended to clone them first.

Returns:

Name	Type	Description
TemplateSegmentValue		The new segment value that's a copy of this one.

Source code in wagtail_localize/segments/types.py

def clone(self):
    """
    Makes an exact copy of this TemplateSegmentValue.

    Instead of mutating SegmentValue classes in place, it's recommended to clone them first.

    Returns:
        TemplateSegmentValue: The new segment value that's a copy of this one.
    """
    return TemplateSegmentValue(
        self.path, self.format, self.template, self.string_count, order=self.order
    )

is_empty()

Returns True if the template is blank.

Returns:

Name	Type	Description
boolean		True if the template is blank.

Source code in wagtail_localize/segments/types.py

def is_empty(self):
    """
    Returns True if the template is blank.

    Returns:
        boolean: True if the template is blank.
    """
    return self.template in ["", None]