PR: [WIP] update_font script

[kumattau]

Hi @dalthviz @ccordoba12

related to #188, #189, #191

This is a draft of the update_font.

For example,

(1) Codicon is updated to the latest release (0.0.26)

python update_font.py --prefix=msc --version=0.0.26 --cmaphex=0x --nopatch
Update started

Info URL      : https://github.com/microsoft/vscode-codicons/commit/a409f88773a7690461aaa651bd699271ee39e367

Charmap URL   : https://github.com/microsoft/vscode-codicons/raw/0.0.26/dist/codicon.css
Charmap Path  : qtawesome/fonts/codicon-charmap.json

Charmap Count : 476
Charmap Hex   : 0x

Font URL      : https://github.com/microsoft/vscode-codicons/raw/0.0.26/dist/codicon.ttf
Font Path     : qtawesome/fonts/codicon.ttf

Font md5sum   : 805fb6ad1751ed8b849b5bf9be742ab5

Patch Font    : nothing

Update finished

(2) FontAwesome5 Brands is updated to the master branch version

python update_font.py --prefix=fa5b --compat
Update started

Info URL      : https://github.com/FortAwesome/Font-Awesome/commit/7cbd7f9951be31f9d06b6ac97739a700320b9130

Charmap URL   : https://github.com/FortAwesome/Font-Awesome/raw/master/metadata/icons.json
Charmap Path  : qtawesome/fonts/fontawesome5-brands-webfont-charmap.json

Charmap Count : 457
Charmap Hex   : asis

Font URL      : https://github.com/FortAwesome/Font-Awesome/raw/master/webfonts/fa-brands-400.ttf
Font Path     : qtawesome/fonts/fontawesome5-brands-webfont.ttf

Font md5sum   : b37ae0f14cbc958316fac4635383b6e8

Patch Font    : utf-8      Font Family Name         -> Font Awesome 5 Free Brands
Patch Font    : utf-8      Full Font Name           -> Font Awesome 5 Free Brands
Patch Font    : utf-8      Typographic Family Name  -> Font Awesome 5 Free Brands
Patch Font    : utf-8      WWS Family Name          -> Font Awesome 5 Free Brands
Patch Font    : utf-16-be  Font Family Name         -> Font Awesome 5 Free Brands
Patch Font    : utf-16-be  Full Font Name           -> Font Awesome 5 Free Brands
Patch Font    : utf-16-be  Typographic Family Name  -> Font Awesome 5 Free Brands
Patch Font    : utf-16-be  WWS Family Name          -> Font Awesome 5 Free Brands

Font md5sum   : e4a11520df4bb6e8912e845c973ea212

Update finished

(3) Material Design Icons is updated to the v6.5.95 with default font patching

python update_font.py --prefix=mdi6 --version=v6.5.95
Update started

Info URL      : https://github.com/Templarian/MaterialDesign-Webfont/commit/8cfdab3f63b70c2948e68e134d58aab63e430a39

Charmap URL   : https://github.com/Templarian/MaterialDesign-Webfont/raw/v6.5.95/css/materialdesignicons.css
Charmap Path  : qtawesome/fonts/materialdesignicons6-webfont-charmap.json

Charmap Count : 6595
Charmap Hex   : asis

Font URL      : https://github.com/Templarian/MaterialDesign-Webfont/raw/v6.5.95/fonts/materialdesignicons-webfont.ttf
Font Path     : qtawesome/fonts/materialdesignicons6-webfont.ttf

Font md5sum   : b62641afc9ab487008e996a5c5865e56

Patch Font    : utf-8      Font Family Name         -> qta+b62641@Material Design Icons
Patch Font    : utf-8      Full Font Name           -> qta+b62641@Material Design Icons
Patch Font    : utf-8      PostScript Name          -> qta+b62641@MaterialDesignIcons
Patch Font    : utf-16-be  Font Family Name         -> qta+b62641@Material Design Icons
Patch Font    : utf-16-be  Full Font Name           -> qta+b62641@Material Design Icons
Patch Font    : utf-16-be  PostScript Name          -> qta+b62641@MaterialDesignIcons

Font md5sum   : 83f6f66aa42bf77cb652faf1962e5a65

Update finished

