10000 Documentation of fontdict · Issue #10293 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

Documentation of fontdict #10293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
timhoffm opened this issue Jan 22, 2018 · 14 comments · Fixed by #25799
Closed

Documentation of fontdict #10293

timhoffm opened this issue Jan 22, 2018 · 14 comments · Fixed by #25799
Labels
Documentation

Comments

@timhoffm
Copy link
Member

While working on the docs, I've found a fontdict parameter on multiple pyplot functions such as xlabel, text, title etc.

I've not found a concise documentation which values are supported here.

Questions:

  1. What are the allowed values?
  2. What's the exact purpose of this parameter? AFAICS it's simply passing it's contents to a Text object, which can already be achieved by kwargs.
@anntzer
Copy link
Contributor
anntzer commented Jan 23, 2018

Answer to 1) is pretty clearly "any kwarg to Text" and to 2) is probably "because no one complained about the redundant API" (seems to have come in very early, in e34a333).
(funny thing is that many of these kwargs are then themselves forwarded to fontproperties (see also #10249))
I would support making this more principled...

@timhoffm
Copy link
Member Author
timhoffm commented Jan 23, 2018 •
edited
Loading

Thanks for the reply. So this is 'historic'.

Is there a benefit from using fontdict compared to kwargs?

If not, should this be deprecated for removal in 3.0?
If so, what do we do about it?

  • Just document how it works (all Text properties)?
  • Limit and document the set of accepted parameters?
  • Somehow merge it with fontproperties (not looked into this)?

@jklymak
Copy link
Member
jklymak commented Jan 23, 2018

Are all the extra kwargs passed through? Umm, OK, I'm dumb, but how do I mix a kwarg dictionary with bare kwargs? i.e. set_title('boo', location='left', kargdict) Its pretty convenient to have a dict to pass to all your future text calls.

@anntzer
Copy link
Contributor
anntzer commented Jan 23, 2018

set_title('boo', location='left', **kargdict) will unpack your kwargs there

@jklymak
Copy link
Member
jklymak commented Jan 23, 2018

Certainly we'd want to have lots of examples of this, because I don't think a lot of users know this syntax.

@efiring
Copy link
Member
efiring commented Jan 23, 2018

It looks like text._process_text_args is used only in figure.Figure.Text, and all it does there is to return the fontdict if it exists, or an empty dictionary if not; so that function can be removed.

I'm not sure that removing the fontdict kwarg itself is a good idea, however. In various text calls one might want a common font-related properties in a single dictionary, and other kwargs in another dictionary. Only one of them can be supplied via **kwargs (unless this has changed recently). Having a single common fontdict kwarg also provides some organization to the signature and the corresponding documentation.

I'm not unalterably opposed to deprecating fontdict over several--not just one--release cycles, but I need some convincing.

@anntzer
Copy link
Contributor
anntzer commented Jan 23, 2018

I think we should also consider the opposite route of requiring text kwargs to be passed in their own dict (as mentioned by @efiring the organization it provides it worthwhile). Of course this goes back to the general issue of mpl's use of kwargs throughout to set properties through the entire call stack.

@jklymak
Copy link
Member
jklymak commented Jan 23, 2018

I've often found myself confused how to specify font properties and have to look it up. And then some properties can be set by keyword and others (I think) need to be provided in fontdict. So I'm actually pretty 👍 on simplifying/unifying the API.

An would be to have a fontdict() function that had all the font properties as kwargs so the possible kwargs at least command-completed in various tools.

@anntzer
Copy link
Contributor
anntzer commented Jan 23, 2018

See #10249 for a writeup/todo on font properties...

@timhoffm
Copy link
Member Author

@anntzer I don't think "requiring text kwargs to be passed in their own dict" is a good idea. It would significantly clutter simple use cases, in particular in pyplot

text('foo', fontdict={'color': red})
# vs.
text('foo', color='red')

For the moment, I will just document the current state, that fontdict is an additional way of specifying Text parameters by passing a dict as a single argument. This is needed anyway, since fontdict will still be around for a while even if we decide to deprecate it or modify its behavior.

@dopplershift
Copy link
Contributor

To muddy the waters a bit, @efiring, that behavior about unpacking multiple dicts for kwargs has indeed changed in Python 3, which coincidentally we're about to be able to start using:

def foo(**kwargs):
    print(list(kwargs))

d1 = dict(a=1, b=2)
d2 = dict(c=3, d=4)

foo(**d1, **d2)

yields

['a', 'b', 'c', 'd']

I'm not sure if that affects any arguments.

@timhoffm
Copy link
Member Author
timhoffm commented Jan 24, 2018 •
edited
Loading

Indeed, multiple dicts reduce the benefit of an explicit fontdict. Essentially the only use case of the explicit version is the ability to pass two parameter dicts, such as:

fontdict = {'color': 'red', 'size': 16}
leftaligned = {'multialignment': 'left', 'rotation': 45}
rightaligned = {'multialignment': 'right', 'rotation': -45}
text('foo', fontdict=fontdict, **leftaligned)
text('bar', fontdict=fontdict, **rightaligned)
# ... more text()

This can then be written as:

text('foo', **fontdict, **leftaligned)
text('bar', **fontdict, **rightaligned)

Under these circumstances I vote for deprecating and removing the explicit fontdict parameter in the long run. I don't see any need for it and the interface stays simpler.

@timhoffm timhoffm mentioned this issue Jul 27, 2018
Closed
@t0mdavid-m t0mdavid-m mentioned this issue Jun 25, 2021
Closed
@github-actions
Copy link

This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!

@github-actions github-actions bot added the status: inactive Marked by the “Stale” Github Action label Apr 30, 2023
@anntzer
Copy link
Contributor
anntzer commented Apr 30, 2023

At least discouraging the use of fontdict seems reasonable here.

@github-actions github-actions bot removed the status: inactive Marked by the “Stale” Github Action label May 1, 2023
timhoffm added a commit to timhoffm/matplotlib that referenced this issue May 1, 2023
@timhoffm
Discourage fontdict
c447d73 
Closes matplotlib#10293. `fontdict` is redundant API, but it's not bad enough to
justify the user hassle of a deprecation. By discouraging we point the
users away from `fontdict` so that the somewhat messy documentation
state of `fontdict` is less of a concern.
@timhoffm timhoffm mentioned this issue May 1, 2023
Merged
timhoffm added a commit to timhoffm/matplotlib that referenced this issue May 1, 2023
@timhoffm @story645
Discourage fontdict
8d39a8b 
Closes matplotlib#10293. `fontdict` is redundant API, but it's not bad enough to
justify the user hassle of a deprecation. By discouraging we point the
users away from `fontdict` so that the somewhat messy documentation
state of `fontdict` is less of a concern.

Co-authored-by: hannah <story645@gmail.com>
eslothower pushed a commit to eslothower/matplotlib that referenced this issue May 3, 2023
@timhoffm @story645 @eslothower
Discourage fontdict
cb8cde3 
Closes matplotlib#10293. `fontdict` is redundant API, but it's not bad enough to
justify the user hassle of a deprecation. By discouraging we point the
users away from `fontdict` so that the somewhat messy documentation
state of `fontdict` is less of a concern.

Co-authored-by: hannah <story645@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Discourage fontdict timhoffm/matplotlib
5 participants
@efiring @dopplershift @anntzer @jklymak @timhoffm
0