docs: update examples given in README.rst file and use table 'name'

* Update README.rst examples (--verbose not -v, use id_list.split()).
* Use original table 'name' instead of 'processed_name' in fetch_names.
* Correct some typos in docstrings and expand content of README.md file.
* Remove .hidden and add to .gitignore (with .idea, hepdata-downloads).

.gitignore

@@ -129,4 +129,13 @@ dmypy.json
 .pyre/
 
 # Temporary files
-*.*~
+*.*~
+
+# .hidden files
+**/.hidden
+
+# PyCharm directory
+.idea
+
+# Default download directory
+hepdata-downloads

README.md

@@ -12,11 +12,11 @@
 
 Command line interface (CLI) and application program interface (API) to allow users to search and download from HEPData.
 
-The code is compatible with both Python 2 and Python 3.
+The code is compatible with both Python 2 and Python 3. Inspiration from [arxiv-cli](https://github.com/jacquerie/arxiv-cli).
 
 ## Installation (for users)
 
-Install from [PyPI](https://pypi.org/) (coming soon):
+Install from [PyPI](https://pypi.org/project/hepdata-cli/) using ```pip```:
 
 ```code
 $ pip install --user hepdata-cli
@@ -46,38 +46,41 @@ You can use HEPData-CLI both as a command-line interface (CLI) to search and dow
 
 ```code
 $ hepdata-cli [-v/--version, --help]
-$ hepdata-cli [--verbose] find [TEXT] [-kw/--keyword TEXT] [-i/--ids IDTYPE]
-$ hepdata-cli [--verbose] download [IDS] [-f/--file-format FORMAT] [-i/--ids IDTYPE] [-t/--table-name TABLE-NAME]
+$ hepdata-cli [--verbose] find [QUERY] [-kw/--keyword KEYWORD] [-i/--ids IDTYPE]
+$ hepdata-cli [--verbose] download [IDS] [-f/--file-format FORMAT] [-i/--ids IDTYPE] [-t/--table-name TABLE-NAME] [-d/--download-dir DOWNLOAD-DIR]
 $ hepdata-cli [--verbose] fetch-names [IDS] [-i/--ids IDTYPE]
 ```
 
-The command ```find``` searches the [HEPData](https://www.hepdata.net/) database for matches of ```TEXT```. The advanced search syntax from the website can be used.
+The command ```find``` searches the [HEPData](https://www.hepdata.net/) database for matches of ```QUERY```. The advanced search syntax from the website can be used.
 
 The command ```download``` downloads records from the database (see options below).
 
 The command ```fetch-names``` returns the names of the data tables in the records whose ids are supplied.
 
-The argument ```[-kw/--keyword TEXT]``` filters the search result dictionary for specific keywords.
+The argument ```[-kw/--keyword KEYWORD]``` filters the search result dictionary for specific keywords.
 An exact match of the keyword is first attempted, otherwise partial matches are accepted.
 
 The argument ```[-i/--ids IDTYPE]``` accepts ```IDTYPE``` equal to ```arxiv```, ```hepdata``` or```inspire```.
 
 The argument  ```[-f/--file-format FORMAT]``` accepts ```FORMAT``` equal to ```csv```, ```root```, ```yaml```, ```yoda```, or ```json```.
-In the first four cases a .tar.gz archive is downloaded, in the last case a .json file is downloaded.
+In the first four cases a .tar.gz archive is downloaded and unpacked as a directory, whereas in the last case a .json file is downloaded.
 
-The argument  ```[-t/--table TABLE-NUMBER]``` accepts a number as input.
-In this case only the specified table is download as a .csv, .root, .yaml or .yoda file.
+The argument  ```[-t/--table-name TABLE-NAME]``` accepts a string giving the table name as input.
+In this case only the specified table is downloaded as a .csv, .root, .yaml, .yoda or .json file.
 
-The ```hepdata-cli download/fetch-names``` and ```hepdata-cli find``` commands can be concatenated, if a ```IDTYPE``` is specified for ```find```.
-It is also possible to concatenate ```arxiv download```, form [pypi/arxiv-cli](https://pypi.org/project/arxiv-cli/), with ```hepdata-cli find```, if ```arxiv``` is used as ```IDTYPE```.
+The argument ```[-d/--download-dir DOWNLOAD-DIR]``` specifies the directory to download the files.
+If not specified, the default download directory is ```./hepdata-downloads```.
+
+The ```hepdata-cli download/fetch-names``` and ```hepdata-cli find``` commands can be concatenated, if an ```IDTYPE``` is specified for ```find```.
+It is also possible to concatenate ```arxiv download```, from [pypi/arxiv-cli](https://pypi.org/project/arxiv-cli/), with ```hepdata-cli find```, if ```arxiv``` is used as ```IDTYPE```.
 
 # API
 
 Equivalently to the above, these commands can be invoked by the API (in fact, the CLI is just a wrapper around the API).
 
 ```python
 from hepdata_cli.api import Client
-client = Client(verbose=False)
+client = Client(verbose=True)
 client.find(query, keyword, ids)
 client.download(id_list, file_format, ids, table_name, download_dir)
 client.fetch_names(id_list, ids)
@@ -89,7 +92,7 @@ client.fetch_names(id_list, ids)
 ### Example 1 - a plain search:
 
 ```code
-$ hepdata-cli -v find 'reactions:"P P--> LQ LQ X"'
+$ hepdata-cli --verbose find 'reactions:"P P--> LQ LQ X"'
 ```
 
 or equivalently
@@ -103,7 +106,7 @@ matches a single entry and returns full metadata dictionary.
 ### Example 2 - search with keyword:
 
 ```code
-$ hepdata-cli -v find 'reactions:"P P--> LQ LQ"' -kw year
+$ hepdata-cli --verbose find 'reactions:"P P--> LQ LQ"' -kw year
 ```
 
 or equivalently
@@ -117,7 +120,7 @@ matches four entries and returns their publication years, as a dictionary.
 ### Example 3 - search for ids of records:
 
 ```code
-$ hepdata-cli -v find 'reactions:"P P--> LQ LQ"' -i hepdata
+$ hepdata-cli --verbose find 'reactions:"P P--> LQ LQ"' -i hepdata
 ```
 
 or equivalently
@@ -131,31 +134,50 @@ matches four entries and returns their hepdata ids, as a plain list.
 ### Example 4 - concatenate search with download using inspire ids:
 
 ```code
-$ hepdata-cli -v download $(hepdata-cli find 'reactions:"P P--> LQ LQ"' -i inspire) -i inspire -f csv
+$ hepdata-cli --verbose download $(hepdata-cli find 'reactions:"P P--> LQ LQ"' -i inspire) -i inspire -f csv
 ```
 
 or equivalently
 
 ```python
 id_list = client.find('reactions:"P P--> LQ LQ"', ids='inspire')
-client.download(id_list, ids='inspire', file_format='csv')
+client.download(id_list.split(), ids='inspire', file_format='csv')
+```
+
+downloads four .tar.gz archives containing csv files and unpacks them in the default ```./hepdata-downloads``` directory.
+
+### Example 5 - find table names in records:
+
+```code
+$ hepdata-cli fetch-names $(hepdata-cli find 'reactions:"P P--> LQ LQ"' -i hepdata) -i hepdata
 ```
 
-downloads four csv.tar.gz archives.
+or equivalently
 
-### Example 5 - concatenate search with download from arxiv-cli:
+```python
+id_list = client.find('reactions:"P P--> LQ LQ"', ids='hepdata')
+client.fetch_names(id_list.split(), ids='hepdata')
+```
+
+returns all table names in the four matching records.
+
+### Example 6 - concatenate search with download from arxiv-cli:
 
 This example requires [arxiv-cli](https://github.com/jacquerie/arxiv-cli) to be installed, which is easily done via:
 
 ```code
 $ pip install --user arxiv-cli
 ```
 
+Note that arxiv-cli installs an older version of [click](https://pypi.org/project/click/) which changes the CLI command
+in Example 5 above from ```fetch-names``` to ```fetch_names```.
+
 Then,
 
 ```code
 $ arxiv download $(hepdata-cli find 'reactions:"P P--> LQ LQ"' -i arxiv)
 ```
+
 or equivalently
 
 ```python
@@ -164,22 +186,7 @@ import hepdata_cli
 arxiv_client = arxiv_cli.Client()
 hepdata_client = hepdata_cli.Client()
 id_list = hepdata_client.find('reactions:"P P--> LQ LQ"', ids='arxiv')
-arxiv_client.download(id_list)
-```
-
-downloads two pdfs from the arXiv.
-
-### Example 6 - find table names in records:
-
-```code
-$ hepdata-cli fetch-names $(hepdata-cli find 'reactions:"P P--> LQ LQ"' -i hepdata) -i hepdata
-```
-
-or equivalently
-
-```python
-id_list = client.find('reactions:"P P--> LQ LQ"', ids='hepdata')
-client.fetch_names(id_list, ids='hepdata')
+arxiv_client.download(id_list.split())
 ```
 
-returns all table names in the four matching records.
+downloads two pdfs from the arXiv.

hepdata_cli/api.py

@@ -56,7 +56,7 @@ def find(self, query, keyword=None, ids=None, max_matches=MAX_MATCHES, matches_p
 
         :param query: string passed to hepdata.net search function. See advanced search tips at hepdata.net.
         :param keyword: filters return dictionary for given keyword. Exact match is first attempted, otherwise partial match is accepted.
-        :param ids: acceps one of ("arxiv", "inspire", "hepdata").
+        :param ids: accepts one of ("arxiv", "inspire", "hepdata").
 
         :return: returns a list of (filtered if 'keyword' is specified) dictionaries for the search matches. If 'ids' is specified it instead returns a list of ids as a string.
         """
@@ -101,11 +101,12 @@ def download(self, id_list, file_format=None, ids=None, table_name='', download_
         Downloads from the hepdata database the specified records.
 
         :param id_list: list of ids to download. These can be obtained by the find function.
-        :param file_format: accepts one of ('csv', 'root', 'yaml', 'yoda', 'json'). Specified the download file format.
-        :param ids: accepts one of ('inspire', 'hepdata'). It specifies what type of ids have been passes.
+        :param file_format: accepts one of ('csv', 'root', 'yaml', 'yoda', 'json'). Specifies the download file format.
+        :param ids: accepts one of ('inspire', 'hepdata'). It specifies what type of ids have been passed.
         :param table_name: restricts download to specific tables.
-        :param download_dir: defaults to ~/Downloads. Speficies where to download the files.
+        :param download_dir: defaults to ./hepdata-downloads. Specifies where to download the files.
         """
+
         urls = self._build_urls(id_list, file_format, ids, table_name)
         for url in urls:
             if self.verbose is True:
@@ -117,14 +118,14 @@ def fetch_names(self, id_list, ids=None):
         Returns the names of the tables in the provided records. These are the possible inputs of table_name parameter in download function.
 
         :param id_list: list of id of records of which to return table names.
-        :param ids: accepts one of ('inspire', 'hepdata'). It specifies what type of ids have been passes.
+        :param ids: accepts one of ('inspire', 'hepdata'). It specifies what type of ids have been passed.
         """
         urls = self._build_urls(id_list, 'json', ids, '')
         table_names = []
         for url in urls:
             response = requests_retry('get', url)
             json_dict = response.json()
-            table_names += [[data_table['processed_name'] for data_table in json_dict['data_tables']]]
+            table_names += [[data_table['name'] for data_table in json_dict['data_tables']]]
         return table_names
 
     def _build_urls(self, id_list, file_format, ids, table_name):

hepdata_cli/cli.py

@@ -30,7 +30,7 @@ def find(client, query, keyword, ids):
 @click.option('-f', '--file-format', required=True, type=str, help='Specify file format (csv, root, yaml, yoda, or json) to be downloaded.')
 @click.option('-i', '--ids', required=True, type=str, help='Specify which ids (hepdata or inspire) are given.')
 @click.option('-t', '--table-name', default='', type=str, help='Specify table to be downloaded.')
-@click.option('-d', '--download-dir', default='./hepdata-downloads', type=str, help='Specify where to download the files..')
+@click.option('-d', '--download-dir', default='./hepdata-downloads', type=str, help='Specify where to download the files.')
 @click.pass_obj
 def download(client, id_list, file_format, ids, table_name, download_dir):
     """CLI interface to API client.download function."""

tests/test_fetch.py

@@ -1,7 +1,6 @@
 # -*- coding: utf-8 -*-
 
 import pytest
-import sys
 
 from click.testing import CliRunner