Have 'usage' report default value

[Tristan Croll]

The following bug report has been submitted:
Platform:        Darwin-19.6.0-x86_64-i386-64bit
ChimeraX Version: 1.1rc202009070534 (2020-09-07 05:34:34 UTC)
Description
It might be a really nice touch if for commands with optional and/or keyword arguments, "usage {command}" reported the default values of those arguments. It should be possible to do that pretty straightforwardly using the `inspect` module on the method the command wraps - `inspect.signature(function)` lets you query each argument and its default value (if any).  

Log:
UCSF ChimeraX version: 1.1rc202009070534 (2020-09-07)  
© 2016-2020 Regents of the University of California. All rights reserved.  
How to cite UCSF ChimeraX  

> usage volume

volume [volumes] [style style] [change change] [show] [hide] [toggle] [close
close] [level level] [rmsLevel rmsLevel] [sdLevel sdLevel] [encloseVolume
encloseVolume] [fastEncloseVolume fastEncloseVolume] [color color] [brightness
a number] [transparency a number] [appearance appearance] [nameAppearance a
text string] [nameForget nameForget] [step map step] [region map region]
[expandSinglePlane true or false] [origin 1 or 3 floats] [originIndex 1 or 3
floats] [voxelSize 1 or 3 floats] [planes planes
x|y|z[,<start>[,<end>[,<increment>[,<depth>]]]]] [dumpHeader true or false]
[pickable true or false] [symmetry symmetry] [center center point]
[centerIndex 1 or 3 floats] [axis an axis vector] [coordinateSystem a
coordinate-system] [dataCacheSize a number] [showOnOpen true or false]
[voxelLimitForOpen a number] [showPlane true or false] [voxelLimitForPlane a
number] [showOutlineBox true or false] [outlineBoxRgb a color]
[limitVoxelCount true or false] [voxelLimit a number] [colorMode colorMode]
[colormapOnGpu true or false] [colormapSize an integer] [colormapExtendLeft
true or false] [colormapExtendRight true or false] [backingColor backingColor]
[blendOnGpu true or false] [projectionMode projectionMode] [planeSpacing
planeSpacing] [fullRegionOnGpu true or false] [btCorrection true or false]
[minimalTextureMemory true or false] [maximumIntensityProjection true or
false] [linearInterpolation true or false] [dimTransparency true or false]
[dimTransparentVoxels true or false] [smoothLines true or false] [meshLighting
true or false] [twoSidedLighting true or false] [flipNormals true or false]
[subdivideSurface true or false] [subdivisionLevels an integer]
[surfaceSmoothing true or false] [smoothingIterations an integer]
[smoothingFactor a number] [squareMesh true or false] [capFaces true or false]
[boxFaces true or false] [orthoplanes orthoplanes] [positionPlanes
positionPlanes] [tiltedSlab true or false] [tiltedSlabAxis an axis vector]
[tiltedSlabOffset a number] [tiltedSlabSpacing a number] [tiltedSlabPlaneCount
an integer] [imageMode imageMode] [calculateSurfaces true or false]  
— set volume model parameters, display style and colors  
style: one of image, mesh, solid, or surface  
change: one of image or surface  
close: one of image or surface  
level: some numbers, repeatable  
rmsLevel: some numbers, repeatable  
sdLevel: some numbers, repeatable  
encloseVolume: some numbers  
fastEncloseVolume: some numbers  
color: a color, repeatable  
appearance: one of Airways, airways, Airways II, Black & White, Bone + Skin,
Bone + Skin II, brain, chest, CT_Bones, CT_Kidneys, CT_Liver, CT_Lungs,
CT_Muscles, CT_Skin, CT_Soft_Tissue, CT_Vessels, CT_w_Contrast, Dark Bone,
Glossy, Glossy II, Gold Bone, High Contrast, initial, Low Contrast, Mid
Contrast, No Shading, Pencil, Red on White, Skin On Blue, Skin On Blue II,
Soft, Soft + Skin, Soft + Skin II, Soft + Skin III, Soft On Blue, Soft on
White, Standard, Vascular, Vascular II, Vascular III, Vascular IV, or Yellow
Bone  
nameForget: one of Airways, airways, Airways II, Black & White, Bone + Skin,
Bone + Skin II, brain, chest, CT_Bones, CT_Kidneys, CT_Liver, CT_Lungs,
CT_Muscles, CT_Skin, CT_Soft_Tissue, CT_Vessels, CT_w_Contrast, Dark Bone,
Glossy, Glossy II, Gold Bone, High Contrast, initial, Low Contrast, Mid
Contrast, No Shading, Pencil, Red on White, Skin On Blue, Skin On Blue II,
Soft, Soft + Skin, Soft + Skin II, Soft + Skin III, Soft On Blue, Soft on
White, Standard, Vascular, Vascular II, Vascular III, Vascular IV, or Yellow
Bone  
colorMode: one of auto12, auto16, auto4, auto8, l12, l16, l4, l8, la12, la16,
la4, la8, opaque12, opaque16, opaque4, opaque8, rgb12, rgb16, rgb4, rgb8,
rgba12, rgba16, rgba4, or rgba8  
backingColor: a color or none  
projectionMode: one of 2d-x, 2d-xyz, 2d-y, 2d-z, 3d, or auto  
planeSpacing: one of max, mean, or min or a number  
orthoplanes: one of off, xy, xyz, xz, or yz  
positionPlanes: some integers  
imageMode: one of box faces, full region, orthoplanes, or tilted slab  
Subcommands are:

  * volume add
  * volume bin
  * volume boxes
  * volume copy
  * volume cover
  * volume erase
  * volume falloff
  * volume flatten
  * volume flip
  * volume fourier
  * volume gaussian
  * volume laplacian
  * volume localCorrelation
  * volume mask
  * volume maximum
  * volume median
  * volume minimum
  * volume morph
  * volume multiply
  * volume new
  * volume octant
  * volume ~octant
  * volume onesmask
  * volume permuteAxes
  * volume resample
  * volume ridges
  * volume scale
  * volume settings
  * volume splitbyzone
  * volume subtract
  * volume threshold
  * volume tile
  * volume unbend
  * volume unroll
  * volume unzone
  * volume zone

  




OpenGL version: 4.1 INTEL-14.7.8
OpenGL renderer: Intel(R) HD Graphics 6000
OpenGL vendor: Intel Inc.Hardware:

    Hardware Overview:

      Model Name: MacBook Air
      Model Identifier: MacBookAir7,2
      Processor Name: Dual-Core Intel Core i5
      Processor Speed: 1.6 GHz
      Number of Processors: 1
      Total Number of Cores: 2
      L2 Cache (per Core): 256 KB
      L3 Cache: 3 MB
      Hyper-Threading Technology: Enabled
      Memory: 8 GB
      Boot ROM Version: 195.0.0.0.0
      SMC Version (system): 2.27f2

Software:

    System Software Overview:

      System Version: macOS 10.15.6 (19G2021)
      Kernel Version: Darwin 19.6.0
      Time since boot: 34 days 21:19

Graphics/Displays:

    Intel HD Graphics 6000:

      Chipset Model: Intel HD Graphics 6000
      Type: GPU
      Bus: Built-In
      VRAM (Dynamic, Max): 1536 MB
      Vendor: Intel
      Device ID: 0x1626
      Revision ID: 0x0009
      Metal: Supported, feature set macOS GPUFamily1 v4
      Displays:
        Color LCD:
          Display Type: LCD
          Resolution: 1440 x 900 (Widescreen eXtended Graphics Array Plus)
          UI Looks like: 1440 x 900
          Framebuffer Depth: 24-Bit Color (ARGB8888)
          Main Display: Yes
          Mirror: Off
          Online: Yes
          Automatically Adjust Brightness: No
          Connection Type: Internal

PyQt version: 5.12.3
Compiled Qt version: 5.12.4
Runtime Qt version: 5.12.9
Installed Packages:
    alabaster: 0.7.12
    appdirs: 1.4.4
    appnope: 0.1.0
    Babel: 2.8.0
    backcall: 0.2.0
    blockdiag: 2.0.1
    certifi: 2020.6.20
    chardet: 3.0.4
    ChimeraX-AddH: 2.1.1
    ChimeraX-AlignmentAlgorithms: 2.0
    ChimeraX-AlignmentHdrs: 3.2
    ChimeraX-AlignmentMatrices: 2.0
    ChimeraX-Alignments: 2.1
    ChimeraX-Arrays: 1.0
    ChimeraX-Atomic: 1.6.1
    ChimeraX-AtomSearch: 2.0
    ChimeraX-AxesPlanes: 2.0
    ChimeraX-BasicActions: 1.1
    ChimeraX-BILD: 1.0
    ChimeraX-BlastProtein: 1.0.1
    ChimeraX-BondRot: 2.0
    ChimeraX-BugReporter: 1.0
    ChimeraX-BuildStructure: 2.0
    ChimeraX-Bumps: 1.0
    ChimeraX-BundleBuilder: 1.0
    ChimeraX-ButtonPanel: 1.0
    ChimeraX-CageBuilder: 1.0
    ChimeraX-CellPack: 1.0
    ChimeraX-Centroids: 1.1
    ChimeraX-ChemGroup: 2.0
    ChimeraX-Clashes: 2.0
    ChimeraX-Clipper: 0.15.0
    ChimeraX-ColorActions: 1.0
    ChimeraX-ColorGlobe: 1.0
    ChimeraX-CommandLine: 1.1.3
    ChimeraX-ConnectStructure: 2.0
    ChimeraX-Contacts: 1.0
    ChimeraX-Core: 1.1rc202009070534
    ChimeraX-CoreFormats: 1.0
    ChimeraX-coulombic: 1.0.1
    ChimeraX-Crosslinks: 1.0
    ChimeraX-Crystal: 1.0
    ChimeraX-DataFormats: 1.0
    ChimeraX-Dicom: 1.0
    ChimeraX-DistMonitor: 1.1
    ChimeraX-DistUI: 1.0
    ChimeraX-Dssp: 2.0
    ChimeraX-EMDB-SFF: 1.0
    ChimeraX-ExperimentalCommands: 1.0
    ChimeraX-FileHistory: 1.0
    ChimeraX-FunctionKey: 1.0
    ChimeraX-Geometry: 1.1
    ChimeraX-gltf: 1.0
    ChimeraX-Graphics: 1.0
    ChimeraX-Hbonds: 2.0
    ChimeraX-Help: 1.0
    ChimeraX-HKCage: 1.0
    ChimeraX-IHM: 1.0
    ChimeraX-ImageFormats: 1.0
    ChimeraX-IMOD: 1.0
    ChimeraX-IO: 1.0
    ChimeraX-ISOLDE: 1.0.2
    ChimeraX-Label: 1.0
    ChimeraX-ListInfo: 1.0
    ChimeraX-Log: 1.1.1
    ChimeraX-LookingGlass: 1.1
    ChimeraX-Map: 1.0.1
    ChimeraX-MapData: 2.0
    ChimeraX-MapEraser: 1.0
    ChimeraX-MapFilter: 2.0
    ChimeraX-MapFit: 2.0
    ChimeraX-MapSeries: 2.0
    ChimeraX-Markers: 1.0
    ChimeraX-Mask: 1.0
    ChimeraX-MatchMaker: 1.1
    ChimeraX-MDcrds: 2.0
    ChimeraX-MedicalToolbar: 1.0.1
    ChimeraX-Meeting: 1.0
    ChimeraX-MLP: 1.0
    ChimeraX-mmCIF: 2.2
    ChimeraX-MMTF: 2.0
    ChimeraX-Modeller: 1.0
    ChimeraX-ModelPanel: 1.0
    ChimeraX-ModelSeries: 1.0
    ChimeraX-Mol2: 2.0
    ChimeraX-Morph: 1.0
    ChimeraX-MouseModes: 1.0
    ChimeraX-Movie: 1.0
    ChimeraX-Neuron: 1.0
    ChimeraX-Nucleotides: 2.0
    ChimeraX-OpenCommand: 1.2.1
    ChimeraX-PDB: 2.1
    ChimeraX-PDBBio: 1.0
    ChimeraX-PickBlobs: 1.0
    ChimeraX-Positions: 1.0
    ChimeraX-PresetMgr: 1.0
    ChimeraX-PubChem: 2.0
    ChimeraX-Read-Pbonds: 1.0
    ChimeraX-Registration: 1.1
    ChimeraX-RemoteControl: 1.0
    ChimeraX-ResidueFit: 1.0
    ChimeraX-RestServer: 1.0
    ChimeraX-RNALayout: 1.0
    ChimeraX-RotamerLibMgr: 2.0
    ChimeraX-RotamerLibsDunbrack: 2.0
    ChimeraX-RotamerLibsDynameomics: 2.0
    ChimeraX-RotamerLibsRichardson: 2.0
    ChimeraX-SaveCommand: 1.2
    ChimeraX-SchemeMgr: 1.0
    ChimeraX-SDF: 2.0
    ChimeraX-Segger: 1.0
    ChimeraX-Segment: 1.0
    ChimeraX-SeqView: 2.2
    ChimeraX-Shape: 1.0.1
    ChimeraX-Shell: 1.0
    ChimeraX-Shortcuts: 1.0
    ChimeraX-ShowAttr: 1.0
    ChimeraX-ShowSequences: 1.0
    ChimeraX-SideView: 1.0
    ChimeraX-Smiles: 2.0
    ChimeraX-SmoothLines: 1.0
    ChimeraX-SpaceNavigator: 1.0
    ChimeraX-StdCommands: 1.0.4
    ChimeraX-STL: 1.0
    ChimeraX-Storm: 1.0
    ChimeraX-Struts: 1.0
    ChimeraX-Surface: 1.0
    ChimeraX-SwapAA: 2.0
    ChimeraX-SwapRes: 2.0
    ChimeraX-TapeMeasure: 1.0
    ChimeraX-Test: 1.0
    ChimeraX-Toolbar: 1.0
    ChimeraX-ToolshedUtils: 1.0
    ChimeraX-Tug: 1.0
    ChimeraX-UI: 1.2.3
    ChimeraX-uniprot: 2.0
    ChimeraX-ViewDockX: 1.0
    ChimeraX-Vive: 1.1
    ChimeraX-VolumeMenu: 1.0
    ChimeraX-VTK: 1.0
    ChimeraX-WavefrontOBJ: 1.0
    ChimeraX-WebCam: 1.0
    ChimeraX-WebServices: 1.0
    ChimeraX-Zone: 1.0
    colorama: 0.4.3
    comtypes: 1.1.7
    cxservices: 1.0
    cycler: 0.10.0
    Cython: 0.29.20
    decorator: 4.4.2
    distlib: 0.3.1
    docutils: 0.16
    filelock: 3.0.12
    funcparserlib: 0.3.6
    grako: 3.16.5
    h5py: 2.10.0
    html2text: 2020.1.16
    idna: 2.10
    ihm: 0.16
    imagecodecs: 2020.5.30
    imagecodecs-lite: 2020.1.31
    imagesize: 1.2.0
    ipykernel: 5.3.0
    ipython: 7.15.0
    ipython-genutils: 0.2.0
    jedi: 0.17.2
    Jinja2: 2.11.2
    jupyter-client: 6.1.3
    jupyter-core: 4.6.3
    kiwisolver: 1.2.0
    line-profiler: 2.1.2
    lxml: 4.5.1
    MarkupSafe: 1.1.1
    matplotlib: 3.2.1
    msgpack: 1.0.0
    netifaces: 0.10.9
    networkx: 2.4
    numexpr: 2.7.1
    numpy: 1.18.5
    numpydoc: 1.0.0
    openvr: 1.12.501
    packaging: 20.4
    parso: 0.7.1
    pexpect: 4.8.0
    pickleshare: 0.7.5
    Pillow: 7.1.2
    pip: 20.2.2
    pkginfo: 1.5.0.1
    prompt-toolkit: 3.0.7
    psutil: 5.7.0
    ptyprocess: 0.6.0
    pycollada: 0.7.1
    pydicom: 2.0.0
    Pygments: 2.6.1
    PyOpenGL: 3.1.5
    PyOpenGL-accelerate: 3.1.5
    pyparsing: 2.4.7
    PyQt5-commercial: 5.12.3
    PyQt5-sip: 4.19.19
    PyQtWebEngine-commercial: 5.12.1
    python-dateutil: 2.8.1
    pytz: 2020.1
    pyzmq: 19.0.2
    qtconsole: 4.7.4
    QtPy: 1.9.0
    RandomWords: 0.3.0
    requests: 2.24.0
    scipy: 1.4.1
    setuptools: 49.4.0
    sfftk-rw: 0.6.6.dev0
    six: 1.15.0
    snowballstemmer: 2.0.0
    sortedcontainers: 2.2.2
    Sphinx: 3.1.1
    sphinxcontrib-applehelp: 1.0.2
    sphinxcontrib-blockdiag: 2.0.0
    sphinxcontrib-devhelp: 1.0.2
    sphinxcontrib-htmlhelp: 1.0.3
    sphinxcontrib-jsmath: 1.0.1
    sphinxcontrib-qthelp: 1.0.3
    sphinxcontrib-serializinghtml: 1.1.4
    suds-jurko: 0.6
    tables: 3.6.1
    tifffile: 2020.6.3
    tinyarray: 1.2.2
    tornado: 6.0.4
    traitlets: 5.0.4
    urllib3: 1.25.10
    wcwidth: 0.2.5
    webcolors: 1.11.1
    wheel: 0.34.2

