improve wording in documentation

src/ahriman/application/ahriman.py

@@ -717,7 +717,7 @@ def _set_repo_triggers_parser(root: SubParserAction) -> argparse.ArgumentParser:
                              description="run triggers on empty build result as configured by settings",
                              formatter_class=_formatter)
     parser.add_argument("trigger", help="instead of running all triggers as set by configuration, just process "
-                                        "specified ones oin order of metion", nargs="*")
+                                        "specified ones in order of mention", nargs="*")
     parser.set_defaults(handler=handlers.Triggers)
     return parser
 

src/ahriman/application/application/application_repository.py

@@ -52,7 +52,7 @@ class ApplicationRepository(ApplicationProperties):
         Args:
             cache(bool): clear directory with package caches
             chroot(bool): clear build chroot
-            manual(bool): clear directory with manually added packages
+            manual(bool): clear directory with manually added packages' bases
             packages(bool): clear directory with built packages
             pacman(bool): clear directory with pacman databases
         """

src/ahriman/application/handlers/backup.py

@@ -57,7 +57,7 @@ class Backup(Handler):
     @staticmethod
     def get_paths(configuration: Configuration) -> Set[Path]:
         """
-        extract paths to backup
+        extract paths to back up
 
         Args:
             configuration(Configuration): configuration instance

src/ahriman/application/handlers/handler.py

@@ -45,6 +45,7 @@ class Handler:
         be called directly. The recommended way is to call ``execute`` class method, e.g.::
 
             >>> from ahriman.application.handlers import Add
+            >>>
             >>> Add.execute(args)
     """
 

src/ahriman/application/handlers/setup.py

@@ -139,7 +139,7 @@ class Setup(Handler):
             prefix(str): command prefix in {prefix}-{architecture}-build
             architecture(str): repository architecture
             source(Path): path to source configuration file
-            multilib(bool): add or do not multilib repository
+            multilib(bool): add or do not multilib repository to the configuration
             repository(str): repository name
             paths(RepositoryPaths): repository paths instance
         """

src/ahriman/core/alpm/pacman.py

@@ -68,7 +68,7 @@ class Pacman(LazyLogging):
 
         Args:
             database(DB): pacman database instance to be copied
-            pacman_root(Path): operating system pacman's root
+            pacman_root(Path): operating system pacman root
             paths(RepositoryPaths): repository paths instance
             use_ahriman_cache(bool): use local ahriman cache instead of system one
         """

src/ahriman/core/auth/auth.py

@@ -55,7 +55,7 @@ class Auth(LazyLogging):
     def auth_control(self) -> str:
         """
         This workaround is required to make different behaviour for login interface.
-        In case of internal authentication it must provide an interface (modal form) to login with button sends POST
+        In case of internal authentication it must provide an interface (modal form) to log in with button sends POST
         request. But for an external providers behaviour can be different: e.g. OAuth provider requires sending GET
         request to external resource
 

src/ahriman/core/auth/mapping.py

@@ -32,7 +32,7 @@ class Mapping(Auth):
     user authorization based on mapping from configuration file
 
     Attributes:
-        salt(str): random generated string to salt passwords
+        salt(str): random generated string to salted password
         database(SQLite): database instance
     """
 

src/ahriman/core/auth/oauth.py

@@ -30,7 +30,7 @@ from ahriman.models.auth_settings import AuthSettings
 
 class OAuth(Mapping):
     """
-    OAuth user authorization.
+    OAuth's user authorization.
     It is required to create application first and put application credentials.
 
     Attributes:
@@ -58,7 +58,7 @@ class OAuth(Mapping):
         # thus we expect that address is set
         self.redirect_uri = f"""{configuration.get("web", "address")}/api/v1/login"""
         self.provider = self.get_provider(configuration.get("auth", "oauth_provider"))
-        # it is list but we will have to convert to string it anyway
+        # it is list, but we will have to convert to string it anyway
         self.scopes = configuration.get("auth", "oauth_scopes")
 
     @property

src/ahriman/core/build_tools/sources.py

@@ -33,7 +33,7 @@ from ahriman.models.repository_paths import RepositoryPaths
 
 class Sources(LazyLogging):
     """
-    helper to download package sources (PKGBUILD etc)
+    helper to download package sources (PKGBUILD etc...)
 
     Attributes:
         DEFAULT_BRANCH(str): (class attribute) default branch to process git repositories.

src/ahriman/core/configuration.py

@@ -284,8 +284,8 @@ class Configuration(configparser.RawConfigParser):
             # get overrides
             specific = self.section_name(section, architecture)
             if self.has_section(specific):
-                # if there is no such section it means that there is no overrides for this arch
-                # but we anyway will have to delete sections for others archs
+                # if there is no such section it means that there is no overrides for this arch,
+                # but we anyway will have to delete sections for others architectures
                 for key, value in self[specific].items():
                     self.set_option(section, key, value)
             # remove any arch specific section

src/ahriman/core/database/operations/logs_operations.py

@@ -46,7 +46,7 @@ class LogsOperations(Operations):
                 for row in connection.execute(
                     """
                     select created, record from logs where package_base = :package_base
