gh-86017: Improve font actual docs by E-Paine · Pull Request #22434 · python/cpython · GitHub

Given that Serhiy does not see the reason for a equal method and Tal was unaware of the actual method, I instead propose a major improvement to the actual docs. The docs are currently very brief and do not offer any explanation on what the kwargs are for. I have completely removed the existing doc and instead added a modified version of the tk man's description.

With it being so heavy based on the man page, I assume we need to give credit but would appreciate if someone could double check I have done so correctly.

EDIT:
I do not intend to add a news entry as I deem this a fairly trivial change, though obviously cannot add the skip-news tag myself (so will just ignore the bedevere/news failure).

https://bugs.python.org/issue41851

Issue: tkinter: improve font.actual doc #86017

Thanks Tal for adding the label!

These are excellent improvements to the docs!

I have a few suggestions.

This says "above" but the reference is to a separate page. Is "above" referencing the constructor's docs? If so, let's add a link to it.

The "above" is referring to "additional keyword options". The link is to give reasonable credit to the man page as the entirety of the actual docs is just a modified version of the content found there (though I'm open to a more clear way of showing this).

Nice!

This will be very useful to many who wouldn't know where to find this otherwise!

Note that Docs/library/tkinter.font.rst only exists since 3.9.

The Tk docs are released under a permissive license that allows free use, but require attribution. See full quote of the license below. (source: the license.terms file in the tk-8.6.10.tar.gz source archive, which includes the documentation in the doc/ directory.)

Would you be able to re-word that part in your own words, so we can avoid having to include the full attribution notice?

This software is copyrighted by the Regents of the University of
California, Sun Microsystems, Inc., Scriptics Corporation, ActiveState
Corporation, Apple Inc. and other parties. The following terms apply to
all files associated with the software unless explicitly disclaimed in
individual files.

The authors hereby grant permission to use, copy, modify, distribute,
and license this software and its documentation for any purpose, provided
that existing copyright notices are retained in all copies and that this
notice is included verbatim in any distributions. No written agreement,
license, or royalty fee is required for any of the authorized uses.
Modifications to this software may be copyrighted by their authors
and need not follow the licensing terms described here, provided that
the new terms are clearly indicated on the first page of each file where
they apply.

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE
IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
MODIFICATIONS.

GOVERNMENT USE: If you are acquiring this software on behalf of the
U.S. government, the Government shall have only "Restricted Rights"
in the software and related documentation as defined in the Federal
Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you
are acquiring the software on behalf of the Department of Defense, the
software shall be classified as "Commercial Computer Software" and the
Government shall have only "Restricted Rights" as defined in Clause
252.227-7013 (b) (3) of DFARs. Notwithstanding the foregoing, the
authors grant the U.S. Government and others acting in its behalf
permission to use and distribute the software in accordance with the
terms specified in this license.

Oh... I'll work on it!

Thanks for the rewrite, @E-Paine, looking good!

Perhaps let's separate the last sentence about displayof into a new paragraph, and mention what type of object it is: Is it a string? What does it reference? Can we give an example?

@taleinat did you mean to repeat what you said earlier in the review about separating the last sentence into its own paragraph? I believe this is already resolved but can look at it again if you want.

@taleinat did you mean to repeat what you said earlier in the review about separating the last sentence into its own paragraph? I believe this is already resolved but can look at it again if you want.

Yes, it was intentional. I should have mentioned that I was repeating it.

The current text still doesn't explain what "displayof" refers to and what type(s) it supports.

@taleinat I am not quite sure I understand. I had already said it accepted any tkinter widget but have attempted to clarify in the latest commit.

Unless someone beats me, I intend to review, fix the merge conflict (easy context change), and likely merge. I opened a draft issue on IDLE Issues under Configure to not forget forever: "Use font.actual to compare user font to defaults".

All commit authors signed the Contributor License Agreement.

This PR is stale because it has been open for 30 days with no activity.

Thanks, and to @taleinat for the review! The actual() docs were reworked under gh-143990 (#152025) — they now cover the platform differences and the dict-vs-single return, more concisely (and without the man-page attribution question). Closing as superseded. The two remaining bits — the displayof explanation and the copy() clarification — I'll fold into a separate doc change. Much appreciated!

E-Paine added 2 commits September 28, 2020 17:08

First iteration of improved Font.actual docs

82019b6

Slight clarification on Font.copy's name behaviour

a446cd6

the-knights-who-say-ni added the CLA signed label Sep 28, 2020

bedevere-bot added docs Documentation in the Doc dir awaiting review labels Sep 28, 2020

E-Paine added 2 commits September 28, 2020 19:14

Added reference to tk man page

cf263fb

Minor rephrasing (and typo fix)

63adfdc

taleinat added the skip news label Sep 28, 2020

taleinat reviewed Sep 28, 2020

View reviewed changes

taleinat added the needs backport to 3.9 label Sep 28, 2020

E-Paine added 3 commits September 28, 2020 21:42

Initial commit of Tal's suggestions

966592d

Attempt clarification of reason for link

4a3ea48

Fix :meth: link to method

b8ca758

E-Paine requested a review from taleinat September 29, 2020 15:51

Major rephrasing of actual docs

b30dbcc

Clarify 'displayof' option

f0767f0

Rewrap second paragraph

28879b1

serhiy-storchaka reviewed Dec 15, 2020

View reviewed changes

Comment thread Doc/library/tkinter.font.rst Outdated

Minor rephrasing to avoid saying 'kwargs'

2a8eab5

serhiy-storchaka added needs backport to 3.10 needs backport to 3.11 only security fixes and removed needs backport to 3.9 labels May 20, 2022

ezio-melotti removed the CLA signed label Jul 13, 2022

E-Paine mannequin mentioned this pull request Apr 10, 2022

tkinter: improve font.actual doc #86017

Closed

Merge branch 'main' into font-actual-docs

fc61256

hugovk removed the needs backport to 3.10 label Apr 8, 2023

erlend-aasland changed the title bpo-41851: Improve font actual docs gh-86017: Improve font actual docs Jan 5, 2024

erlend-aasland added the needs backport to 3.12 only security fixes label Jan 5, 2024

Merge branch 'main' into font-actual-docs

9e7f20c

erlend-aasland assigned terryjreedy Jan 5, 2024

hugovk removed the needs backport to 3.11 only security fixes label Apr 11, 2024

serhiy-storchaka added the needs backport to 3.13 only security fixes label May 9, 2024

hugovk removed the needs backport to 3.12 only security fixes label Apr 10, 2025

Merge branch 'main' into font-actual-docs

7e08284

serhiy-storchaka added the needs backport to 3.14 bugs and security fixes label May 8, 2025

github-actions Bot added the stale Stale PR or inactive for long period of time. label Apr 8, 2026

serhiy-storchaka added the needs backport to 3.15 bugs and security fixes label May 30, 2026

github-actions Bot removed the stale Stale PR or inactive for long period of time. label Jun 4, 2026

serhiy-storchaka closed this Jul 7, 2026

+                    If *option* is specified, the value of just that attribute is returned;
+                    if it is omitted, the return value is a dictionary of all the attributes
+                    and their values. See above for a list of the possible attributes. [1]_

                  .. method:: copy()
-                    Return new instance of the current font.
+                    Return new instance of the current font with a different *name*.

		.. [1] Tk 8.6 font man page
		https://www.tcl.tk/man/tcl8.6/TkCmd/font.htm#M5

gh-86017: Improve font actual docs by E-Paine · Pull Request #22434 · python/cpython · GitHub

Repository navigation

gh-86017: Improve font actual docs - #22434

gh-86017: Improve font actual docs#22434E-Paine wants to merge 14 commits intopython:mainpython/cpython:mainfrom E-Paine:font-actual-docsE-Paine/cpython:font-actual-docsCopy head branch name to clipboard

Conversation

E-Paine commented Sep 28, 2020 • edited by bedevere-app Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

E-Paine commented Sep 28, 2020

Uh oh!

taleinat left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

taleinat Sep 28, 2020

Choose a reason for hiding this comment

Uh oh!

E-Paine Sep 28, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

taleinat Sep 28, 2020

Choose a reason for hiding this comment

Uh oh!

taleinat Sep 28, 2020

Choose a reason for hiding this comment

Uh oh!

taleinat commented Sep 28, 2020

Uh oh!

taleinat commented Sep 29, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

E-Paine commented Sep 29, 2020

Uh oh!

taleinat commented Sep 30, 2020

Uh oh!

E-Paine commented Sep 30, 2020

Uh oh!

taleinat commented Sep 30, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

E-Paine commented Sep 30, 2020

Uh oh!

Uh oh!

terryjreedy commented Nov 3, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

python-cla-bot Bot commented Apr 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 8, 2026

Uh oh!

serhiy-storchaka commented Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

gh-86017: Improve font actual docs#22434
E-Paine wants to merge 14 commits into
python:mainfrom
E-Paine:font-actual-docs

E-Paine commented Sep 28, 2020 •
edited by bedevere-app Bot
Loading

E-Paine Sep 28, 2020 •
edited
Loading

taleinat commented Sep 29, 2020 •
edited
Loading

taleinat commented Sep 30, 2020 •
edited
Loading

terryjreedy commented Nov 3, 2022 •
edited
Loading

python-cla-bot Bot commented Apr 18, 2025 •
edited
Loading