Series.weekday is totally undocumented

[cancan101]

There is no documentations for this method: http://pandas.pydata.org/pandas-docs/dev/generated/pandas.Series.weekday.html

[jtratner]

Okay, great that you are finding all of these undocumented areas. Feel free
to submit a PR.

[jorisvandenbossche]

But maybe another question: why is there a Series.weekday method? Because it is the only date-time component that is available directly on the Series object. All the others (like hour, minute, year, date, ...) are only available for the index object.
So I would say: or all those methods should be made available as Series method, or we remove the Series.weekday method (or at least: don't document it if it can't be removed, or refer to DatetimeIndex.weekday).
Or is there a good reason that Series.weekday is available?

[cancan101]

I have no idea why Series.weekday is the only date-time component available on the Series object. I would be fine with removing it.

[jtratner]

Okay, might be nice to add deprecated method decorators so you could just slap one on with a version number for when they'll be removed. Seems like there have been a number.

Doesn't need to be complicated or anything.

[cancan101]

Something along these lines, adding a parameter to the decorator with the version: https://wiki.python.org/moin/PythonDecoratorLibrary#Generating_Deprecation_Warnings ?

[jtratner]

Sure, again doesn't need to be anything complicated. I'd probably prefer to do something like the following (and you can play around with or discard this if you like, I don't have time to put anything together right now). First, you'll probably want the optional_args decorator that I wrote up (I think its in testing) so it's less verbose:

@optional_args
def deprecated(f, future_version='a future version', alternative='', name=None):
    if not compat.callable(f): # pragma: no cover
        raise TypeError('Can only deprecate functions. Got %r' % f)
    name = name or f.__name__ or ''
    msg = '%(name) is deprecated and will be removed in %(future_version).' % dict(future_version=future_version, name=name)
     if alternative:
        msg += ' Use %r instead' % alternative

    @functools.wraps(f)
    def wrapper(*args, **kwargs):
        warnings.warn(msg) # might want to bump the stack level here
        return f(*args, **kwargs)
     wrapper.__doc__ = 'DEPRECATED: %s\n%s' % (msg, wrapper.__doc__)
     return wrapper

Otherwise I might have time to do this next week.