Switch 'osc.conf.config' from dict to Options class with type checking

contrib/osc.spec

@@ -26,8 +26,11 @@
 %endif
 
 %define argparse_manpage_pkg %{use_python_pkg}-argparse-manpage
+%define sphinx_pkg %{use_python_pkg}-Sphinx
+
 %if 0%{?fedora}
 %define argparse_manpage_pkg argparse-manpage
+%define sphinx_pkg %{use_python_pkg}-sphinx
 %endif
 
 Name:           osc
@@ -50,6 +53,7 @@ BuildRoot:      %{_tmppath}/%{name}-%{version}-build
 
 %if %{with man}
 BuildRequires:  %{argparse_manpage_pkg}
+BuildRequires:  %{sphinx_pkg}
 %endif
 BuildRequires:  %{use_python_pkg}-cryptography
 BuildRequires:  %{use_python_pkg}-devel >= 3.6
@@ -124,7 +128,7 @@ cat << EOF > macros.osc
 %%osc_plugin_dir %{osc_plugin_dir}
 EOF
 
-# build man page
+# build man pages
 %if %{with man}
 PYTHONPATH=. argparse-manpage \
     --output=osc.1 \
@@ -136,6 +140,8 @@ PYTHONPATH=. argparse-manpage \
     --description="openSUSE Commander" \
     --author="Contributors to the osc project. See the project's GIT history for the complete list." \
     --url="https://github.com/openSUSE/osc/"
+
+sphinx-build -b man doc .
 %endif
 
 %install
@@ -157,6 +163,7 @@ install -Dm0644 macros.osc %{buildroot}%{_rpmmacrodir}/macros.osc
 # install man page
 %if %{with man}
 install -Dm0644 osc.1 %{buildroot}%{_mandir}/man1/osc.1
+install -Dm0644 oscrc.5 %{buildroot}%{_mandir}/man5/oscrc.5
 %endif
 
 %check
@@ -169,7 +176,7 @@ install -Dm0644 osc.1 %{buildroot}%{_mandir}/man1/osc.1
 %license COPYING
 %doc AUTHORS README.md NEWS
 %if %{with man}
-%{_mandir}/man1/osc.*
+%{_mandir}/man*/osc*
 %endif
 
 # executables

doc/_static/css/custom.css

@@ -0,0 +1,3 @@
+dl.property {
+   display: block !important;
+}

doc/api/osc.conf.rst

@@ -1,13 +1,10 @@
 .. py:module:: osc.conf
 
-conf
-====
 
-This is the osc conf module.
-It handles the configuration of osc
+osc.conf
+========
 
-basic structures
-----------------
 
 .. automodule:: osc.conf
    :members:
+   :exclude-members: maintained_attribute, maintenance_attribute, maintained_update_project_attribute

doc/conf.py

@@ -12,7 +12,12 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), ".."))
+import textwrap
+
+TOPDIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(TOPDIR, ".."))
+
+import osc.conf
 
 
 # -- Project information -----------------------------------------------------
