Skip to content
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

Undocumented method for "slice" class #99121

Open
WANGCHEN722 opened this issue Nov 5, 2022 · 5 comments
Open

Undocumented method for "slice" class #99121

WANGCHEN722 opened this issue Nov 5, 2022 · 5 comments
Labels
docs Documentation in the Doc dir

Comments

@WANGCHEN722
Copy link

WANGCHEN722 commented Nov 5, 2022

Documentation

The "slice" class has a method "indices" that, when given a length of a sequence, will return a tuple with (start, stop, step) that is adjusted for the length of that sequence. This method is completely undocumented

For example,

x=slice(0, 10, -2)
x.indices(5) #This returns (0, 4, -2)
x.indices(10) #This returns (0, 9, -2)
x.indices(100) #This returns (0, 9, -2)

The only example that I could find in any official Python documents is this, there is a single reference to this method at the bottom of the page. However, as of the lastest version of Python, which is 3.11.0 at the time of writing, using this method in a standard installation of CPython still works.

@WANGCHEN722 WANGCHEN722 added the docs Documentation in the Doc dir label Nov 5, 2022
@hugovk
Copy link
Member

hugovk commented Nov 5, 2022

I found this by searching for "indices":

https://docs.python.org/3/reference/datamodel.html?highlight=indices#slice.indices

Slice objects support one method:

slice.indices(self, length)

This method takes a single integer argument length and computes information about the slice that the slice object would describe if applied to a sequence of length items. It returns a tuple of three integers; respectively these are the start and stop indices and the step or stride length of the slice. Missing or out-of-bounds indices are handled in a manner consistent with regular slices.

@stevendaprano
Copy link
Member

stevendaprano commented Nov 5, 2022

The documentation for the slice class should mention the indices method. It is a documentation bug to say that slice objects "have no other explicit functionality".

The comment "they are used by NumPy and other third-party packages" seems to be irrelevant. Most builtins are used by numpy and other third-party packages. I think that comment might be a left-over from ancient Python 1.5 when extended slicing with a step had been added to the language for numpy but no builtins used it yet? Maybe I am misremembering.

Either way, I think we can also remove the bit about numpy and third party packages.

@pochmann
Copy link
Contributor

pochmann commented Nov 5, 2022

You're looking at the built-in functions page. That's the wrong place. That doesn't contain documentations of the whole types. The built-in types page does. The slice type doesn't have its own section there, but it's listed in Internal Objects, which refers to the data model page, where the slice type and this method are indeed documented (as shown by @hugovk above). Looks fine to me.

@pochmann
Copy link
Contributor

pochmann commented Nov 5, 2022

On the built-in functions page, set() starts with "Return a new set object", linking to the built-in types page. While slice() starts with "Return a slice object", linking to the glossary. Maybe that link should instead equivalently go to the data model page section about the slice type.

@hugovk
Copy link
Member

hugovk commented Nov 5, 2022

Thanks, I've updated PR #99129.

I also removed the NumPy bit, please let me know if that should stay, and if the text should be reflowed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir
Projects
None yet
Development

No branches or pull requests

4 participants