Segment value types
These classes are used to represent segment values in Python without needing a model instance.
BaseValue
clone(self)
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(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')
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(self, 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(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')
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
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. |
__init__(self, path, data, **kwargs)
special
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(self)
Makes an exact copy of this OverridableSegmentValue.
Instead of mutating SegmentValue classes in place, it's recommended to clone them first.
Returns:
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(self)
Returns True if the data is empty.
Returns:
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
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 |
order |
int |
The index that this segment appears on a page. |
__init__(self, path, content_type, translation_key, **kwargs)
special
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 |
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(self)
Makes an exact copy of this RelatedObjectSegmentValue.
Instead of mutating SegmentValue classes in place, it's recommended to clone them first.
Returns:
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 |
Exceptions:
Type | Description |
---|---|
AttributeError |
If the instance is not translatable. |
Returns:
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(self, locale)
Gets an instance of the referenced translatable object for the given locale.
Exceptions:
Type | Description |
---|---|
Model.DoesNotExist |
If there isn't an instance of the translatable object in the given locale. |
Returns:
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(self)
Returns True if the related object is null.
Returns:
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
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. |
__init__(self, path, string, attrs=None, **kwargs)
special
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(
"`string` must be either a `StringValue` or a `str`. Got `{}`".format(
type(string).__name__
)
)
self.string = string
self.attrs = attrs or None
super().__init__(path, **kwargs)
clone(self)
Makes an exact copy of this StringSegmentValue.
Instead of mutating SegmentValue classes in place, it's recommended to clone them first.
Returns:
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(self)
Returns True if the StringValue is blank.
Returns:
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(self)
Returns a HTML representation of the segment value.
Note: If the segment value was created from plain text, this escapes special characters.
Returns:
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(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:
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
Represents a 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. |
__init__(self, path, format, template, string_count, **kwargs)
special
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(self)
Makes an exact copy of this TemplateSegmentValue.
Instead of mutating SegmentValue classes in place, it's recommended to clone them first.
Returns:
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(self)
Returns True if the template is blank.
Returns:
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]