pyfonts 0.0.1__py3-none-any.whl

pyfonts/__init__.py

@@ -0,0 +1,4 @@
+from .main import load_font
+from .preview_font import preview_font
+
+__all__ = ["load_font", "preview_font"]

pyfonts/get_font.py

@@ -0,0 +1,76 @@
+from urllib.request import urlopen
+from urllib.error import URLError, HTTPError
+from tempfile import NamedTemporaryFile
+from matplotlib.font_manager import FontProperties
+
+from .is_valid import _is_url, _is_valid_raw_url
+
+
+def _get_font_from_url(font_location: str) -> FontProperties:
+    """
+    Retrieves a font from a Github url. The function attempts to access the font
+    at the given url by checking a few elements, creates a temporary file with the
+    font found and returns a FontProperties.
+
+    Params:
+    - font_location: url that points to the binary font file on Github
+
+    Returns:
+    - matplotlib.font_manager.FontProperties: A FontProperties object containing the loaded font.
+    """
+
+    if not _is_url(font_location):
+        raise ValueError(f"`font_location` must be an url, not: {font_location}.")
+
+    elif not _is_valid_raw_url(font_location):
+        raise ValueError(
+            f"""
+            The URL provided ({font_location}) does not appear to be valid.
+            It must point to a binary font file from Github.
+            Have you forgotten to append `?raw=true` to the end of the URL?
+            """
+        )
+
+    else:
+        try:
+            with NamedTemporaryFile(delete=False) as temp_file:
+                response = urlopen(font_location)
+                temp_file.write(response.read())
+
+        except HTTPError as e:
+            if e.code == 404:
+                raise Exception(
+                    "404 error. The url passed does not exist: font file not found."
+                )
+
+        except URLError:
+            raise Exception(
+                "Failed to load font. This may be due to a lack of internet connection."
+            )
+
+        font = FontProperties(fname=temp_file.name)
+        return font
+
+
+def _get_local_font(font_location: str) -> FontProperties:
+    """
+    Retrieves a font from a local path.
+
+    Params:
+    - font_location: path to a font file.
+
+    Returns:
+    - matplotlib.font_manager.FontProperties: A FontProperties object containing the loaded font.
+    """
+
+    if _is_url(font_location):
+        raise ValueError("`font_location` must point to a local file on your computer.")
+
+    else:
+        font = FontProperties(fname=font_location)
+        try:
+            font.get_name()
+        except FileNotFoundError:
+            raise ValueError(f"Font file not found at : '{font_location}'")
+
+    return font

pyfonts/is_valid.py

@@ -0,0 +1,43 @@
+import re
+from urllib.parse import urlparse
+
+
+def _is_url(s: str) -> bool:
+    """
+    Tests whether a string is an url.
+
+    Parameters:
+       - s: a string.
+
+    Returns:
+       - a boolean indicating whether the string is an url or not.
+    """
+    is_an_url = urlparse(s).scheme != ""
+    return is_an_url
+
+
+def _is_valid_raw_url(url: str) -> bool:
+    """
+    Tests whether an url from Github pointing to a font
+    is actually a raw url (e.g pointing to the binary font file and not the Github view).
+
+    There are 3 ways/patterns to point to the raw version of a file from Github that are defined
+    in `patterns`.
+
+    Parameters:
+       - url: the url of the font file.
+
+    Returns:
+       - a boolean indicating whether the url corresponds to a raw file.
+    """
+    patterns = [
+        r"^https://github\.com/[^/]+/[^/]+/blob/[^/]+/.+\.(ttf|otf|woff|woff2)\?raw=true$",
+        r"^https://github\.com/[^/]+/[^/]+/raw/[^/]+/.+\.(ttf|otf|woff|woff2)$",
+        r"^https://raw\.githubusercontent\.com/[^/]+/[^/]+/[^/]+/.+\.(ttf|otf|woff|woff2)$",
+    ]
+
+    for pattern in patterns:
+        if re.match(pattern, url):
+            return True
+
+    return False

pyfonts/main.py

@@ -0,0 +1,33 @@
+from matplotlib.font_manager import FontProperties
+from typing import Optional
+
+from .get_font import _get_font_from_url, _get_local_font
+
+
+def load_font(
+    font_url: Optional[str] = None,
+    font_path: Optional[str] = None,
+) -> FontProperties:
+    """
+    Loads a FontProperties object from a remote Github repo or a local file.
+
+    Parameters:
+    - font_url: A URL pointing to a binary font file from Github.
+    - font_path: The local file path of the font.
+
+    Returns:
+    - matplotlib.font_manager.FontProperties: A FontProperties object containing the loaded font.
+    """
+    if font_url and font_path:
+        raise ValueError(
+            "You must provide only one of the following: `font_url` or `font_path`."
+        )
+    elif font_url:
+        font = _get_font_from_url(font_url)
+    elif font_path:
+        font = _get_local_font(font_path)
+    else:
+        raise ValueError(
+            "You must provide one of the following: `font_url` or `font_path`."
+        )
+    return font

