Source code
Revision control
Copy as Markdown
Other Tools
# Copyright Mozilla Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Generic, TypeVar
from .format import Format
__all__ = [
"Comment",
"Entry",
"Metadata",
"Resource",
"Section",
]
M = TypeVar("M")
"""
The metadata value type.
"""
V = TypeVar("V")
"""
The Message value type.
"""
@dataclass
class LinePos:
"""
The source line position of an entry or section header.
"""
start: int
"""
The starting line of the entry or section.
May be less than `value` if preceded by a comment.
"""
key: int
"""
The start line of the entry or section header key or name.
"""
value: int
"""
The start line of the entry pattern or section header.
"""
end: int
"""
The line one past the end of the entry or section header.
"""
@dataclass
class Metadata(Generic[M]):
"""
Metadata is attached to a resource, section, or a single entry.
The type parameter defines the metadata value type.
"""
key: str
"""
A non-empty string keyword.
Most likely a sequence of `a-z` characters,
but may technically contain any characters
which might require escaping in the syntax.
"""
value: M
"""
The metadata contents.
String values have all their character \\escapes processed.
"""
@dataclass
class Comment:
comment: str
"""
A standalone comment.
May contain multiple lines separated by newline characters.
Lines should have any comment-start sigil and up to one space trimmed from the start,
along with any trailing whitespace.
An empty or whitespace-only comment will be represented by an empty string.
"""
@dataclass
class Entry(Generic[V, M]):
"""
A message entry.
The first type parameter defines the Message value type,
and the second one defines the metadata value type.
"""
id: tuple[str, ...]
"""
The entry identifier.
This MUST be a non-empty array of non-empty `string` values.
The entry identifiers are not normalized,
i.e. they do not include this identifier.
In a valid resource, each entry has a distinct normalized identifier,
i.e. the concatenation of its section header identifier (if any) and its own.
"""
value: V
"""
The value of an entry, i.e. the message.
String values have all their character \\escapes processed.
"""
comment: str = ""
"""
A comment on this entry.
May contain multiple lines separated by newline characters.
Lines should have any comment-start sigil and up to one space trimmed from the start,
along with any trailing whitespace.
An empty or whitespace-only comment will be represented by an empty string.
"""
meta: list[Metadata[M]] = field(default_factory=list)
"""
Metadata attached to this entry.
"""
linepos: LinePos | None = None
"""
The parsed position of the entry,
available for some formats.
"""
@dataclass
class Section(Generic[V, M]):
"""
A section of a resource.
The first type parameter defines the Message value type,
and the second one defines the metadata value type.
"""
id: tuple[str, ...]
"""
The section identifier.
Each `string` part of the identifier MUST be a non-empty string.
The top-level or anonymous section has an empty `id` array.
The resource syntax requires this array to be non-empty
for all sections after the first one,
but empty identifier arrays MAY be used
when this data model is used to represent other message resource formats,
such as Fluent FTL files.
The entry identifiers are not normalized,
i.e. they do not include this identifier.
"""
entries: list[Entry[V, M] | Comment]
"""
Section entries consist of message entries and comments.
Empty lines are not included in the data model.
"""
comment: str = ""
"""
A comment on the whole section, which applies to all of its entries.
May contain multiple lines separated by newline characters.
Lines should have any comment-start sigil and up to one space trimmed from the start,
along with any trailing whitespace.
An empty or whitespace-only comment will be represented by an empty string.
"""
meta: list[Metadata[M]] = field(default_factory=list)
"""
Metadata attached to this section.
"""
linepos: LinePos | None = None
"""
The parsed position of the section,
available for some formats.
"""
@dataclass
class Resource(Generic[V, M]):
"""
A message resource.
The first type parameter defines the Message value type,
and the second one defines the metadata value type.
"""
format: Format | None
"""
The serialization format for the resource, if any.
"""
sections: list[Section[V, M]]
"""
The body of a resource, consisting of an array of sections.
A valid resource may have an empty sections array.
"""
comment: str = ""
"""
A comment on the whole resource, which applies to all of its sections and entries.
May contain multiple lines separated by newline characters.
Lines should have any comment-start sigil and up to one space trimmed from the start,
along with any trailing whitespace.
An empty or whitespace-only comment will be represented by an empty string.
"""
meta: list[Metadata[M]] = field(default_factory=list)
"""
Metadata attached to the whole resource.
"""