The update_font.py can update the corresponding font for each prefix.
The following options can be specified.

  --prefix {fa,fa5,fa5s,fa5b,ei,mdi,mdi6,ph,ri,msc}
  --version VERSION (git branch or tag)
  --cmaphex {asis,no,0x,0X} (for control charmap's value format, default: asis)
  --nopatch (don't patch font)
  --compat (run the original font patch for fa5/fa5s/fa5b)

As default, font family is renamed to f"qta+{md5sum(font)[:6]}@<original family>".
If you don't mind a lot of diffs, by update_font.py with --prefix and --version, all fonts can be updated without collide.

I think it is defficult for this update_font.py to merge to setupbase.py keeping compatibility.
In setupbase.py, FontAwesome5 zip is downloaded and processed but this is much special than other fonts.
So, I changed that, in update_font.py, FontAwesome5 ttf is downloaded and processed same as other fonts.

Could you try it and give me some feedback?

[dalthviz]

Hi @kumattau thank you for all the work on this !! After a quick review I think it could be nice to have this in the console_scripts entrypoint (add in setup.py an entry to the console_scripts pointing to the main function of the update_font script as is done for icon_browser) and add the missing/outdated documentation. Will check locally the script 👍

Furthermore, seeing that each font can potentially implement it's own logic if needed as done for FontAwesome5. I think this work kind off standarizes and makes available an utility command to update all the fonts available in a more in context way that using distutils.cmd.Command as interface/base abstract class. Seems resonable to me then to remove setupbase in favor of update_font.

However, just in case, what do you think @ccordoba12 ? Do you know if is there any reason to keep using the current approach with distutils.cmd.Command ?

[kumattau]

I added --cmapfmt option for more charmap formatting.
The original Material Design Icons's charmap is "ab-testing": "F01C9",
but qtawesome's charmap is "ab-testing": "0xf01c9".
To convert from original to qtawesome, the following options needs to be specified.

# convert charmap value to f"0x{value.lower()}"
python update_font.py --prefix=mdi6 --version=v6.5.95 --cmaphex=0x --cmapfmt=lower

[kumattau]

Thank you for feedback @dalthviz, I will try console_scripts !

Related to #188 (comment),
but the problem with this script is that it can update fonts, but it cannot add fonts.
This is because patch_iconic does not work well and it is difficult to add new font definitions in the python source (__init__.py).

To add new font, I think it is easiest to stop defining the source code
and detect the necessary definitions from the directory structure.
In this case, if fonts, json, and md5sum can be saved, there is no need to update the source code.

In addition, since the directory is divided by prefix, you can use the original font file name as it is,
and if you want to save the log output by update_font.py, it is easier to manage the log file.

For example, prefix "ph" defintion is detected from directory structure.

fonts/ph/phosphor.ttf
fonts/ph/phosphor-charmap.json
fonts/ph/phosphor-md5sum.txt
fonts/ph/phosphor-update.txt

[ccordoba12]

Do you know if is there any reason to keep using the current approach with distutils.cmd.Command ?

Probably because we were more familiar with distutils when that feature was implemented. But now we should replace it because distutils is going to be removed in the future.

[kumattau]

But now we should replace it because distutils is going to be removed in the future.

distutils in qtawesome can be replaced with setuptools. I sent PR #199.
I agree removing distutils, but I think it's simply a matter of preference.

[dalthviz]

Thanks for the PR @kumattau ! Although I think the idea will be to remove those commands in favor of the usage of the update_font script you are implementing here. So actually, you can remove those commands in this PR and then #199 will not be necessary. How that sounds to you?

[kumattau]

I think the traditional command should be supported for a few versions after the release of the update_font script to allow for a migration period.

The point I was trying to make is that the discontinuation of distutils is not a reason to discontinue the traditional commands, because distutils can be replaced with setuptools.

I like script, but I cannot answer which best, because I have not been able to compare it sufficiently with traditional commands.

This PR is still WIP, so I think applying #199 won't lose anything.

[dalthviz]

Ok @kumattau I will check PR #199 👍

Although I think that at the end we will need to remove the current subclasses in favor of the script here. Maybe we could check if makes sense to make the update_font script (the FontUpdater class in particular) a subclass of setuptools.Command while preserving the logic that it currently handles instead of adding update_font into the console_scripts entry point

[kumattau]

The point I was trying to make is that the discontinuation of distutils is not a reason to discontinue the traditional commands, because distutils can be replaced with setuptools.

Information sharing.

• setuptools document

https://setuptools.pypa.io/en/latest/deprecated/distutils-legacy.html#prefer-setuptools

Prefer Setuptools

As Distutils is deprecated, any usage of functions or objects from distutils is similarly discouraged, and Setuptools aims to replace or deprecate all such uses. This section describes the recommended replacements.

distutils.core.setup → setuptools.setup
distutils.cmd.Command → setuptools.Command
distutils.command.{build_clib,build_ext,build_py,sdist} → setuptools.command.*
distutils.log → (no replacement yet)
distutils.version.* → packaging.version.*
distutils.errors.* → setuptools.errors.*

• PEP 632 -- Deprecate distutils module

https://www.python.org/dev/peps/pep-0632/

Migration Advice

Note
This section suggests some alternative replacements for popular functionality that is being formally deprecated with this PEP. It is current at time of writing, but is not kept up to date.

For these modules or types, setuptools is the best substitute:

distutils.ccompiler
distutils.cmd.Command
distutils.command
distutils.config
distutils.core.Distribution
distutils.errors

For these modules or types, use the standards-defined Python Packaging Authority packages specified:

distutils.version — use the packaging package

For these modules or functions, use the standard library module shown:

distutils.fancy_getopt — use the argparse module
distutils.spawn.find_executable — use the shutil.which function
distutils.spawn.spawn — use the subprocess.run function
distutils.sysconfig — use the sysconfig module
distutils.util.get_platform — use the platform module

For these functions, and any others not mentioned here, you will need to reimplement the functionality yourself. The legacy documentation can be found at https://docs.python.org/3.9/distutils/apiref.html

distutils.dir_util.create_tree
distutils.util.change_root
distutils.util.strtobool

[kumattau]

@dalthviz

I think it could be nice to have this in the console_scripts entrypoint

I think it is better not to specify update_font.py in console_scrtipts.

console_scripts installs the specified script as user's script in the directory like as /usr/bin or $HOME/.local/bin,
but update_font.py focuses to update existing bundled fonts for qtawesome developpers,
and update_font.py lacks the following functions for qtawesome users.

• Updating the bundled fonts with keeping compatibility without user's care
• Installing new fonts and charmaps in user's fonts directory and updating them.

[dalthviz]

I think it is better not to specify update_font.py in console_scrtipts.

console_scripts installs the specified script as user's script in the directory like as /usr/bin or $HOME/.local/bin,
but update_font.py focuses to update existing bundled fonts for qtawesome developpers,
and update_font.py lacks the following functions for qtawesome users.

Updating the bundled fonts with keeping compatibility without user's care
Installing new fonts and charmaps in user's fonts directory and updating them.

That makes sense, actually I think that it would be better to have it as a cmdclass (then being accesible as the current update_fa5 or update_msc commands)