From 9bfcb3aef9ae198833d637416b9252941e634901 Mon Sep 17 00:00:00 2001 From: Daniil Baturin Date: Thu, 21 Jun 2018 11:47:09 +0200 Subject: Add some documentation for vyos.version --- python/vyos/version.py | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/python/vyos/version.py b/python/vyos/version.py index b7fb04b52..383efbc1e 100644 --- a/python/vyos/version.py +++ b/python/vyos/version.py @@ -13,6 +13,21 @@ # You should have received a copy of the GNU Lesser General Public # License along with this library. If not, see . +""" +VyOS version data access library. + +VyOS stores its version data, which include the version number and some +additional information in a JSON file. This module provides a convenient +interface to reading it. + +Example of the version data dict:: + { + 'built_by': 'autobuild@vyos.net', + 'build_id': '021ac2ee-cd07-448b-9991-9c68d878cddd', + 'version': '1.2.0-rolling+201806200337', + 'built_on': 'Wed 20 Jun 2018 03:37 UTC' + } +""" import os import json @@ -22,11 +37,29 @@ import vyos.defaults version_file = os.path.join(vyos.defaults.directories['data'], 'version.json') def get_version_data(file=version_file): + """ + Get complete version data + + Args: + file (str): path to the version file + + Returns: + dict: version data + + The optional ``file`` argument comes in handy in upgrade scripts + that need to retrieve information from images other than the running image. + It should not be used on a running system since the location of that file + is an implementation detail and may change in the future, while the interface + of this module will stay the same. + """ with open(file, 'r') as f: version_data = json.load(f) return version_data def get_version(file=None): + """ + Get the version number + """ version_data = None if file: version_data = get_version_data(file=file) -- cgit v1.2.3