[pett]

Well, this is really what 'help' is for. While the approach you suggest would "mostly" work, the problem is that sometimes the "default" value is in fact an illegal value -- used to detect that the parameter was not explicitly supplied by the user and that special behavior (or a special value) should be used.

[Tristan Croll]

Hmm... hadn't considered the "illegal value" situation - but the problem with having it in the help file is the same as with all documentation - it's painfully easy for what's in the help file to get out of step with what's actually in the code.
________________________________
From: ChimeraX <ChimeraX-bugs-admin@cgl.ucsf.edu>
Sent: 18 September 2020 16:35
Cc: gregc@cgl.ucsf.edu <gregc@cgl.ucsf.edu>; pett@cgl.ucsf.edu <pett@cgl.ucsf.edu>; Tristan Croll <tic20@cam.ac.uk>
Subject: Re: [ChimeraX] #3734: Have 'usage' report default value (was: ChimeraX bug report submission)

#3734: Have 'usage' report default value
------------------------------------+------------------------
          Reporter:  Tristan Croll  |      Owner:  Greg Couch
              Type:  defect         |     Status:  assigned
          Priority:  normal         |  Milestone:
         Component:  Command Line   |    Version:
        Resolution:                 |   Keywords:
        Blocked By:                 |   Blocking:
Notify when closed:                 |   Platform:  all
           Project:  ChimeraX       |
------------------------------------+------------------------
Changes (by Eric Pettersen):

 * status:  new => assigned
 * cc: Eric Pettersen (added)
 * component:  Unassigned => Command Line
 * project:   => ChimeraX
 * platform:   => all
 * owner:  (none) => Greg Couch


Comment:

 Well, this is really what 'help' is for.  While the approach you suggest
 would "mostly" work, the problem is that sometimes the "default" value is
 in fact an illegal value -- used to detect that the parameter was not
 explicitly supplied by the user and that special behavior (or a special
 value) should be used.

--
Ticket URL: <https://plato.cgl.ucsf.edu/trac/ChimeraX/ticket/3734#comment:1>
ChimeraX <http://www.rbvi.ucsf.edu/chimerax/>
ChimeraX Issue Tracker