Docs for a method wrapping a matplotlib method

3rd Party Packages
1

Hi,

I am building a package to visualize football/soccer data: https://github.com/andrewRowlinson/mplsoccer.

The main Pitch class has methods that wrap around matplotlib’s plotting methods, e.g. ax.scatter, ax.plot etc… The main reason for including these methods are because the pitches are often flipped vertically, which switches the x and y axis. People often forget to do this, so I want to do it automatically. As well as add some extra features like rotating markers.

I was wondering what is the best way of documenting these methods that wrap around Matplotlib’s methods. Do I just copy the docstrings manually and paste them, or do you use some library to do this automatically? Also is there any issues with copying the docs from Matplotlib as I ideally want to release it with an MIT license.

Thanks

Andy

2

I’m doing a similar thing where it makes a lot of sense to wholesale copy sections of the matplotlib docstrings. So I’m also curious about the copyright situation. So in essence: bump of this

3

@andrewRowlinson you may be interested in this function: https://github.com/matplotlib/matplotlib/blob/fd8c87ecaccfdf798a9d7664a32434cc25720291/lib/matplotlib/pyplot.py#L82

4

Sorry for seeing this so late.

We are licensed under a permissive license (it is a derivative of the PSF license and in the BSD family). If you end up copying a non-trivial amount of code or docs the safest course of action is to add the Matplotlib license to your project as a derived work (see points 2 and 3 of https://matplotlib.org/users/license.html).

@ianhi Please do not use private functions, we can (and do) change them with out warning, if you want that function for your own purposes either convince us to make it public or vendor it into your code :slight_smile: .

5

@QuLogic pointed out that fastai has a tiny bit of maybe easy to vendor code (delegets) that’s also kinda implemented in #14857 that is a decorator where you specify which function you’re wrapping and it handles kwarg expansion.

6

Thanks for the responses. Two follow up questions:

@ianhi Please do not use private functions, we can (and do) change them with out warning,

:grimacing: I just started calling a different private function maybe 30 minutes ago. What is the appropriate venue for attempts at convincing, maybe feature requests? I’m using ax._sci because that’s what pyplot.sci does and I’ve been trying to avoid importing pyplot because I think you’re supposed to avoid that when writing a library using OO interface??

If you end up copying a non-trivial amount of code or docs the safest course of action is to add the Matplotlib license to your project as a derived work

I imagine there’s no clear line on what “non-trivial” means? I had actually read that page before, but found it a bit mystifying to go from the words there to an actionable step. Maybe a potential doc improvement would be a page with clear instructions for following that? I.e. “if you are copying this, then an example of what to do is this”

7
  1. Don’t use ax._sci, keep track of your images your self so you can be consistent with scatter and othe other collection types :wink:
  2. IANAL (and if I were I would not be your lawyer), but I do not think that is settled case law (see the google v oracle case that is still working its way through the courts https://www.eff.org/cases/oracle-v-google (which is now out of date as those scheduled dates are past, but)). I see you are a graduate student so I assume you have TA’d, at what point do you identify your students are not turning in thier own work :wink: ? When in doubt, I err on the side of including a copy license and leaving a comment in the source saying “this function copied from Matplotlib”.
8
  1. Don’t use ax._sci , keep track of your images your self so you can be consistent with scatter and other collection types

fear not! I keep track of the returned objects directly, but I don’t want to disrupt colorbars. So when users (i.e. me) run this code everything should “just work”:

from mpl_interactions import interactive_imshow
def f(param):
....
interactive_imshow(f, param = (0,5))
plt.colorbar()

and have the colorbar show up in the correct place and be based on the correct image.

now out of date as those scheduled dates are past, but)). I see you are a graduate student so I assume you have TA’d, at what point do you identify your students are not turning in thier own work :wink: ? When in doubt, I err on the side of including a copy license and leaving a comment in the source saying “this function copied from Matplotlib

hahaha that’s a good test for copying. I will do as much.

To my earlier point about docs I think it would be awesome if the docs had something like a writing a third party package page. With some basic practical advice such as:

  • practical copyright rules
  • Explain the standard for inclusion in the third-party-packages list
    • Is there a standard? I felt very weird about how I seemed to be self-advertising when I added mine
  • point out that pytest-mpl exists
    • I somehow missed this for weeks
  • admonish the use of private methods
  • mention that they can (should?) redirect questions to discourse
  • information in this post about passing through docstrings
1 Like
9

That page is totally supposed to be for self-advertising. My long term goal is for that page to go away and it instead be populated by a list generated using the “Framework :: Matplotlib” PyPI classifier (issue #16592 ), which would be purely self-selecting opt on. I just haven’t had the bandwidth to work on this & haven’t conned someone else to take it on :wink:

I :100: support you opening an issue on documenting how to make a 3rd party package with all the other things you’ve listed + some ideas from a talk a few years back (yourplotlib which clarifies a recommendation I can’t link to in the usage guide for the signature of 3rd party plot wrapper functions.

10

@story645 yourplotlib is a good read thanks. At the risk of getting too far out of scope for this post: What is the vibe around the twitter account? As in, say I added something to my package that enables making cool plots and I’m going to tweet about it because I want people to be aware, should I @matplotlib or is that weird?

(Sometime later I’m gonna put a new version on pypi with scatter plot support and I was gonna tweet this wealth of nations gif: https://mpl-interactions.readthedocs.io/en/latest/examples/scatter-plots.html#putting-it-together-wealth-of-nations)

11

DO IT! Seriously, the vibe is tell @matplotlib about all the cool awesome things you’re doing w/ matplotlib, 'specially specially 3rd party packages & extra specially 'cause you’re a contributor & I totally use @matplotlib as an advert service for contributors projects. :wink:

If you’re interested, it’s more fully spelled out in the communications guide

1 Like