Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC: Fix colLoc default #26696

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.

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

Merged
merged 1 commit into from
Oct 19, 2023
Merged

DOC: Fix colLoc default #26696

merged 1 commit into from
Oct 19, 2023

Conversation

StefRe
Copy link
Contributor

@StefRe StefRe commented Sep 5, 2023

PR summary

  • fix colLoc default
  • make docs in table.py conform to numpydoc
  • move setting default value of loc of Cell from code to signature

PR checklist

@story645 story645 added topic: table Documentation: API files in lib/ and doc/api labels Sep 5, 2023
@oscargus
Copy link
Member

oscargus commented Sep 5, 2023

I took the liberty to merge a fix removing a trailing space that I had introduced in the earlier suggestion...

@StefRe
Copy link
Contributor Author

StefRe commented Sep 6, 2023

Thanks @oscargus and @QuLogic for your reviews. I took this opportunity to take another look at the rules for docstrings in matplotlib (this referring to numpydoc] and it says

When a parameter can only assume one of a fixed set of values, those values can be listed in braces, with the default appearing first:

order : {'C', 'F', 'A'}
   Description of `order`.

so I reordered the options accordingling and removed the explict mentioning of the default value in the docstring.

I further noticed that loc in Cell has a default value of None

which is then set to right in the code:

if loc is None:
loc = 'right'

so I took the liberty to change the default directly to 'right'. Formally speaking, this is an API change but in practice this will only have any effect if someone would explitely use Cell(... loc=None). The only place where Cell() is used in the matplotlib code is in add_cell and non of the calls of add_cell pass None for loc. However, if you feel this is too unsafe a change I will be happy to reverse it.

@story645
Copy link
Member

Could you add an api change note if it isn't too much trouble?

@tacaswell
Copy link
Member

What is the API change? The default value in the signature changed, but the run time behavior should not have changed.

@story645
Copy link
Member

story645 commented Oct 12, 2023

The default value in the signature changed

Isn't that usually something we flag as an API change even if the behavior doesn't change? Just in case someone was relying on it?
ETA: @StefRe explains why #26696 (comment)

Formally speaking, this is an API change but in practice this will only have any effect if someone would explitely use Cell(... loc=None).

@StefRe
Copy link
Contributor Author

StefRe commented Oct 15, 2023

As I said before, I'm happy with any of the three options:

  1. change the default loc paramter in Cell to 'right' but don't add an API change note (this is what this PR currently is)
  2. change the default loc paramter in Cell to 'right' and add an API change note
  3. leave the default loc paramter in Cell unchanged

I tried to find an answer to the question about API changes in the documentation and found this:

  • If in doubt, decisions about API changes are finally made by the API consistency lead developer

which leads to the question who the API consistency lead developer is.

@story645
Copy link
Member

who the API consistency lead developer is.

@timhoffm - that info lives at https://matplotlib.org/governance/people.html#deputy-project-leads

@timhoffm
Copy link
Member

No API change note is a bit too adventurous. If we wanted to be very defensive, the removal of None support would have to go through a deprecation cycle. We may dare to remove it immediately, but we at least have to document this in an API change note.

@StefRe
Copy link
Contributor Author

StefRe commented Oct 18, 2023

@story645 I added the API change note. The Sphinx FileNotFoundError: [Errno 2] No such file or directory: '/tmp/pip-build-env-cidrmif2/normal/bin/ninja' seems to be unrelated to this PR.

@QuLogic
Copy link
Member

QuLogic commented Oct 18, 2023

You'll need to rebase to fix CI.

- fix colLoc default
- make docs in table.py conform to numpydoc
- move setting default value of loc of Cell from code to signature
@story645 story645 modified the milestones: v3.8.1, v3.9.0 Oct 19, 2023
@story645 story645 merged commit 26b3128 into matplotlib:main Oct 19, 2023
@story645
Copy link
Member

Thanks for going the extra steps of making the API note!

@StefRe StefRe deleted the patch-1 branch October 19, 2023 06:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation: API files in lib/ and doc/api topic: table
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants