docs: add more docstrings

Author: sdn4z

src/twyn/base/constants.py

@@ -12,15 +12,20 @@
 
 
 MANUAL_INPUT_SOURCE = "manual_input"
+"""Source identifier for manually provided dependencies."""
 
 SELECTOR_METHOD_MAPPING: dict[str, type[selectors.AbstractSelector]] = {
     "first-letter": selectors.FirstLetterExact,
     "nearby-letter": selectors.FirstLetterNearbyInKeyboard,
     "all": selectors.AllSimilar,
 }
+"""Mapping of selector method names to their corresponding classes."""
 
 SELECTOR_METHOD_KEYS = set(SELECTOR_METHOD_MAPPING.keys())
+"""Set of available selector method names."""
+
 SelectorMethod = Literal["first-letter", "nearby-letter", "all"]
+"""Type alias for valid selector method strings."""
 
 DEPENDENCY_FILE_MAPPING: dict[str, type[AbstractParser]] = {
     "requirements.txt": dependency_parser.RequirementsTxtParser,
@@ -29,13 +34,24 @@
     "package-lock.json": dependency_parser.PackageLockJsonParser,
     "yarn.lock": dependency_parser.YarnLockParser,
 }
+"""Mapping of dependency file names to their parser classes."""
 
 
 DEFAULT_SELECTOR_METHOD = "all"
+"""Default method for selecting similar packages."""
+
 DEFAULT_PROJECT_TOML_FILE = "pyproject.toml"
+"""Default filename for project configuration."""
+
 DEFAULT_TWYN_TOML_FILE = "twyn.toml"
+"""Default filename for Twyn-specific configuration."""
+
 DEFAULT_USE_CACHE = True
+"""Default setting for cache usage."""
+
 DEFAULT_RECURSIVE = False
+"""Default setting for recursive processing."""
 
 
 PackageEcosystems: TypeAlias = Literal["pypi", "npm"]
+"""Type alias for supported package ecosystems."""

src/twyn/base/exceptions.py

@@ -29,6 +29,7 @@ def __init__(self, message: str = "") -> None:
             super().__init__(message)
 
         def show(self, file: Optional[IO[Any]] = None) -> None:
+            """Display the error message."""
             logger.debug(self.format_message(), exc_info=True)
             logger.error(self.format_message(), exc_info=False)
 

src/twyn/base/utils.py

@@ -39,6 +39,7 @@
 @click.group()
 @click.version_option(__version__, "--version")
 def entry_point() -> None:
+    """Provide main CLI entry point for Twyn."""
     pass
 
 
