diff options
author | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-03-16 18:35:28 +0900 |
---|---|---|
committer | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-03-20 16:55:56 +0900 |
commit | 7777d390c789d8ebaab993fdb6efd0b018ffd541 (patch) | |
tree | 02440c82ac165054272c3a2a65d78fd2bf0dc958 | |
parent | 810f6c330ed41934c60d626e6e2bc90b79233a92 (diff) | |
download | buildstream-7777d390c789d8ebaab993fdb6efd0b018ffd541.tar.gz |
source.py: Document ref accessors to mandate support for None values.
This is technically an API break, but will be transparant for the
vast majority of the current hand full of source implementations
which exist at this time. This is a lesser evil than bloating the
API with new methods.
-rw-r--r-- | buildstream/source.py | 15 |
1 files changed, 12 insertions, 3 deletions
diff --git a/buildstream/source.py b/buildstream/source.py index 436c9912e..61bc3b549 100644 --- a/buildstream/source.py +++ b/buildstream/source.py @@ -190,13 +190,17 @@ class Source(Plugin): """Fetch the internal ref, however it is represented Returns: - (simple object): The internal source reference + (simple object): The internal source reference, or ``None`` + + .. note:: - Note: The reference is the user provided (or track resolved) value the plugin uses to represent a specific input, like a commit in a VCS or a tarball's checksum. Usually the reference is a string, but the plugin may choose to represent it with a tuple or such. + + Implementations *must* return a ``None`` value in the case that + the ref was not loaded. E.g. a ``(None, None)`` tuple is not acceptable. """ raise ImplError("Source plugin '{}' does not implement get_ref()".format(self.get_kind())) @@ -204,12 +208,17 @@ class Source(Plugin): """Applies the internal ref, however it is represented Args: - ref (simple object): The internal source reference to set + ref (simple object): The internal source reference to set, or ``None`` node (dict): The same dictionary which was previously passed to :func:`~buildstream.source.Source.configure` See :func:`~buildstream.source.Source.get_ref` for a discussion on the *ref* parameter. + + .. note:: + + Implementors must support the special ``None`` value here to + allow clearing any existing ref. """ raise ImplError("Source plugin '{}' does not implement set_ref()".format(self.get_kind())) |