Deprecation in EngFormatter

Passing a string as *num* argument when calling an instance of

`matplotlib.ticker.EngFormatter` is deprecated and will be removed in 2.3.

New keyword argument 'sep' for EngFormatter

A new "sep" keyword argument has been added to

:class:`~matplotlib.ticker.EngFormatter` and provides a means to define

the string that will be used between the value and its unit. The default

string is " ", which preserves the former behavior. Besides, the separator is

now present between the value and its unit even in the absence of SI prefix.

There was formerly a bug that was causing strings like "3.14V" to be returned

instead of the expected "3.14 V" (with the default behavior).

fig, (ax0, ax1) = plt.subplots(nrows=2, figsize=(7, 9.6))

for ax in (ax0, ax1):

ax.set_xscale('log')

ax0.set_title('Full unit ticklabels, w/ default precision & space separator')

formatter0 = EngFormatter(unit='Hz')

ax0.xaxis.set_major_formatter(formatter0)

ax0.plot(xs, ys)

ax0.set_xlabel('Frequency')

ax1.set_title('SI-prefix only ticklabels, 1-digit precision & '

'thin space separator')

formatter1 = EngFormatter(places=1, sep=u"\N{THIN SPACE}") # U+2009

ax1.xaxis.set_major_formatter(formatter1)

ax1.plot(xs, ys)

ax1.set_xlabel('Frequency [Hz]')

plt.tight_layout()

# (input, expected) where ''expected'' corresponds to the outputs

# respectively returned when (places=None, places=0, places=2)

raw_format_data = [

(-1234.56789, ('-1.23457 k', '-1 k', '-1.23 k')),

(-1.23456789, ('-1.23457', '-1', '-1.23')),

(-0.123456789, ('-123.457 m', '-123 m', '-123.46 m')),

(-0.00123456789, ('-1.23457 m', '-1 m', '-1.23 m')),

(-0.0, ('0', '0', '0.00')),

(-0, ('0', '0', '0.00')),

(0, ('0', '0', '0.00')),

(1.23456789e-6, ('1.23457 \u03bc', '1 \u03bc', '1.23 \u03bc')),

(0.123456789, ('123.457 m', '123 m', '123.46 m')),

(0.1, ('100 m', '100 m', '100.00 m')),

(1, ('1', '1', '1.00')),

(1.23456789, ('1.23457', '1', '1.23')),

(999.9, ('999.9', '1 k', '999.90')), # places=0: corner-case rounding

(999.9999, ('1 k', '1 k', '1.00 k')), # corner-case roudning for all

(1000, ('1 k', '1 k', '1.00 k')),

(1001, ('1.001 k', '1 k', '1.00 k')),

(100001, ('100.001 k', '100 k', '100.00 k')),

(987654.321, ('987.654 k', '988 k', '987.65 k')),

(1.23e27, ('1230 Y', '1230 Y', '1230.00 Y')) # OoR value (> 1000 Y)

@pytest.mark.parametrize('input, expected', raw_format_data)

def test_params(self, input, expected):

UNIT = 's' # seconds

DIGITS = '0123456789' # %timeit showed 10-20% faster search than set

# Case 0: unit='' (default) and sep=' ' (default).

# 'expected' already corresponds to this reference case.

exp_outputs = expected

formatters = (

mticker.EngFormatter(), # places=None (default)

mticker.EngFormatter(places=0),

mticker.EngFormatter(places=2)

)

for _formatter, _exp_output in zip(formatters, exp_outputs):

assert _formatter(input) == _exp_output

# Case 1: unit=UNIT and sep=' ' (default).

# Append a unit symbol to the reference case.

# Beware of the values in [1, 1000), where there is no prefix!

exp_outputs = (_s + " " + UNIT if _s[-1] in DIGITS # case w/o prefix

else _s + UNIT for _s in expected)

formatters = (

mticker.EngFormatter(unit=UNIT), # places=None (default)

mticker.EngFormatter(unit=UNIT, places=0),

mticker.EngFormatter(unit=UNIT, places=2)

)

for _formatter, _exp_output in zip(formatters, exp_outputs):

assert _formatter(input) == _exp_output

# Test several non default separators: no separator, a narrow

# no-break space (unicode character) and an extravagant string.

for _sep in ("", "\N{NARROW NO-BREAK SPACE}", "@_@"):

# Case 2: unit=UNIT and sep=_sep.

# Replace the default space separator from the reference case

# with the tested one `_sep` and append a unit symbol to it.

exp_outputs = (_s + _sep + UNIT if _s[-1] in DIGITS # no prefix

else _s.replace(" ", _sep) + UNIT

for _s in expected)

formatters = (

mticker.EngFormatter(unit=UNIT, sep=_sep), # places=None

mticker.EngFormatter(unit=UNIT, places=0, sep=_sep),

mticker.EngFormatter(unit=UNIT, places=2, sep=_sep)

)

for _formatter, _exp_output in zip(formatters, exp_outputs):

assert _formatter(input) == _exp_output

# Case 3: unit='' (default) and sep=_sep.

# Replace the default space separator from the reference case

# with the tested one `_sep`. Reference case is already unitless.

exp_outputs = (_s.replace(" ", _sep) for _s in expected)

formatters = (

mticker.EngFormatter(sep=_sep), # places=None (default)

mticker.EngFormatter(places=0, sep=_sep),

mticker.EngFormatter(places=2, sep=_sep)

)

for _formatter, _exp_output in zip(formatters, exp_outputs):

assert _formatter(input) == _exp_output

def __init__(self, unit="", places=None, sep=" "):

"""

self.sep = sep

# Remove the trailing separator when there is neither prefix nor unit

if len(self.sep) > 0 and s.endswith(self.sep):

s = s[:-len(self.sep)]

if isinstance(num, six.string_types):

warnings.warn(

"Passing a string as *num* argument is deprecated since"

"Matplotlib 2.1, and is expected to be removed in 2.3.",

mplDeprecation)

dnum = float(num)

fmt = "g" if self.places is None else ".{:d}f".format(self.places)

pow10 = int(math.floor(math.log10(dnum) / 3) * 3)

pow10 = 0

# Force dnum to zero, to avoid inconsistencies like

# format_eng(-0) = "0" and format_eng(0.0) = "0"

# but format_eng(-0.0) = "-0.0"

dnum = 0.0

pow10 = np.clip(pow10, min(self.ENG_PREFIXES), max(self.ENG_PREFIXES))

mant = sign * dnum / (10.0 ** pow10)

# Taking care of the cases like 999.9..., which

# may be rounded to 1000 instead of 1 k. Beware

# of the corner case of values that are beyond

# the range of SI prefixes (i.e. > 'Y').

_fmant = float("{mant:{fmt}}".format(mant=mant, fmt=fmt))

if _fmant >= 1000 and pow10 != max(self.ENG_PREFIXES):

mant /= 1000

pow10 += 3

formatted = "{mant:{fmt}}{sep}{prefix}".format(

mant=mant, sep=self.sep, prefix=prefix, fmt=fmt)