Implement changes for v0.1.1 release (#15)

* Update version to 0.1.1

* Fix path to .env file on Windows

* Add metadata property to Job class

* Trigger GitHub Actions workflows on push to main

* Update changelog with 0.1.1 release notes

* Add .env file locations to Settings docstring

* Unify Connection docstring with other class docstrings

* Add example to Settings docstring

* Add XCC modules to API section of sidebar

* Add REFRESH_TOKEN example to 'xcc config set' help text

* Add documentation updates to changelog

* Apply format and lint suggestions

* Simplified 'xcc config set' help description

.github/CHANGELOG.md

@@ -1,6 +1,37 @@
-## Release 0.2.0 (development release)
+## Release 0.1.1 (current release)
 
-## Release 0.1.0 (current release)
+### New features since last release
+
+* The Job class now has a `metadata` property which, by convention, returns
+  information about job failures.
+  [(#15)](https://github.com/XanaduAI/xanadu-cloud-client/pull/15)
+
+### Improvements
+
+* The CI workflows are now triggered when a branch is merged into `main`.
+  [(#15)](https://github.com/XanaduAI/xanadu-cloud-client/pull/15)
+
+### Bug Fixes
+
+* On Windows, the XCC configuration file is now stored at `...\Xanadu\xanadu-cloud\.env`.
+  [(#15)](https://github.com/XanaduAI/xanadu-cloud-client/pull/15)
+
+### Documentation
+
+* Individual modules are now listed in the *API* section of the Sphinx sidebar.
+  [(#15)](https://github.com/XanaduAI/xanadu-cloud-client/pull/15)
+
+* The `Settings` class docstring now includes an example walkthrough as well as
+  the location of the XCC configuration file.
+  [(#15)](https://github.com/XanaduAI/xanadu-cloud-client/pull/15)
+
+### Contributors
+
+This release contains contributions from (in alphabetical order):
+
+[Mikhail Andrenkov](https://github.com/Mandrenkov).
+
+## Release 0.1.0
 
 ### New features since last release
 

.github/workflows/docs.yml

@@ -1,6 +1,9 @@
 name: Documentation Check
 on:
-- pull_request
+  pull_request:
+  push:
+    branches:
+      - main
 
 jobs:
   sphinx:

.github/workflows/format.yml

@@ -1,6 +1,9 @@
 name: Formatting Check
 on:
-- pull_request
+  pull_request:
+  push:
+    branches:
+      - main
 
 jobs:
   format:

.github/workflows/tests.yml

@@ -3,7 +3,8 @@ on:
   pull_request:
   push:
     branches:
-      - master
+      - main
+
 jobs:
   test:
     runs-on: ${{ matrix.os }}

docs/index.rst

@@ -112,4 +112,8 @@ XCC Documentation
    :caption: API
    :hidden:
 
-   api/xcc
+   api/xcc
+   api/xcc.Connection
+   api/xcc.Device
+   api/xcc.Job
+   api/xcc.Settings

docs/xcc.rst

@@ -7,4 +7,4 @@ xcc
     :toctree: api
     :recursive:
 
-    xcc
+    xcc

tests/test_job.py

@@ -115,9 +115,13 @@ def test_overview(self, job, add_response, datetime_):
             "created_at": datetime_.isoformat(),
             "finished_at": datetime_.isoformat(),
             "running_time": 0.12345,
+            "meta": {},
         }
         add_response(body=body)
-        assert set(job.overview) == set(body)
+
+        have_keys = set(job.overview)
+        want_keys = set(body) ^ {"meta", "metadata"}
+        assert have_keys == want_keys
 
     @responses.activate
     def test_result(self, connection, job):
@@ -251,6 +255,12 @@ def test_finished(self, job, add_response, status, finished):
         add_response(body={"status": status})
         assert job.finished is finished
 
+    @responses.activate
+    def test_metadata(self, job, add_response):
+        """Tests that the correct metadata is returned for a job."""
+        add_response(body={"meta": {"foo": "bar", "baz": 123}})
+        assert job.metadata == {"foo": "bar", "baz": 123}
+
     def test_repr(self, job):
         """Tests that the correct printable representation is returned for a job."""
         assert repr(job) == f"<Job: id={job.id}>"

tests/test_settings.py

@@ -21,8 +21,12 @@ def env_file(monkeypatch):
 
 def test_get_path_to_env_file(monkeypatch):
     """Tests that the path to the .env file is derived correctly."""
-    monkeypatch.setattr("xcc.settings.user_config_dir", lambda path: f"foo/bar/{path}")
-    assert xcc.settings.get_path_to_env_file() == "foo/bar/xanadu-cloud/.env"
+
+    def user_config_dir(appname: str, appauthor: str) -> str:
+        return f"foo/bar/{appauthor}/{appname}"
+
+    monkeypatch.setattr("xcc.settings.user_config_dir", user_config_dir)
+    assert xcc.settings.get_path_to_env_file() == "foo/bar/Xanadu/xanadu-cloud/.env"
 
 
 def test_get_name_of_env_var():

xcc/_version.py

@@ -3,4 +3,4 @@
 See https://semver.org/.
 """
 
-__version__ = "0.2.0-dev"
+__version__ = "0.1.1"

xcc/commands.py

@@ -94,6 +94,10 @@ def list_settings() -> Mapping[str, Any]:
 def set_setting(name: str, value: Union[str, int, bool]) -> str:
     """Sets the value of a setting.
 
+    To configure your Xanadu Cloud credentials, simply run
+
+    $ xcc config set REFRESH_TOKEN "Xanadu Cloud API key goes here"
+
     Args:
         name (str): Name of the setting (e.g., "PORT").
         value (str, int, bool): Value of the setting (e.g., 443).

xcc/connection.py

@@ -10,7 +10,7 @@
 
 
 class Connection:
-    """Manages remote connections to the Xanadu Cloud.
+    """Represents a connection to the Xanadu Cloud.
 
     Args:
         refresh_token (str, optional): JWT refresh token, such as a Xanadu Cloud

xcc/job.py

@@ -166,6 +166,7 @@ def overview(self) -> Mapping[str, Any]:
             "created_at": self.created_at,
             "finished_at": self.finished_at,
             "running_time": self.running_time,
+            "metadata": self.metadata,
         }
 
     @cached_property
@@ -300,6 +301,19 @@ def finished(self) -> bool:
         """
         return self.status in ("cancelled", "complete", "failed")
 
+    @property
+    def metadata(self) -> Mapping[str, Any]:
+        """Returns the metadata of a job.
+
+        Returns:
+            Mapping[str, Any]: metadata of this job
+
+        .. note::
+
+            Error details for failed jobs are reported here.
+        """
+        return self._details["meta"]
+
     @cached_property
     def _details(self) -> Mapping[str, Any]:
         """Returns the details of a job.

xcc/settings.py

@@ -12,7 +12,7 @@
 
 def get_path_to_env_file() -> str:
     """Returns the path to the .env file containing the Xanadu Cloud connection settings."""
-    path_to_config_dir = user_config_dir("xanadu-cloud")
+    path_to_config_dir = user_config_dir(appname="xanadu-cloud", appauthor="Xanadu")
     return os.path.join(path_to_config_dir, ".env")
 
 
@@ -22,7 +22,50 @@ def get_name_of_env_var(key: str = "") -> str:
 
 
 class Settings(BaseSettings):
-    """Represents the configuration for connecting to the Xanadu Cloud."""
+    """Represents the configuration for connecting to the Xanadu Cloud.
+
+    The location where this configuration is saved depends on the current
+    operating system. Specifically,
+
+    * Windows: ``C:\\Users\\%USERNAME%\\AppData\\Local\\Xanadu\\xanadu-cloud\\.env``
+
+    * MacOS: ``/home/$USER/Library/Application\\ Support/xanadu-cloud/.env``
+
+    * Linux: ``/home/$USER/.config/xanadu-cloud/.env``
+
+    **Example:**
+
+    The following example shows how to use the :class:`Settings` class to load
+    and save a Xanadu Cloud configuration. To begin, loading a configuration is
+    as simple as instantiating a settings object:
+
+    >>> import xcc
+    >>> settings = xcc.Settings()
+    >>> settings
+    REFRESH_TOKEN=None ACCESS_TOKEN=None HOST='platform.strawberryfields.ai' PORT=443 TLS=True
+
+    Now, individual options can be accessed or assigned through their
+    corresponding attribute:
+
+    >>> settings.PORT
+    443
+    >>> settings.PORT = 80
+    >>> settings.PORT
+    80
+
+    .. note::
+
+        Several aggregate representations of options are also available, such as
+
+        >>> settings.dict()
+        {'REFRESH_TOKEN': None, 'ACCESS_TOKEN': None, ..., 'TLS': True}
+        >>> settings.json()
+        '{"REFRESH_TOKEN": null, "ACCESS_TOKEN": null, ..., "TLS": true}'
+
+    Finally, saving a configuration can be done by invoking :meth:`Settings.save`:
+
+    >>> settings.save()
+    """
 
     REFRESH_TOKEN: Optional[str] = None
     """JWT refresh token that can be used to fetch access tokens from the Xanadu Cloud."""