Change of top-level package name

.flake8

@@ -6,3 +6,5 @@ count = True
 color = auto
 show_source = True
 statistics = True
+per-file-ignores =
+    term_img/*:F401,F403

README.md

@@ -126,7 +126,7 @@ If the image is animated (GIF, WEBP), the animation is infinitely looped **by de
 
 **By default, if multiple sources or at least one directory is given, the TUI (Text-based/Terminal User Interface) is launched to navigate through the images (and/or directories).**
 
-**NOTE:** `python -m term_img` can be used as an alternative to the `term-image` command ***(take note of the differences)***.
+**NOTE:** `python -m term_image` can be used as an alternative to the `term-image` command ***(take note of the differences)***.
 
 </details>
 
@@ -139,22 +139,22 @@ If the image is animated (GIF, WEBP), the animation is infinitely looped **by de
 <summary>Click to expand</summary>
 
 ```python
-from term_img.image import TermImage
+from term_image.image import TermImage
 
 image = TermImage.from_file("path/to/image.png")
 ```
 
 You can also use a URL if you don't have the file stored locally
 ```python
-from term_img.image import TermImage
+from term_image.image import TermImage
 
 image = TermImage.from_url("https://www.example.com/image.png")
 ```
 
 The library can also be used with PIL images
 ```python
 from PIL import Image
-from term_img.image import TermImage
+from term_image.image import TermImage
 
 img = Image.open("path/to/image.png")
 image = TermImage(img)

docs/source/glossary.rst

@@ -72,7 +72,7 @@ Below are definitions of terms used across the library's public interface, excep
    font ratio
       The **aspect ratio** of a terminal’s font i.e the ratio of **width to height** of a single **character cell** on the terminal.
 
-      See also: :py:func:`get_font_ratio() <term_img.get_font_ratio>` and :py:func:`set_font_ratio() <term_img.set_font_ratio>`.
+      See also: :py:func:`get_font_ratio() <term_image.get_font_ratio>` and :py:func:`set_font_ratio() <term_image.set_font_ratio>`.
 
    padding
    padding width

docs/source/library/index.rst

@@ -19,7 +19,7 @@ Known Issues
 
    * **Comment**: First of all, the issue is inherent to these shells and neither a fault of this library nor the Windows Terminal, as drawing images and animations works properly with WSL within Windows Terminal.
 
-   * **Solution**: A workaround is to leave some **horizontal allowance** of **at least two columns** to ensure the image never reaches the right edge of the terminal. This can be achieved in the library by using the *h_allow* parameter of :py:meth:`TermImage.set_size() <term_img.image.TermImage.set_size>`.
+   * **Solution**: A workaround is to leave some **horizontal allowance** of **at least two columns** to ensure the image never reaches the right edge of the terminal. This can be achieved in the library by using the *h_allow* parameter of :py:meth:`TermImage.set_size() <term_image.image.TermImage.set_size>`.
 
 
 .. _library-planned:

docs/source/library/reference/exceptions.rst

@@ -1,5 +1,5 @@
-.. automodule:: term_img.exceptions
+.. automodule:: term_image.exceptions
    :members:
    :show-inheritance:
 
-   The ``term_img.exceptions`` module defines the following:
+   The ``term_image.exceptions`` module defines the following:

docs/source/library/reference/image.rst

@@ -1,11 +1,11 @@
 Core Library Definitions
 ========================
 
-.. automodule:: term_img.image
+.. automodule:: term_image.image
    :members:
    :show-inheritance:
 
-   The ``term_img.image`` module defines the following:
+   The ``term_image.image`` module defines the following:
 
    .. note:: It's allowed to set properties for :term:`animated` images on non-animated ones, the values are simply ignored.
 

docs/source/library/reference/index.rst

@@ -11,9 +11,9 @@ Reference
 Top-Level Functions
 -------------------
 
-.. autofunction:: term_img.get_font_ratio
+.. autofunction:: term_image.get_font_ratio
 
-.. autofunction:: term_img.set_font_ratio
+.. autofunction:: term_image.set_font_ratio
 
 |
 

docs/source/library/tutorial.rst

@@ -16,20 +16,20 @@ Creating an instance
 
 If the file is stored on your local filesystem::
 
-   from term_img.image import TermImage
+   from term_image.image import TermImage
 
    image = TermImage.from_file("python.png")
 
 You can also use a URL if you don't have the file stored locally::
 
-   from term_img.image import TermImage
+   from term_image.image import TermImage
 
    image = TermImage.from_url("https://raw.githubusercontent.com/AnonymouX47/term-image/docs/source/resources/python.png")
 
 The library can also be used with PIL images::
 
    from PIL import Image
-   from term_img.image import TermImage
+   from term_image.image import TermImage
 
    img = Image.open("python.png")
    image = TermImage(img)
@@ -137,12 +137,12 @@ Drawing/Displaying an image to/in the terminal
 
 There are two ways to draw an image to the terminal screen:
 
-1. The :py:meth:`draw() <term_img.image.TermImage.draw>` method
+1. The :py:meth:`draw() <term_image.image.TermImage.draw>` method
    ::
 
       image.draw()
 
-   **NOTE:** :py:meth:`TermImage.draw() <term_img.image.TermImage.draw>` has various parameters for :term:`alignment`/:term:`padding`, transparency and animation control.
+   **NOTE:** :py:meth:`TermImage.draw() <term_image.image.TermImage.draw>` has various parameters for :term:`alignment`/:term:`padding`, transparency and animation control.
 
 2. Using ``print()`` with an image render output (i.e printing the rendered string)
 
@@ -157,7 +157,7 @@ There are two ways to draw an image to the terminal screen:
       print(f"{image:>200.^70#ffffff}")  # Uses format()
 
 .. note::
-   - For :term:`animated` images, only the former animates the output, the latter only draws the **current** frame (see :py:meth:`TermImage.seek() <term_img.image.TermImage.seek()>` and :py:meth:`TermImage.tell() <term_img.image.TermImage.tell()>`).
+   - For :term:`animated` images, only the former animates the output, the latter only draws the **current** frame (see :py:meth:`TermImage.seek() <term_image.image.TermImage.seek()>` and :py:meth:`TermImage.tell() <term_image.image.TermImage.tell()>`).
    - Also, the former performs size validation to see if the image will fit into the terminal, while the latter doesn't.
 
 
@@ -167,7 +167,7 @@ There are two ways to draw an image to the terminal screen:
 Image render size
 -----------------
 | The :term:`render size` of an image is the dimension with which an image is rendered.
-| The *render size* can be retrieved via the :py:attr:`size <term_img.image.TermImage.size>`, :py:attr:`width <term_img.image.TermImage.width>` and :py:attr:`height <term_img.image.TermImage.height>` properties.
+| The *render size* can be retrieved via the :py:attr:`size <term_image.image.TermImage.size>`, :py:attr:`width <term_image.image.TermImage.width>` and :py:attr:`height <term_image.image.TermImage.height>` properties.
 
 The *render size* of an image can be in either of two states:
 
@@ -226,7 +226,7 @@ Traceback (most recent call last):
   .
 ValueError: Cannot specify both width and height
 
-The :py:attr:`width <term_img.image.TermImage.width>` and :py:attr:`height <term_img.image.TermImage.height>` properties are used to set the :term:`render size` of an image after instantiation.
+The :py:attr:`width <term_image.image.TermImage.width>` and :py:attr:`height <term_image.image.TermImage.height>` properties are used to set the :term:`render size` of an image after instantiation.
 
 >>> image = Termimage.from_file("python.png")  # Unset
 >>> image.size is None
@@ -260,7 +260,7 @@ True
 
 .. note:: An exception is raised if the terminal size is too small to calculate a size.
 
-The :py:attr:`size <term_img.image.TermImage.size>` property can only be set to one value, ``None`` and doing this :ref:`unsets <unset-size>` the :term:`render size`.
+The :py:attr:`size <term_image.image.TermImage.size>` property can only be set to one value, ``None`` and doing this :ref:`unsets <unset-size>` the :term:`render size`.
 
 >>> image = Termimage.from_file("python.png", width=100)
 >>> image.size
@@ -279,7 +279,7 @@ True
 
 .. hint::
 
-   See :py:meth:`TermImage.set_size() <term_img.image.TermImage.set_size()>` for advanced sizing control.
+   See :py:meth:`TermImage.set_size() <term_image.image.TermImage.set_size()>` for advanced sizing control.
 
 
 .. _render-scale:
@@ -290,7 +290,7 @@ Image render scale
 | The :term:`render scale` of an image is the **fraction** of the :term:`render size` that'll actually be used to render the image.
 | A valid scale value is a ``float`` in the range ``0 < x <= 1`` i.e greater than zero and less than or equal to one.
 
-The *render scale* can be retrieved via the properties :py:attr:`scale <term_img.image.TermImage.scale>`, :py:attr:`scale_x <term_img.image.TermImage.scale_x>` and :py:attr:`scale_y <term_img.image.TermImage.scale_y>`.
+The *render scale* can be retrieved via the properties :py:attr:`scale <term_image.image.TermImage.scale>`, :py:attr:`scale_x <term_image.image.TermImage.scale_x>` and :py:attr:`scale_y <term_image.image.TermImage.scale_y>`.
 
 The scale can be set at instantiation by passing a value to the *scale* **keyword-only** paramter.
 
@@ -312,7 +312,7 @@ The rendered result (using ``image.draw()``) should look like:
 
 .. image:: /resources/tutorial/scale_unset.png
 
-| The properties :py:attr:`scale <term_img.image.TermImage.scale>`, :py:attr:`scale_x <term_img.image.TermImage.scale_x>` and :py:attr:`scale_y <term_img.image.TermImage.scale_y>` are used to set the *render scale* of an image after instantiation.
+| The properties :py:attr:`scale <term_image.image.TermImage.scale>`, :py:attr:`scale_x <term_image.image.TermImage.scale_x>` and :py:attr:`scale_y <term_image.image.TermImage.scale_y>` are used to set the *render scale* of an image after instantiation.
 
 | ``scale`` accepts a tuple of two scale values or a single scale value.
 | ``scale_x`` and ``scale_y`` each accept a single scale value.

docs/source/viewer/index.rst

@@ -10,7 +10,7 @@ Image viewer
 
 The package comes with a standalone in-terminal image viewer based on the library.
 
-| The image viewer is started from the command line using either the ``term-image`` command (only works if the Python scripts directory is on ``PATH``) or ``python -m term_img``.
+| The image viewer is started from the command line using either the ``term-image`` command (only works if the Python scripts directory is on ``PATH``) or ``python -m term_image``.
 | **\*Take note of the differences**.
 
 

docs/source/viewer/tui.rst

@@ -132,4 +132,4 @@ Actions
 
 .. note::
 
-   All contexts and their actions (with default properties) are defined in ``_context_keys`` in the ``term_img.config`` sub-module.
+   All contexts and their actions (with default properties) are defined in ``_context_keys`` in the ``term_image.config`` sub-module.

setup.py

@@ -6,7 +6,7 @@
 # To locate the package since `setuptools.build_meta` modifies `sys.path`
 sys.path.append(os.getcwd())
 
-from term_img import __author__, __version__  # noqa: E402
+from term_image import __author__, __version__  # noqa: E402
 
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -41,13 +41,13 @@
     description="Display images in the terminal",
     long_description=long_description,
     long_description_content_type="text/markdown",
-    packages=find_packages(where=".", include=["term_img*"]),
+    packages=find_packages(where=".", include=["term_image*", "term_img*"]),
     license="MIT",
     classifiers=classifiers,
     python_requires=">=3.7",
     install_requires=["pillow>=9.1,<10.0", "requests>=2.23,<3.0", "urwid>=2.1,<3.0"],
     entry_points={
-        "console_scripts": ["term-image=term_img.__main__:main"],
+        "console_scripts": ["term-image=term_image.__main__:main"],
     },
     keywords=[
         "image",

term_image/__init__.py

@@ -0,0 +1,66 @@
+"""
+term-image
+
+Display images in a terminal
+
+Provides
+========
+    1. A library with utilities to display images in a terminal in various ways.
+    2. A CLI to display individual images from a local filesystem or URLs.
+    3. A TUI to browse multiple images on a local filesystem or from URLS.
+
+It basically works by converting images into text, since that's all conventional
+terminals can represent.
+Colored output is achieved using ANSI 24-bit color escape codes.
+
+AUTHOR: AnonymouX47 <anonymoux47@gmail.com>
+Copyright (c) 2022
+"""
+
+from __future__ import annotations
+
+__all__ = ("set_font_ratio", "get_font_ratio")
+__author__ = "AnonymouX47"
+
+version_info = (0, 3, 0, "dev0")
+__version__ = ".".join(map(str, version_info))
+
+
+def get_font_ratio() -> float:
+    """Return the set libray-wide :term:`font ratio`"""
+    return _font_ratio
+
+
+def set_font_ratio(ratio: float) -> None:
+    """Set the library-wide font ratio
+
+    Args:
+        ratio: The aspect ratio of your terminal's font i.e `width / height` of a single
+          character cell.
+
+    This value is taken into consideration when rendering images in order for images
+    drawn to the terminal to have a proper perceived scale.
+
+    If you can't determine this value from your terminal's configuration,
+    you might have to try different values till you get a good fit.
+    Normally, this value should be between 0 and 1, but not too close to either.
+    """
+    from . import image
+
+    global _font_ratio
+
+    if not isinstance(ratio, float):
+        raise TypeError(f"Font ratio must be a float (got: {type(ratio).__name__})")
+    if ratio <= 0:
+        raise ValueError(f"Font ratio must be positive (got: {ratio})")
+
+    # cell-size == width * height
+    # font-ratio == width / height
+    # There are two pixels vertically arranged in one character cell
+    # pixel-size == width * height/2
+    # pixel-ratio == width / (height/2) == 2 * (width / height) == 2 * font-ratio
+    _font_ratio = ratio
+    image._pixel_ratio = 2 * ratio
+
+
+_font_ratio = 0.5  # Default

term_img/__main__.py → term_image/__main__.py

@@ -45,8 +45,8 @@ def finish_multi_logging():
                 log_queue.put((None,) * 2)  # End of logs
                 log_queue.join()
 
-    # Can't use "term_img", since the logger's level is changed.
-    # Otherwise, it would affect children of "term_img".
+    # Can't use "term_image", since the logger's level is changed.
+    # Otherwise, it would affect children of "term_image".
     logger = _logging.getLogger("term-image")
     logger.setLevel(_logging.INFO)
 

term_image/exceptions.py

@@ -0,0 +1,18 @@
+"""
+Custom Exceptions
+=================
+"""
+
+from __future__ import annotations
+
+
+class TermImageException(Exception):
+    """Package exception baseclass"""
+
+
+class URLNotFoundError(FileNotFoundError, TermImageException):
+    """Raised for 404 errors"""
+
+
+class InvalidSize(ValueError, TermImageException):
+    """Raised when the given/set image render size is larger than the terminal size"""