1

Closed

ptvsd.enable_attach should include the signature in it's doc string and wrap to 80 chars

description

If you look at the doc string for enable_attach from a console it's a little rough. First the doc string refers to the parameters, but doesn't tell you which is which. We should have:
enable_attach(secret, address = ('0.0.0.0', 5678), certfile = None, keyfile = None, redirect_output = True)
As the 1st line of the doc string.

Then there's some wrapping issues because the doc string is wider than 80 columns which actually violates PEP 8. Here's what I see in an 80-column console window:
  >>> print ptvsd.enable_attach.__doc__
  Enables Python Tools for Visual Studio to attach to this process remotely to deb
  ug Python code.

      The secret parameter is used to validate the clients - only those clients pr
  oviding the valid
      secret will be allowed to connect to this server. On client side, the secret
   is prepended to
      the Qualifier string, separated from the hostname by '@', e.g.: secret@myhos
  t.cloudapp.net:5678.
      If secret is None, there's no validation, and any client can connect freely.


      The address parameter specifies the interface and port on which the debuggin
  g server should listen
      for TCP connections. It is in the same format as used for regular sockets of
   the AF_INET family,
      i.e. a tuple of (hostname, port). On client side, the server is identified b
  y the Qualifier string
      in the usual hostname:port format, e.g.: myhost.cloudapp.net:5678.

      The certfile parameter is used to enable SSL. If not specified, or if set to
   None, the connection
      between this program and the debugger will be unsecure, and can be intercept
  ed on the wire.
      If specified, the meaning of this parameter is the same as for ssl.wrap_sock
  et.

      The keyfile parameter is used together with certfile when SSL is enabled. It
  s meaning is the same
      as for ssl.wrap_socket.

      The redirect_output parameter specifies whether any output (on both stdout a
  nd stderr) produced
      by this program should be sent to the debugger.

      This function returns immediately after setting up the debugging server, and
   does not block program
      execution. If you need to block until debugger is attached, call ptvsd.wait_
  for_attach. The debugger
      can be detached and re-attached multiple times after enable_attach is called
  .

      Only the thread on which this function is called, and any threads that are c
  reated after it returns,
      will be visible in the debugger once it is attached. Any threads that are al
  ready running before
      this function is called will not be visible.

  >>> ptvsd.enable_attach()
  Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
  TypeError: enable_attach() takes at least 1 argument (0 given)
  >>> ptvsd.enable_attach('foo')
  >>> sys.path.append(r'C:\Users\dinov')
  >>> import x
  >>> x.f()
  hi
  >>> x.f()
  hi
  >>> ^Z


  C:\Python27>.\python.exe
  Python 2.7.3 (default, Apr 10 2012, 23:31:26) [MSC v.1500 32 bit (Intel)] on win
  32
  Type "help", "copyright", "credits" or "license" for more information.
  >>> import sys
  >>> sys.path.append(r'C:\users\dinov')
  >>> import x
  >>> x.f()
  hi
  >>> x.f()
  hi
  >>> ^Z

comments

pminaev wrote Mar 21, 2013 at 10:05 PM

Function signature should be printed out by the help system itself, rather than being part of the docstring - use help() rather than going directly for doc:
>>> import ptvsd
>>> help(ptvsd.enable_attach)
Help on function enable_attach in module ptvsd.attach_server:

enable_attach(secret, address=('0.0.0.0', 5678), certfile=None, keyfile=None, redirect_output=True)
    Enables Python Tools for Visual Studio to attach to this process remotely
    to debug Python code.

    The secret parameter is used to validate the clients - only those clients
    providing the valid secret will be allowed to connect to this server. On
    client side, the secret is prepended to the Qualifier string, separated from
    the hostname by '@', e.g.: secret@myhost.cloudapp.net:5678. If secret is
    None, there's no validation, and any client can connect freely.

    The address parameter specifies the interface and port on which the
    debugging server should listen for TCP connections. It is in the same format
    as used for regular sockets of the AF_INET family, i.e. a tuple of
    (hostname, port). On client side, the server is identified by the Qualifier
    string in the usual hostname:port format, e.g.: myhost.cloudapp.net:5678.

    The certfile parameter is used to enable SSL. If not specified, or if set to
    None, the connection between this program and the debugger will be unsecure,
    and can be intercepted on the wire. If specified, the meaning of this
    parameter is the same as for ssl.wrap_socket.

    The keyfile parameter is used together with certfile when SSL is enabled.
    Its meaning is the same as for ssl.wrap_socket.

    The redirect_output parameter specifies whether any output (on both stdout
    and stderr) produced by this program should be sent to the debugger.

    This function returns immediately after setting up the debugging server,
    and does not block program execution. If you need to block until debugger
    is attached, call ptvsd.wait_for_attach. The debugger can be detached and
    re-attached multiple times after enable_attach is called.

    Only the thread on which this function is called, and any threads that are
    created after it returns, will be visible in the debugger once it is
    attached. Any threads that are already running before this function is
    called will not be visible.

pminaev wrote Mar 25, 2013 at 5:26 PM

Fixed in internal branch.