pyfonts/preview_font.py

@@ -0,0 +1,45 @@
+from .main import load_font
+import matplotlib.pyplot as plt
+from typing import Optional
+
+
+def preview_font(
+    font_url: Optional[str] = None,
+    font_path: Optional[str] = None,
+):
+    """
+    Preview a font.
+    """
+    font = load_font(font_url, font_path)
+
+    plt.figure(figsize=(10, 5))
+    plt.text(
+        0.5,
+        0.5,
+        "Hello, World From PyFonts!",
+        fontsize=30,
+        ha="center",
+        va="center",
+        font=font,
+    )
+    plt.text(
+        0.5,
+        0.35,
+        "This is a test.",
+        fontsize=25,
+        ha="center",
+        va="center",
+        font=font,
+    )
+    plt.text(
+        0.5,
+        0.65,
+        "How about this?",
+        fontsize=20,
+        ha="center",
+        va="center",
+        font=font,
+    )
+
+    plt.axis("off")
+    plt.show()

pyfonts-0.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Joseph Barbier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyfonts-0.0.1.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.1
+Name: pyfonts
+Version: 0.0.1
+Summary: A simple way to load fonts for matplotlib
+Home-page: https://github.com/JosephBARBIERDARNAL/pyfonts/blob/main/README.md
+Author: Joseph Barbier
+Author-email: Joseph Barbier <joseph.barbierdarnal@gmail.com>
+Project-URL: Homepage, https://github.com/JosephBARBIERDARNAL/pyfonts
+Project-URL: Issues, https://github.com/JosephBARBIERDARNAL/pyfonts/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Matplotlib
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+
+# PyFonts
+
+<img src="https://github.com/JosephBARBIERDARNAL/static/blob/main/python-libs/pyfonts/image.png?raw=true" alt="pyfonts logo" align="right" width="200px"/>
+
+A simple (and reproducible) way to load fonts for `matplotlib`.
+
+Check out [the online documentation](https://python-graph-gallery.com/pyfonts/).
+
+<br><br>
+
+# Installation
+
+_Note: pyfonts requires **Python 3.9** and above._
+
+You can install `pyfonts` directly from PyPI with:
+
+```
+pip install pyfonts
+```
+
+<br><br>
+
+# Quick start
+
+`pyfonts` is designed to make the code of your graphs more reproducible by removing the need to add the local path to the font files. For example:
+
+```python
+from pyfonts import load_font
+import matplotlib.pyplot as plt
+
+font = load_font(
+    font_url="https://github.com/google/fonts/raw/main/apache/ultra/Ultra-Regular.ttf"
+)
+
+fig, ax = plt.subplots(figsize=(10, 6))
+ax.text(
+    x=0.5,
+    y=0.5,
+    s=f"What an easy way to load fonts, isn't it?",
+    font=font,
+    fontsize=20,
+    ha="center",
+)
+plt.show()
+```
+
+![output of quick start](https://github.com/JosephBARBIERDARNAL/pyfonts/blob/main/img/quickstart.png?raw=true)
+
+<br><br>
+
+# Usage guide
+
+Check out [the online documentation](https://python-graph-gallery.com/pyfonts/).
+
+<br><br>
+
+# Contributions
+
+Contributions and feedback are welcome.
+
+There's not much that needs to be implemented at the moment. If you've found a bug or want to request a new feature, open an [issue](https://github.com/JosephBARBIERDARNAL/pyfonts/issues).
+
+<br><br><br>

pyfonts-0.0.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+pyfonts/__init__.py,sha256=9_bJ1B6DvZGfQwzS70QiaFReRzUL_nJcFmb2D0wKxD8,108
+pyfonts/get_font.py,sha256=THQu4PR3jMGaItT584i3Fem2P6STvRQk3gzUn8z4lio,2406
+pyfonts/is_valid.py,sha256=sKezwlLjcZGR9ViPfwMAFb5MTXyi9rhULIlqo-29zes,1173
+pyfonts/main.py,sha256=lc97eBRVJxYExI52jHPBgokWfLkdKarH5e4di-7e81Y,1006
+pyfonts/preview_font.py,sha256=mwcQ0E0h1GasxoyB0XCqlvBu14Uox2OOHekMKrxmPk4,809
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_is_valid.py,sha256=v-2Bbg5otcd3P7lTkc0cbxHFZZRan_S-aEbjOsYHNw0,2224
+tests/test_load_font.py,sha256=UHdhiN5O1mXRPfegE1tQ4Q7eVi3_sO0QHCXFhZ4ap3Q,729
+tests/test_preview_font.py,sha256=JvpOjX4WO6rHKhtGdn_hd7vJ6KUwzfquvz6uTFQXH-I,673
+pyfonts-0.0.1.dist-info/LICENSE,sha256=KvIhR13NJbyEXp5UJS9cu5feh8Alen7aQv_zvT-Hvcg,1071
+pyfonts-0.0.1.dist-info/METADATA,sha256=1KEAwYkKLuarUFlvNy7Lx_d6BbAq_eeFmnITJziJfaw,2211
+pyfonts-0.0.1.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+pyfonts-0.0.1.dist-info/top_level.txt,sha256=GlEnd_EJc2WXFW7B_w1xI_eYQkN4avCttKYTd9EAXZw,14
+pyfonts-0.0.1.dist-info/RECORD,,

pyfonts-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyfonts-0.0.1.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+pyfonts
+tests

tests/test_is_valid.py

@@ -0,0 +1,67 @@
+import pytest
+from pyfonts.is_valid import _is_valid_raw_url, _is_url
+
+
+@pytest.mark.parametrize(
+    "input_string, expected_result",
+    [
+        ("https://www.example.com", True),
+        ("http://example.com", True),
+        ("ftp://ftp.example.com", True),
+        ("www.example.com", False),
+        ("example.com", False),
+        ("just a string", False),
+        ("", False),
+        ("file:///C:/Users/username/Documents/file.txt", True),
+        ("mailto:user@example.com", True),
+    ],
+)
+def test_is_url(input_string, expected_result):
+    assert _is_url(input_string) == expected_result
+
+
+def test_is_url_type_error():
+    with pytest.raises(AttributeError):
+        _is_url(123)
+
+
+@pytest.mark.parametrize(
+    "url,expected",
+    [
+        ("https://github.com/user/repo/blob/master/font.ttf?raw=true", True),
+        ("https://github.com/user/repo/raw/master/font.otf", True),
+        ("https://raw.githubusercontent.com/user/repo/master/font.woff", True),
+        (
+            "https://raw.githubusercontent.com/user/repo/branch-name/subfolder/font.woff2",
+            True,
+        ),
+        ("https://github.com/user/repo/blob/master/font.ttf", False),
+        ("https://github.com/user/repo/raw/master/font.txt", False),
+        ("https://raw.githubusercontent.com/user/repo/master/font.exe", False),
+        ("https://example.com/font.ttf", False),
+        ("https://github.com/user/repo/tree/master/fonts/font.ttf", False),
+        ("https://github.com/user/repo/blob/master/font.ttf?raw=false", False),
+        (
+            "https://github.com/user/repo/blob/master/font.ttf?raw=true&param=value",
+            False,
+        ),
+        ("https://github.com/user/repo/raw/master/font.WOFF", False),
+        ("https://raw.githubusercontent.com/user/repo/master/font.ttf?raw=true", False),
+    ],
+)
+def test_is_valid_raw_url(url, expected):
+    assert _is_valid_raw_url(url) == expected
+
+
+def test_is_valid_raw_url_with_empty_string():
+    assert _is_valid_raw_url("") == False
+
+
+def test_is_valid_raw_url_with_none():
+    with pytest.raises(TypeError):
+        _is_valid_raw_url(None)
+
+
+def test_is_valid_raw_url_with_non_string():
+    with pytest.raises(TypeError):
+        _is_valid_raw_url(123)

tests/test_load_font.py

@@ -0,0 +1,26 @@
+import pytest
+from unittest.mock import patch
+from matplotlib.font_manager import FontProperties
+from pyfonts import load_font
+
+
+def test_load_font_with_url():
+    font = load_font(
+        font_url="https://github.com/JosephBARBIERDARNAL/pyfonts/blob/main/tests/Ultra-Regular.ttf?raw=true"
+    )
+    assert isinstance(font, FontProperties)
+
+
+def test_load_font_with_path():
+    font = load_font(font_path="tests/Ultra-Regular.ttf")
+    assert isinstance(font, FontProperties)
+
+
+def test_load_font_invalid_input():
+    with pytest.raises(ValueError):
+        load_font(font_url="http://example.com/font.ttf", font_path="/path/to/font.ttf")
+
+
+def test_load_font_no_input():
+    with pytest.raises(ValueError):
+        load_font()

tests/test_preview_font.py

@@ -0,0 +1,21 @@
+import pytest
+from unittest.mock import patch, MagicMock
+from matplotlib.font_manager import FontProperties
+from pyfonts import preview_font, load_font
+
+
+@pytest.fixture
+def mock_load_font():
+    with patch("pyfonts.load_font") as mock:
+        mock.return_value = FontProperties()
+        yield mock
+
+
+def test_preview_font_raises_value_error_on_invalid_input(mock_load_font):
+    mock_load_font.side_effect = ValueError(
+        "You must provide only one of the following: `font_name`, `font_url` or `font_path`."
+    )
+    with pytest.raises(ValueError):
+        preview_font(
+            font_url="http://example.com/font.ttf", font_path="/path/to/font.ttf"
+        )