@@ -51,6 +56,29 @@ rst_epilog = """
 
 master_doc = 'index'
 
+# order members by __all__ or their order in the source code
+autodoc_default_options = {
+    'member-order': 'bysource',
+}
+
+autodoc_typehints = "both"
+
+# -- Generate documents -------------------------------------------------
+
+osc.conf._model_to_rst(
+    cls=osc.conf.Options,
+    title="Configuration file",
+    description=textwrap.dedent(
+        """
+        The configuration file path is ``$XDG_CONFIG_HOME/osc/oscrc``, which usually translates into ``~/.config/osc/oscrc``.
+        """
+    ),
+    sections={
+        "Host options": osc.conf.HostOptions,
+    },
+    output_file=os.path.join(TOPDIR, "oscrc.rst"),
+)
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -64,3 +92,16 @@ html_theme = 'sphinx_rtd_theme'
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+html_css_files = [
+    # fixes https://github.com/readthedocs/sphinx_rtd_theme/issues/1301
+    'css/custom.css',
+]
+
+
+# -- Options for MAN output -------------------------------------------------
+
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ("oscrc", "oscrc", "openSUSE Commander configuration file", "openSUSE project <opensuse-buildservice@opensuse.org>", 5),
+]

doc/index.rst

@@ -21,6 +21,7 @@ API:
 
    api/modules
    plugins/index
+   oscrc
 
 
 

osc/commandline.py

@@ -1078,10 +1078,7 @@ class Osc(cmdln.Cmdln):
         except oscerr.NoConfigfile as e:
             print(e.msg, file=sys.stderr)
             print('Creating osc configuration file %s ...' % e.file, file=sys.stderr)
-            apiurl = conf.DEFAULTS['apiurl']
-            if self.options.apiurl:
-                apiurl = self.options.apiurl
-            conf.interactive_config_setup(e.file, apiurl)
+            conf.interactive_config_setup(e.file, self.options.apiurl)
             print('done', file=sys.stderr)
             self.post_argparse()
         except oscerr.ConfigMissingApiurl as e:

osc/credentials.py

@@ -19,41 +19,6 @@ from . import conf
 from . import oscerr
 
 
-class _LazyPassword:
-    def __init__(self, pwfunc):
-        self._pwfunc = pwfunc
-        self._password = None
-
-    def __str__(self):
-        if self._password is None:
-            password = self._pwfunc()
-            if callable(password):
-                print('Warning: use of a deprecated credentials manager API.',
-                      file=sys.stderr)
-                password = password()
-            if password is None:
-                raise oscerr.OscIOError(None, 'Unable to retrieve password')
-            self._password = password
-        return self._password
-
-    def __format__(self, format_spec):
-        if format_spec.endswith("s"):
-            return f"{self.__str__():{format_spec}}"
-        return super().__format__(format_spec)
-
-    def __len__(self):
-        return len(str(self))
-
-    def __add__(self, other):
-        return str(self) + other
-
-    def __radd__(self, other):
-        return other + str(self)
-
-    def __getattr__(self, name):
-        return getattr(str(self), name)
-
-
 class AbstractCredentialsManagerDescriptor:
     def name(self):
         raise NotImplementedError()
@@ -90,9 +55,9 @@ class AbstractCredentialsManager:
 
     def get_password(self, url, user, defer=True, apiurl=None):
         if defer:
-            return _LazyPassword(lambda: self._get_password(url, user, apiurl=apiurl))
+            return conf.Password(lambda: self._get_password(url, user, apiurl=apiurl))
         else:
-            return self._get_password(url, user, apiurl=apiurl)
+            return conf.Password(self._get_password(url, user, apiurl=apiurl))
 
     def set_password(self, url, user, password):
         raise NotImplementedError()

tests/test_conf.py

@@ -70,6 +70,8 @@ submitrequest_declined_template = bla bla
 linkcontrol = 0
 include_request_from_project = 1
 local_service_run = 1
+include_files = incl *.incl
+exclude_files = excl *.excl
 maintained_attribute = OBS:Maintained
 maintenance_attribute = OBS:MaintenanceProject
 maintained_update_project_attribute = OBS:UpdateProject
@@ -84,12 +86,13 @@ pass = opensuse
 passx = unused
 aliases = osc
 http_headers = 
-    authorization: Basic QWRtaW46b3BlbnN1c2U=
+    Authorization: Basic QWRtaW46b3BlbnN1c2U=
+    X-Foo: Bar
 realname = The Administrator
 email = admin@example.com
-sslcertck = 1
 cafile = /path/to/custom_cacert.pem
 capath = /path/to/custom_cacert.d/
+sslcertck = 1
 trusted_prj = openSUSE:* SUSE:*
 downloadurl = http://example.com/
 sshkey = ~/.ssh/id_rsa.pub
@@ -309,6 +312,12 @@ class TestExampleConfig(unittest.TestCase):
     def test_local_service_run(self):
         self.assertEqual(self.config["local_service_run"], True)
 
+    def test_exclude_files(self):
+        self.assertEqual(self.config["exclude_files"], ["excl", "*.excl"])
+
+    def test_include_files(self):
+        self.assertEqual(self.config["include_files"], ["incl", "*.incl"])
+
     def test_maintained_attribute(self):
         self.assertEqual(self.config["maintained_attribute"], "OBS:Maintained")
 
@@ -339,7 +348,10 @@ class TestExampleConfig(unittest.TestCase):
         host_options = self.config["api_host_options"][self.config["apiurl"]]
         self.assertEqual(
             host_options["http_headers"],
-            [("authorization", "Basic QWRtaW46b3BlbnN1c2U=")],
+            [
+                ("Authorization", "Basic QWRtaW46b3BlbnN1c2U="),
+                ("X-Foo", "Bar"),
+            ],
         )
 
     def test_host_option_realname(self):
@@ -390,5 +402,40 @@ class TestExampleConfig(unittest.TestCase):
         self.assertEqual(host_options["disable_hdrmd5_check"], False)
 
 
+class TestFromParent(unittest.TestCase):
+    def setUp(self):
+        self.options = osc.conf.Options()
+        self.host_options = osc.conf.HostOptions(apiurl="https://example.com", username="Admin", _parent=self.options)
+        self.options.api_host_options[self.host_options.apiurl] = self.host_options
+
+    def test_disable_hdrmd5_check(self):
+        self.assertEqual(self.options.disable_hdrmd5_check, False)
+        self.assertEqual(self.host_options.disable_hdrmd5_check, False)
+
+        self.options.disable_hdrmd5_check = True
+
+        self.assertEqual(self.options.disable_hdrmd5_check, True)
+        self.assertEqual(self.host_options.disable_hdrmd5_check, True)
+
+        self.host_options.disable_hdrmd5_check = False
+
+        self.assertEqual(self.options.disable_hdrmd5_check, True)
+        self.assertEqual(self.host_options.disable_hdrmd5_check, False)
+
+    def test_email(self):
+        self.assertEqual(self.options.email, None)
+        self.assertEqual(self.host_options.email, None)
+
+        self.options.email = "user@example.com"
+
+        self.assertEqual(self.options.email, "user@example.com")
+        self.assertEqual(self.host_options.email, "user@example.com")
+
+        self.host_options.email = "another-user@example.com"
+
+        self.assertEqual(self.options.email, "user@example.com")
+        self.assertEqual(self.host_options.email, "another-user@example.com")
+
+
 if __name__ == "__main__":
     unittest.main()

tests/test_output.py

@@ -82,7 +82,7 @@ class TestPrintMsg(unittest.TestCase):
         importlib.reload(osc.conf)
 
     def test_debug(self):
-        osc.conf.config["debug"] = 0
+        osc.conf.config["debug"] = False
         stdout = io.StringIO()
         stderr = io.StringIO()
         with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
@@ -90,7 +90,7 @@ class TestPrintMsg(unittest.TestCase):
         self.assertEqual("", stdout.getvalue())
         self.assertEqual("", stderr.getvalue())
 
-        osc.conf.config["debug"] = 1
+        osc.conf.config["debug"] = True
         stdout = io.StringIO()
         stderr = io.StringIO()
         with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
@@ -99,7 +99,7 @@ class TestPrintMsg(unittest.TestCase):
         self.assertEqual("DEBUG: foo bar\n", stderr.getvalue())
 
     def test_verbose(self):
-        osc.conf.config["verbose"] = 0
+        osc.conf.config["verbose"] = False
         stdout = io.StringIO()
         stderr = io.StringIO()
         with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
@@ -107,7 +107,7 @@ class TestPrintMsg(unittest.TestCase):
         self.assertEqual("", stdout.getvalue())
         self.assertEqual("", stderr.getvalue())
 
-        osc.conf.config["verbose"] = 1
+        osc.conf.config["verbose"] = True
         stdout = io.StringIO()
         stderr = io.StringIO()
         with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
@@ -115,8 +115,8 @@ class TestPrintMsg(unittest.TestCase):
         self.assertEqual("foo bar\n", stdout.getvalue())
         self.assertEqual("", stderr.getvalue())
 
-        osc.conf.config["verbose"] = 0
-        osc.conf.config["debug"] = 1
+        osc.conf.config["verbose"] = False
+        osc.conf.config["debug"] = True
         stdout = io.StringIO()
         stderr = io.StringIO()
         with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):