-                    order by created asc
+                    order by created
                     """,
                     {"package_base": package_base})
             ]

src/ahriman/core/report/report.py

@@ -54,7 +54,7 @@ class Report(LazyLogging):
             >>> except Exception as exception:
             >>>     handle_exceptions(exception)
             >>>
-            >>> report.run([], Result())
+            >>> report.run(Result(), [])
     """
 
     def __init__(self, architecture: str, configuration: Configuration) -> None:

src/ahriman/core/report/telegram.py

@@ -17,7 +17,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
-import requests  # technically we could use python-telegram-bot, but it is just a single request, cmon
+import requests  # technically we could use python-telegram-bot, but it is just a single request, c'mon
 
 from typing import Iterable
 

src/ahriman/core/status/web_client.py

@@ -62,7 +62,7 @@ class WebClient(Client, LazyLogging):
         get url for the login api
 
         Returns:
-            str: full url for web service to login
+            str: full url for web service to log in
         """
         return f"{self.address}/api/v1/login"
 

src/ahriman/core/util.py

@@ -154,7 +154,7 @@ def enum_values(enum: Type[Enum]) -> List[str]:
     Returns:
         List[str]: available enumeration values as string
     """
-    return [key.value for key in enum]
+    return [str(key.value) for key in enum]  # explicit str conversion for typing
 
 
 def exception_response_text(exception: requests.exceptions.HTTPError) -> str:
@@ -288,7 +288,7 @@ def safe_filename(source: str) -> str:
     # https://datatracker.ietf.org/doc/html/rfc3986#section-2.3
     #     unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
     # however we would like to allow some gen-delims characters in filename, because those characters are used
-    # as delimiter in other URI parts. The ones we allow are
+    # as delimiter in other URI parts. The ones we allow to are:
     #     ":" - used as separator in schema and userinfo
     #     "[" and "]" - used for host part
     #     "@" - used as separator between host and userinfo

src/ahriman/models/aur_package.py

@@ -42,7 +42,7 @@ class AURPackage:
         description(str): package base description
         url(Optional[str]): package upstream URL
         num_votes(int): number of votes for the package
-        polularity(float): package popularity
+        popularity(float): package popularity
         out_of_date(Optional[datetime.datetime]): package out of date timestamp if any
         maintainer(Optional[str]): package maintainer
         first_submitted(datetime.datetime): timestamp of the first package submission

src/ahriman/models/package_source.py

@@ -36,7 +36,7 @@ class PackageSource(str, Enum):
         AUR(PackageSource): (class attribute) source is an AUR package for which it should search
         Directory(PackageSource): (class attribute) source is a directory which contains packages
         Local(PackageSource): (class attribute) source is locally stored PKGBUILD
-        Remote(PackageSource): (class attribute) source is remote (http, ftp etc) link
+        Remote(PackageSource): (class attribute) source is remote (http, ftp etc...) link
         Repository(PackageSource): (class attribute) source is official repository
 
     Examples:

src/ahriman/models/sign_settings.py

@@ -34,7 +34,7 @@ class SignSettings(str, Enum):
     """
 
     Disabled = "disabled"
-    Packages = "pacakges"
+    Packages = "packages"
     Repository = "repository"
 
     @classmethod

src/ahriman/models/user.py

@@ -41,11 +41,11 @@ class User:
         Simply create user from database data and perform required validation::
 
             >>> password = User.generate_password(24)
-            >>> user = User("ahriman", password, UserAccess.Write)
+            >>> user = User("ahriman", password, UserAccess.Full)
 
         Since the password supplied may be plain text, the ``hash_password`` method can be used to hash the password::
 
-            >>> user.password = user.hash_password("salt")
+            >>> user = user.hash_password("salt")
 
         Having the user instance and password, it can be validated::
 

src/ahriman/web/views/base.py

@@ -101,7 +101,7 @@ class BaseView(View):
         get non-empty value from request parameters
 
         Args:
-            extractor(Callable[[str], T]): function to get value by key
+            extractor(Callable[[str], T]): function to get value by the specified key
             key(str): key to extract value
 
         Returns: