python-fontbro 0.28.0__tar.gz → 0.29.0__tar.gz

{python_fontbro-0.28.0/python_fontbro.egg-info → python_fontbro-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-fontbro
-Version: 0.28.0
+Version: 0.29.0
 Summary: friendly font operations on top of fontTools.
 Author-email: Fabio Caccamo <fabio.caccamo@gmail.com>
 Maintainer-email: Fabio Caccamo <fabio.caccamo@gmail.com>
@@ -138,6 +138,7 @@ with open("fonts/MyFont.ttf") as fh:
 -   [`get_variable_instance_by_style_name`](#get_variable_instance_by_style_name)
 -   [`get_variable_instance_closest_to_coordinates`](#get_variable_instance_closest_to_coordinates)
 -   [`get_version`](#get_version)
+-   [`get_version_formatted`](#get_version_formatted)
 -   [`get_vertical_metrics`](#get_vertical_metrics)
 -   [`get_weight`](#get_weight)
 -   [`get_width`](#get_width)
@@ -163,6 +164,7 @@ with open("fonts/MyFont.ttf") as fh:
 -   [`set_style_flags`](#set_style_flags)
 -   [`set_style_flags_by_subfamily_name`](#set_style_flags_by_subfamily_name)
 -   [`set_style_name`](#set_style_name)
+-   [`set_version`](#set_version)
 -   [`set_vertical_metrics`](#set_vertical_metrics)
 -   [`subset`](#subset)
 -   [`to_sliced_variable`](#to_sliced_variable)
@@ -784,13 +786,48 @@ instance = font.get_variable_instance_closest_to_coordinates(
 #### `get_version`
 ```python
 """
-Gets the font version.
+Gets the font version reading it from head.fontRevision,
+with fallback on the version name record (name id 5) parsed value,
+eg. "Version 1.015;git-0a5106e0b" -> 1.015.
 
-:returns: The font version value.
+:param use_head_revision: If True, the head.fontRevision value is used (if set).
+:type use_head_revision: bool
+:param use_name_record: If True, the version name record value is used as fallback.
+:type use_name_record: bool
+
+:returns: The font version value, 0.0 if the version cannot be read.
 :rtype: float
+
+:raises ArgumentError: If both options are False.
 """
 
-version = font.get_version()
+version = font.get_version(use_head_revision=True, use_name_record=True)
+```
+
+#### `get_version_formatted`
+```python
+"""
+Gets the font version formatted using the version name record convention,
+with the given prefix and a minimum of 3 decimal digits, eg. "v1.015".
+
+:param use_head_revision: If True, the head.fontRevision value is used (if set).
+:type use_head_revision: bool
+:param use_name_record: If True, the version name record value is used as fallback.
+:type use_name_record: bool
+:param prefix: The prefix to prepend to the version value.
+:type prefix: str
+
+:returns: The formatted font version value, eg. "v0.000" if the version cannot be read.
+:rtype: str
+
+:raises ArgumentError: If both source options are False.
+"""
+
+version = font.get_version_formatted(
+    use_head_revision=True,
+    use_name_record=True,
+    prefix="v",
+)
 ```
 
 #### `get_vertical_metrics`
@@ -1240,6 +1277,28 @@ Sets the style name updating the related font names records.
 font.set_style_name(name="Bold Italic")
 ```
 
+#### `set_version`
+```python
+"""
+Sets the font version, the version value can be a number (eg. 1.015)
+or a version string (eg. "Version 1.015"), parsed the same way the
+version name record value is parsed when read.
+The head.fontRevision and the version name record (name id 5) are
+updated, the latter is overwritten with the canonical "Version X.YYY"
+form (any extra info it contained is dropped).
+The unique identifier name record (name id 3) is updated only if its
+first ";" separated part holds the current version value, and only in
+that part. The CFF version is updated only if the font already has it.
+
+:param version: The version value, eg. 1.015 or "Version 1.015"
+:type version: float or str
+
+:raises ArgumentError: If the version value is not valid.
+"""
+
+font.set_version(1.015)
+```
+
 #### `set_vertical_metrics`
 ```python
 """

{python_fontbro-0.28.0 → python_fontbro-0.29.0}/README.md

@@ -74,6 +74,7 @@ with open("fonts/MyFont.ttf") as fh:
 -   [`get_variable_instance_by_style_name`](#get_variable_instance_by_style_name)
 -   [`get_variable_instance_closest_to_coordinates`](#get_variable_instance_closest_to_coordinates)
 -   [`get_version`](#get_version)
+-   [`get_version_formatted`](#get_version_formatted)
 -   [`get_vertical_metrics`](#get_vertical_metrics)
 -   [`get_weight`](#get_weight)
 -   [`get_width`](#get_width)
@@ -99,6 +100,7 @@ with open("fonts/MyFont.ttf") as fh:
 -   [`set_style_flags`](#set_style_flags)
 -   [`set_style_flags_by_subfamily_name`](#set_style_flags_by_subfamily_name)
 -   [`set_style_name`](#set_style_name)
+-   [`set_version`](#set_version)
 -   [`set_vertical_metrics`](#set_vertical_metrics)
 -   [`subset`](#subset)
 -   [`to_sliced_variable`](#to_sliced_variable)
@@ -720,13 +722,48 @@ instance = font.get_variable_instance_closest_to_coordinates(
 #### `get_version`
 ```python
 """
-Gets the font version.
+Gets the font version reading it from head.fontRevision,
+with fallback on the version name record (name id 5) parsed value,
+eg. "Version 1.015;git-0a5106e0b" -> 1.015.
 
-:returns: The font version value.
+:param use_head_revision: If True, the head.fontRevision value is used (if set).
+:type use_head_revision: bool
+:param use_name_record: If True, the version name record value is used as fallback.
+:type use_name_record: bool
+
+:returns: The font version value, 0.0 if the version cannot be read.
 :rtype: float
+
+:raises ArgumentError: If both options are False.
 """
 
-version = font.get_version()
+version = font.get_version(use_head_revision=True, use_name_record=True)
+```
+
+#### `get_version_formatted`
+```python
+"""
+Gets the font version formatted using the version name record convention,
+with the given prefix and a minimum of 3 decimal digits, eg. "v1.015".
+
+:param use_head_revision: If True, the head.fontRevision value is used (if set).
+:type use_head_revision: bool
+:param use_name_record: If True, the version name record value is used as fallback.
+:type use_name_record: bool
+:param prefix: The prefix to prepend to the version value.
+:type prefix: str
+
+:returns: The formatted font version value, eg. "v0.000" if the version cannot be read.
+:rtype: str
+
+:raises ArgumentError: If both source options are False.
+"""
+
+version = font.get_version_formatted(
+    use_head_revision=True,
+    use_name_record=True,
+    prefix="v",
+)
 ```
 
 #### `get_vertical_metrics`
@@ -1176,6 +1213,28 @@ Sets the style name updating the related font names records.
 font.set_style_name(name="Bold Italic")
 ```
 
+#### `set_version`
+```python
+"""
+Sets the font version, the version value can be a number (eg. 1.015)
+or a version string (eg. "Version 1.015"), parsed the same way the
+version name record value is parsed when read.
+The head.fontRevision and the version name record (name id 5) are
+updated, the latter is overwritten with the canonical "Version X.YYY"
+form (any extra info it contained is dropped).
+The unique identifier name record (name id 3) is updated only if its
+first ";" separated part holds the current version value, and only in
+that part. The CFF version is updated only if the font already has it.
+
+:param version: The version value, eg. 1.015 or "Version 1.015"
+:type version: float or str
+
+:raises ArgumentError: If the version value is not valid.
+"""
+
+font.set_version(1.015)
+```
+
 #### `set_vertical_metrics`
 ```python
 """

{python_fontbro-0.28.0 → python_fontbro-0.29.0}/fontbro/files.py

@@ -93,14 +93,3 @@ def get_filename(
     extension = get_format(ttfont)
     filename = f"{basename}.{extension}"
     return filename
-
-
-def get_version(
-    ttfont: TTFont,
-) -> float:
-    """
-    Gets the version of the given font (head.fontRevision).
-    """
-    head = ttfont.get("head")
-    version = float(head.fontRevision)
-    return version

{python_fontbro-0.28.0 → python_fontbro-0.29.0}/fontbro/font.py

@@ -29,6 +29,7 @@ from fontbro import support as _support
 from fontbro import tables as _tables
 from fontbro import unicode as _unicode
 from fontbro import variable as _variable
+from fontbro import version as _version
 from fontbro.exceptions import (
     ArgumentError,
     OperationError,
@@ -1027,15 +1028,62 @@ class Font:
 
     def get_version(
         self,
+        *,
+        use_head_revision: bool = True,
+        use_name_record: bool = True,
     ) -> float:
         """
-        Gets the font version.
+        Gets the font version reading it from head.fontRevision,
+        with fallback on the version name record (name id 5) parsed value,
+        eg. "Version 1.015;git-0a5106e0b" -> 1.015.
+
+        :param use_head_revision: If True, the head.fontRevision value is used (if set).
+        :type use_head_revision: bool
+        :param use_name_record: If True, the version name record value is used as fallback.
+        :type use_name_record: bool
 
-        :returns: The font version value.
+        :returns: The font version value, 0.0 if the version cannot be read.
         :rtype: float
+
+        :raises ArgumentError: If both options are False.
+        """
+        ttfont = self.get_ttfont()
+        return _version.get_version(
+            ttfont,
+            use_head_revision=use_head_revision,
+            use_name_record=use_name_record,
+        )
+
+    def get_version_formatted(
+        self,
+        *,
+        use_head_revision: bool = True,
+        use_name_record: bool = True,
+        prefix: str = "v",
+    ) -> str:
+        """
+        Gets the font version formatted using the version name record convention,
+        with the given prefix and a minimum of 3 decimal digits, eg. "v1.015".
+
+        :param use_head_revision: If True, the head.fontRevision value is used (if set).
+        :type use_head_revision: bool
+        :param use_name_record: If True, the version name record value is used as fallback.
+        :type use_name_record: bool
+        :param prefix: The prefix to prepend to the version value.
+        :type prefix: str
+
+        :returns: The formatted font version value, eg. "v0.000" if the version cannot be read.
+        :rtype: str
+
+        :raises ArgumentError: If both source options are False.
         """
         ttfont = self.get_ttfont()
-        return _files.get_version(ttfont)
+        return _version.get_version_formatted(
+            ttfont,
+            use_head_revision=use_head_revision,
+            use_name_record=use_name_record,
+            prefix=prefix,
+        )
 
     def get_vertical_metrics(
         self,
@@ -1670,6 +1718,29 @@ class Font:
             style_name=name,
         )
 
+    def set_version(
+        self,
+        version: float | str,
+    ) -> None:
+        """
+        Sets the font version, the version value can be a number (eg. 1.015)
+        or a version string (eg. "Version 1.015"), parsed the same way the
+        version name record value is parsed when read.
+        The head.fontRevision and the version name record (name id 5) are
+        updated, the latter is overwritten with the canonical "Version X.YYY"
+        form (any extra info it contained is dropped).
+        The unique identifier name record (name id 3) is updated only if its
+        first ";" separated part holds the current version value, and only in
+        that part. The CFF version is updated only if the font already has it.
+
+        :param version: The version value, eg. 1.015 or "Version 1.015"
+        :type version: float or str
+
+        :raises ArgumentError: If the version value is not valid.
+        """
+        ttfont = self.get_ttfont()
+        _version.set_version(ttfont, version)
+
     def set_vertical_metrics(
         self,
         **vertical_metrics: Any,

{python_fontbro-0.28.0 → python_fontbro-0.29.0}/fontbro/metadata.py

@@ -4,4 +4,4 @@ __description__ = "friendly font operations on top of fontTools."
 __email__ = "fabio.caccamo@gmail.com"
 __license__ = "MIT"
 __title__ = "python-fontbro"
-__version__ = "0.28.0"
+__version__ = "0.29.0"

{python_fontbro-0.28.0 → python_fontbro-0.29.0}/fontbro/names.py

@@ -72,6 +72,8 @@ _NAMES_BY_KEY: dict[str, dict[str, Any]] = {item["key"]: item for item in _NAMES
 _NAMES_WIN_IDS: dict[str, Any] = {"platformID": 3, "platEncID": 1, "langID": 0x409}
 # macintosh: platform 1, encoding 0 (roman), language 0 (english)
 _NAMES_MAC_IDS: dict[str, Any] = {"platformID": 1, "platEncID": 0, "langID": 0x0}
+# unicode: platform 0, encoding 3 (unicode bmp), language 0 (no language)
+_NAMES_UNI_IDS: dict[str, Any] = {"platformID": 0, "platEncID": 3, "langID": 0x0}
 
 
 def _get_name_id(
@@ -101,6 +103,10 @@ def _is_encodable(
         platform_ids["platEncID"],
         platform_ids["langID"],
     )
+    if not encoding:
+        # the encoding of the name records is unknown (eg. the macintosh
+        # "uninterpreted" script), so the value cannot be written to them
+        return False
     try:
         value.encode(encoding)
     except UnicodeEncodeError:
@@ -108,6 +114,31 @@ def _is_encodable(
     return True
 
 
+def _get_name_records_ids(
+    name_table: Any,
+    name_id: int,
+    platform_ids: dict[str, Any],
+) -> list[dict[str, Any]]:
+    """
+    Gets the ids of the existing name records with the given name id, matching
+    the platform and the language of the given platform ids. The encoding is
+    not matched: the same name id can have more than one record with different
+    encodings (eg. a windows symbol record and a windows unicode one).
+    Records in other languages are not matched, so they are never overwritten.
+    """
+    return [
+        {
+            "platformID": record.platformID,
+            "platEncID": record.platEncID,
+            "langID": record.langID,
+        }
+        for record in name_table.names
+        if record.nameID == name_id
+        and record.platformID == platform_ids["platformID"]
+        and record.langID == platform_ids["langID"]
+    ]
+
+
 def get_name(
     ttfont: TTFont,
     key: int | str,
@@ -116,11 +147,20 @@ def get_name(
     Gets the name by its identifier from the name table of the given font.
     """
     name_id = _get_name_id(key)
-    name_table = ttfont["name"]
-    name = name_table.getName(name_id, **_NAMES_WIN_IDS)
-    if not name:
-        name = name_table.getName(name_id, **_NAMES_MAC_IDS)
-    return str(name.toUnicode()) if name else None
+    name_table = ttfont.get("name")
+    if not name_table:
+        return None
+    # the windows english record is preferred: mac records are legacy
+    # and they can follow different naming conventions (eg. name id 1)
+    name_record = name_table.getName(name_id, **_NAMES_WIN_IDS)
+    if name_record:
+        try:
+            return str(name_record.toUnicode())
+        except UnicodeDecodeError:
+            pass
+    # fallback to the english (mac) record or to any other decodable record
+    name: str | None = name_table.getDebugName(name_id)
+    return name
 
 
 def get_names(
@@ -129,12 +169,12 @@ def get_names(
     """
     Gets the names records of the given font mapped by their property name.
     """
-    names_by_id = {record.nameID: f"{record}" for record in ttfont["name"].names}
-    names = {
-        _NAMES_BY_ID[name_id]["key"]: value
-        for name_id, value in names_by_id.items()
-        if name_id in _NAMES_BY_ID
-    }
+    # read each name as get_name does, to get consistent values
+    names = {}
+    for name_id, name_item in _NAMES_BY_ID.items():
+        name = get_name(ttfont, name_id)
+        if name is not None:
+            names[name_item["key"]] = name
     return names
 
 
@@ -149,14 +189,23 @@ def set_name(
     name_id = _get_name_id(key)
     name_table = ttfont["name"]
     # https://github.com/fonttools/fonttools/blob/main/Lib/fontTools/ttLib/tables/_n_a_m_e.py#L568
+    # the windows record is always written, it's the one read first by get_name
     name_table.setName(value, name_id, **_NAMES_WIN_IDS)
-    # the mac roman encoding can't encode many characters (eg. greek, cyrillic, cjk),
-    # in that case the mac name record is removed (as fontTools addMultilingualName
-    # does), otherwise the font would raise UnicodeEncodeError when saved
-    if _is_encodable(value, _NAMES_MAC_IDS):
-        name_table.setName(value, name_id, **_NAMES_MAC_IDS)
-    else:
-        name_table.removeNames(nameID=name_id, **_NAMES_MAC_IDS)
+    # the other records of the same name id are updated only if the font
+    # already has them (mac and unicode records are legacy, modern tools don't
+    # produce them anymore, so they are never added): a record left with its
+    # previous value would contradict the record just written
+    for platform_ids in (_NAMES_WIN_IDS, _NAMES_UNI_IDS, _NAMES_MAC_IDS):
+        for record_ids in _get_name_records_ids(name_table, name_id, platform_ids):
+            # the value is written only if the record encoding can encode it
+            # (eg. mac roman can't encode greek, cyrillic, cjk), otherwise the
+            # record is removed (as fontTools addMultilingualName does),
+            # because the font would raise UnicodeEncodeError when saved;
+            # removing it is safe because the windows record has just been written
+            if _is_encodable(value, record_ids):
+                name_table.setName(value, name_id, **record_ids)
+            else:
+                name_table.removeNames(nameID=name_id, **record_ids)
 
 
 def set_names(