Is cbook public?

Nelle_Varoquaux · January 7, 2013, 3:24pm

Hello everyone,

I was recently looking at the cbook module, and I was wondering
whether this module was public or not. I think there are several
unused method in it, such as ``unmasked_index_ranges``. If this isn't
public, it may be worth cleaning the module a bit and removing the
unused method.

Cheers,
Nelle

Benjamin_Root1 · January 7, 2013, 3:32pm

Yes, it is public, but it is geared for internal use.

Michael_Droettboom · January 7, 2013, 3:38pm

I know there's a lot of code in the wild that treats cbook as public and would probably be affected by it going away. However, there hasn't been much care taken within that module as to what we want to support publicly and what would be better left as private. Many things in it, of course, are imported to the top-level of the matplotlib package, and those are quite strongly public, I would say, but we probably have to do these things on a case-by-case basis. I think the best approach is to probably deprecate now and remove later -- though there may be some things in there that we want to keep even if they aren't used internally (but let's add some tests in the latter case). Do you have a complete list of everything in cbook that isn't used by matplotlib itself?

Mike

···

On 01/07/2013 10:24 AM, Nelle Varoquaux wrote:

Hello everyone,

I was recently looking at the cbook module, and I was wondering
whether this module was public or not. I think there are several
unused method in it, such as ``unmasked_index_ranges``. If this isn't
public, it may be worth cleaning the module a bit and removing the
unused method.

Cheers,
Nelle

------------------------------------------------------------------------------
Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
MVC, Windows 8 Apps, JavaScript and much more. Keep your skills current
with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
MVPs and experts. SALE $99.99 this month only -- learn more at:
http://p.sf.net/sfu/learnmore_122412
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options

Nelle_Varoquaux · January 7, 2013, 4:05pm

I know there's a lot of code in the wild that treats cbook as public and
would probably be affected by it going away. However, there hasn't been
much care taken within that module as to what we want to support
publicly and what would be better left as private. Many things in it,
of course, are imported to the top-level of the matplotlib package, and
those are quite strongly public, I would say, but we probably have to do
these things on a case-by-case basis. I think the best approach is to
probably deprecate now and remove later -- though there may be some
things in there that we want to keep even if they aren't used internally
(but let's add some tests in the latter case). Do you have a complete
list of everything in cbook that isn't used by matplotlib itself?

This is a list I quickly built: I have no certainty that it is correct
nor complete:

book's unused functions and classes in matplotlib:

unmasked_index_ranges
tostr (note that there is a method called tostr in mlab)
todatetime
todate
tofloat
toint
_BoundMethodProxy
TimeOut
Idler
Scheduler (is used by TimeOut and Idler)
uniquer
Sorter
Xlator
soundex
Null
dict_delall
RingBuffer
wrap (unsure)
pieces
alltrue
allpairs
finddir
reverse_dict
MemoryMonitor
unmasked_index_ranges

functions that are redefined elsewhere:
is_math_text (in the text module)

I can have a closer look and deprecate things that aren't used
anywhere and don't seem very useful to anyone.

Thanks,
N

···

On 7 January 2013 16:38, Michael Droettboom <mdroe@...31...> wrote:

Mike

On 01/07/2013 10:24 AM, Nelle Varoquaux wrote:

Hello everyone,

I was recently looking at the cbook module, and I was wondering
whether this module was public or not. I think there are several
unused method in it, such as ``unmasked_index_ranges``. If this isn't
public, it may be worth cleaning the module a bit and removing the
unused method.

Cheers,
Nelle

------------------------------------------------------------------------------
Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
MVC, Windows 8 Apps, JavaScript and much more. Keep your skills current
with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
MVPs and experts. SALE $99.99 this month only -- learn more at:
http://p.sf.net/sfu/learnmore_122412
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options

------------------------------------------------------------------------------
Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
MVC, Windows 8 Apps, JavaScript and much more. Keep your skills current
with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
MVPs and experts. SALE $99.99 this month only -- learn more at:
http://p.sf.net/sfu/learnmore_122412
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options

Michael_Droettboom · January 7, 2013, 5:26pm

I know there's a lot of code in the wild that treats cbook as public and
would probably be affected by it going away. However, there hasn't been
much care taken within that module as to what we want to support
publicly and what would be better left as private. Many things in it,
of course, are imported to the top-level of the matplotlib package, and
those are quite strongly public, I would say, but we probably have to do
these things on a case-by-case basis. I think the best approach is to
probably deprecate now and remove later -- though there may be some
things in there that we want to keep even if they aren't used internally
(but let's add some tests in the latter case). Do you have a complete
list of everything in cbook that isn't used by matplotlib itself?

This is a list I quickly built: I have no certainty that it is correct
nor complete:

book's unused functions and classes in matplotlib:

unmasked_index_ranges
tostr (note that there is a method called tostr in mlab)
todatetime
todate
tofloat
toint
_BoundMethodProxy
TimeOut
Idler
Scheduler (is used by TimeOut and Idler)
uniquer
Sorter
Xlator
soundex
Null
dict_delall
RingBuffer
wrap (unsure)
pieces
alltrue
allpairs
finddir
reverse_dict
MemoryMonitor
unmasked_index_ranges

functions that are redefined elsewhere:
is_math_text (in the text module)

I can have a closer look and deprecate things that aren't used
anywhere and don't seem very useful to anyone.

That seems like a reasonable approach.

One way to handle this might be to

a) create a new module "_cbook.py" for internal use.
b) move everything used internally into there
c) in cbook.py, put "from _cbook import *" and include all of these other functions in there
d) emit a MatplotlibDeprecationWarning at the top level of cbook.py so there's a deprecation warning about the entire module.

I'm not sure this is the best approach, but it's an easy way to deprecate a lot of things at once. Comments from other are appreciated.

Cheers,
Mike

···

On 01/07/2013 11:05 AM, Nelle Varoquaux wrote:

On 7 January 2013 16:38, Michael Droettboom <mdroe@...31...> wrote:

Thanks,
N

Mike

On 01/07/2013 10:24 AM, Nelle Varoquaux wrote:

Hello everyone,

I was recently looking at the cbook module, and I was wondering
whether this module was public or not. I think there are several
unused method in it, such as ``unmasked_index_ranges``. If this isn't
public, it may be worth cleaning the module a bit and removing the
unused method.

Cheers,
Nelle

------------------------------------------------------------------------------
Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
MVC, Windows 8 Apps, JavaScript and much more. Keep your skills current
with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
MVPs and experts. SALE $99.99 this month only -- learn more at:
http://p.sf.net/sfu/learnmore_122412
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options

------------------------------------------------------------------------------
Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
MVC, Windows 8 Apps, JavaScript and much more. Keep your skills current
with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
MVPs and experts. SALE $99.99 this month only -- learn more at:
http://p.sf.net/sfu/learnmore_122412
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options

Nelle_Varoquaux · January 8, 2013, 4:12pm

One way to handle this might be to

a) create a new module "_cbook.py" for internal use.
b) move everything used internally into there
c) in cbook.py, put "from _cbook import *" and include all of these other
functions in there
d) emit a MatplotlibDeprecationWarning at the top level of cbook.py so
there's a deprecation warning about the entire module.

I'm not sure this is the best approach, but it's an easy way to deprecate a
lot of things at once. Comments from other are appreciated.

I think it is going to be slightly more complicated than that, as
there are method that are meant for public use (such as
get_sample_data).
I think indeed it would be nice to deprecate most of the methods that
aren't use in matplotlib, and make private the ones that aren't useful
to users (that would make refactoring easier), but that needs to be
done cases by cases.

I can work on that and submit a PR.

···

Cheers,
Mike

Thanks,
N

Mike

On 01/07/2013 10:24 AM, Nelle Varoquaux wrote:

Hello everyone,

I was recently looking at the cbook module, and I was wondering
whether this module was public or not. I think there are several
unused method in it, such as ``unmasked_index_ranges``. If this isn't
public, it may be worth cleaning the module a bit and removing the
unused method.

Cheers,
Nelle

------------------------------------------------------------------------------
Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
MVC, Windows 8 Apps, JavaScript and much more. Keep your skills current
with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
MVPs and experts. SALE $99.99 this month only -- learn more at:
http://p.sf.net/sfu/learnmore_122412
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options

------------------------------------------------------------------------------
Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
MVC, Windows 8 Apps, JavaScript and much more. Keep your skills current
with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
MVPs and experts. SALE $99.99 this month only -- learn more at:
http://p.sf.net/sfu/learnmore_122412
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options

Nelle_Varoquaux · January 9, 2013, 2:00pm

I can work on that and submit a PR.

I've submitted a PR (this is Work In Progress):

github.com/matplotlib/matplotlib

WIP: Deprecation of the cbook module

matplotlib:master ← NelleV:cleanup_cbook_next

opened 01:57PM - 09 Jan 13 UTC

NelleV

+2272 -2342

Most of the methods in `cbook` are only meant for internal use. This PR deprecat…es the `cbook` module in favor of a new one which will not be mentionned in the user documentation. Moreover many of the methods present in the current `cbook` module are not used in matplotlib anymore. Hence, deprecating the module will help removing unused methods in the future. I've proceeded into two steps: 1. As suggested by @mdboom, I deprecated the module cbook, and move the methods to a private module _cbook 2. I then moved all the used methods to a new module utils, and updated the code, documentation, tests and examples to reflect that change. Hence we now have two new submodules: `_cbook`, which contains methods that aren't used in matplotlib, and `utils` containing methods used in matplotlib.

I think ``get_sample_data`` should be moved to a public, documented module,
as, unlike other methods from the cbook module, it is meant for public use.

···

>
> Cheers,
> Mike
>
>
>>
>> Thanks,
>> N
>>
>>> Mike
>>>
>>>
>>> On 01/07/2013 10:24 AM, Nelle Varoquaux wrote:
>>>>
>>>> Hello everyone,
>>>>
>>>> I was recently looking at the cbook module, and I was wondering
>>>> whether this module was public or not. I think there are several
>>>> unused method in it, such as ``unmasked_index_ranges``. If this isn't
>>>> public, it may be worth cleaning the module a bit and removing the
>>>> unused method.
>>>>
>>>> Cheers,
>>>> Nelle
>>>>
>>>>
>>>>
------------------------------------------------------------------------------
>>>> Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
>>>> MVC, Windows 8 Apps, JavaScript and much more. Keep your skills
current
>>>> with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
>>>> MVPs and experts. SALE $99.99 this month only -- learn more at:
>>>> http://p.sf.net/sfu/learnmore_122412
>>>> _______________________________________________
>>>> Matplotlib-devel mailing list
>>>> Matplotlib-devel@lists.sourceforge.net
>>>> matplotlib-devel List Signup and Options
>>>
>>>
>>>
>>>
------------------------------------------------------------------------------
>>> Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
>>> MVC, Windows 8 Apps, JavaScript and much more. Keep your skills current
>>> with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
>>> MVPs and experts. SALE $99.99 this month only -- learn more at:
>>> http://p.sf.net/sfu/learnmore_122412
>>> _______________________________________________
>>> Matplotlib-devel mailing list
>>> Matplotlib-devel@lists.sourceforge.net
>>> matplotlib-devel List Signup and Options
>
>