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

Skip to content

Soft deprecate the textpath module (import from text instead) #23576

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
Merged
merged 1 commit into from
Dec 21, 2022
Merged

Soft deprecate the textpath module (import from text instead) #23576

merged 1 commit into from
Dec 21, 2022

Conversation

oscargus
Copy link
Member

@oscargus oscargus commented Aug 7, 2022

The textpath module was created in 2009, but the status has
been a bit vague with many examples and exisiting code found
on the internet importing from text instead.

In this PR everything is changed to point at text, although textpath
is still available for backwards compatibility.

PR Summary

See discussion in #23565 (comment)

Also a bit of cleanup of related documentation.

PR Checklist

Tests and Styling

  • [N/A] Has pytest style unit tests (and pytest passes).
  • Is Flake 8 compliant (install flake8-docstrings and run flake8 --docstring-convention=all).

Documentation

  • [N/A] New features are documented, with examples if plot related.
  • [N/A] New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
  • [N/A] API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).
  • [N/A] Documentation is sphinx and numpydoc compliant (the docs should build without error).

@oscargus oscargus mentioned this pull request Aug 7, 2022
Closed
2 tasks
@tacaswell
Copy link
Member

I'm 50/50 on this. If anything I think the error is the places than are importing transitively through matplotilb.text not the other way around....

@oscargus
Copy link
Member Author

There is also #23565 where the consensus seems to be that this is the correct solution. Somehow, one of them should be...

@tacaswell tacaswell added this to the v3.7.0 milestone Dec 16, 2022
@tacaswell
Copy link
Member

Re-reading the conversation here and in #23565 , the consensus seems to be in favor of this path (I'm still a coin flip), so lets go with this for 3.7.

@ksunden
Copy link
Member

ksunden commented Dec 16, 2022

Should we add a __all__ to text.py to make it even more explicit that TextPath is an exported public api?

The potential downside of course being that things we don't consider "public" would no longer be imported if someone did from matplotlib.text import * ...

That said, this mostly applies to transitive imports since anything defined here would be exported and _methods are explicitly private. so this would only really affect people doing things like using Artist or np from the * import of text, which is not intended usage)

The other one that is closely related enough that I'd consider it reasonable to think "that is in text" would be FontProperties, Everything else is pretty clearly not "text" and so should not be expected to be imported via mpl.text I would expect.

timhoffm
timhoffm reviewed Dec 17, 2022
View reviewed changes
@timhoffm
Copy link
Member

The overall strategiy is good.

Should we add a __all__ to text.py to make it even more explicit that TextPath is an exported public api?

Unfortunately. specification of public API does not have proper language support in python. __all__ is only a band aid and not really suited for the task. I would refrain from this.

Another issue is that TextPath will not disguise its origin. The fully qualified name will stay matplotlib.textpath.TextPath however much we document and __all__. Well, we could monkey patch that, but that's not a good idea either. It may be reasonable to bite the bullet and actually move the code to text. Then, reverse the import and from matplotlib.text import TextPath in textpath for backward compatibility. But that can be done later.

@oscargus oscargus force-pushed the softdeprecatetextpath branch from aa0bf63 to c00711b Compare December 17, 2022 10:39
@oscargus oscargus force-pushed the softdeprecatetextpath branch from c00711b to 71a3685 Compare December 17, 2022 10:44
@oscargus
Soft deprecate the textpath module (import from text instead)
9b8a598 
The textpath module was created in 2009, but the status has
been a bit vague with many examples and exisiting code found
on the internet importing from text instead.

In this PR everything is changed to point at text, although textpath
is still available for backwards compatibility.
@oscargus oscargus force-pushed the softdeprecatetextpath branch from 71a3685 to 9b8a598 Compare December 17, 2022 10:46
@oscargus
Copy link
Member Author

Another issue is that TextPath will not disguise its origin.

As long as we use and document it consistently it will be better than the current situation. I do not think that we actually need to move it, but it is confusing if it sometimes is imported from text and sometimes from textpath.

@QuLogic QuLogic merged commit 0425a7f into matplotlib:main Dec 21, 2022
@oscargus oscargus deleted the softdeprecatetextpath branch December 21, 2022 23:22
@QuLogic QuLogic mentioned this pull request Jun 28, 2023
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@QuLogic QuLogic QuLogic approved these changes

@timhoffm timhoffm timhoffm approved these changes

Assignees
No one assigned
Labels
API: consistency Documentation topic: text
Projects
None yet
Milestone
v3.7.0
Development

Successfully merging this pull request may close these issues.
5 participants
@oscargus @tacaswell @ksunden @timhoffm @QuLogic