@@ -188,13 +189,15 @@ def run(  # noqa: C901
 
 @entry_point.group()
 def allowlist() -> None:
+    """Manage package allowlist configuration."""
     pass
 
 
 @allowlist.command()
 @click.option("--config", type=click.STRING)
 @click.argument("package_name")
 def add(package_name: str, config: str) -> None:
+    """Add package to allowlist."""
     fh = FileHandler(config or ConfigHandler.get_default_config_file_path())
     ConfigHandler(fh).add_package_to_allowlist(package_name)
 
@@ -203,12 +206,14 @@ def add(package_name: str, config: str) -> None:
 @click.option("--config", type=click.STRING)
 @click.argument("package_name")
 def remove(package_name: str, config: str) -> None:
+    """Remove package from allowlist."""
     fh = FileHandler(config or DEFAULT_PROJECT_TOML_FILE)
     ConfigHandler(fh).remove_package_from_allowlist(package_name)
 
 
 @entry_point.group()
 def cache() -> None:
+    """Manage cache operations."""
     pass
 
 

src/twyn/cli.py

@@ -33,27 +33,43 @@ class TwynConfiguration:
     """Fully resolved configuration for Twyn."""
 
     dependency_files: set[str]
+    """Set of dependency file paths to analyze."""
     selector_method: str
+    """Method for selecting similar packages."""
     allowlist: set[str]
+    """Set of package names to allow without checking."""
     pypi_source: Optional[str]
+    """Alternative PyPI source URL."""
     npm_source: Optional[str]
+    """Alternative npm source URL."""
     use_cache: bool
+    """Whether to use cached trusted packages."""
     package_ecosystem: Optional[PackageEcosystems]
+    """Target package ecosystem for analysis."""
     recursive: Optional[bool]
+    """Whether to recursively search for dependency files."""
 
 
 @dataclass
 class ReadTwynConfiguration:
     """Configuration for twyn as set by the user. It may have None values."""
 
     dependency_files: Optional[set[str]] = field(default_factory=set)
+    """Optional set of dependency file paths to analyze."""
     selector_method: Optional[str] = None
+    """Optional method for selecting similar packages."""
     allowlist: set[str] = field(default_factory=set)
+    """Set of package names to allow without checking."""
     pypi_source: Optional[str] = None
+    """Optional alternative PyPI source URL."""
     npm_source: Optional[str] = None
+    """Optional alternative npm source URL."""
     use_cache: Optional[bool] = None
+    """Optional setting for using cached trusted packages."""
     package_ecosystem: Optional[PackageEcosystems] = None
+    """Optional target package ecosystem for analysis."""
     recursive: Optional[bool] = None
+    """Optional setting for recursive dependency file search."""
 
 
 class ConfigHandler:
@@ -200,11 +216,13 @@ def _write_config(self, toml: TOMLDocument, config: ReadTwynConfiguration) -> No
         self._write_toml(toml)
 
     def _write_toml(self, toml: TOMLDocument) -> None:
+        """Write TOML document to file."""
         if not self.file_handler:
             raise ConfigFileNotConfiguredError("Config file not configured. Cannot perform write operation.")
         self.file_handler.write(dumps(toml))
 
     def _read_toml(self) -> TOMLDocument:
+        """Read TOML document from file."""
         if not self.file_handler:
             raise ConfigFileNotConfiguredError("Config file not configured. Cannot perform read operation.")
         try:
@@ -227,6 +245,8 @@ def get_default_config_file_path() -> str:
 
 
 def _serialize_config(x: Any) -> Union[Any, str, list[Any]]:
+    """Serialize configuration values for TOML format."""
+
     def _value_to_for_config(v: Any) -> Union[str, list[Any], Any]:
         if isinstance(v, Enum):
             return v.name

src/twyn/config/config_handler.py

@@ -13,19 +13,25 @@ class BaseDependencyManager:
     """
 
     name: str
+    """Name identifier for the package ecosystem."""
     trusted_packages_source: type[AbstractPackageReference]
+    """Reference class for trusted packages source."""
     dependency_files: set[str]
+    """Set of supported dependency file names."""
 
     @classmethod
     def matches_dependency_file(cls, dependency_file: str) -> bool:
+        """Check if this manager can handle the given dependency file."""
         return Path(dependency_file).name in cls.dependency_files
 
     @classmethod
     def matches_ecosystem_name(cls, name: str) -> bool:
+        """Check if this manager matches the given ecosystem name."""
         return cls.name == Path(name).name.lower()
 
     @classmethod
     def get_alternative_source(cls, sources: dict[str, str]) -> Optional[str]:
+        """Get alternative source URL for this ecosystem from sources dict."""
         match = [x for x in sources if x == cls.name]
 
         return sources[match[0]] if match else None

src/twyn/dependency_managers/dependency_manager.py

@@ -8,5 +8,8 @@
 @dataclass
 class NpmDependencyManager(BaseDependencyManager):
     name = "npm"
+    """Name of the npm package ecosystem."""
     trusted_packages_source = TopNpmReference
+    """Reference source for trusted npm packages."""
     dependency_files = {PACKAGE_LOCK_JSON, YARN_LOCK}
+    """Set of supported npm dependency file names."""

src/twyn/dependency_managers/managers/base.py

@@ -8,5 +8,8 @@
 @dataclass
 class PypiDependencyManager(BaseDependencyManager):
     name = "pypi"
+    """Name of the PyPI package ecosystem."""
     trusted_packages_source = TopPyPiReference
+    """Reference source for trusted PyPI packages."""
     dependency_files = {UV_LOCK, POETRY_LOCK, REQUIREMENTS_TXT}
+    """Set of supported Python dependency file names."""

src/twyn/dependency_managers/managers/npm_dependency_manager.py

@@ -3,23 +3,27 @@
 from twyn.dependency_managers.managers.npm_dependency_manager import NpmDependencyManager
 from twyn.dependency_managers.managers.pypi_dependency_manager import PypiDependencyManager
 
+DEPENDENCY_MANAGERS: list[type[BaseDependencyManager]] = [
+    PypiDependencyManager,
+    NpmDependencyManager,
+]
+"""List of available dependency manager classes."""
+
+PACKAGE_ECOSYSTEMS = {x.name for x in DEPENDENCY_MANAGERS}
+"""Set of package ecosystem names from available dependency managers."""
+
 
 def get_dependency_manager_from_file(dependency_file: str) -> type[BaseDependencyManager]:
+    """Get dependency manager that can handle the given file."""
     for manager in DEPENDENCY_MANAGERS:
         if manager.matches_dependency_file(dependency_file):
             return manager
     raise NoMatchingDependencyManagerError
 
 
 def get_dependency_manager_from_name(name: str) -> type[BaseDependencyManager]:
+    """Get dependency manager by ecosystem name."""
     for manager in DEPENDENCY_MANAGERS:
         if manager.matches_ecosystem_name(name):
             return manager
     raise NoMatchingDependencyManagerError
-
-
-DEPENDENCY_MANAGERS: list[type[BaseDependencyManager]] = [
-    PypiDependencyManager,
-    NpmDependencyManager,
-]
-PACKAGE_ECOSYSTEMS = {x.name for x in DEPENDENCY_MANAGERS}