From 7777d390c789d8ebaab993fdb6efd0b018ffd541 Mon Sep 17 00:00:00 2001 From: Tristan Van Berkom Date: Fri, 16 Mar 2018 18:35:28 +0900 Subject: 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. --- buildstream/source.py | 15 ++++++++++++--- 1 file 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())) -- cgit v1.2.1