bpo-27867: Add a porting guide for PySlice_GetIndicesEx(). by serhiy-storchaka · Pull Request #1973

bpo-27867: Add a porting guide for PySlice_GetIndicesEx(). by serhiy-storchaka · Pull Request #1973 · python/cpython

		Returns ``0`` on success and ``-1`` on error with exception set.

		.. note::
		This function considered not safe for resizable sequences. Replace its invocation ::

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a typo? Maybe is considered? Also there is a whitespace before ::. I do not know if it is intentional, considering you apply the :: without a whitespace in the sentence below

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you. Yes, this is a typo. A whitespace before :: is intentional.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The manual change looks good to me (could improve still), the what's new blurb is a tad confusing.

		Returns ``0`` on success and ``-1`` on error with exception set.

		.. note::
		This function is considered not safe for resizable sequences. Replace its invocation ::

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought about "is considered not" v.s. "is not considered" for a while, but actually the former/current version as its semantics seem more appropriate

		// return error
		}

		with using functions :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices`::

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You want to link to these functions here? It makes the sentence a bit of a roller coaster.

Could it be possible to move the "using ..." to after the code block? so:

with

if (Py [...]

using functions :c: ...

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or restructure it, so that the whole block is

"This function is considered not safe for resizable sequences. Its invocation should be replaced by a combination of :c:... and :c:... where

if (PySlice_Get[...]

is replaced by

if (PySlice_Unpack..."

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, I'll restructure it.

		Changes in the C API
		--------------------

		* Function :c:func:`PySlice_GetIndicesEx` is considered not safe for

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Function" -> "The function"


		* Function :c:func:`PySlice_GetIndicesEx` is considered not safe for
		resizable sequences. It takes the current length of the sequence, but
		if the slice indices are not instances of :class:`int`, but objects that

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"[...] instances of :class:int" seems like an unended thoought. The double but in a row ("but if ..", "but objects") is quite confusing. Consider splitting into 2 or more sentences?


		is replaced by ::

		if (PySlice_Unpack(slice, length, &start, &stop, &step) < 0) {

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove length from argument list.