Merge branch 'matplotlib:master' into patch-2

Author: Tortar

.circleci/config.yml

@@ -119,51 +119,6 @@ commands:
 #
 
 jobs:
-  docs-python37:
-    docker:
-      - image: circleci/python:3.7
-    steps:
-      - checkout
-
-      - apt-install
-      - fonts-install
-      - pip-install
-
-      - deps-install
-      - mpl-install
-
-      - doc-build
-
-      - doc-bundle
-
-      - store_artifacts:
-          path: doc/build/html
-      - store_test_results:
-          path: doc/build/test-results
-
-  docs-python38-min:
-    docker:
-      - image: circleci/python:3.8
-    steps:
-      - checkout
-
-      - apt-install
-      - fonts-install
-      - pip-install
-
-      - deps-install:
-          numpy_version: "==1.17.3"
-      - mpl-install
-
-      - doc-build
-
-      - doc-bundle
-
-      - store_artifacts:
-          path: doc/build/html
-      - store_test_results:
-          path: doc/build/test-results
-
   docs-python38:
     docker:
       - image: circleci/python:3.8
@@ -201,6 +156,4 @@ workflows:
   version: 2
   build:
     jobs:
-      - docs-python37
       - docs-python38
-      - docs-python38-min

.github/workflows/circleci.yml

@@ -9,4 +9,4 @@ jobs:
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           artifact-path: 0/doc/build/html/index.html
-          circleci-jobs: docs-python37,docs-python38,docs-python38-min
+          circleci-jobs: docs-python38

doc/conf.py

@@ -20,6 +20,11 @@
 import sphinx
 
 from datetime import datetime
+import time
+
+# Parse year using SOURCE_DATE_EPOCH, falling back to current time.
+# https://reproducible-builds.org/specs/source-date-epoch/
+sourceyear = datetime.utcfromtimestamp(int(os.environ.get('SOURCE_DATE_EPOCH', time.time()))).year
 
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
@@ -212,7 +217,7 @@ def _check_dependencies():
 project = 'Matplotlib'
 copyright = ('2002 - 2012 John Hunter, Darren Dale, Eric Firing, '
              'Michael Droettboom and the Matplotlib development '
-             f'team; 2012 - {datetime.now().year} The Matplotlib development team')
+             f'team; 2012 - {sourceyear} The Matplotlib development team')
 
 
 # The default replacements for |version| and |release|, also used in various

doc/users/fonts.rst

