Merge pull request #139 from bskinn/release-2.1a2

Merge for release of v2.1a2

CHANGELOG.md

@@ -7,30 +7,38 @@ and this project strives to adhere to
 [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 
-### [unreleased changes]
+### [2.1.0a2] - 2020-10-27
 
 #### Added
 
  * A hyphen can now be passed as the CLI input and/or output file name
    to instruct sphobjinv to use stdin and/or stdout, respectively.
 
+ * When an inventory is retrieved from a remote URL with `-u`, the
+   resolved location of the inventory is included in generated JSON
+   at `json_dict.metadata.url`.
+
  * The `fileops` and `inventory` APIs are now tested to work with
    both strings and `pathlib.Path` objects, where they interact
-   with the filesystem
+   with the filesystem.
+
+#### Changed
+
+ * CLI logging messages are now emitted to stderr instead of stdout.
 
 #### Refactored
 
  * Patterns in regular expressions are now defined with raw strings
-   to improve readability
+   to improve readability.
 
 ### [2.0.1] - 2020-01-26
 
 #### Fixed
 
  * attr.s usage on Inventory changed to use eq=False where possible,
-   per the deprecation of the cmp argument
+   per the deprecation of the cmp argument.
  * URL inventory retrieval now sends a User-Agent header, to avoid
-   403 FORBIDDEN errors on some docs servers
+   403 FORBIDDEN errors on some docs servers.
 
 
 ### [2.0.1rc1] - 2019-02-01
@@ -65,7 +73,7 @@ and this project strives to adhere to
 #### Fixed
 
  * API code no longer contains any `sys.exit` calls;
-   CLI interactions should now be properly segregated from the internal API
+   CLI interactions should now be properly segregated from the internal API.
 
 #### Added
 

README.rst

@@ -121,11 +121,11 @@ inventory creation/modification::
     >>> import sphobjinv as soi
     >>> inv = soi.Inventory('doc/build/html/objects.inv')
     >>> print(inv)
-    <Inventory (fname_zlib): sphobjinv v2.1, 183 objects>
+    <Inventory (fname_zlib): sphobjinv v2.1a2, 184 objects>
     >>> inv.project
     'sphobjinv'
     >>> inv.version
-    '2.1'
+    '2.1a2'
     >>> inv.objects[0]
     DataObjStr(name='sphobjinv.cmdline', domain='py', role='module', priority='0', uri='cli/implementation.html#module-$', dispname='-')
 

doc/source/cli/convert.rst

@@ -30,6 +30,7 @@ Basic file conversion to the default output filename is straightforward:
     Conversion completed.
     '...objects_attrs.inv' converted to '...objects_attrs.txt' (plain).
     <BLANKLINE>
+    <BLANKLINE>
     >>> print(file_head('objects_attrs.txt', head=6))
     # Sphinx inventory version 2
     # Project: attrs
@@ -44,16 +45,17 @@ file:
 .. doctest:: convert_main
 
     >>> cli_run('sphobjinv convert plain objects_attrs.inv', inp='n\n')
-    <BLANKLINE>
     File exists. Overwrite (Y/N)? n
     <BLANKLINE>
+    <BLANKLINE>
     Exiting...
     <BLANKLINE>
     >>> cli_run('sphobjinv convert plain objects_attrs.inv objects_attrs_foo.txt')
     <BLANKLINE>
     Conversion completed.
     '...objects_attrs.inv' converted to '...objects_attrs_foo.txt' (plain).
     <BLANKLINE>
+    <BLANKLINE>
 
 If you don't provide an output file extension, the |soi| defaults
 (`.inv`/`.txt`/`.json`) will be used.
@@ -71,6 +73,7 @@ indicated URL):
     Conversion completed.
     'https://github.com/b[...]ce/objects_attrs.inv' converted to '...objects.txt' (plain).
     <BLANKLINE>
+    <BLANKLINE>
     >>> print(file_head('objects.txt', head=6))
     # Sphinx inventory version 2
     # Project: attrs
@@ -99,10 +102,11 @@ it will automatically find and use the correct |objects.inv|:
     Conversion completed.
     '...objects.inv' converted to '...objects.txt' (plain).
     <BLANKLINE>
+    <BLANKLINE>
 
 |soi| only supports download of zlib-compressed |objects.inv| files by URL.
 Plaintext download by URL is unreliable, presumably due to encoding problems.
-If download of JSON files by URL is desirable, please
+If processing of JSON files by API URL is desirable, please
 `submit an issue <https://github.com/bskinn/sphobjinv/issues>`__.
 
 

doc/source/cli/suggest.rst

@@ -10,57 +10,27 @@ fuzzy-matching a given search string. Fuzzy-matching is carried out via the
 |fuzzywuzzy|_ library, against the Restructured Text-like representation of each
 object exposed by :attr:`SuperDataObj.as_rst <sphobjinv.data.SuperDataObj.as_rst>`:
 
-.. doctest:: suggest_main
-
-    >>> cli_run('sphobjinv suggest objects_attrs.inv instance')
-    <BLANKLINE>
-    :py:exception:`attr.exceptions.FrozenInstanceError`
-    :py:function:`attr.validators.instance_of`
-    <BLANKLINE>
+.. command-output:: sphobjinv suggest objects_attrs.inv instance
+   :cwd: /../../tests/resource
 
 The |fuzzywuzzy|_ match score and the index of the object within the inventory can
 be printed by passing the :option:`--score` and :option:`--index` options,
 respectively:
 
-.. doctest:: suggest_main
-
-    >>> cli_run('sphobjinv suggest objects_attrs.inv instance -s -i')  # doctest: +NORMALIZE_WHITESPACE
-    <BLANKLINE>
-      Name                                                  Score    Index
-    -----------------------------------------------------  -------  -------
-    :py:exception:`attr.exceptions.FrozenInstanceError`      90        9
-    :py:function:`attr.validators.instance_of`               90       23
-    <BLANKLINE>
+.. command-output:: sphobjinv suggest objects_attrs.inv instance -s -i
+   :cwd: /../../tests/resource
 
 If too few or too many matches are returned, the reporting threshold can be changed
 via :option:`--thresh`:
 
-.. doctest:: suggest_main
-
-    >>> cli_run('sphobjinv suggest objects_attrs.inv instance -s -i -t 48')  # doctest: +NORMALIZE_WHITESPACE
-    <BLANKLINE>
-      Name                                                  Score    Index
-    -----------------------------------------------------  -------  -------
-    :py:exception:`attr.exceptions.FrozenInstanceError`      90        9
-    :py:function:`attr.validators.instance_of`               90       23
-    :std:doc:`license`                                       51       47
-    :py:function:`attr.filters.include`                      48       13
-    <BLANKLINE>
+.. command-output:: sphobjinv suggest objects_attrs.inv instance -s -i -t 48
+   :cwd: /../../tests/resource
 
 Remote |objects.inv| files can be retrieved for inspection by passing the
 :option:`--url` flag:
 
-.. doctest:: suggest_main
-
-    >>> cli_run('sphobjinv suggest https://github.com/bskinn/sphobjinv/raw/master/tests/resource/objects_attrs.inv instance -u -t 48')  # doctest: +NORMALIZE_WHITESPACE
-    <BLANKLINE>
-    Remote inventory found.
-    <BLANKLINE>
-    :py:exception:`attr.exceptions.FrozenInstanceError`
-    :py:function:`attr.validators.instance_of`
-    :std:doc:`license`
-    :py:function:`attr.filters.include`
-    <BLANKLINE>
+.. command-output:: sphobjinv suggest https://github.com/bskinn/sphobjinv/raw/master/tests/resource/objects_attrs.inv instance -u -t 48
+   :cwd: /../../tests/resource
 
 The URL provided **MUST** have the leading protocol specified (here,
 |cour|\ https\ ://\ |/cour|).
@@ -69,18 +39,8 @@ It is not necessary to locate the |objects.inv| file before running |soi|;
 for most Sphinx documentation sets, if you provide a URL to any page in the docs,
 it will automatically find and use the correct |objects.inv|:
 
-.. doctest:: suggest_main
-
-    >>> cli_run('sphobjinv suggest -u https://sphobjinv.readthedocs.io/en/v2.0rc1/cmdline.html compress')  # doctest: +NORMALIZE_WHITESPACE
-    <BLANKLINE>
-    No inventory at provided URL.
-    Attempting "https://sphobjinv.readthedocs.io/en/v2.0rc1/cmdline.html/objects.inv" ...
-    Attempting "https://sphobjinv.readthedocs.io/en/v2.0rc1/objects.inv" ...
-    Remote inventory found.
-    <BLANKLINE>
-    :py:function:`sphobjinv.zlib.compress`
-    :py:function:`sphobjinv.zlib.decompress`
-    <BLANKLINE>
+.. command-output:: sphobjinv suggest -u https://sphobjinv.readthedocs.io/en/v2.0rc1/cmdline.html compress
+   :cwd: /../../tests/resource
 
 |soi| only supports download of zlib-compressed |objects.inv| files by URL.
 Plaintext download by URL is unreliable, presumably due to encoding problems.
@@ -90,12 +50,8 @@ If download of JSON files by URL is desirable, please
 
 **Usage**
 
-.. doctest:: suggest_usage
-
-    >>> cli_run('sphobjinv suggest --help', head=3)
-    usage: sphobjinv suggest [-h] [-a] [-i] [-s] [-t {0-100}] [-u] infile search
-    <BLANKLINE>
-    Fuzzy-search intersphinx inventory for desired object(s).
+.. command-output:: sphobjinv suggest --help
+   :ellipsis: 4
 
 **Positional Arguments**