Move some files around

README.md

@@ -11,7 +11,20 @@ The Message and Resource representations are drawn from work done for the
 Unicode [MessageFormat 2 specification](https://github.com/unicode-org/message-format-wg/tree/main/spec)
 and the [Message resource specification](https://github.com/eemeli/message-resource-wg/).
 
-Support for XML formats (`android`, `xliff`) is an optional extra;
+The library currently supports the following resource formats:
+
+- `android`†: Android string resources (strings.xml)
+- `dtd`: .dtd
+- `fluent`: Fluent (.ftl)
+- `inc`: .inc
+- `ini`: .ini
+- `plain_json`: Plain JSON (.json)
+- `po`: Gettext (.po, .pot)
+- `properties`: .properties
+- `webext`: WebExtensions (messages.json)
+- `xliff`†: XLIFF 1.2, including XCode customizations (.xlf, .xliff)
+
+**†** Support for XML formats (`android`, `xliff`) is an optional extra;
 to support them, install as `moz.l10n[xml]`.
 
 ## Command-line Tools
@@ -48,9 +61,33 @@ Fix the formatting for localization resources.
 If `paths` is a single directory, it is iterated with `L10nConfigPaths` if `--config` is set, or `L10nDiscoverPaths` otherwise.
 If `paths` is not a single directory, its values are treated as glob expressions, with `**` support.
 
-## moz.l10n.paths
+## Python API
+
+### moz.l10n.formats.FORMAT
 
-### L10nConfigPaths
+Parsers and serializers are provided for a number of formats,
+using common and well-established libraries to take care of the details.
+A unified API for these is provided,
+such that `FORMAT_parse(text)` will always accept `str` input,
+and `FORMAT_serialize(resource)` will always provide a `str` iterator.
+All the serializers accept a `trim_comments` argument
+which leaves out comments from the serialized result,
+but additional input types and options vary by format.
+
+### moz.l10n.formats.detect_format
+
+```python
+from moz.l10n.formats import detect_format
+
+def detect_format(name: str | None, source: bytes | str) -> Format | None
+```
+
+Detect the format of the input based on its file extension
+and/or contents.
+
+Returns a `Format` enum value, or `None` if the input is not recognized.
+
+### moz.l10n.paths.L10nConfigPaths
 
 Wrapper for localization config files.
 
@@ -66,7 +103,7 @@ Differences:
 
 Does not consider `.l10n-ignore` files.
 
-### L10nDiscoverPaths
+### moz.l10n.paths.L10nDiscoverPaths
 
 Automagical localization resource discovery.
 
@@ -80,33 +117,11 @@ BCP 47 locale identifiers, i.e. like `aa`, `aa-AA`, `aa-Aaaa`, or `aa-Aaaa-AA`.
 
 An underscore may also be used as a separator, as in `en_US`.
 
-## moz.l10n.resources
-
-Parsers and serializers are provided for a number of formats,
-using common and well-established libraries to take care of the details.
-A unified API for these is provided,
-such that `FORMAT_parse(text)` will always accept `str` input,
-and `FORMAT_serialize(resource)` will always provide a `str` iterator.
-All the serializers accept a `trim_comments` argument
-which leaves out comments from the serialized result,
-but additional input types and options vary by format.
-
-The library currently supports the following resource formats:
-
-- `android`: Android string resources (strings.xml)
-- `dtd`: .dtd
-- `fluent`: Fluent (.ftl)
-- `inc`: .inc
-- `ini`: .ini
-- `plain_json`: Plain JSON (.json)
-- `po`: Gettext (.po, .pot)
-- `properties`: .properties
-- `webext`: WebExtensions (messages.json)
-- `xliff`: XLIFF 1.2, including XCode customizations (.xlf, .xliff)
-
-### add_entries
+### moz.l10n.resource.add_entries
 
 ```python
+from moz.l10n.resource import add_entries
+
 def add_entries(
     target: Resource,
     source: Resource,
@@ -126,42 +141,11 @@ Entries are not copied, so further changes will be reflected in both resources.
 
 Returns a count of added or changed entries and sections.
 
-### detect_format
+### moz.l10n.resource.l10n_equal
 
 ```python
-def detect_format(name: str | None, source: bytes | str) -> Format | None
-```
+from moz.l10n.resource import l10n_equal
 
-Detect the format of the input based on its file extension
-and/or contents.
-
-Returns a `Format` enum value, or `None` if the input is not recognized.
-
-### iter_resources
-
-```python
-def iter_resources(
-    root: str,
-    dirs: list[str] | None = None,
-    ignorepath: str = ".l10n-ignore"
-) -> Iterator[tuple[str, Resource[Message, str] | None]]
-```
-
-Iterate through localizable resources under the `root` directory.
-Use `dirs` to limit the search to only some subdirectories under `root`.
-
-Yields `(str, Resource | None)` tuples,
-with the file path and the corresponding `Resource`,
-or `None` for files that could not be parsed as localization resources.
-
-To ignore files, include a `.l10n-ignore` file in `root`,
-or some other location passed in as `ignorepath`.
-This file uses a git-ignore syntax,
-and is always based in the `root` directory.
-
-### l10n_equal
-
-```python
 def l10n_equal(a: Resource, b: Resource) -> bool
 ```
 
@@ -171,9 +155,11 @@ Compares the localization-relevant content
 Sections with no message entries are ignored,
 and the order of sections, entries, and metadata is ignored.
 
-### parse_resource
+### moz.l10n.resource.parse_resource
 
 ```python
+from moz.l10n.resource import parse_resource
+
 def parse_resource(
     input: Format | str | None,
     source: str | bytes | None = None
@@ -191,9 +177,11 @@ If the first argument is a string path,
 the `source` argument is optional,
 as the file will be opened and read.
 
-### serialize_resource
+### moz.l10n.resource.serialize_resource
 
 ```python
+from moz.l10n.resource import serialize_resource
+
 def serialize_resource(
     resource: Resource[str, str] | Resource[Message, str],
     format: Format | None = None,
@@ -207,3 +195,24 @@ If `format` is set, it overrides the `resource.format` value.
 
 With `trim_comments`,
 all standalone and attached comments are left out of the serialization.
+
+### moz.l10n.util.walk_files
+
+```python
+from moz.l10n.util import walk_files
+
+def walk_files(
+    root: str,
+    dirs: list[str] | None = None,
+    ignorepath: str | None = ".l10n-ignore"
+) -> Iterator[str]
+```
+
+Iterate through all files under the `root` directory.
+Use `dirs` to limit the search to only some subdirectories under `root`.
+
+All files and directories with names starting with `.` are ignored.
+To ignore other files, include a `.l10n-ignore` file in `root`,
+or some other location passed in as `ignorepath`.
+This file uses git-ignore syntax,
+and is always based in the `root` directory.

moz/l10n/bin/build.py

@@ -22,11 +22,11 @@
 from shutil import copyfile
 from textwrap import dedent
 
-from moz.l10n.message import Message
+from moz.l10n.formats import Format
+from moz.l10n.message.data import Message
 from moz.l10n.paths.config import L10nConfigPaths
 from moz.l10n.resource import UnsupportedResource, parse_resource, serialize_resource
 from moz.l10n.resource.data import Comment, Entry, Resource, Section
-from moz.l10n.resource.format import Format
 
 log = logging.getLogger(__name__)
 

moz/l10n/resource/format.py → moz/l10n/formats/__init__.py

@@ -20,7 +20,7 @@
 from os.path import splitext
 from typing import Any
 
-# from moz.l10n.resource.xliff.common import xliff_ns
+# from moz.l10n.formats.xliff.common import xliff_ns
 xliff_ns = {
     "urn:oasis:names:tc:xliff:document:1.0",
     "urn:oasis:names:tc:xliff:document:1.1",

moz/l10n/resource/android/parse.py → moz/l10n/formats/android/parse.py

@@ -19,7 +19,7 @@
 
 from lxml import etree
 
-from ...message import (
+from ...message.data import (
     CatchallKey,
     Expression,
     FunctionAnnotation,
@@ -29,8 +29,8 @@
     SelectMessage,
     VariableRef,
 )
-from ..data import Comment, Entry, Metadata, Resource, Section
-from ..format import Format
+from ...resource.data import Comment, Entry, Metadata, Resource, Section
+from .. import Format
 
 plural_categories = ("zero", "one", "two", "few", "many", "other")
 xliff_ns = "urn:oasis:names:tc:xliff:document:1.2"

moz/l10n/resource/android/serialize.py → moz/l10n/formats/android/serialize.py

@@ -20,7 +20,7 @@
 
 from lxml import etree
 
-from ...message import (
+from ...message.data import (
     CatchallKey,
     Expression,
     FunctionAnnotation,
@@ -30,7 +30,7 @@
     SelectMessage,
     VariableRef,
 )
-from ..data import Entry, Metadata, Resource
+from ...resource.data import Entry, Metadata, Resource
 from .parse import plural_categories, resource_ref, xliff_g, xliff_ns, xml_name
 
 

moz/l10n/resource/dtd/parse.py → moz/l10n/formats/dtd/parse.py

@@ -22,10 +22,9 @@
 from sys import maxsize
 from typing import Any
 
-from moz.l10n.message import Message, PatternMessage
-
-from ..data import Comment, Entry, Resource, Section
-from ..format import Format
+from ...message.data import Message, PatternMessage
+from ...resource.data import Comment, Entry, Resource, Section
+from .. import Format
 
 name_start_char = (
     ":A-Z_a-z\xc0-\xd6\xd8-\xf6\xf8-\u02ff"

moz/l10n/resource/dtd/serialize.py → moz/l10n/formats/dtd/serialize.py

@@ -18,9 +18,8 @@
 from re import UNICODE, compile
 from typing import Any
 
-from moz.l10n.message import Message, PatternMessage
-
-from ..data import Entry, Resource
+from ...message.data import Message, PatternMessage
+from ...resource.data import Entry, Resource
 from .parse import name, re_comment
 
 re_name = compile(name, UNICODE)

moz/l10n/resource/fluent/parse.py → moz/l10n/formats/fluent/parse.py

@@ -22,9 +22,9 @@
 from fluent.syntax import FluentParser
 from fluent.syntax import ast as ftl
 
-from ... import message as msg
-from .. import data as res
-from ..format import Format
+from ...message import data as msg
+from ...resource import data as res
+from .. import Format
 
 
 @overload

moz/l10n/resource/fluent/serialize.py → moz/l10n/formats/fluent/serialize.py

@@ -21,8 +21,8 @@
 from fluent.syntax import FluentSerializer
 from fluent.syntax import ast as ftl
 
-from ... import message as msg
-from .. import data as res
+from ...message import data as msg
+from ...resource import data as res
 
 
 def fluent_serialize(

moz/l10n/resource/inc/parse.py → moz/l10n/formats/inc/parse.py

@@ -17,10 +17,9 @@
 from re import compile
 from typing import Any
 
-from moz.l10n.message import Message, PatternMessage
-
-from ..data import Comment, Entry, Resource, Section
-from ..format import Format
+from ...message.data import Message, PatternMessage
+from ...resource.data import Comment, Entry, Resource, Section
+from .. import Format
 
 re_define = compile(r"#define[ \t]+(\w+)(?:[ \t](.*))?")
 

moz/l10n/resource/inc/serialize.py → moz/l10n/formats/inc/serialize.py

@@ -17,9 +17,8 @@
 from collections.abc import Iterator
 from typing import Any
 
-from moz.l10n.message import Message, PatternMessage
-
-from ..data import Entry, Resource
+from ...message.data import Message, PatternMessage
+from ...resource.data import Entry, Resource
 
 
 def inc_serialize(

moz/l10n/resource/ini/parse.py → moz/l10n/formats/ini/parse.py

@@ -19,10 +19,9 @@
 
 from iniparse import ini  # type: ignore[import-untyped]
 
-from moz.l10n.message import Message, PatternMessage
-
-from ..data import Comment, Entry, Resource, Section
-from ..format import Format
+from ...message.data import Message, PatternMessage
+from ...resource.data import Comment, Entry, Resource, Section
+from .. import Format
 
 
 def ini_parse(source: TextIO | str | bytes) -> Resource[Message, Any]:

moz/l10n/resource/ini/serialize.py → moz/l10n/formats/ini/serialize.py

@@ -18,9 +18,8 @@
 from re import search
 from typing import Any
 
-from moz.l10n.message import Message, PatternMessage
-
-from ..data import Entry, Resource
+from ...message.data import Message, PatternMessage
+from ...resource.data import Entry, Resource
 
 
 def ini_serialize(

moz/l10n/resource/plain_json/parse.py → moz/l10n/formats/plain_json/parse.py

@@ -18,10 +18,9 @@
 from json import loads
 from typing import Any
 
-from moz.l10n.message import Message, PatternMessage
-
-from ..data import Entry, Resource, Section
-from ..format import Format
+from ...message.data import Message, PatternMessage
+from ...resource.data import Entry, Resource, Section
+from .. import Format
 
 
 def plain_json_parse(source: str | bytes) -> Resource[Message, Any]:

moz/l10n/resource/plain_json/serialize.py → moz/l10n/formats/plain_json/serialize.py

@@ -19,9 +19,8 @@
 from json import dumps
 from typing import Any
 
-from moz.l10n.message import Message, PatternMessage
-
-from ..data import Entry, Resource
+from ...message.data import Message, PatternMessage
+from ...resource.data import Entry, Resource
 
 
 def plain_json_serialize(