mirrors/github.com_openSUSE_osc
1
0
Fork 0
mirror of https://github.com/openSUSE/osc.git synced 2024-12-25 17:36:13 +01:00
Code

Fix several issues in HTML doc rendering, improve output

Browse Source
This commit is contained in:
Daniel Mach 2022-01-24 08:57:53 +01:00
parent 3ca3c804d1
commit 1385297978
9 changed files with 100 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/api/osc.OscConfigParser.rst
View File

@ -1,7 +1,7 @@
.. py:module:: osc.OscConfigParser
OscConfigParser
====
===============
This is the osc config parser.

2
doc/api/osc.build.rst
View File

@ -1,7 +1,7 @@
.. py:module:: osc.build
build
====
=====
This is the osc build module to talk to the build script.

2
doc/api/osc.credentials.rst
View File

@ -1,7 +1,7 @@
.. py:module:: osc.credentials
credentials
====
===========
This is the osc credentials module.

8
osc/OscConfigParser.py
View File

@ -173,11 +173,13 @@ class CommentLine(Line):
class OptionLine(Line):
"""
This class represents an option. The class' "name" attribute is used
This class represents an option. The class' ``name`` attribute is used
to store the option's name and the "value" attribute contains the option's
value. The "frmt" attribute preserves the format which was used in the configuration
value. The ``frmt`` attribute preserves the format which was used in the configuration
file.
Example:
Example::
optionx:<SPACE><SPACE>value
=> self.frmt = '%s:<SPACE><SPACE>%s'
optiony<SPACE>=<SPACE>value<SPACE>;<SPACE>some_comment

11
osc/build.py
View File

@ -301,10 +301,12 @@ class Pac:
def get_preinstall_image(apiurl, arch, cache_dir, img_info, offline=False):
"""
Searches preinstall image according to build info and downloads it to cache
(unless offline is set to True (default: False)).
(unless offline is set to ``True`` (default: ``False``)).
Returns preinstall image path, source and list of image binaries, which can
be used to create rpmlist.
NOTE: preinstall image can be used only for new build roots!
.. note::
preinstall image can be used only for new build roots!
"""
imagefile = ''
imagesource = ''
@ -436,8 +438,9 @@ def get_built_files(pacdir, buildtype):
def get_repo(path):
"""Walks up path looking for any repodata directories.
@param path path to a directory
@return str path to repository directory containing repodata directory
:param path: path to a directory
:return: path to repository directory containing repodata directory
:rtype: str
"""
oldDirectory = None
currentDirectory = os.path.abspath(path)

12
osc/conf.py
View File

@ -442,7 +442,7 @@ def urljoin(scheme, apisrv, path=''):
def is_known_apiurl(url):
"""returns true if url is a known apiurl"""
"""returns ``True`` if url is a known apiurl"""
apiurl = urljoin(*parse_apisrv_url(None, url))
return apiurl in config['api_host_options']
@ -464,8 +464,8 @@ def extract_known_apiurl(url):
def get_apiurl_api_host_options(apiurl):
"""
Returns all apihost specific options for the given apiurl, None if
no such specific optiosn exist.
Returns all apihost specific options for the given apiurl, ``None`` if
no such specific options exist.
"""
# FIXME: in A Better World (tm) there was a config object which
# knows this instead of having to extract it from a url where it
@ -729,9 +729,9 @@ def config_set_option(section, opt, val=None, delete=False, update=True, creds_m
"""
Sets a config option. If val is not specified the current/default value is
returned. If val is specified, opt is set to val and the new value is returned.
If an option was modified get_config is called with **kwargs unless update is set
to False (override_conffile defaults to config['conffile']).
If val is not specified and delete is True then the option is removed from the
If an option was modified get_config is called with ``**kwargs`` unless update is set
to ``False`` (``override_conffile`` defaults to ``config['conffile']``).
If val is not specified and delete is ``True`` then the option is removed from the
config/reset to the default value.
"""
cp = get_configParser(config['conffile'])

126
osc/core.py
View File

@ -296,7 +296,7 @@ class Serviceinfo:
self.package = None
def read(self, serviceinfo_node, append=False):
"""read in the source services <services> element passed as
"""read in the source services ``<services>`` element passed as
elementtree node.
"""
def error(msg, xml):
@ -509,7 +509,7 @@ class Serviceinfo:
return 0
class Linkinfo:
"""linkinfo metadata (which is part of the xml representing a directory
"""linkinfo metadata (which is part of the xml representing a directory)
"""
def __init__(self):
"""creates an empty linkinfo instance"""
@ -523,9 +523,9 @@ class Linkinfo:
self.baserev = None
def read(self, linkinfo_node):
"""read in the linkinfo metadata from the <linkinfo> element passed as
"""read in the linkinfo metadata from the ``<linkinfo>`` element passed as
elementtree node.
If the passed element is None, the method does nothing.
If the passed element is ``None``, the method does nothing.
"""
if linkinfo_node == None:
return
@ -539,19 +539,19 @@ class Linkinfo:
self.baserev = linkinfo_node.get('baserev')
def islink(self):
"""returns True if the linkinfo is not empty, otherwise False"""
""":return: ``True`` if the linkinfo is not empty, otherwise ``False``"""
if self.xsrcmd5 or self.lsrcmd5 or self.error is not None:
return True
return False
def isexpanded(self):
"""returns True if the package is an expanded link"""
""":return: ``True`` if the package is an expanded link"""
if self.lsrcmd5 and not self.xsrcmd5:
return True
return False
def haserror(self):
"""returns True if the link is in error state (could not be applied)"""
""":return: ``True`` if the link is in error state (could not be applied)"""
if self.error:
return True
return False
@ -1824,12 +1824,12 @@ class Package:
def islink(self):
"""tells us if the package is a link (has 'linkinfo').
A package with linkinfo is a package which links to another package.
Returns True if the package is a link, otherwise False."""
Returns ``True`` if the package is a link, otherwise ``False``."""
return self.linkinfo.islink()
def isexpanded(self):
"""tells us if the package is a link which is expanded.
Returns True if the package is expanded, otherwise False."""
Returns ``True`` if the package is expanded, otherwise ``False``."""
return self.linkinfo.isexpanded()
def islinkrepair(self):
@ -1856,21 +1856,21 @@ class Package:
def haslinkerror(self):
"""
Returns True if the link is broken otherwise False.
If the package is not a link it returns False.
Returns ``True`` if the link is broken otherwise ``False``.
If the package is not a link it returns ``False``.
"""
return self.linkinfo.haserror()
def linkerror(self):
"""
Returns an error message if the link is broken otherwise None.
If the package is not a link it returns None.
Returns an error message if the link is broken otherwise ``None``.
If the package is not a link it returns ``None``.
"""
return self.linkinfo.error
def hasserviceinfo(self):
"""
Returns True, if this package contains services.
Returns ``True``, if this package contains services.
"""
return self.serviceinfo.lsrcmd5 is not None or self.serviceinfo.xsrcmd5 is not None
@ -1908,24 +1908,22 @@ class Package:
def status(self, n):
"""
status can be:
file storefile file present STATUS
exists exists in _files
x - - 'A' and listed in _to_be_added
x x - 'R' and listed in _to_be_added
x x x ' ' if digest differs: 'M'
and if in conflicts file: 'C'
x - - '?'
- x x 'D' and listed in _to_be_deleted
x x x 'D' and listed in _to_be_deleted (e.g. if deleted file was modified)
x x x 'C' and listed in _in_conflict
x - x 'S' and listed in self.skipped
- - x 'S' and listed in self.skipped
- x x '!'
- - - NOT DEFINED
status can be::
file storefile file present STATUS
exists exists in _files
x - - 'A' and listed in _to_be_added
x x - 'R' and listed in _to_be_added
x x x ' ' if digest differs: 'M'
and if in conflicts file: 'C'
x - - '?'
- x x 'D' and listed in _to_be_deleted
x x x 'D' and listed in _to_be_deleted (e.g. if deleted file was modified)
x x x 'C' and listed in _in_conflict
x - x 'S' and listed in self.skipped
- - x 'S' and listed in self.skipped
- x x '!'
- - - NOT DEFINED
"""
known_by_meta = False
@ -2513,29 +2511,29 @@ rev: %s
class AbstractState:
"""
Base class which represents state-like objects (<review />, <state />).
Base class which represents state-like objects (``<review />``, ``<state />``).
"""
def __init__(self, tag):
self.__tag = tag
def get_node_attrs(self):
"""return attributes for the tag/element"""
""":return: attributes for the tag/element"""
raise NotImplementedError()
def get_node_name(self):
"""return tag/element name"""
""":return: tag/element name"""
return self.__tag
def get_comment(self):
"""return data from <comment /> tag"""
""":return: data from ``<comment />`` tag"""
raise NotImplementedError()
def get_description(self):
"""return data from <description /> tag"""
""":return: data from ``<description />`` tag"""
raise NotImplementedError()
def to_xml(self):
"""serialize object to XML"""
""":return: object serialized to XML"""
root = ET.Element(self.get_node_name())
for attr in self.get_node_attrs():
val = getattr(self, attr)
@ -2548,7 +2546,7 @@ class AbstractState:
return root
def to_str(self):
"""return "pretty" XML data"""
""":return: object serialized to pretty-printed XML"""
root = self.to_xml()
xmlindent(root)
return ET.tostring(root, encoding=ET_ENCODING)
@ -2655,11 +2653,15 @@ class RequestState(AbstractState):
class Action:
"""
Represents a <action /> element of a Request.
Represents an ``<action />`` element of a Request.
This class is quite common so that it can be used for all different
action types. Note: instances only provide attributes for their specific
type.
Examples:
action types.
.. note::
Instances only provide attributes for their specific type.
Examples::
r = Action('set_bugowner', tgt_project='foo', person_name='buguser')
# available attributes: r.type (== 'set_bugowner'), r.tgt_project (== 'foo'), r.tgt_package (== None)
r.to_str() ->
@ -2667,7 +2669,7 @@ class Action:
<target project="foo" />
<person name="buguser" />
</action>
##
r = Action('delete', tgt_project='foo', tgt_package='bar')
# available attributes: r.type (== 'delete'), r.tgt_project (== 'foo'), r.tgt_package (=='bar')
r.to_str() ->
@ -2712,13 +2714,18 @@ class Action:
"""
Serialize object to XML.
The xml tag names and attributes are constructed from the instance's attributes.
Example:
:return: object serialized to XML
Example::
self.group_name -> tag name is "group", attribute name is "name"
self.src_project -> tag name is "source" (translated via prefix_to_elm dict),
attribute name is "project"
Attributes prefixed with "opt_" need a special handling, the resulting xml should
look like this: opt_updatelink -> <options><updatelink>value</updatelink></options>.
Attributes which are "None" will be skipped.
Attributes prefixed with ``opt_`` need a special handling, the resulting xml should
look like this: ``opt_updatelink`` -> ``<options><updatelink>value</updatelink></options>``.
Attributes which are ``None`` will be skipped.
"""
root = ET.Element('action', type=self.type)
for i in Action.type_args[self.type]:
@ -2743,7 +2750,7 @@ class Action:
return root
def to_str(self):
"""return "pretty" XML data"""
""":return: object serialized to pretty-printed XML"""
root = self.to_xml()
xmlindent(root)
return ET.tostring(root, encoding=ET_ENCODING)
@ -2778,7 +2785,7 @@ class Action:
class Request:
"""Represents a request (<request />)"""
"""Represents a request (``<request />``)"""
def __init__(self):
self._init_attributes()
@ -2850,7 +2857,7 @@ class Request:
return self.creator
def to_xml(self):
"""serialize object to XML"""
""":return: object serialized to XML"""
root = ET.Element('request')
if self.reqid is not None:
root.set('id', self.reqid)
@ -2875,7 +2882,7 @@ class Request:
return root
def to_str(self):
"""return "pretty" XML data"""
""":return: object serialized to pretty-printed XML"""
root = self.to_xml()
xmlindent(root)
return ET.tostring(root, encoding=ET_ENCODING)
@ -4789,7 +4796,7 @@ def sha256_dgst(file):
return s.hexdigest()
def binary(s):
"""return true if a string is binary data using diff's heuristic"""
"""return ``True`` if a string is binary data using diff's heuristic"""
if s and bytes('\0', "utf-8") in s[:4096]:
return True
return False
@ -6739,7 +6746,11 @@ def checkRevision(prj, pac, revision, apiurl=None, meta=False):
def build_table(col_num, data = [], headline = [], width=1, csv = False):
"""
This method builds a simple table.
Example1: build_table(2, ['foo', 'bar', 'suse', 'osc'], ['col1', 'col2'], 2)
Example::
build_table(2, ['foo', 'bar', 'suse', 'osc'], ['col1', 'col2'], 2)
col1 col2
foo bar
suse osc
@ -7309,7 +7320,9 @@ def getPrjPacPaths(path):
returns the path for a project and a package
from path. This is needed if you try to add
or delete packages:
Examples:
Examples::
osc add pac1/: prj_dir = CWD;
pac_dir = pac1
osc add /path/to/pac1:
@ -7814,8 +7827,8 @@ def run_external(filename, *args, **kwargs):
def return_external(filename, *args, **kwargs):
"""Executes the program filename via subprocess.check_output.
*args are additional arguments which are passed to the
program filename. **kwargs specify additional arguments for
``*args`` are additional arguments which are passed to the
program filename. ``**kwargs`` specify additional arguments for
the subprocess.check_output function.
if no args are specified the plain filename is passed
to subprocess.check_output (this can be used to execute a shell
@ -7823,7 +7836,6 @@ def return_external(filename, *args, **kwargs):
to the subprocess.check_output function.
Returns the output of the command.
"""
if args:
cmd = [filename] + list(args)

2
osc/util/packagequery.py
View File

@ -26,7 +26,7 @@ class PackageQueries(dict):
"""Adds package query to dict if it is of the correct architecture and
is newer (has a greater version) than the currently assigned package.
@param a PackageQuery
:param query: a PackageQuery
"""
self.__setitem__(query.name(), query)

19
osc/util/repodata.py
View File

@ -31,9 +31,10 @@ OPERATOR_BY_FLAGS = {
def primaryPath(directory):
"""Returns path to the primary repository data file.
@param directory repository directory that contains the repodata subdirectory
@return str path to primary repository data file
@raise IOError if repomd.xml contains no primary location
:param directory: repository directory that contains the repodata subdirectory
:return: path to primary repository data file
:rtype: str
:raise IOError: if repomd.xml contains no primary location
"""
metaDataPath = os.path.join(directory, "repodata", "repomd.xml")
elementTree = ET.parse(metaDataPath)
@ -55,10 +56,9 @@ def queries(directory):
"""Returns a list of RepoDataQueries constructed from the repodata under
the directory.
@param directory path to a repository directory (parent directory of
repodata directory)
@return list of RepoDataQueryResult instances
@raise IOError if repomd.xml contains no primary location
:param directory: path to a repository directory (parent directory of repodata directory)
:return: list of RepoDataQueryResult instances
:raise IOError: if repomd.xml contains no primary location
"""
path = primaryPath(directory)
@ -99,9 +99,8 @@ class RepoDataQueryResult(osc.util.packagequery.PackageQueryResult):
"""Creates a RepoDataQueryResult from the a package Element under a metadata
Element in a primary.xml file.
@param directory repository directory path. Used to convert relative
paths to full paths.
@param element package Element
:param directory: repository directory path. Used to convert relative paths to full paths.
:param element: package Element
"""
self.__directory = os.path.abspath(directory)
self.__element = element