New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: Add command summaries to datalad.api.__doc__ #2728

merged 12 commits into from Aug 4, 2018


None yet
2 participants

kyleam commented Aug 2, 2018

This pull request closes #2718.

  • clarify datalad.__doc__ description

kyleam added some commits Aug 2, 2018

RF: cmdline: Use a dict rather than a list for short descriptions
This is cleaner because it avoids building up two lists and because
downstream code that works with the description doesn't have to know
the order, just the group name.
RF: Extract CLI-independent parts from get_description_with_cmd_summary
We'll use the list of command summaries in datalad.api.__doc__.
RF: Teach get_interface_groups about plugins
Otherwise we'll need to duplicate the "get groups, then append
plugins" code when we add command information to datalad.api.__doc__.
RF: Move get_cmd_summaries from cmdline/main to interface/base
This will be used outside of the command-line interface.
RF: Move "load module from interface" code to a dedicated function
An upcoming commit will use this to add command summaries in
RF: Move "get interface doc" code into dedicated function
An upcoming commit will use this to add command summaries in

@kyleam kyleam added the documentation label Aug 2, 2018

kyleam added some commits Aug 2, 2018

DOC: Add summary of commands to datalad.api.__doc__
Make it easier for users to discover what methods are available by
looking at the help for the api module.  One concern with this change
could be that we're bringing in more modules than before, but
inspecting sys.modules suggests that this is not the case.

There is still some code duplication between api._command_summary and
main.setup_parser that could pulled out, but that can be done later if
someone thinks it's worth the effort.

Closes #2718.

@kyleam kyleam force-pushed the kyleam:doc-api-commands branch from 373852a to 84278f4 Aug 2, 2018


This comment has been minimized.


yarikoptic commented Aug 2, 2018

Awesome! Thank you @kyleam

once minor whining from a dumb user perspective:

In [1]: import datalad

In [2]: datalad?
Commands are exposed through both a command-line interface and a Python API. On
the command line, run 'datalad --help' for a summary of the available commands.
From an interactive Python session, call `help(datalad.api)` instead.

In [3]: help(datalad.api)
AttributeError                            Traceback (most recent call last)
<ipython-input-3-dc23a2ea50dc> in <module>()
----> 1 help(datalad.api)

AttributeError: module 'datalad' has no attribute 'api'

In [4]: import datalad.api

In [5]: help(datalad.api)

so should it may be have ' ... after you import datalad.api'?


This comment has been minimized.


kyleam commented Aug 2, 2018

so should it may be have ' ... after you import datalad.api'?

fair enough

