Skip to content

Derby #3: Convert 67 sites to Argument Clinic across 4 files (Windows) #64371

Closed

Description

@larryhastings
BPO 20172
Nosy @loewis, @larryhastings, @zware, @zooba
Dependencies
  • bpo-20189: inspect.Signature doesn't recognize all builtin types
  • bpo-20586: Argument Clinic: functions with valid sig but no docstring have no text_signature
  • Files
  • conglomerate.v2.diff
  • conglomerate.v3.diff
  • conglomerate.v4-two-pass.diff
  • conglomerate.v5-post-20189.diff
  • conglomerate.v6-post-20326.diff
  • issue20172.v7.diff
  • issue20172.v8.diff
  • 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 = 'https://github.com/zware'
    closed_at = <Date 2015-05-13.06:34:00.754>
    created_at = <Date 2014-01-07.23:45:08.589>
    labels = ['extension-modules', 'type-bug', 'expert-argument-clinic']
    title = 'Derby #3: Convert 67 sites to Argument Clinic across 4 files (Windows)'
    updated_at = <Date 2015-05-13.15:58:54.139>
    user = 'https://github.com/larryhastings'

    bugs.python.org fields:

    activity = <Date 2015-05-13.15:58:54.139>
    actor = 'python-dev'
    assignee = 'zach.ware'
    closed = True
    closed_date = <Date 2015-05-13.06:34:00.754>
    closer = 'zach.ware'
    components = ['Extension Modules', 'Argument Clinic']
    creation = <Date 2014-01-07.23:45:08.589>
    creator = 'larry'
    dependencies = ['20189', '20586']
    files = ['33504', '33606', '33661', '33695', '33775', '36256', '39016']
    hgrepos = ['216']
    issue_num = 20172
    keywords = ['patch']
    message_count = 34.0
    messages = ['207617', '207703', '207705', '207715', '207718', '207719', '207834', '207854', '207864', '207876', '207881', '207898', '208004', '208052', '208064', '208080', '208149', '208198', '208231', '208742', '208749', '208750', '208969', '209156', '209560', '224118', '224180', '224752', '241009', '241117', '241130', '243044', '243045', '243100']
    nosy_count = 5.0
    nosy_names = ['loewis', 'larry', 'python-dev', 'zach.ware', 'steve.dower']
    pr_nums = []
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = 'behavior'
    url = 'https://bugs.python.org/issue20172'
    versions = ['Python 3.5']

    Activity

    1. larryhastings commented on Jan 7, 2014

      @larryhastings
      ContributorAuthor

      This issue is part of the Great Argument Clinic Conversion Derby,
      where we're trying to convert as much of Python 3.4 to use
      Argument Clinic as we can before Release Candidate 1 on January 19.

      This issue asks you to change the following bundle of files:
      PC/msvcrtmodule.c: 18 sites
      PC/winreg.c: 24 sites
      PC/winsound.c: 3 sites
      Modules/_winapi.c: 22 sites

      Talk to me (larry) if you only want to attack part of a bundle.

      For instructions on how to convert a function to work with Argument
      Clinic, read the "howto":
      http://docs.python.org/dev/howto/clinic.html

    2. zware commented on Jan 8, 2014

      @zware
      Member

      I'll take a stab at this one, but I may make you rue the day you said you'd review until your eyes bleed ;)

      Here's a partial patch to PC/winreg.c, converting only the CloseKey function just to make sure I have some basic idea of what I'm doing.

      (Also, if anyone else wants this one, please don't hesitate on account of me; just let me know and it's yours.)

    3. zware commented on Jan 8, 2014

      @zware
      Member

      To possibly ease review (and for keeping track of what I'm doing), I'm linking hg.python.org/sandbox/zware#bpo-20172 where I'll try to do a commit per converted function.

    4. larryhastings commented on Jan 8, 2014

      @larryhastings
      ContributorAuthor

      The piecemeal approach sounds fine, but I'm only going to review patches once you post them here. (I'm not sure I can get to reviewing your patch today, but definitely tomorrow.)

    5. larryhastings commented on Jan 9, 2014

      @larryhastings
      ContributorAuthor

      I lied, I just looked at it. You said it was only one function, so it went quickly.

      It looks totally fine. In fact, Argument Clinic is generating better code than the original!

    6. larryhastings commented on Jan 9, 2014

      @larryhastings
      ContributorAuthor

      Oh, and, p.s. I was a Win32 developer for about fifteen years. I don't touch it anymore, but I consider myself still competent to read patches for simple stuff like the registry library.

    7. zware commented on Jan 10, 2014

      @zware
      Member

      Thanks, Larry. Conversion proceeds apace in winreg.c, but I have a couple questions.

      1. Since the comment above CConverter.format_unit says all custom converters should use 'O&' instead of defining format_unit, there must be another way to do this:

      /*[python input]
      class REGSAM_converter(CConverter):
      type = 'REGSAM'
      format_unit = 'i'
      default = 0

          def converter_init(self, *, key_name=""):
              if key_name == "":
                  raise ValueError('must provide the key name')
              self.doc_default = self.py_default = self.c_default = key_name
      [python start generated code]*/

      (see http://hg.python.org/sandbox/zware/rev/f0662bf33e65)

      I don't know what the 'other way' is though :). The above works, but I don't understand it completely and thus don't like it. Also, it causes help(winreg.CreateKeyEx) to show "access='KEY_WRITE'" in the signature, when it should have no quotes (being a name).

      1. Is there an easy way to give a function multiple names? OpenKey and OpenKeyEx are the same function, OpenKeyEx has been just defined by an extra methoddef pointing at OpenKey; for now I've just modified that line to make things work.

      Neither of these is blocking progress, so not a huge deal other than getting a little bit of review done early.

    8. larryhastings commented on Jan 10, 2014

      @larryhastings
      ContributorAuthor

      When I wrote that I hadn't considered that people would want custom subclasses of ints. I assumed they'd be using custom converter *functions*, which of course means they'd use 'O&'. I can think of how to reword the text but for now I assume your approach for REGSAM is fine; certainly I approve of using the correct type in the generated code.

      However, I doubt doc_default, py_default, and c_default should all be exactly the same. And the 'key_name' parameter seems a little awkward.

      Here's something you could consider: I don't think it's documented yet (I'm going as fast as I can over here, honest) but now you can use simple constants as Python defaults. So maybe you can use REGSAM like this:
      arg: REGSAM(c_default='KEY_READ') = winreg.KEY_READ

      and then REGSAM could simply be an empty ("pass") subclass of int_converter.

      No convenient way yet. Let me think about it.

    9. zware commented on Jan 10, 2014

      @zware
      Member

      Ahhhh, much better. An empty subclass doesn't do quite the right thing, but class REGSAM_converter(int_converter): type = 'REGSAM' does the trick (see http://hg.python.org/sandbox/zware/rev/5af08aa49631).

      Thanks, Larry!

      (Next will probably be trying to get a proper HKEY converter to work, but I'm holding off on that until I have most everything else clinicized first.)

    10. zware commented on Jan 10, 2014

      @zware
      Member

      Here's the complete patch for PC/winreg.c. One clinic/signature/pydoc issue I've noticed:

      >>> help(winreg.HKEYType.Close)
      Help on method_descriptor:

      Close(...) <--- No signature
      Close() <--- Extra
      Closes the underlying Windows handle.

      If the handle is already closed, no error is raised.
      
      >>> winreg.HKEYType.Close.__doc__
      'Close()\nCloses the underlying Windows handle.\n\nIf the handle is already clos
      ed, no error is raised.'
      >>> winreg.HKEYType.Close.__text_signature__
      Traceback (most recent call last):
        File "<stdin>", line 1, in <module>
      AttributeError: 'method_descriptor' object has no attribute '__text_signature__'

      My gut feeling is that it's a Clinic issue; Clinic should be adding 'self' to the signature, which should then be picked up by the __text_signature__ parser, and used by inspect and pydoc.

      As far as the patch, one point I'd like some extra scrutiny on is the HKEY_converter (and C clinic_HKEY_converter). I don't understand how all of the C machinery there works properly, so I can't say with confidence that it is right. It compiles without errors and the tests pass, but beyond that, I can't guarantee anything.

    11. zware commented on Jan 10, 2014

      @zware
      Member

      PC/winsound.c went pretty quick and easy.

    12. zware commented on Jan 11, 2014

      @zware
      Member

      Here's msvcrt.

    13. zware commented on Jan 13, 2014

      @zware
      Member

      And here is the patch to _winapi.c.

    14. 10 remaining items

    15. zware commented on Jan 25, 2014

      @zware
      Member

      Ok, v5 should be ready to go in, so long as you don't see anything scary.

    16. zware commented on Jan 28, 2014

      @zware
      Member

      I have high hopes for this latest update :)

    17. loewis commented on Jul 27, 2014

      loewismannequin
      Mannequin

      2 hunks of _winapi.c currently fail to apply. Can you please update the patch?

    18. zware commented on Jul 28, 2014

      @zware
      Member

      Certainly, Martin. I'm in the process of getting it updated and self-reviewing again. This patch will require bpo-20586 and possibly another new Clinic feature (allowing output to multiple destinations; I have a change for that feature on my bpo-20172 sandbox branch, but don't remember why and never got an issue made for it) before commit.

      I'll try to have a fresh patch up here within a week or so.

    19. zware commented on Aug 4, 2014

      @zware
      Member

      Here's an updated patch. It includes the patch from bpo-20586 for proper signature/docstring output in _winapi.

    20. zware commented on Apr 14, 2015

      @zware
      Member

      Latest patch ought to be good, if anybody feels like rubber-stamping a 5000 line patch :)

    21. zooba commented on Apr 15, 2015

      @zooba
      Member

      Reviewed v8 and it looks good to me. Not a clinic expert, but I assume that it'll fail at build if anything is really wrong.

    22. larryhastings commented on Apr 15, 2015

      @larryhastings
      ContributorAuthor

      If

      • the diff looks clean
      • it compiles without any *new* (sigh) errors, and
      • it passes the unit test suite without any *new* (sigh) failures,
        then the Clinic conversion can generally be considered a success.
    23. python-dev commented on May 13, 2015

      python-devmannequin
      Mannequin

      New changeset d3582826d24c by Zachary Ware in branch 'default':
      Issue bpo-20172: Convert the winsound module to Argument Clinic.
      https://hg.python.org/cpython/rev/d3582826d24c

      New changeset 6e613ecd70f0 by Zachary Ware in branch 'default':
      Issue bpo-20172: Convert the winreg module to Argument Clinic.
      https://hg.python.org/cpython/rev/6e613ecd70f0

      New changeset c190cf615eb2 by Zachary Ware in branch 'default':
      Issue bpo-20172: Convert the msvcrt module to Argument Clinic.
      https://hg.python.org/cpython/rev/c190cf615eb2

      New changeset 4cf37a50d91a by Zachary Ware in branch 'default':
      Issue bpo-20172: Convert the _winapi module to Argument Clinic.
      https://hg.python.org/cpython/rev/4cf37a50d91a

    24. zware commented on May 13, 2015

      @zware
      Member

      Committed, thanks for the reviews, guidance, and patience!

    25. self-assigned this
      on May 13, 2015
    26. python-dev commented on May 13, 2015

      python-devmannequin
      Mannequin

      New changeset c8adc2c13c8b by Zachary Ware in branch 'default':
      Issue bpo-20172: Update clinicizations to current clinic.
      https://hg.python.org/cpython/rev/c8adc2c13c8b

    27. transferred this issue fromon Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

    Metadata

    Metadata

    Assignees

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions