mcfonts¶

mcfonts is a versatile, fast, and extensible package for working with Minecraft fonts.

mcfonts works with any valid font JSON and can export every kind of texture and sizing.

Submodules¶

Package Contents¶

Classes¶

Functions¶

Attributes¶

class mcfonts.MinecraftFont(provider_list, is_monochrome=True)¶

The MinecraftFont class.

Requires the providers of a provider file, and the associated resources mapping.

You should never instantiate this class directly. Use mcfonts.importing.

If you need to add, modify, or remove providers, do it through self.providers; it's a list of Provider classes, each containing relevant fields and methods.

Be sure to run mcfonts.MinecraftFont.validate() after making any changes; it won't be done automatically.

Warning

If more than one mcfonts.providers.OptionsProvider is present in provider_list, only the last one will be used.

Parameters:¶

provider_list : list[providers.base.Provider]¶

A list of providers, all of which are instances of mcfonts.providers.base.Provider.

is_monochrome : bool¶

Whether font resources are loaded in grayscale or not. Default is True.

providers¶

Do not iterate over this! Use yield_providers() instead.

compact(chars_in_row=0, cell_size=(0, 0), square_cells=True, output_file=None)¶

Take all "bitmap" providers and export every character sheet into a single sheet.

Characters are scaled according to the largest effective bounding box in all providers.

Parameters:¶

chars_in_row : int¶

How many characters to fit inside each row of the resulting sheet. If this is 0, this will be set to the length of the first string in the "charlist" list. If this is negative, this will be set so that the resulting sheet is square. By default, this is 0 (auto first string).

cell_size : tuple[int, int]¶

What size to make each glyph cell. If this is (0, 0), this will be set to the largest dimensions of every glyph in glyphs.

square_cells : bool¶

If True, each glyph's width will equal its height. This is based on whichever number is largest. If False, each glyph's width will be unrelated to its height.

output_file : str | None¶

Where to write the sheet to. If this is None, nothing will be written.

Returns:¶

A list of the new characters, and the new file as a PIL.Image.Image.

Return type:¶

tuple[list[str], PIL.Image.Image, tuple[int, int]]

compare(other)¶

Given other, compare the two, using self as a baseline.

The information compared is:

• Character count

• Blocks covered

• Providers included

Parameters:¶

other : Self¶

A second instance of mcfonts.MinecraftFont to compare to.

Return type:¶

None

count_providers()¶

Return a counted summary of the providers this font contains.

This is future-proof, and will work with any provider as long as it has a "type" key.

Returns:¶

A summary of font's providers.

Return type:¶

dict[str, int]

count_providers_total()¶

Count the number of providers in the font.

Returns:¶

Number of providers.

Return type:¶

int

coverage_report()¶

Build a report of what characters this font contains.

This includes information like how many characters are in the font, and what Unicode blocks are covered.

Returns:¶

A dictionary of {"chars": int, "blocks": {str: int}}.

Return type:¶

coverage_reports.CoverageReport

export(export_format, settings=None, filter_instance=None)¶

Export this Minecraft font to another format. See available formats at mcfonts.export_formats.EXPORT_FORMATS_MAP.

Parameters:¶

export_format : collections.abc.Callable[[dict[str, glyphs.Glyph], export_formats.ExportSettings], bytes]¶

The function to pass glyphs and settings to. Look in mcfonts.export_formats for a list of the functions you can pass. Also accepts a string of the format name (see mcfonts.export_formats.EXPORT_FORMATS_MAP).

settings : export_formats.ExportSettings | None¶

A dictionary of the needed parameters to attach to the exported font. See mcfonts.export_formats.ExportSettings.

filter_instance : filters.Filter | None¶

An optional instance of mcfonts.filters.Filter. If supplied, filter rules will be obeyed.

Returns:¶

The exported data in the specified format that can be written to a file and saved.

Return type:¶

bytes

get_covering_providers(unirange_notation)¶

Given a codepoint range, return a list of providers that cover these characters.

Parameters:¶

unirange_notation : str¶

A string representing the requested range of chars. See https://pypi.org/project/unirange/.

Returns:¶

A list of the providers that cover codeopints defined in unirange_notation.

