docs: add docstrings to all classes and methods

Author: sdn4z

src/twyn/cli.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/dependency_managers/dependency_manager.py

@@ -18,14 +18,17 @@ class BaseDependencyManager:
 
     @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/managers/base.py

@@ -5,13 +5,15 @@
 
 
 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

src/twyn/dependency_managers/utils.py

@@ -12,11 +12,14 @@
 
 
 class DependencySelector:
+    """Select and provide parsers for dependency files."""
+
     def __init__(self, dependency_files: Optional[set[str]] = None, root_path: str = ".") -> None:
         self.dependency_files = dependency_files or set()
         self.root_path = root_path
 
     def auto_detect_dependency_file_parser(self) -> list[AbstractParser]:
+        """Automatically detect and return parsers for dependency files."""
         parsers: list[AbstractParser] = []
         root = Path(self.root_path)
         for path in root.rglob("*"):
@@ -37,6 +40,7 @@ def auto_detect_dependency_file_parser(self) -> list[AbstractParser]:
         return parsers
 
     def get_dependency_file_parsers_from_file_name(self) -> list[AbstractParser]:
+        """Get parsers for dependency files based on their names."""
         parsers = []
         for dependency_file in self.dependency_files:
             for known_dependency_file_name in DEPENDENCY_FILE_MAPPING:
@@ -49,6 +53,7 @@ def get_dependency_file_parsers_from_file_name(self) -> list[AbstractParser]:
         return parsers
 
     def get_dependency_parsers(self) -> list[AbstractParser]:
+        """Get appropriate dependency parsers based on configuration."""
         if self.dependency_files:
             logger.debug("Dependency file provided. Assigning a parser.")
             return self.get_dependency_file_parsers_from_file_name()

src/twyn/dependency_parser/dependency_selector.py

@@ -20,9 +20,11 @@ def __init__(self, file_path: str) -> None:
         self.file_handler = FileHandler(file_path=self.file_path)
 
     def __str__(self) -> str:
+        """Return string representation of parser class name."""
         return self.__class__.__name__
 
     def file_exists(self) -> bool:
+        """Check if dependency file exists."""
         return self.file_handler.exists()
 
     @abstractmethod

src/twyn/dependency_parser/parsers/abstract_parser.py

@@ -11,13 +11,17 @@
 
 
 class FileHandler:
+    """Handle file operations for reading and writing."""
+
     def __init__(self, file_path: str) -> None:
         self.file_path = self._get_file_path(file_path)
 
     def is_handler_of_file(self, name: str) -> bool:
+        """Check if this handler manages the specified file."""
         return self._get_file_path(name) == self.file_path
 
     def read(self) -> str:
+        """Read file content as string."""
         self._raise_for_file_exists()
 
         content = self.file_path.read_text()
@@ -27,30 +31,35 @@ def read(self) -> str:
 
     @contextmanager
     def open(self, mode="r") -> Iterator[TextIO]:
+        """Open file with context manager."""
         self._raise_for_file_exists()
 
         with self.file_path.open(mode) as fp:
             yield fp
         logger.debug("Successfully read content from local dependencies file")
 
     def exists(self) -> bool:
+        """Check if file exists and is a valid file."""
         try:
             self._raise_for_file_exists()
         except (PathNotFoundError, PathIsNotFileError):
             return False
         return True
 
     def _raise_for_file_exists(self) -> None:
+        """Raise appropriate exception if file doesn't exist or isn't a file."""
         if not self.file_path.exists():
             raise PathNotFoundError
 
         if not self.file_path.is_file():
             raise PathIsNotFileError
 
     def write(self, data: str) -> None:
+        """Write data to file."""
         self.file_path.write_text(data)
 
     def delete(self, delete_parent_dir: bool = False) -> None:
+        """Delete file and optionally its parent directory."""
         if not self.exists():
             logger.info("File does not exist, nothing to delete")
             return
@@ -68,4 +77,5 @@ def delete(self, delete_parent_dir: bool = False) -> None:
                 )
 
     def _get_file_path(self, file_path: str) -> Path:
+        """Convert string path to absolute Path object."""
         return Path(os.path.abspath(os.path.join(os.getcwd(), file_path)))

src/twyn/file_handler/file_handler.py

@@ -11,6 +11,8 @@
 
 
 class SimilarityThreshold:
+    """Define threshold values for similarity comparison."""
+
     LENGTH_CUTOFF = 5
     MIN_VALUE = 1.0
     MAX_FOR_SHORT_WORDS = 1.0
@@ -25,6 +27,7 @@ def __init__(self, max: float) -> None:
 
     @classmethod
     def from_name(cls, name: str) -> SimilarityThreshold:
+        """Create threshold based on name length."""
         name_length = len(name)
         if name_length <= cls.LENGTH_CUTOFF:
             logger.debug("max length of %s selected for %s", cls.MAX_FOR_SHORT_WORDS, name)
@@ -34,6 +37,7 @@ def from_name(cls, name: str) -> SimilarityThreshold:
         return cls(max=cls.MAX_FOR_LONG_WORDS)  # we allow more typos if the name is longer
 
     def is_inside_threshold(self, value: float) -> bool:
+        """Check if value is within threshold bounds."""
         return self.min <= value <= self.max
 
 
@@ -60,4 +64,5 @@ class EditDistance(AbstractSimilarityAlgorithm):
     """Levenshtein algorithm that computes the edit distance between words."""
 
     def _run_algorithm(self, first_sequence: str, second_sequence: str) -> int:
+        """Compute Damerau-Levenshtein distance between sequences."""
         return DamerauLevenshtein.distance(s1=first_sequence, s2=second_sequence)