Description

serhiy-storchaka

opened on Aug 9, 2013

Issue body actions

BPO	18697
Nosy	@vstinner, @ezio-melotti, @serhiy-storchaka, @matheusportela, @Windsooon, @CraftSpider
PRs	gh-62897: Update PyUnicode parameter names #12680

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2013-08-09.18:48:46.553>
labels = ['easy', '3.7', '3.8', '3.9', 'expert-C-API', 'type-feature', 'expert-unicode', 'docs']
title = 'Unify arguments names in Unicode object C API documentation'
updated_at = <Date 2019-12-09.16:13:02.233>
user = 'https://github.com/serhiy-storchaka'

bugs.python.org fields:

activity = <Date 2019-12-09.16:13:02.233>
actor = 'vstinner'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Unicode', 'C API']
creation = <Date 2013-08-09.18:48:46.553>
creator = 'serhiy.storchaka'
dependencies = []
files = []
hgrepos = []
issue_num = 18697
keywords = ['patch', 'easy']
message_count = 9.0
messages = ['194755', '224600', '224609', '231274', '249437', '337589', '339088', '339420', '347171']
nosy_count = 8.0
nosy_names = ['vstinner', 'ezio.melotti', 'docs@python', 'serhiy.storchaka', 'matheus.v.portela', 'Windson Yang', 'Rune Tynan', 'Philip Dye']
pr_nums = ['12680']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue18697'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

Linked PRs

• [3.12] gh-62897: Update PyUnicode C API parameter names (GH-12680) #112744
• [3.11] gh-62897: Update PyUnicode C API parameter names (GH-12680) #112745

Activity

1. serhiy-storchaka commented on Aug 9, 2013

   

   serhiy-storchaka

   on Aug 9, 2013

   MemberAuthor

   More actions

   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().
2. serhiy-storchaka

   assigned

   docspython

   on Aug 9, 2013
3. serhiy-storchaka

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   topic-unicode

   easy

   type-featureA feature request or enhancementA feature request or enhancement

   on Aug 9, 2013
4. BreamoreBoy commented on Aug 3, 2014

   

   BreamoreBoymannequin

   on Aug 3, 2014

   Mannequin

   More actions

   @serhiy will you be proposing a patch for this?
5. serhiy-storchaka commented on Aug 3, 2014

   

   serhiy-storchaka

   on Aug 3, 2014

   MemberAuthor

   More actions

   @serhiy will you be proposing a patch for this?

   No, I am not. I have no opinion what name is better.
6. serhiy-storchaka commented on Nov 17, 2014

   

   serhiy-storchaka

   on Nov 17, 2014

   MemberAuthor

   More actions

   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.
7. matheusportela commented on Aug 31, 2015

   

   matheusportelamannequin

   on Aug 31, 2015

   Mannequin

   More actions

   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.
8. Windsooon commented on Mar 10, 2019

   

   Windsooonmannequin

   on Mar 10, 2019

   Mannequin

   More actions

   I agreed with @matheus, it would be better than the current implementation
9. Windsooon

   added

   3.7 (EOL)end of lifeend of life

   on Mar 10, 2019
10. CraftSpider commented on Mar 29, 2019

    

    CraftSpidermannequin

    on Mar 29, 2019

    Mannequin

    More actions

    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.
11. CraftSpider commented on Apr 4, 2019

    

    CraftSpidermannequin

    on Apr 4, 2019

    Mannequin

    More actions

    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?
12. CraftSpider commented on Jul 2, 2019

    

    CraftSpidermannequin

    on Jul 2, 2019

    Mannequin

    More actions

    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.
13. matrixise

    added

    3.8 (EOL)end of lifeend of life

    3.9 (EOL)end of lifeend of life

    on Sep 11, 2019
14. vstinner

    added

    topic-C-API

    on Dec 9, 2019
15. ezio-melotti

    transferred this issue fromon Apr 10, 2022
16. serhiy-storchaka

    added 4 commits that reference this issue on Dec 5, 2023

    gh-62897: Update PyUnicode C API parameter names (GH-12680)

    b31232d

    [3.12] pythongh-62897: Update PyUnicode C API parameter names (python…

    58b2258

    [3.11] pythongh-62897: Update PyUnicode C API parameter names (python…

    381ce3a

    [3.12] gh-62897: Update PyUnicode C API parameter names (GH-12680) (G…

    f1a0c77
17. serhiy-storchaka

    closed this as completedon Dec 5, 2023
18. serhiy-storchaka

    added a commit that references this issue on Dec 5, 2023

    [3.11] gh-62897: Update PyUnicode C API parameter names (GH-12680) (G…

    8a51f6d
19. aisk

    added a commit that references this issue on Feb 11, 2024

    pythongh-62897: Update PyUnicode C API parameter names (pythonGH-12680)

    326ba4b
20. Glyphack

    added a commit that references this issue on Sep 2, 2024

    pythongh-62897: Update PyUnicode C API parameter names (pythonGH-12680)

    3a80a49

Issue actions