Return type:¶

list[providers.base.Provider]

print_info(table_chars=True, summary_only=False)¶

Print basic information about the font.

Parameters:¶

table_chars : bool¶

Whether to print a 'chars' list as a square table, or as a simple string. This only applies to mcfonts.providers.BitmapProvider.

summary_only : bool¶

If True, will only print the number of characters and providers.

Return type:¶

None

regenerate_charlists()¶

Iterate through each resource and analyse it.

For each resource, an entry will be made in a dictionary that contains the same height and ascent fields as the original, except the "chars" list will be updated to reflect the glyphs in the associated resource.

Warning

This only works if the first character in the original charlist is present, and if the order is incremental (U+0100, then U+0101, then U+0102, so on).

If this condition isn't true, this function will fail. There are no checks for this rule.

Returns:¶

A dictionary matching a normal font JSON, with each "chars" list updated.

Return type:¶

utils.types.TypedProvidersDict

reload_to_monochrome()¶

Replace the resources used in the providers with a grayscale version.

If the resource is already grayscale, this will have no effect. This modifies the resource of this provider in place, and can't be undone.

Return type:¶

None

save(indent='\t')¶

Recursively write all providers to their original file locations.

This is different from exporting. The file is indented by default.

Warning

Not to be confused with MinecraftFont.export().

Warning

Doesn't save resources.

Parameters:¶

indent : int | str | None¶

The indentation level, refer to json.dump() for possible values.

Return type:¶

None

validate()¶

Run basic structure checks on the providers of the font JSON.

Return type:¶

None

yield_characters()¶

Yield all the characters this font covers and has a definition for.

Note

Any character in mcfonts.constants.PADDING_CHARS isn't counted.

Returns:¶

A yield of strings of individual characters.

Return type:¶

collections.abc.Iterable[str]

yield_glyphs_in_unirange(unirange_notation)¶

Given a unirange_notation, yield a tuple of the requested character to their glyph.

Parameters:¶

unirange_notation : str¶

A string representing the requested range of chars. See https://pypi.org/project/unirange/.

Returns:¶

A yield of the requested characters and associated glyphs that match unirange_notation.

Return type:¶

collections.abc.Iterable[tuple[str, glyphs.Glyph | None]]

yield_providers(unwind_reference_children=True)¶

Yield the providers in this font.

By default, this will unpack reference providers and yield its children instead. Reference providers will never yield the same referenced font twice if unwind_reference_children is True.

Parameters:¶

unwind_reference_children : bool¶

Whether to yield a reference provider's children instead of the reference provider plainly. Usually, this is a good idea. This also prevents the same font from being yielded twice.

Returns:¶

A yield of Provider.

Return type:¶

collections.abc.Iterable[providers.base.Provider]

mcfonts.from_java_ambiguous(path, read_colors=False, strict=True)¶

For file paths where the file pointed to is of an unknown type; it could be a JSON, ZIP, or directory.

This function automatically figures out which function to use, and returns a MinecraftFont.

Parameters:¶

path : pathlib.Path¶

The real path to either a file or a folder.

read_colors : bool¶

If True, glyph will be loaded in 'RGBA'. If False, loaded in 'LA'.

RGBA images incur heavy time cost. Be careful.

strict : bool¶

If True:

• Bad providers will raise an error.

• Missing files will raise an error.

If False:

• Bad providers will be ignored.

• Missing files will be skipped.

Returns:¶

A mcfonts.MinecraftFont instance.

Return type:¶

MinecraftFont

mcfonts.from_java_font_contents(file_contents, file_path, read_colors=False, strict=True)¶

Load a Java Edition font JSON into a mcfonts.MinecraftFont.

Requires a "providers" list, and missing files will raise an error.

Parameters:¶

file_contents : dict[str, Any]¶

The contents of the font JSON file, loaded as a dictionary. This dictionary should include the base "providers" key.

file_path : pathlib.Path¶

The path to the font JSON. This is needed for loading resources.

read_colors : bool¶

If True, glyph will be loaded in RGBA (Red, Green, Blue, Alpha). If false, loaded in LA. RGBA images incur heavy time cost. Be careful.