@@ -0,0 +1,130 @@
+Fonts in Matplotlib Text Engine
+===============================
+
+Matplotlib needs fonts to work with its text engine, some of which are shipped
+alongside the installation. However, users can configure the default fonts, or
+even provide their own custom fonts! For more details, see :doc:`Customizing 
+text properties </tutorials/text/text_props>`.
+
+However, Matplotlib also provides an option to offload text rendering to a TeX
+engine (``usetex=True``),
+see :doc:`Text rendering with LaTeX </tutorials/text/usetex>`.
+
+Font Specifications
+-------------------
+Fonts have a long and sometimes incompatible history in computing, leading to
+different platforms supporting different types of fonts. In practice, there are
+3 types of font specifications Matplotlib supports (in addition to 'core
+fonts', more about which is explained later in the guide):
+
+.. list-table:: Type of Fonts
+   :header-rows: 1
+
+   * - Type 1 (PDF)
+     - Type 3 (PDF/PS)
+     - TrueType (PDF)
+   * - One of the oldest types, introduced by Adobe
+     - Similar to Type 1 in terms of introduction
+     - Newer than previous types, used commonly today, introduced by Apple
+   * - Restricted subset of PostScript, charstrings are in bytecode
+     - Full PostScript language, allows embedding arbitrary code
+       (in theory, even render fractals when rasterizing!)
+     - Include a virtual machine that can execute code!
+   * - These fonts support font hinting
+     - Do not support font hinting
+     - Hinting supported (virtual machine processes the "hints")
+   * - Non-subsetted through Matplotlib
+     - Subsetted via external module `ttconv <https://github.com/sandflow/ttconv>`_
+     - Subsetted via external module `fonttools <https://github.com/fonttools/fonttools>`_
+
+NOTE: Adobe will disable support for authoring with Type 1 fonts in
+January 2023. `Read more here. <https://helpx.adobe.com/fonts/kb/postscript-type-1-fonts-end-of-support.html>`_
+
+Special Mentions
+^^^^^^^^^^^^^^^^
+Other font specifications which Matplotlib supports:
+
+- Type 42 fonts (PS):
+
+  - PostScript wrapper around TrueType fonts
+  - 42 is the `Answer to Life, the Universe, and Everything! <https://en.wikipedia.org/wiki/Answer_to_Life,_the_Universe,_and_Everything>`_
+  - Matplotlib uses an external library called `fonttools <https://github.com/fonttools/fonttools>`_
+    to subset these types of fonts
+
+- OpenType fonts:
+
+  - OpenType is a new standard for digital type fonts, developed jointly by
+    Adobe and Microsoft
+  - Generally contain a much larger character set!
+  - Limited Support with Matplotlib
+
+Subsetting
+----------
+Matplotlib is able to generate documents in multiple different formats. Some of
+those formats (for example, PDF, PS/EPS, SVG) allow embedding font data in such
+a way that when these documents are visually scaled, the text does not appear
+pixelated.
+
+This can be achieved by embedding the *whole* font file within the
+output document. However, this can lead to very large documents, as some
+fonts (for instance, CJK - Chinese/Japanese/Korean fonts) can contain a large
+number of glyphs, and thus their embedded size can be quite huge.
+
+Font Subsetting can be used before generating documents, to embed only the
+*required* glyphs within the documents. Fonts can be considered as a collection
+of glyphs, so ultimately the goal is to find out *which* glyphs are required
+for a certain array of characters, and embed only those within the output.
+
+.. note::
+  The role of subsetter really shines when we encounter characters like **ä**
+  (composed by calling subprograms for **a** and **¨**); since the subsetter
+  has to find out *all* such subprograms being called by every glyph included
+  in the subset, this is a generally difficult problem!
+
+Luckily, Matplotlib uses a fork of an external dependency called
+`ttconv <https://github.com/sandflow/ttconv>`_, which helps in embedding and
+subsetting font data. (however, recent versions have moved away from ttconv to
+pure Python for certain types: for more details visit
+`these <https://github.com/matplotlib/matplotlib/pull/18370>`_, `links <https://github.com/matplotlib/matplotlib/pull/18181>`_)
+
+| *Type 1 fonts are still non-subsetted* through Matplotlib. (though one will encounter these mostly via *usetex*/*dviread* in PDF backend)
+| **Type 3 and Type 42 fonts are subsetted**, with a fair amount of exceptions and bugs for the latter.
+
+What to use?
+------------
+Practically, most fonts that are readily available on most operating systems or
+are readily available on the internet to download include *TrueType fonts* and
+its "extensions" such as MacOS-resource fork fonts and the newer OpenType
+fonts.
+
+PS and PDF backends provide support for yet another type of fonts, which remove
+the need of subsetting altogether! These are called **Core Fonts**, and
+Matplotlib calls them via the keyword **AFM**; all that is supplied from
+Matplotlib to such documents are font metrics (specified in AFM format), and it
+is the job of the viewer applications to supply the glyph definitions.
+
+This is especially helpful to generate *really lightweight* documents.::
+
+    # trigger core fonts for PDF backend
+    plt.rcParams["pdf.use14corefonts"] = True
+    # trigger core fonts for PS backend
+    plt.rcParams["ps.useafm"] = True
+
+    chars = "AFM ftw!"
+    fig, ax = plt.subplots()
+    ax.text(0.5, 0.5, chars)
+
+    fig.savefig("AFM_PDF.pdf", format="pdf")
+    fig.savefig("AFM_PS.ps", format="ps)
+
+.. note::
+  These core fonts are limited to PDF and PS backends only; they can not be
+  rendered in other backends.
+
+  Another downside to this is that while the font metric are standardized,
+  different PDF viewer applications will have different fonts to render these
+  metrics. In other words, the **output might look different on different
+  viewers**, as well as (let's say) Windows and Linux, if Linux tools included
+  free versions of the proprietary fonts.
+
+  This also violates the *what-you-see-is-what-you-get* feature of Matplotlib.

doc/users/index.rst

@@ -13,6 +13,7 @@ User's guide
     :maxdepth: 2
 
     interactive.rst
+    fonts.rst
     release_notes.rst
     license.rst
     ../citing.rst

examples/axes_grid1/make_room_for_ylabel_using_axesgrid.py

@@ -14,8 +14,7 @@
 plt.figure()
 ax = plt.axes([0, 0, 1, 1])
 
-ax.set_yticks([0.5])
-ax.set_yticklabels(["very long label"])
+ax.set_yticks([0.5], labels=["very long label"])
 
 make_axes_area_auto_adjustable(ax)
 
@@ -26,8 +25,7 @@
 ax1 = plt.axes([0, 0, 1, 0.5])
 ax2 = plt.axes([0, 0.5, 1, 0.5])
 
-ax1.set_yticks([0.5])
-ax1.set_yticklabels(["very long label"])
+ax1.set_yticks([0.5], labels=["very long label"])
 ax1.set_ylabel("Y label")
 
 ax2.set_title("Title")
@@ -53,8 +51,7 @@
 divider.add_auto_adjustable_area(use_axes=[ax1, ax2], pad=0.1,
                                  adjust_dirs=["top", "bottom"])
 
-ax1.set_yticks([0.5])
-ax1.set_yticklabels(["very long label"])
+ax1.set_yticks([0.5], labels=["very long label"])
 
 ax2.set_title("Title")
 ax2.set_xlabel("X - Label")

examples/axes_grid1/simple_axisline4.py

@@ -13,9 +13,9 @@
 ax.plot(xx, np.sin(xx))
 
 ax2 = ax.twin()  # ax2 is responsible for "top" axis and "right" axis
-ax2.set_xticks([0., .5*np.pi, np.pi, 1.5*np.pi, 2*np.pi])
-ax2.set_xticklabels(["$0$", r"$\frac{1}{2}\pi$",
-                     r"$\pi$", r"$\frac{3}{2}\pi$", r"$2\pi$"])
+ax2.set_xticks([0., .5*np.pi, np.pi, 1.5*np.pi, 2*np.pi],
+               labels=["$0$", r"$\frac{1}{2}\pi$",
+                       r"$\pi$", r"$\frac{3}{2}\pi$", r"$2\pi$"])
 
 ax2.axis["right"].major_ticklabels.set_visible(False)
 ax2.axis["top"].major_ticklabels.set_visible(True)

examples/axisartist/demo_ticklabel_alignment.py

@@ -12,10 +12,8 @@
 
 def setup_axes(fig, pos):
     ax = fig.add_subplot(pos, axes_class=axisartist.Axes)
-    ax.set_yticks([0.2, 0.8])
-    ax.set_yticklabels(["short", "loooong"])
-    ax.set_xticks([0.2, 0.8])
-    ax.set_xticklabels([r"$\frac{1}{2}\pi$", r"$\pi$"])
+    ax.set_yticks([0.2, 0.8], labels=["short", "loooong"])
+    ax.set_xticks([0.2, 0.8], labels=[r"$\frac{1}{2}\pi$", r"$\pi$"])
     return ax
 
 

examples/images_contours_and_fields/image_annotated_heatmap.py

@@ -59,12 +59,9 @@
 fig, ax = plt.subplots()
 im = ax.imshow(harvest)
 
-# We want to show all ticks...
-ax.set_xticks(np.arange(len(farmers)))
-ax.set_yticks(np.arange(len(vegetables)))
-# ... and label them with the respective list entries
-ax.set_xticklabels(farmers)
-ax.set_yticklabels(vegetables)
+# Show all ticks and label them with the respective list entries
+ax.set_xticks(np.arange(len(farmers)), labels=farmers)
+ax.set_yticks(np.arange(len(vegetables)), labels=vegetables)
 
 # Rotate the tick labels and set their alignment.
 plt.setp(ax.get_xticklabels(), rotation=45, ha="right",
@@ -133,12 +130,9 @@ def heatmap(data, row_labels, col_labels, ax=None,
     cbar = ax.figure.colorbar(im, ax=ax, **cbar_kw)
     cbar.ax.set_ylabel(cbarlabel, rotation=-90, va="bottom")
 
-    # We want to show all ticks...
-    ax.set_xticks(np.arange(data.shape[1]))
-    ax.set_yticks(np.arange(data.shape[0]))
-    # ... and label them with the respective list entries.
-    ax.set_xticklabels(col_labels)
-    ax.set_yticklabels(row_labels)
+    # Show all ticks and label them with the respective list entries.
+    ax.set_xticks(np.arange(data.shape[1]), labels=col_labels)
+    ax.set_yticks(np.arange(data.shape[0]), labels=row_labels)
 
     # Let the horizontal axes labeling appear on top.
     ax.tick_params(top=True, bottom=False,

examples/lines_bars_and_markers/bar_label_demo.py

@@ -40,8 +40,7 @@
 ax.axhline(0, color='grey', linewidth=0.8)
 ax.set_ylabel('Scores')
 ax.set_title('Scores by group and gender')
-ax.set_xticks(ind)
-ax.set_xticklabels(('G1', 'G2', 'G3', 'G4', 'G5'))
+ax.set_xticks(ind, labels=['G1', 'G2', 'G3', 'G4', 'G5'])
 ax.legend()
 
 # Label with label_type 'center' instead of the default 'edge'
@@ -66,8 +65,7 @@
 fig, ax = plt.subplots()
 
 hbars = ax.barh(y_pos, performance, xerr=error, align='center')
-ax.set_yticks(y_pos)
-ax.set_yticklabels(people)
+ax.set_yticks(y_pos, labels=people)
 ax.invert_yaxis()  # labels read top-to-bottom
 ax.set_xlabel('Performance')
 ax.set_title('How fast do you want to go today?')
@@ -84,8 +82,7 @@
 fig, ax = plt.subplots()
 
 hbars = ax.barh(y_pos, performance, xerr=error, align='center')
-ax.set_yticks(y_pos)
-ax.set_yticklabels(people)
+ax.set_yticks(y_pos, labels=people)
 ax.invert_yaxis()  # labels read top-to-bottom
 ax.set_xlabel('Performance')
 ax.set_title('How fast do you want to go today?')