nwdocstringchecking 2.0.1__py3-none-any.whl

nwdocstringchecking-2.0.1.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: nwdocstringchecking
+Version: 2.0.1
+Summary: A library designed to identify which methods in a Python file are missing docstrings.
+Home-page: https://github.com/numbworks/nwdocstringchecking
+Author: numbworks
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-python
+Dynamic: summary
+
+# nwdocstringchecking
+
+## Introduction
+
+This packages consists of the following modules:
+
+- `nwdocstringchecking` is a library designed to identify which methods in a Python file are missing docstrings.
+- `nwdocstringcheckingcli` is a command-line application built on the top of `nwdocstringchecking`.
+
+## Getting Started
+
+I'll use Debian as operating system, but the concept is similar for Windows or Mac.
+
+Procedure:
+
+1. Install `pip` and `venv`:
+
+```sh
+sudo apt install python3-pip python3.12-venv
+```
+
+2. Create a virtual environment:
+
+```sh
+python3 -m venv /tmp/nwdocstringchecking
+source /tmp/nwdocstringchecking/bin/activate
+```
+
+3. Download and install the package:
+
+```sh
+pip install nwdocstringchecking
+```
+
+4. Enter in the interactive Python environment:
+
+```sh
+python3
+```
+```
+Python 3.12.3 (main, Aug 31 2026, 10:18:26) [GCC 13.3.0] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>>
+```
+
+5. Try out if the library works:
+
+```python
+from nwdocstringchecking import DocStringChecker
+
+docstring_checker : DocStringChecker = DocStringChecker()
+```
+
+6. Exit from the interactive Python environment:
+
+```python
+exit()
+```
+
+7. Try out if the CLI application works:
+
+```sh
+nwdocstringcheckingcli
+```
+
+8. Deactivate and delete the virtual environment:
+
+```sh
+deactivate
+rm -rf /tmp/nwdocstringchecking
+```
+
+9. Done!
+
+## Examples
+
+Run it against a `file_path`:
+
+```sh
+nwdocstringcheckingcli --file_path src/nwdocstringchecking.py
+```
+
+```
+*******************************************
+'##::: ##:'##:::::'##:'########:::'######::
+ ###:: ##: ##:'##: ##: ##.... ##:'##... ##:
+ ####: ##: ##: ##: ##: ##:::: ##: ##:::..::
+ ## ## ##: ##: ##: ##: ##:::: ##:. ######::
+ ##. ####: ##: ##: ##: ##:::: ##::..... ##:
+ ##:. ###: ##: ##: ##: ##:::: ##:'##::: ##:
+ ##::. ##:. ###. ###:: ########::. ######::
+..::::..:::...::...:::........::::......:::
+************************Version: 2.0.1*****
+
+file_path: 'src/nwdocstringchecking.py'
+exclude: '[]'
+
+_MessageCollectionValidator.provided_file_path_doesnt_exist
+```
+
+Run it against a `file_path` with `exclude`:
+
+```sh
+nwdocstringcheckingcli 	--file_path src/nwdocstringchecking.py 	--exclude Message 	--exclude Something
+```
+
+```
+*******************************************
+'##::: ##:'##:::::'##:'########:::'######::
+ ###:: ##: ##:'##: ##: ##.... ##:'##... ##:
+ ####: ##: ##: ##: ##: ##:::: ##: ##:::..::
+ ## ## ##: ##: ##: ##: ##:::: ##:. ######::
+ ##. ####: ##: ##: ##: ##:::: ##::..... ##:
+ ##:. ###: ##: ##: ##: ##:::: ##:'##::: ##:
+ ##::. ##:. ###. ###:: ########::. ######::
+..::::..:::...::...:::........::::......:::
+************************Version: 2.0.1*****
+
+file_path: 'src/nwdocstringchecking.py'
+exclude: '['Message', 'Something']'
+
+All methods have docstrings.
+```
+
+## Links
+
+- Source: https://github.com/numbworks/nwdocstringchecking
+- License: https://github.com/numbworks/nwdocstringchecking/blob/master/LICENSE
+
+## Total Downloads (PyPi)
+
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nwdocstringchecking?period=total&units=NONE&left_color=BLACK&right_color=BLUE&left_text=TOTAL+DOWNLOADS)](https://pepy.tech/projects/nwdocstringchecking)

nwdocstringchecking-2.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+nwdocstringchecking.py,sha256=en2BhIbWK4newXig-kPjVFePGjd0n_4gZweoaxlfFq8,2613
+nwdocstringcheckingcli.py,sha256=6Xxr9Fb8ArsbWy9MztGw1NQdeWDwDOxUNR7wQWST06s,11857
+setupinfo.py,sha256=bxSRJLmhxTbDpQ5NSPPbudbV__EoxGw8yTsvyOJ9kBg,557
+nwdocstringchecking-2.0.1.dist-info/METADATA,sha256=TnfCZ6b3-v4wrGcgVkrwXYuxwUJ0Ng5GWrA0NGy3tF0,3611
+nwdocstringchecking-2.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+nwdocstringchecking-2.0.1.dist-info/entry_points.txt,sha256=zVRHVw0fuAi4ScBzKUt82iMFltcpWJCDNcP8E5Q58Co,71
+nwdocstringchecking-2.0.1.dist-info/top_level.txt,sha256=CMJgYLAyf5OdUH_PfZuM5ywuBhEdv6N6DhVyg_hMVJs,53
+nwdocstringchecking-2.0.1.dist-info/RECORD,,

nwdocstringchecking-2.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nwdocstringchecking-2.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nwdocstringcheckingcli = nwdocstringcheckingcli:main

nwdocstringchecking-2.0.1.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+nwdocstringchecking
+nwdocstringcheckingcli
+setupinfo

nwdocstringchecking.py

@@ -0,0 +1,86 @@
+'''
+A library designed to identify which methods in a Python file are missing docstrings.
+
+Alias: nwds
+'''
+
+# GLOBAL MODULES
+import ast
+import os
+from ast import Module
+from typing import cast
+
+# LOCAL MODULES
+# CONSTANTS
+# STATIC CLASSES
+class _MessageCollectionValidator():
+
+    '''Collects all the messages used for logging and for the exceptions used by Validator.'''
+
+    @staticmethod
+    def provided_file_path_doesnt_exist(file_path : str) -> str:
+        return f"The provided 'file_path' doesn't exist: '{file_path}'."
+class _MessageCollection(
+        _MessageCollectionValidator):
+
+    '''Collects all the messages used for logging and for the exceptions.'''
+class Validator():
+
+    '''Collects all validation methods.'''
+
+    @staticmethod
+    def validate_file_path(file_path : str) -> None:
+
+        '''Returns file_path or raises Exception.'''
+        
+        if not os.path.isfile(file_path):
+            raise Exception(_MessageCollection.provided_file_path_doesnt_exist(file_path))
+
+# CLASSES
+class DocStringChecker():
+
+    '''Collects all the logic related to docstrings management.'''
+
+    def __load_source(self, file_path : str) -> str:
+
+        '''Loads source from file_path.'''
+
+        source : str = ""
+
+        with open(file_path, "r", encoding='utf-8') as file:
+            source = file.read()
+
+        return source
+    def __get_missing_docstrings(self, source : str, exclude : list[str]) -> list[str]:
+
+        '''Returns all the method names missing docstrings by excluding specified substrings.'''
+
+        tree : Module = ast.parse(source = source)
+
+        method_names : list[str] = []
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                for item in node.body:
+                    if isinstance(item, ast.FunctionDef):
+                        if ast.get_docstring(item) is None:
+                            method_name = f"{node.name}.{item.name}"
+                            if not any(substring in method_name for substring in exclude):
+                                method_names.append(method_name)
+
+        return method_names
+
+    def run(self, file_path : str, exclude : list[str] = []) -> list[str]:
+
+        '''Runs the docstring check.'''
+
+        Validator.validate_file_path(file_path)
+
+        source : str = self.__load_source(file_path = cast(str, file_path))
+        missing : list[str] = self.__get_missing_docstrings(source = source, exclude = exclude)
+
+        return missing
+
+# MAIN
+if __name__ == "__main__":
+    pass

nwdocstringcheckingcli.py

@@ -0,0 +1,358 @@
+'''
+A CLI application built on the top of nwdocstringchecking.
+'''
+
+# GLOBAL MODULES
+import os
+import subprocess
+from argparse import ArgumentParser, Namespace
+from shutil import get_terminal_size
+from subprocess import CompletedProcess
+from typing import Any, Callable, Final, Optional
+
+# LOCAL MODULES
+from nwdocstringchecking import DocStringChecker, Validator
+from setupinfo import CLI_DESCRIPTION, PROJECT_VERSION
+
+# CONSTANTS
+class CLISTRING:
+
+    '''Collects all the CLI-related strings.'''
+
+    OPTION_FILEPATH_FLAGS : Final[list[str]] = ["--file_path"]
+    OPTION_FILEPATH_DEST : Final[str] = "file_path"
+    OPTION_FILEPATH_REQUIRED : Final[bool] = True
+    OPTION_FILEPATH_HELP : Final[str] = "The path to the Python file to check docstrings for."
+
+    OPTION_EXCLUDE_FLAGS : Final[list[str]] = ["--exclude"]
+    OPTION_EXCLUDE_DEST : Final[str] = "exclude"
+    OPTION_EXCLUDE_REQUIRED : Final[bool] = False
+    OPTION_EXCLUDE_HELP : Final[str] = "One or multiple substrings to exclude from the output."
+    OPTION_EXCLUDE_DEFAULT : Final[list[str]] = []
+    OPTION_EXCLUDE_ACTION : Final[str] = "append"
+
+# STATIC CLASSES
+class _MessageCollectionAsciiBannerManager():
+
+    '''Collects all the messages used for logging and for the exceptions.'''
+
+    @staticmethod
+    def provided_version_empty_whitespace() -> str:
+        return "The provided 'version' is empty or whitespace."
+class _MessageCollectionCLIManager():
+
+    '''Collects all the messages used for logging and for the exceptions.'''
+    
+    @staticmethod
+    def all_methods_have_docstrings() -> str:
+        return "All methods have docstrings."
+class _MessageCollection(
+        _MessageCollectionAsciiBannerManager,
+        _MessageCollectionCLIManager):
+
+    '''Collects all the messages used for logging and for the exceptions.'''
+
+# CLASSES
+class AsciiBannerManager:
+
+    """
+        Creates the ASCII banner for the provided library's version.
+
+        The figlet can be generated using 
+            - 'http://www.network-science.de/ascii/' (font: "banner3-D", width: 120)
+            - 'https://www.askapache.com/online-tools/figlet-ascii/'.
+    """
+
+    def __validate(self, version: str) -> None:
+        
+        """Validates the provided 'version'."""
+
+        if not version or not version.strip():
+            raise ValueError(_MessageCollection.provided_version_empty_whitespace())
+    def __create_figlet(self) -> tuple:
+        
+        """Returns a tuple containing the figlet and its width."""
+        
+        lines : list[str] = [
+            "'##::: ##:'##:::::'##:'########:::'######::",
+            " ###:: ##: ##:'##: ##: ##.... ##:'##... ##:",
+            " ####: ##: ##: ##: ##: ##:::: ##: ##:::..::",
+            " ## ## ##: ##: ##: ##: ##:::: ##:. ######::",
+            " ##. ####: ##: ##: ##: ##:::: ##::..... ##:",
+            " ##:. ###: ##: ##: ##: ##:::: ##:'##::: ##:",
+            " ##::. ##:. ###. ###:: ########::. ######::",
+            "..::::..:::...::...:::........::::......:::"
+        ]
+
+        return (os.linesep.join(lines), len(lines[0]))
+    def __create_frame(self, version: str, max_length: int) -> tuple:
+        
+        """Returns a tuple containing the frame of the figlet."""
+        
+        version_token : str = f"Version: {version}"
+        
+        margin_length : int = 5
+        total_length : int = max_length - len(version_token) - margin_length
+
+        top_line : str = "*" * max_length
+        bottom_line : str = f"{top_line[:total_length]}{version_token}{'*' * margin_length}"
+
+        return (top_line, bottom_line)
+
+    def create_standard(self, version : str) -> str:
+        
+        """Creates the standard ASCII banner."""
+        
+        self.__validate(version)
+
+        figlet, max_length = self.__create_figlet()
+        top_line, bottom_line = self.__create_frame(version, max_length)
+
+        ascii_banner : str = os.linesep.join([
+            top_line,
+            figlet,
+            bottom_line,
+            ""
+        ])
+
+        return ascii_banner
+    def create_mini(self, version : str) -> str:
+
+        """
+            Creates the mini ASCII banner:
+            
+                ***************
+                * NWDS v1.0.0 *
+                ***************
+        """
+
+        self.__validate(version)
+
+        assembly_name : str = "NWDS"
+        middle_line : str = f"* {assembly_name} v{version} *"
+        
+        top_line : str = "*" * len(middle_line)
+        bottom_line : str = top_line
+
+        ascii_banner : str = os.linesep.join([
+            top_line,
+            middle_line,
+            bottom_line,
+            ""
+        ])
+
+        return ascii_banner
+    def create(self, version : str, terminal_width : int) -> str:
+
+        """Creates either a standard or mini ASCII banner depending on the terminal width."""
+        
+        _, max_length = self.__create_figlet()
+
+        if max_length <= terminal_width:
+            return self.create_standard(version)
+        else:
+            return self.create_mini(version)
+class TerminalWindowManager:
+
+    '''Handles terminal window size.'''
+
+    __shutil_width_function : Callable[[], Optional[int]]
+    __stty_width_function : Callable[[], Optional[int]]
+
+    cutoff_width : Final[int] = 70
+
+    @staticmethod
+    def default_shutil_width_function() -> Optional[int]:
+
+        """Get terminal width using shutil (multi-platform)."""
+
+        try:
+
+            terminal_width : int = get_terminal_size().columns
+
+            return terminal_width
+        
+        except:
+            return None
+
+    @staticmethod
+    def default_stty_width_function() -> Optional[int]:
+
+        """Get terminal width using stty command (Linux)."""
+
+        try:
+
+            process : CompletedProcess[str] = subprocess.run(
+                ["/bin/sh", "-c", "stty size | cut -d' ' -f2"],
+                capture_output = True,
+                text = True,
+                check = False,
+            )
+
+            stty_output : str = process.stdout.strip()
+            terminal_width : int = int(stty_output)
+
+            if terminal_width >= 0:
+                return terminal_width
+
+            return None
+        except:
+            return None
+
+    def __init__(
+        self,
+        shutil_width_function : Optional[Callable[[], Optional[int]]] = None,
+        stty_width_function : Optional[Callable[[], Optional[int]]] = None,
+    ) -> None:
+        
+        if shutil_width_function is None:
+            shutil_width_function = self.default_shutil_width_function
+        
+        if stty_width_function is None:
+            stty_width_function = self.default_stty_width_function
+
+        self.__shutil_width_function = shutil_width_function
+        self.__stty_width_function = stty_width_function
+
+    def get_or_cutoff(self) -> int:
+
+        terminal_width : Optional[int] = self.__shutil_width_function()
+
+        if terminal_width is None:
+            terminal_width = self.__stty_width_function()
+
+        if terminal_width is None:
+            terminal_width = self.cutoff_width
+
+        return terminal_width
+class CLIValidator:
+
+    '''Handles CLI argument validation.'''
+
+    def validate_file_path(self, file_path: str) -> str:
+
+        '''Returns file_path or raises Exception.'''
+
+        Validator().validate_file_path(file_path)
+
+        return file_path
+class APFactory():
+
+    '''Encapsulates all the logic related to the creation of a custom instance of argparse.ArgumentParser.'''
+
+    __cli_validator : CLIValidator
+
+    def __init__(self, cli_validator : CLIValidator = CLIValidator()) -> None:
+        self.__cli_validator = cli_validator
+
+    def create(self) -> ArgumentParser:
+
+        '''
+            Creates a custom instance of argparse.ArgumentParser.
+
+            The "prog" argument is not provided in order to make the "usage" statement  dynamic:
+
+                usage: nwdocstringcheckingcli.py [-h] --file_path FILE_PATH [--exclude EXCLUDE]
+        '''
+
+        argument_parser : ArgumentParser = ArgumentParser(description = CLI_DESCRIPTION)
+
+        argument_parser.add_argument(
+            *CLISTRING.OPTION_FILEPATH_FLAGS,
+            dest = CLISTRING.OPTION_FILEPATH_DEST,
+            required = CLISTRING.OPTION_FILEPATH_REQUIRED,
+            help = CLISTRING.OPTION_FILEPATH_HELP,
+            type = self.__cli_validator.validate_file_path)
+        
+        argument_parser.add_argument(
+            *CLISTRING.OPTION_EXCLUDE_FLAGS,
+            dest = CLISTRING.OPTION_EXCLUDE_DEST,
+            required = CLISTRING.OPTION_EXCLUDE_REQUIRED,
+            help = CLISTRING.OPTION_EXCLUDE_HELP,
+            default = CLISTRING.OPTION_EXCLUDE_DEFAULT,
+            action = CLISTRING.OPTION_EXCLUDE_ACTION)
+
+        return argument_parser
+class CLIManager():
+
+    '''Collects all the logic related to the CLI management.'''
+
+    __ap_factory : APFactory
+    __ascii_banner_manager : AsciiBannerManager
+    __docstring_checker : DocStringChecker
+    __tw_manager : TerminalWindowManager
+    __logging_function : Callable[[str], None]
+
+    def __init__(
+        self, 
+        ap_factory : APFactory = APFactory(), 
+        ascii_banner_manager : AsciiBannerManager = AsciiBannerManager(),
+        docstring_checker : DocStringChecker = DocStringChecker(),
+        tw_manager : TerminalWindowManager = TerminalWindowManager(),
+        logging_function : Callable[[str], None] = lambda msg : print(msg)) -> None:
+        
+        self.__ap_factory = ap_factory
+        self.__ascii_banner_manager = ascii_banner_manager
+        self.__docstring_checker = docstring_checker
+        self.__tw_manager = tw_manager
+        self.__logging_function = logging_function
+
+    def __log_ascii_banner(self) -> None:
+
+        """Logs the ascii banner."""
+
+        terminal_width : int = self.__tw_manager.get_or_cutoff()
+        ascii_banner : str = self.__ascii_banner_manager.create(PROJECT_VERSION, terminal_width)
+
+        self.__logging_function("")
+        self.__logging_function(ascii_banner)
+    def __log_namespace(self, args : Namespace):
+
+        '''Logs the provided args.'''
+
+        for key, value in vars(args).items():
+            self.__logging_function(f"{key}: '{value}'")
+            
+        self.__logging_function("")
+    def __log_docstrings(self, missing: list[str]) -> None:
+
+        '''Logs missing docstrings.'''
+
+        if missing:
+            for method in missing:
+                self.__logging_function(method)
+        else:
+            self.__logging_function(_MessageCollection.all_methods_have_docstrings())
+
+    def run_and_log(self) -> None:
+
+        '''
+            Extract the missing docstrings and log them.
+            
+            The SystemExit exception occurs when a required option is not provided.
+            SystemExit doesn't inherit from Exception and has no message, therefore we need to handle it accordingly.            
+        '''
+
+        try:
+
+            self.__log_ascii_banner()
+
+            argument_parser : ArgumentParser = self.__ap_factory.create()
+            args : Namespace = argument_parser.parse_args()
+
+            self.__log_namespace(args)
+
+            missing : list[str] = self.__docstring_checker.run(file_path = args.file_path, exclude = args.exclude)
+            
+            self.__log_docstrings(missing)
+            
+        except (Exception, SystemExit) as e:
+            
+            if not isinstance(e, SystemExit):
+                self.__logging_function(str(e))
+
+# MAIN
+def main(): CLIManager().run_and_log()
+
+if __name__ == "__main__":
+    main()

setupinfo.py

@@ -0,0 +1,14 @@
+'''Contains project information.'''
+
+# INFORMATION
+PROJECT_VERSION : str = "2.0.1"
+PROJECT_AUTHOR : str = "numbworks"
+PROJECT_ALIAS : str = "nwds"
+
+LIBRARY_NAME : str = "nwdocstringchecking"
+LIBRARY_DESCRIPTION : str = "A library designed to identify which methods in a Python file are missing docstrings."
+
+CLI_NAME : str = "nwdocstringcheckingcli"
+CLI_DESCRIPTION : str = "A CLI application designed to identify which methods in a Python file are missing docstrings."
+
+PROJECT_URL : str = f"https://github.com/{PROJECT_AUTHOR}/{LIBRARY_NAME}"