Differential D89

yumrepoinfo: convert docstrings to sphinx format
ClosedPublic
Actions

Authored by kparal on May 7 2014, 2:56 PM.

Tags

None

Subscribers

Details

Reviewers

tflink
mkrizek
jskladan

Commits

rLTRN08db578a9f53: yumrepoinfo: convert docstrings to sphinx format

Summary

To get some experience with Sphinx, I re-formatted yumrepoinfo docstrings into it.

Test Plan

Generated the docs, they look fine.

Diff Detail

Lint

Lint Skipped

Unit

Unit Tests Skipped

A couple of nits but overall, looks pretty good. I'm not sure that I like how autodoc renders with the theme we're using but that's a whole different issue :)

libtaskotron/yumrepoinfo.py
24	I think that the rendered docs would be more read-able if the explanation of the singleton pattern was in the body of the function doc instead of attached to the return
42–43	I think that 'create X object' in the constructor is a bit excessive, no?
112–117	this is missing a param description for `reponame`

libtaskotron/yumrepoinfo.py
42–43	I always thought that there has to be a "title" and then an optional "description" separated by an empty line from the title. But the rendered docs look fine even if I don't follow this format. I guess I mixed up Java and Python worlds.

address issues raised in review

Looks good

Closed by commit rLTRN08db578a9f53 (authored by @kparal).

Revision Contents

			Path
M			docs/source/library.rst (5 lines)
M			libtaskotron/yumrepoinfo.py (93 lines)

Diff 258

docs/source/library.rst

Show All 17 Lines		17	.. automodule:: libtaskotron.runner
18	:members:	18		:members:
19		19
20	check (no sphinx-style docstrings)	20		check (no sphinx-style docstrings)
21	==================================	21		==================================
22		22
23	.. automodule:: libtaskotron.check	23		.. automodule:: libtaskotron.check
24	:members:	24		:members:
25		25
		26		yumrepoinfo
		27		===========
		28
		29		.. automodule:: libtaskotron.yumrepoinfo
		30		:members:

libtaskotron/yumrepoinfo.py

Show All 12 Lines
13	from . import exceptions as exc	13		from . import exceptions as exc
14		14
15		15
16	# a singleton instance of YumRepoInfo (a dict with arches as keys)	16		# a singleton instance of YumRepoInfo (a dict with arches as keys)
17	_yumrepoinfo = {}	17		_yumrepoinfo = {}
18		18
19		19
20	def get_yumrepoinfo(arch=None):	20		def get_yumrepoinfo(arch=None):
21	'''Get YumRepoInfo instance.	21		'''Get YumRepoInfo instance. This method is implemented using the singleton
22		22		pattern - you will always receive the same instance, which will get
23	@param arch architecture to return the YumRepoInfo for. It's always	23		auto-initialized on the first method call.
24	converted to basearch. If None, then local machine arch is used.	24
			tflinkUnsubmitted Not Done I think that the rendered docs would be more read-able if the explanation of the singleton pattern was in the body of the function doc instead of attached to the return
25	@return shared YumRepoInfo instance. This method is implemented using the	25		:param str arch: architecture to return the YumRepoInfo for. It's always
26	singleton pattern - you will always receive the same instance, which	26		converted to basearch. If ``None``, then local machine arch
27	will get auto-initialized on the first method call.	27		is used.
28	@throw TaskotronConfigError if file config parsing and handling failed	28		:return: shared :class:`YumRepoInfo` instance
		29		:raise TaskotronConfigError: if file config parsing and handling failed
29	'''	30		'''
30	# converts to basearch, returns local arch for None	31		# converts to basearch, returns local arch for None
31	arch = rpm_utils.basearch(arch)	32		arch = rpm_utils.basearch(arch)
32		33
33	if not arch in _yumrepoinfo:	34		if not arch in _yumrepoinfo:
34	_yumrepoinfo[arch] = YumRepoInfo(arch)	35		_yumrepoinfo[arch] = YumRepoInfo(arch)
35	return _yumrepoinfo[arch]	36		return _yumrepoinfo[arch]
36		37
37		38
38	class YumRepoInfo(object):	39		class YumRepoInfo(object):
39	'''This class is a wrapper for easily accessing repoinfo.conf file.'''	40		'''This class is a wrapper for easily accessing repoinfo.conf file.'''
40		41
41	def __init__(self, arch=None, filelist=None):	42		def __init__(self, arch=None, filelist=None):
42	'''Create YumRepoinfoConfig object.	43		'''
			tflinkUnsubmitted Not Done I think that 'create X object' in the constructor is a bit excessive, no?
			kparalAuthorUnsubmitted Not Done I always thought that there has to be a "title" and then an optional "description" separated by an empty line from the title. But the rendered docs look fine even if I don't follow this format. I guess I mixed up Java and Python worlds.