strict : bool¶

If True:

• Bad providers will raise an error.

• Missing files will raise an error.

If False:

• Bad providers will be ignored.

• Missing files will be skipped.

Returns:¶

A mcfonts.MinecraftFont instance.

Raises:¶

FileNotFoundError -- If a referenced file isn't found and strict is True.

Return type:¶

MinecraftFont

mcfonts.from_java_font_file(file_path, read_colors=False, strict=True)¶

Load a Java Edition font JSON into a mcfonts.MinecraftFont.

Requires a "providers" list, and missing files will raise an error.

Parameters:¶

file_path : pathlib.Path¶

The real path to the font JSON.

read_colors : bool¶

If True, glyph will be loaded in RGBA. If false, loaded in LA.

RGBA images incur heavy time cost. Be careful.

strict : bool¶

If True:

• Bad providers will raise an error.

• Missing files will raise an error.

If False:

• Bad providers will be ignored.

• Missing files will be skipped.

Returns:¶

A mcfonts.MinecraftFont instance.

Raises:¶

FileNotFoundError -- If a referenced file is not found and strict is True.

Return type:¶

MinecraftFont

mcfonts.from_java_pack_folder(folder_path, font_file_name='default.json', namespace='minecraft', read_colors=False, strict=True)¶

Load a Java Edition resource pack into a mcfonts.MinecraftFont.

The font must be in the path assets/<namespace>/font/<fontfile>.

Parameters:¶

folder_path : pathlib.Path¶

The real path to the folder that contains a resource pack. This isn't the /assets/ folder, nor is it a ZIP file. The files inside this folder should be assets/, and pack.mcmeta.

font_file_name : str¶

The name of the font file. By default, this is "default.json".

namespace : str¶

The namespace to find assets in. By default, this is "minecraft".

read_colors : bool¶

If True, glyph will be loaded in 'RGBA'. If False, loaded in 'LA'.

RGBA images incur heavy time cost. Be careful.

strict : bool¶

If True:

• Bad providers will raise an error.

• Missing files will raise an error.

If False:

• Bad providers will be ignored.

• Missing files will be skipped.

Returns:¶

A mcfonts.MinecraftFont instance.

Raises:¶

FileNotFoundError -- If a referenced file isn't found and strict is True.

Return type:¶

MinecraftFont

mcfonts.from_java_pack_zip(file_path, password=None, read_colors=False, strict=True)¶

Load a Java Edition resource pack ZIP into a mcfonts.MinecraftFont.

The font must be in the path assets/<namespace>/font/<fontfile>.

Parameters:¶

file_path : pathlib.Path¶

The real path to the ZIP file.

password : bytes | None¶

Password to use when reading the ZIP file. Set to None if there is no password.

read_colors : bool¶

If True, glyph will be loaded in 'RGBA'. If False, loaded in 'LA'.

RGBA images incur heavy time cost. Be careful.

strict : bool¶

If True:

• Bad providers will raise an error.

• Missing files will raise an error.

If False:

• Bad providers will be ignored.

• Missing files will be skipped.

Returns:¶

A mcfonts.MinecraftFont instance.

Raises:¶

FileNotFoundError -- If a referenced file isn't found and strict is True.

Return type:¶

MinecraftFont

mcfonts.from_java_resource_template(file_path, template_provider, read_colors=False, strict=True)¶

Given the path to a texture and the contents of an individual font provider,

return a mcfonts.MinecraftFont instance with it, and the resource in file_path.

template_provider["file"] can be any value; it will be overwritten anyway, although it must exist.

Parameters:¶

file_path : pathlib.Path¶

The path to the PNG resource that needs templating.

template_provider : dict[str, Any]¶

An individual provider dictionary. Not a list of providers.

read_colors : bool¶

If True, glyph will be loaded in 'RGBA'. If False, loaded in 'LA'. RGBA images incur heavy time cost. Be careful.

strict : bool¶

If a provider has bad data, an exception will be raised and no provider list will be returned if this is True. If this is False, it will be ignored.

Returns:¶

A mcfonts.MinecraftFont instance.

Return type:¶

MinecraftFont

mcfonts.logger¶