[issue18697] Unify arguments names in Unicode object C API documentation

[STINNER Victor]

Change by STINNER Victor :


--
components: +C API
nosy: +vstinner

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Stéphane Wirtel]

Change by Stéphane Wirtel :


--
versions: +Python 3.8, Python 3.9 -Python 3.4, Python 3.5, Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Philip Dye]

Change by Philip Dye :


--
nosy: +Philip Dye

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Rune Tynan]

Rune Tynan  added the comment:

It has been over a month and I'm still waiting for an updated PR review. I 
understand if people are busy, but don't want this to just fall through the 
cracks.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[STINNER Victor]

Change by STINNER Victor :


--
nosy:  -vstinner

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Rune Tynan]

Change by Rune Tynan :


--
keywords: +patch
pull_requests: +12607
stage: needs patch -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Rune Tynan]

Rune Tynan  added the comment:

Another inconsistency I've noticed is that the code sometimes refers to 
Py_ssize_t instances as a 'length' and sometimes as a 'size'. It seems like 
'size' is the more common one in the docs, but the headers more often use 
'length'. Which would be the better one to keep for the common case?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Rune Tynan]

Rune Tynan  added the comment:

I have some interest in making a fix for this. From discussion, I'm thinking 
that, barring names that already have clear meaning (EG, left/right for things 
with two parameters):
- PyObject* that is unknown type remains `obj`
- PyObject* with unicode string is `unicode`
- const char*, const Py_UNICODE*, and const wchar* becomes `str`
- const char, const Py_UNICODE, and const wchar become `ch`

Those seem to be the intersect of most common and most descriptive names 
already seen.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Rune Tynan]

Change by Rune Tynan :


--
nosy: +Rune Tynan

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Windson Yang]

Change by Windson Yang :


--
versions:  -Python 2.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Windson Yang]

Change by Windson Yang :


--
versions: +Python 2.7, Python 3.4, Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Windson Yang]

Windson Yang  added the comment:

I agreed with @Matheus, it would be better than the current implementation

--
nosy: +Windson Yang
versions: +Python 3.6, Python 3.7 -Python 2.7, Python 3.4, Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Mark Lawrence]

Change by Mark Lawrence :


--
nosy:  -BreamoreBoy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Matheus Vieira Portela]

Matheus Vieira Portela added the comment:

Just checking, it would be required to update Objects/unicodeobject.c, 
Include/unicodeobject.h, and Doc/c-api/unicode.rst, right?

As far as I saw, "unicode" means a Python object with unicode string, "u" is a 
UTF-8 encoded C string, "str" and "s" are encoded C strings (UTF-8, UTF-7, 
ASCII, Latin-1, among others). Is it alright to rename Python unicode objects 
to "unicode" and the others to simply "str"? These names are more meaningful 
than the single character alternatives.

The same logic would be applied to the other types, always keeping the longer 
name rather than the single character ones.

--
nosy: +matheus.v.portela

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Serhiy Storchaka]

Serhiy Storchaka added the comment:

The same issue exists for other types. E.g. PyLong_* functions have Python long 
argument named as p, obj and pylong, PyFloat_* -- p and pyfloat, PyList_* -- p 
and list, PyDict_* -- p, a and mapping, PyBytes_* -- o, obj, string and bytes.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Serhiy Storchaka]

Serhiy Storchaka added the comment:

> @Serhiy will you be proposing a patch for this?

No, I am not. I have no opinion what name is better.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Mark Lawrence]

Mark Lawrence added the comment:

@Serhiy will you be proposing a patch for this?

--
nosy: +BreamoreBoy
versions: +Python 3.5 -Python 3.3

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue18697] Unify arguments names in Unicode object C API documentation

[Serhiy Storchaka]

New submission from Serhiy Storchaka:

In declarations of Unicode object C API functions in Doc/c-api/unicode.rst the 
first Unicode object argument has different names: "unicode", "str", "u", "s". 
It will be good to unify these names.

Of course there is no need to change reasonable argument names for such 
functions as PyUnicode_Concat() or PyUnicode_CopyCharacters().

--
assignee: docs@python
components: Documentation, Unicode
keywords: easy
messages: 194755
nosy: docs@python, ezio.melotti, haypo, serhiy.storchaka
priority: normal
severity: normal
stage: needs patch
status: open
title: Unify arguments names in Unicode object C API documentation
type: enhancement
versions: Python 2.7, Python 3.3, Python 3.4

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com