[gentoo-commits] proj/portage:master commit in: lib/portage/util/, /, lib/_emerge/

[gentoo-commits] proj/portage:master commit in: lib/portage/util/, /, lib/_emerge/

[Sam James]

commit:     15fefd7e2e9b400a8a48d59badad632fe290aa5a
Author:     Berin Aniesh <berinaniesh <AT> gmail <DOT> com>
AuthorDate: Mon Jun  5 14:06:24 2023 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Tue Jun  6 06:52:40 2023 +0000
URL:        https://gitweb.gentoo.org/proj/portage.git/commit/?id=15fefd7e

main.py, portage.util: Add docstrings and type annotations

Signed-off-by: Berin Aniesh <berinaniesh <AT> gmail.com>
Signed-off-by: Sam James <sam <AT> gentoo.org>

 .gitignore                   |  4 ++++
 lib/_emerge/main.py          |  6 ++++--
 lib/portage/util/__init__.py | 25 ++++++++++++-------------
 3 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/.gitignore b/.gitignore
index 7c6acadbe..03ae933b5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,7 @@ __pycache__/
 setup.cfg
 .*.swp
 *.vim
+.mypy_cache
+dist
+*.egg-info/
+MANIFEST

diff --git a/lib/_emerge/main.py b/lib/_emerge/main.py
index 850487d36..ec8d21b96 100644
--- a/lib/_emerge/main.py
+++ b/lib/_emerge/main.py
@@ -1163,8 +1163,10 @@ def profile_check(trees, myaction):
 
 def emerge_main(args=None):
     """
-    @param args: command arguments (default: sys.argv[1:])
-    @type args: list
+    Entry point of emerge
+
+    Processes command line arguments and decides what the current run of emerge
+    should by creating `emerge_config`
     """
     if args is None:
         args = sys.argv[1:]

diff --git a/lib/portage/util/__init__.py b/lib/portage/util/__init__.py
index 31aba6702..e446a54f0 100644
--- a/lib/portage/util/__init__.py
+++ b/lib/portage/util/__init__.py
@@ -1,4 +1,4 @@
-# Copyright 2004-2020 Gentoo Authors
+# Copyright 2004-2023 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 from portage.cache.mappings import UserDict
@@ -87,7 +87,7 @@ portage.proxy.lazyimport.lazyimport(
 noiselimit = 0
 
 
-def initialize_logger(level=logging.WARNING):
+def initialize_logger(level=logging.WARNING) -> None:
     """Sets up basic logging of portage activities
     Args:
             level: the level to emit messages at ('info', 'debug', 'warning' ...)
@@ -97,7 +97,7 @@ def initialize_logger(level=logging.WARNING):
     logging.basicConfig(level=level, format="[%(levelname)-4s] %(message)s")
 
 
-def writemsg(mystr, noiselevel=0, fd=None):
+def writemsg(mystr: str, noiselevel: int = 0, fd=None) -> None:
     """Prints out warning and debug messages based on the noiselimit setting"""
     global noiselimit
     if fd is None:
@@ -118,24 +118,23 @@ def writemsg(mystr, noiselevel=0, fd=None):
         fd.flush()
 
 
-def writemsg_stdout(mystr, noiselevel=0):
+def writemsg_stdout(mystr: str, noiselevel: int = 0) -> None:
     """Prints messages stdout based on the noiselimit setting"""
     writemsg(mystr, noiselevel=noiselevel, fd=sys.stdout)
 
 
-def writemsg_level(msg, level=0, noiselevel=0):
+def writemsg_level(msg: str, level: int = 0, noiselevel: int = 0):
     """
     Show a message for the given level as defined by the logging module
-    (default is 0). When level >= logging.WARNING then the message is
+    (default is 0). 
+    
+    When level >= logging.WARNING then the message is
     sent to stderr, otherwise it is sent to stdout. The noiselevel is
     passed directly to writemsg().
-
-    @type msg: str
-    @param msg: a message string, including newline if appropriate
-    @type level: int
-    @param level: a numeric logging level (see the logging module)
-    @type noiselevel: int
-    @param noiselevel: passed directly to writemsg
+    Takes three parameters
+    1. msg  - the message to output
+    2. level - the numeric logging level (see python's logging module)
+    3. noiselevel - portage's logging level, passed directly to writemsg
     """
     if level >= logging.WARNING:
         fd = sys.stderr