43		44		:param str arch: architecture for which to adjust repo URLs. By default
44	@param arch architecture for which to adjust repo URLs. By default it	45		it refers to the architecture of the current machine. It's
45	refers to the architecture of the current machine. It's
46	always converted to basearch.	46		always converted to basearch.
47	@param filelist list of config files to read information from. The first	47		:param filelist: list of config files to read information from. The
48	available config file is used. If None, then the default	48		first available config file is used. If ``None``, then
49	list of locations is used.	49		the default list of locations is used.
50	@raise TaskotronConfigError if no YUM repositories data is found (empty	50		:type filelist: iterable of str
51	or non-existent config file). It's not	51		:raise TaskotronConfigError: if no YUM repositories data is found (empty
52	raised if you specifically request no data	52		or non-existent config file). It's not
53	to load (filelist=[]).	53		raised if you specifically request no data
		54		to load (``filelist=[]``).
54	'''	55		'''
55	self.arch = rpm_utils.basearch(arch)	56		self.arch = rpm_utils.basearch(arch)
56	self.filelist = (filelist if filelist is not None else	57		self.filelist = (filelist if filelist is not None else
57	[os.path.join(confdir, 'yumrepoinfo.conf')	58		[os.path.join(confdir, 'yumrepoinfo.conf')
58	for confdir in config.CONF_DIRS])	59		for confdir in config.CONF_DIRS])
59	self.parser = ConfigParser.SafeConfigParser(defaults=	60		self.parser = ConfigParser.SafeConfigParser(defaults=
60	{'arch': self.arch})	61		{'arch': self.arch})
61		62
Show All 17 Lines
79		80
80	def releases(self):	81		def releases(self):
81	'''Get the list of stable (supported) Fedora releases.'''	82		'''Get the list of stable (supported) Fedora releases.'''
82	return [r for r in self.repos() if self.parser.getboolean(r,	83		return [r for r in self.repos() if self.parser.getboolean(r,
83	'supported')]	84		'supported')]
84		85
85		86
86	def arches(self, reponame):	87		def arches(self, reponame):
87	'''Get the list of all supported architectures for a repo'''	88		'''Get the list of all supported architectures for a repo
		89
		90		:param str reponame: repository name
		91		'''
88	return self._getlist(reponame, 'arches')	92		return self._getlist(reponame, 'arches')
89		93
90		94
91	def get(self, reponame, key):	95		def get(self, reponame, key):
92	'''Get a specific key value from a repo	96		'''Get a specific key value from a repo
93		97
94	@throw TaskotronConfigError if the key can't be retrieved (e.g. wrong	98		:param str reponame: repository name
95	key or repo name)	99		:param str key: name of the key you want to retrieve from a repository
		100		(section)
		101		:raise TaskotronConfigError: if the key can't be retrieved (e.g. wrong
		102		key or repo name)
96	'''	103		'''
97	try:	104		try:
98	return self.parser.get(reponame, key)	105		return self.parser.get(reponame, key)
99	except ConfigParser.Error as e:	106		except ConfigParser.Error as e:
100	raise exc.TaskotronConfigError("Can't retrieve key '%s' from repo "	107		raise exc.TaskotronConfigError("Can't retrieve key '%s' from repo "
101	"'%s': %s" % (key, reponame, e))	108		"'%s': %s" % (key, reponame, e))
102		109
103		110
104	def repo(self, reponame):	111		def repo(self, reponame):
105	'''Given a repo name, return the yumrepoinfo dict, with keys:	112		'''Given a repo name, return the yumrepoinfo dict with keys:
106	'arches', 'parents', 'tag', 'url', 'path' and 'name' '''	113		``arches``, ``parents``, ``tag``, ``url``, ``path`` and ``name``
		114
		115		:param str reponame: repository name
		116		:rtype: dict
		117		'''
			tflinkUnsubmitted Not Done this is missing a param description for `reponame`