(I'll wait for Travis to finish before pushing an update.)


This comment has been minimized.

codecov bot commented Aug 2, 2018

Codecov Report

Merging #2728 into master will decrease coverage by <.01%.
The diff coverage is 91.93%.

Impacted file tree graph

@@            Coverage Diff             @@
##           master    #2728      +/-   ##
- Coverage   90.42%   90.42%   -0.01%     
  Files         245      245              
  Lines       30918    30948      +30     
+ Hits        27958    27984      +26     
- Misses       2960     2964       +4
Impacted Files Coverage Δ
datalad/ 88.61% <ø> (ø) ⬆️
datalad/interface/ 94.55% <90.32%> (-0.61%) ⬇️
datalad/cmdline/ 78.11% <90.9%> (-0.55%) ⬇️
datalad/ 89.65% <95%> (-5.09%) ⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update cce8cf5...8d1d125. Read the comment docs.

kyleam added a commit to kyleam/datalad that referenced this pull request Aug 2, 2018


This comment has been minimized.


kyleam commented Aug 3, 2018

nd90 failure is unrelated. I apologize for the 42% drop in coverage, but IMO this change is worth it.


This comment has been minimized.


yarikoptic commented Aug 3, 2018

So Travis didn't run at all? Amend and push again?


This comment has been minimized.


kyleam commented Aug 3, 2018

So Travis didn't run at all?

I skipped it because the commit was a pure doc change on top of a PR that already ran through and had a coverage report.

Amend and push again?

I don't see the point, but, sure, I'll do that if you'd like.

@kyleam kyleam force-pushed the kyleam:doc-api-commands branch from b39b6b0 to 8d1d125 Aug 3, 2018

@yarikoptic yarikoptic merged commit dc68aca into datalad:master Aug 4, 2018

9 checks passed

codecov/patch 91.93% of diff hit (target 90.42%)
codecov/project Absolute coverage decreased by -<.01% but relative coverage increased by +1.5% compared to cce8cf5
continuous-integration/appveyor/pr AppVeyor build succeeded
continuous-integration/travis-ci/pr The Travis CI build passed
datalad-pr-dl-osx-64 DEV build done.
datalad-pr-docker-dl-nd14_04 DEV build done.
datalad-pr-docker-dl-nd16_04 DEV build done.
datalad-pr-docker-dl-nd80 DEV build done.
datalad-pr-docker-dl-nd90 DEV build done.

@kyleam kyleam deleted the kyleam:doc-api-commands branch Aug 6, 2018

@yarikoptic yarikoptic added this to the Release 0.10.3 milestone Sep 12, 2018

yarikoptic added a commit that referenced this pull request Sep 13, 2018

Merge tag '0.10.3' into debian
0.10.3 (Sep 13, 2018) -- Almost-perfect

This is largely a bugfix release which addressed many (but not yet all)
issues of working with git-annex direct and version 6 modes, and operation
on Windows in general.  Among enhancements you will see the
support of public S3 buckets (even with periods in their names),
ability to configure new providers interactively, and improved `egrep`
search backend.

Although we do not require with this release, it is recommended to make
sure that you are using a recent `git-annex` since it also had a variety
of fixes and enhancements in the past months.


- Parsing of combined short options has been broken since DataLad
  v0.10.0. ([#2710])
- The `datalad save` instructions shown by `datalad run` for a command
  with a non-zero exit were incorrectly formatted. ([#2692])
- Decompression of zip files (e.g., through `datalad
  add-archive-content`) failed on Python 3.  ([#2702])
- Windows:
  - colored log output was not being processed by colorama.  ([#2707])
  - more codepaths now try multiple times when removing a file to deal
    with latency and locking issues on Windows.  ([#2795])
- Internal git fetch calls have been updated to work around a
  GitPython `BadName` issue.  ([#2712]), ([#2794])
- The progess bar for annex file transferring was unable to handle an
  empty file.  ([#2717])
- `datalad add-readme` halted when no aggregated metadata was found
  rather than displaying a warning.  ([#2731])
- `datalad rerun` failed if `--onto` was specified and the history
  contained no run commits.  ([#2761])
- Processing of a command's results failed on a result record with a
  missing value (e.g., absent field or subfield in metadata).  Now the
  missing value is rendered as "N/A".  ([#2725]).
- A couple of documentation links in the "Delineation from related
  solutions" were misformatted.  ([#2773])
- With the latest git-annex, several known V6 failures are no longer
  an issue.  ([#2777])
- In direct mode, commit changes would often commit annexed content as
  regular Git files.  A new approach fixes this and resolves a good
  number of known failures.  ([#2770])
- The reporting of command results failed if the current working
  directory was removed (e.g., after an unsuccessful `install`). ([#2788])
- When installing into an existing empty directory, `datalad install`
  removed the directory after a failed clone.  ([#2788])
- `datalad run` incorrectly handled inputs and outputs for paths with
  spaces and other characters that require shell escaping.  ([#2798])
- Globbing inputs and outputs for `datalad run` didn't work correctly
  if a subdataset wasn't installed.  ([#2796])
- Minor (in)compatibility with git 2.19 - (no) trailing period
  in an error message now. ([#2815])

Enhancements and new features

- Anonymous access is now supported for S3 and other downloaders.  ([#2708])
- A new interface is available to ease setting up new providers.  ([#2708])
- Metadata: changes to egrep mode search  ([#2735])
  - Queries in egrep mode are now case-sensitive when the query
    contains any uppercase letters and are case-insensitive otherwise.
    The new mode egrepcs can be used to perform a case-sensitive query
    with all lower-case letters.
  - Search can now be limited to a specific key.
  - Multiple queries (list of expressions) are evaluated using AND to
    determine whether something is a hit.
  - A single multi-field query (e.g., `pa*:findme`) is a hit, when any
    matching field matches the query.
  - All matching key/value combinations across all (multi-field)
    queries are reported in the query_matched result field.
  - egrep mode now shows all hits rather than limiting the results to
    the top 20 hits.
- The documentation on how to format commands for `datalad run` has
  been improved.  ([#2703])
- The method for determining the current working directory on Windows
  has been improved.  ([#2707])
- `datalad --version` now simply shows the version without the
  license.  ([#2733])
- `datalad export-archive` learned to export under an existing
  directory via its `--filename` option.  ([#2723])
- `datalad export-to-figshare` now generates the zip archive in the
  root of the dataset unless `--filename` is specified.  ([#2723])
- After importing `datalad.api`, `help(datalad.api)` (or
  `datalad.api?` in IPython) now shows a summary of the available
  DataLad commands.  ([#2728])
- Support for using `datalad` from IPython has been improved.  ([#2722])
- `datalad wtf` now returns structured data and reports the version of
  each extension.  ([#2741])
- The internal handling of gitattributes information has been
  improved.  A user-visible consequence is that `datalad create
  --force` no longer duplicates existing attributes.  ([#2744])
- The "annex" metadata extractor can now be used even when no content
  is present.  ([#2724])
- The `add_url_to_file` method (called by commands like `datalad
  download-url` and `datalad add-archive-content`) learned how to
  display a progress bar.  ([#2738])

* tag '0.10.3': (214 commits)
  Changelog entry for 2.19 git compat fix
  DOC: slight tune ups to the ChangeLog
  ENH: link issue/pull #s in CHANGELOG, use tools/link_issues_CHANGELOG
  BF: remove trailing period while matching a mesage from git
  DOC: try_multiple_dec: Add description of `duration` parameter
  CLN: annexrepo: Fix grammar in a recently added comment
  TST: auto: Reformat comment from 900ee08
  DOC: _rmtree: Drop a word from summary line
  DOC: Info on IDs (fixes gh-2801)
  BF: diff -- when reraising - just raise, do not raise that instance of exception from new location
  BF(TST): precommit before removing submodule so there is no batched processes
  ENH+BF(TST): close established ssh sockets upon test finish
  BF(TST): One more "clost all log handlers in the test" Start adding entries for v0.10.3
  BF(TST): close cookies db in the teardown since atexit is later, so cannot assure no open files
  BF(TST): explicitly close created log handlers
  ENH(TST): @known_failure_windows to replace plain @skip_if_on_windows where there is hope
  BF(TST): do not swallow output while testing AutomagicIO to not cause some open files issue
  ENH(TST): Skip a test when cannot remove curent directory
  BF(TST): explicitly precommit a repo used under swallow_outputs
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment