Update afm docs and internal data structures #10692

timhoffm · 2018-03-05T21:17:00Z

PR Summary

Improve afm docstrings and cleanup the internal data structures.

PR Checklist

Has Pytest style unit tests
Code is PEP 8 compliant
Documentation is sphinx and numpydoc compliant

jklymak

This seems fine though I'm not quite grokking all the namedtupple stuff. However, the test coverage is good...

QuLogic · 2018-03-16T21:22:11Z

lib/matplotlib/afm.py

-    the character, values are a (*wx*, *name*, *bbox*) tuple, where
-    *wx* is the character width, *name* is the postscript language
-    name, and *bbox* is a (*llx*, *lly*, *urx*, *ury*) tuple.
+    Parse the given filehandle for character metrics information and returns


Some tense inconsistency: Parse vs returns

QuLogic · 2018-03-16T21:23:08Z

lib/matplotlib/afm.py

-    composites.  Values are a num parts list of composite information,
-    with each element being a (*name*, *dx*, *dy*) tuple.  Thus a
-    composites line reading:
+    Parse the given filehandle for composites information returns it as a dict.


Same tense inconsistency.

QuLogic · 2018-03-16T21:32:18Z

lib/matplotlib/afm.py

+    The fields do currently only describe a subset of character metrics
+    information defined in the AFM standard.
+    """
+CharMetrics.width.__doc__ = "The character width (WX)."


Why no triple-quotes (like the other one-line named tuples)?

QuLogic · 2018-03-16T21:34:21Z

lib/matplotlib/afm.py

+    Parse the given filehandle for character metrics information and returns
+    the information as dicts.
+
+    It is assumed that the file cursor is on the line behind


I'm not sure I understand this "behind" business. Should the file cursor not be pointing at the 'S'?

_parse_header consumes lines up to and including StartCharMetrics. It then returns and the file handle is passed on to _parse_char_metrics. The latter interprets the contents of a char metrics block, but not the StartCharMetrics command itself.

This is maybe not 100% clean and intuitive, but good enough for the internal parser functions. The docstring just describes what the code is doing/expecting.

OK, I think I understand now. When I saw 'line behind something', I thought it was a different line from 'something'. I also don't think 'behind' is the right word here.

Since the cursor is in the middle of a line anyway, I would not mention a line, just: 'the file cursor is pointing after "StartCharMetrics".'

QuLogic · 2018-03-16T21:34:39Z

lib/matplotlib/afm.py

-    composites line reading:
+    Parse the given filehandle for composites information returns it as a dict.
+
+    It is assumed that the file cursor is on the line behind 'StartComposites'.


Same question about 'behind'.

Same answer. parse_composites interprets the contents of a composites block, but not the initial StartComposites, which is already consumed by the previous parser function.

QuLogic · 2018-03-16T21:37:02Z

lib/matplotlib/afm.py

-    from :func:`_parse_char_metrics`,
-    *dkernpairs* is a :func:`_parse_kern_pairs` dict (possibly {}) and
-    *dcomposite* is a :func:`_parse_composites` dict (possibly {})
+    Parse the Adobe Font Metics file in file handle *fh*.


QuLogic · 2018-03-16T21:38:08Z

lib/matplotlib/afm.py

+        From :func:`_parse_char_metrics`.
+    cmetrics_by_name : dict
+        From :func:`_parse_char_metrics`.
+    dkernpairs : dict


I think this 'd' in the front stood for dict, so it's probably not needed with the type now explicitly named.

anntzer · 2018-03-21T06:47:39Z

lib/matplotlib/afm.py

-            ascii_d[num] = (wx, name, bbox)
-        name_d[name] = (wx, bbox)
+            ascii_d[num] = metrics
+        name_d[name] = metrics


I guess this is technically a backcompat break? (someone could have been doing wx, bbox = name_d[name].)
It would not have been a problem if parse_afm was private (... as it probably should have been) but a note is probably useful.

If we are at it, shouldn't we just make parse_afm private? After all, parse_afm is not something I would want to maintain as part of the public matplotlib API in the future.

I'm fine with deprecating it.

anntzer · 2018-03-21T06:53:17Z

lib/matplotlib/afm.py

-        self._metrics = dcmetrics_ascii
-        self._metrics_by_name = dcmetrics_name
-        self._composite = dcomposite
+        (header,


Now that you're here you may as well write

(self._header, ..., self._composite) = parse_afm(fh)

anntzer · 2018-03-21T06:56:33Z

lib/matplotlib/afm.py


    def get_height_char(self, c, isord=False):
        """
        Get the height of character *c* from the bounding box.  This
-        is the ink height (space is 0)
+        is the ink height (space is 0).


Get the bounding box (ink) height of character c (space is 0).

anntzer · 2018-03-21T06:56:53Z

lib/matplotlib/afm.py


    def get_kern_dist(self, c1, c2):
        """
        Return the kerning pair distance (possibly 0) for chars *c1*
-        and *c2*
+        and *c2*.


fits in a line

timhoffm · 2018-03-21T22:40:56Z

rebased to fix conflict with master

anntzer

feel free to dismiss this once the backcompat issue is fixed

comments handled

timhoffm · 2018-03-28T09:19:39Z

@anntzer is this approved then, or should still someone else approve?

timhoffm force-pushed the doc-afm branch from 4b1c605 to f4838df Compare March 6, 2018 01:38

dstansby added the Documentation label Mar 6, 2018

timhoffm added the status: needs review label Mar 16, 2018

jklymak added the topic: text label Mar 16, 2018

jklymak approved these changes Mar 16, 2018

View reviewed changes

QuLogic added this to the v3.0 milestone Mar 16, 2018

QuLogic reviewed Mar 16, 2018

View reviewed changes

timhoffm force-pushed the doc-afm branch from f4838df to 89fc65e Compare March 17, 2018 18:46

anntzer reviewed Mar 21, 2018

View reviewed changes

timhoffm force-pushed the doc-afm branch 2 times, most recently from 87f2304 to 2e18e7a Compare March 21, 2018 22:40

anntzer previously requested changes Mar 21, 2018

View reviewed changes

Update afm docs

7e7a8f1

timhoffm force-pushed the doc-afm branch from 2e18e7a to 7e7a8f1 Compare March 22, 2018 00:04

deprecate parse_afm()

75e30bb

anntzer merged commit c8fd779 into matplotlib:master Mar 28, 2018

timhoffm removed the status: needs review label Mar 28, 2018

timhoffm deleted the doc-afm branch March 28, 2018 11:27

Uh oh!

Update afm docs and internal data structures #10692

Update afm docs and internal data structures #10692

Uh oh!

Conversation

timhoffm commented Mar 5, 2018

PR Summary

PR Checklist

Uh oh!

jklymak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhoffm commented Mar 21, 2018

Uh oh!

anntzer left a comment

Choose a reason for hiding this comment

Uh oh!

timhoffm commented Mar 28, 2018

Uh oh!

Uh oh!