107	repo = {'arches': self.arches(reponame),	118		repo = {'arches': self.arches(reponame),
108	'parent': self.get(reponame, 'parent'),	119		'parent': self.get(reponame, 'parent'),
109	'tag': self.get(reponame,'tag'),	120		'tag': self.get(reponame,'tag'),
110	'url': self.get(reponame,'url'),	121		'url': self.get(reponame,'url'),
111	'path': self.get(reponame,'path'),	122		'path': self.get(reponame,'path'),
112	'name': reponame,	123		'name': reponame,
113	}	124		}
114	return repo	125		return repo
115		126
116		127
117	def repo_by_tag(self, tag):	128		def repo_by_tag(self, tag):
118	'''Given a Koji tag, return the corresponding repo dict.	129		'''Given a Koji tag, return the corresponding repo dict.
119		130
120	@param tag a koji tag, e.g. 'f20-updates'. Note: 'rawhide' is not used	131		:param str tag: a koji tag, e.g. ``f20-updates``. Note: ``rawhide`` is
121	as a Koji tag, use number identifier instead or use	132		not used as a Koji tag, use number identifier instead or
122	repo('rawhide')['tag'] to discover it first.	133		use :meth:`repo('rawhide')['tag'] <repo>` to discover it
123	@return repo dict as from @method repo(), or None if no such Koji tag	134		first.
124	found	135		:return: repo dict as from :meth:`repo`, or ``None`` if no such Koji tag
		136		is found
125	'''	137		'''
126	# we don't have repo definition for -candidate tags,	138		# we don't have repo definition for -candidate tags,
127	# let's go up in the hierarchy (stripping '-candidate')	139		# let's go up in the hierarchy (stripping '-candidate')
128	if tag.endswith('-candidate'):	140		if tag.endswith('-candidate'):
129	tag = tag[:-len('-candidate')]	141		tag = tag[:-len('-candidate')]
130	for r in self.repos():	142		for r in self.repos():
131	if self.get(r,'tag') == tag:	143		if self.get(r,'tag') == tag:
132	return self.repo(r)	144		return self.repo(r)
133		145
134		146
135	def top_parent(self, reponame):	147		def top_parent(self, reponame):
136	'''Go through the repo hiearchy and find the top parent for a repo	148		'''Go through the repo hiearchy and find the top parent for a repo
137		149
138	@param reponame repository name	150		:param str reponame: repository name
139	@return the top parent reponame. If @param reponame doesn't have any	151		:return: the top parent reponame. If ``reponame`` doesn't have any
140	parent, its name is returned (it's its own top parent)	152		parent, its name is returned (it's its own top parent)
141	@throw TaskotronConfigError if infinite parent loop detected	153		:rtype: str
		154		:raise TaskotronConfigError: if infinite parent loop detected
142	'''	155		'''
143	parents = []	156		parents = []
144	repo = reponame	157		repo = reponame
145		158
146	while True:	159		while True:
147	parent = self.get(repo, 'parent')	160		parent = self.get(repo, 'parent')
148		161
149	if not parent:	162		if not parent:
Show All 18 Lines		180	for cfg in self.filelist:
168	if self.parser.read(cfg):	181		if self.parser.read(cfg):
169	log.debug('Successfully loaded yumrepoinfo config file: %s',	182		log.debug('Successfully loaded yumrepoinfo config file: %s',
170	cfg)	183		cfg)
171	break	184		break
172	else:	185		else:
173	log.debug('Failed to load yumrepoinfo config file: %s', cfg)	186		log.debug('Failed to load yumrepoinfo config file: %s', cfg)
174		187
175		188
176	def _getlist(self, reponame, item):	189		def _getlist(self, reponame, key):
177	'''Transform a list of comma separated values into a Python list	190		'''Transform a list of comma separated values into a Python list.
178	Returns empty list for non-existent item'''	191		Returns empty list for a non-existent key.
179	itemlist = self.get(reponame, item)	192
		193		:param str reponame: repository name
		194		:param str key: name of the key you want to retrieve from a repository
		195		(section), and then convert it to a list
		196		:rtype: list of str
		197		'''
		198		itemlist = self.get(reponame, key)
180	if not itemlist:	199		if not itemlist:
181	return []	200		return []
182	else:	201		else:
183	return [t.strip() for t in itemlist.split(',')]	202		return [t.strip() for t in itemlist.split(',')]