docstring-format-checker 0.1.0__tar.gz → 0.2.0__tar.gz

{docstring_format_checker-0.1.0 → docstring_format_checker-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-format-checker
-Version: 0.1.0
+Version: 0.2.0
 Summary: A CLI tool to check and validate Python docstring formatting and completeness
 Author: Chris Mahoney
 Author-email: Chris Mahoney <docstring-format-checker@data-science-extensions.com>

{docstring_format_checker-0.1.0 → docstring_format_checker-0.2.0}/pyproject.toml

@@ -1,217 +1,217 @@
-[project]
-name = "docstring-format-checker"
-version = "0.1.0"
-description = "A CLI tool to check and validate Python docstring formatting and completeness"
-readme = "README.md"
-license = "MIT"
-authors = [
-    { name="Chris Mahoney", email="docstring-format-checker@data-science-extensions.com" },
-]
-maintainers = [
-    { name="Chris Mahoney", email="docstring-format-checker@data-science-extensions.com" },
-]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "License :: OSI Approved :: MIT License",
-    "Topic :: Software Development :: Quality Assurance",
-    "Topic :: Software Development :: Libraries :: Python Modules",
-    "Topic :: Software Development :: Testing :: Unit",
-    "Topic :: Utilities",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Intended Audience :: Developers",
-    "Environment :: Console",
-]
-requires-python = ">=3.9"
-dependencies = [
-    "typer>=0.9.0",
-    "tomli>=2.0.0;python_version<'3.11'",
-    "rich>=13.0.0",
-    "toolbox-python==1.*",
-]
-
-[project.urls]
-Homepage = "https://github.com/data-science-extensions/docstring-format-checker"
-Documentation = "https://github.com/data-science-extensions/docstring-format-checker/blob/main/README.md"
-Repository = "https://github.com/data-science-extensions/docstring-format-checker"
-Changelog = "https://github.com/data-science-extensions/docstring-format-checker/releases"
-Issues = "https://github.com/data-science-extensions/docstring-format-checker/issues"
-
-[project.scripts]
-docstring-format-checker = "docstring_format_checker.cli:entry_point"
-dfc = "docstring_format_checker.cli:entry_point"
-
-[dependency-groups]
-dev = [
-    "black==25.*",
-    "blacken-docs==1.*",
-    "codespell==2.*",
-    "ipykernel==6.*",
-    "isort==6.*",
-    "pre-commit==4.*",
-    "pycln==2.*",
-    "pylint==3.*",
-    "pyupgrade==3.*",
-    "uv==0.*",
-    "pip==25.*",
-]
-docs = [
-    "black==25.*",
-    "docstring-inheritance==2.*",
-    "livereload==2.*",
-    "mike==2.*",
-    "mkdocs==1.*",
-    "mkdocs-autorefs==1.*",
-    "mkdocs-coverage==1.*",
-    "mkdocs-material==9.*",
-    "mkdocstrings==0.*",
-    "mkdocstrings-python==1.*",
-    "pygithub==2.*",
-]
-test = [
-    "mypy==1.*,!=1.17.*",
-    "parameterized==0.*",
-    "pytest==8.*",
-    "pytest-clarity==1.*",
-    "pytest-cov==6.*",
-    "pytest-icdiff==0.*",
-    "pytest-sugar==1.*",
-    "pytest-xdist==3.*",
-    "requests==2.*",
-]
-
-[tool.black]
-line-length = 120
-color = true
-exclude = '''
-/(
-    \.git
-    | \.hg
-    | \.mypy_cache
-    | \.tox
-    | \.venv
-    | _build
-    | buck-out
-    | build
-    | dist
-    | env
-    | venv
-)/
-'''
-
-[tool.pytest.ini_options]
-filterwarnings = [
-    # "ignore::typeguard.InstrumentationWarning",
-    "ignore::DeprecationWarning",
-]
-addopts = [
-    "--verbose",
-    "--verbose",
-    "--cov=src/docstring_format_checker",
-    "--cov-report=term",
-    "--cov-report=html:cov-report/html",
-    "--cov-report=xml:cov-report/xml/cov-report.xml",
-]
-testpaths = [
-    "src/tests",
-]
-python_files = ["test_*.py"]
-python_classes = ["Test*"]
-python_functions = ["test_*"]
-
-[tool.mypy]
-ignore_missing_imports = true
-pretty = true
-disable_error_code = [
-    "valid-type",
-    "attr-defined",
-    "no-redef",
-]
-
-[tool.isort]
-import_heading_future = "## Future Python Library Imports ----"
-import_heading_stdlib = "## Python StdLib Imports ----"
-import_heading_thirdparty = "## Python Third Party Imports ----"
-import_heading_firstparty = "## Local First Party Imports ----"
-import_heading_localfolder = "## Local Module Imports ----"
-profile = "black"
-split_on_trailing_comma = true
-combine_as_imports = true
-lines_after_imports = 2
-
-[tool.codespell]
-ignore-words-list = "demog"
-
-[tool.bump_version.replacements]
-files = [
-    { file = "src/docstring_format_checker/__init__.py", pattern = "__version__ = \"{VERSION}\"" },
-    { file = "src/tests/test_version.py", pattern = "__version__ = \"{VERSION}\"" },
-    { file = "pyproject.toml", pattern = "version = \"{VERSION}\"" },
-]
-
-[tool.dfc]
-# Default configuration for docstring format checker
-
-[[tool.dfc.sections]]
-order = 1
-name = "summary"
-type = "free_text"
-admonition = "note"
-prefix = "!!!"
-required = true
-
-[[tool.dfc.sections]]
-order = 2
-name = "details"
-type = "free_text"
-admonition = "info"
-prefix = "???+"
-required = false
-
-[[tool.dfc.sections]]
-order = 3
-name = "params"
-type = "list_name_and_type"
-required = true
-
-[[tool.dfc.sections]]
-order = 4
-name = "returns"
-type = "list_name_and_type"
-required = false
-
-[[tool.dfc.sections]]
-order = 5
-name = "yields"
-type = "list_type"
-required = false
-
-[[tool.dfc.sections]]
-order = 6
-name = "raises"
-type = "list_type"
-required = false
-
-[[tool.dfc.sections]]
-order = 7
-name = "examples"
-type = "free_text"
-admonition = "example"
-prefix = "???+"
-required = false
-
-[[tool.dfc.sections]]
-order = 8
-name = "notes"
-type = "free_text"
-admonition = "note"
-prefix = "???"
-required = false
-
-[build-system]
-requires = ["uv_build>=0.7.19,<0.8.0"]
-build-backend = "uv_build"
+[project]
+name = "docstring-format-checker"
+version = "v0.2.0"
+description = "A CLI tool to check and validate Python docstring formatting and completeness"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name="Chris Mahoney", email="docstring-format-checker@data-science-extensions.com" },
+]
+maintainers = [
+    { name="Chris Mahoney", email="docstring-format-checker@data-science-extensions.com" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Testing :: Unit",
+    "Topic :: Utilities",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Developers",
+    "Environment :: Console",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "typer>=0.9.0",
+    "tomli>=2.0.0;python_version<'3.11'",
+    "rich>=13.0.0",
+    "toolbox-python==1.*",
+]
+
+[project.urls]
+Homepage = "https://github.com/data-science-extensions/docstring-format-checker"
+Documentation = "https://github.com/data-science-extensions/docstring-format-checker/blob/main/README.md"
+Repository = "https://github.com/data-science-extensions/docstring-format-checker"
+Changelog = "https://github.com/data-science-extensions/docstring-format-checker/releases"
+Issues = "https://github.com/data-science-extensions/docstring-format-checker/issues"
+
+[project.scripts]
+docstring-format-checker = "docstring_format_checker.cli:entry_point"
+dfc = "docstring_format_checker.cli:entry_point"
+
+[dependency-groups]
+dev = [
+    "black==25.*",
+    "blacken-docs==1.*",
+    "codespell==2.*",
+    "ipykernel==6.*",
+    "isort==6.*",
+    "pre-commit==4.*",
+    "pycln==2.*",
+    "pylint==3.*",
+    "pyupgrade==3.*",
+    "uv==0.*",
+    "pip==25.*",
+]
+docs = [
+    "black==25.*",
+    "docstring-inheritance==2.*",
+    "livereload==2.*",
+    "mike==2.*",
+    "mkdocs==1.*",
+    "mkdocs-autorefs==1.*",
+    "mkdocs-coverage==1.*",
+    "mkdocs-material==9.*",
+    "mkdocstrings==0.*",
+    "mkdocstrings-python==1.*",
+    "pygithub==2.*",
+]
+test = [
+    "mypy==1.*,!=1.17.*",
+    "parameterized==0.*",
+    "pytest==8.*",
+    "pytest-clarity==1.*",
+    "pytest-cov==6.*",
+    "pytest-icdiff==0.*",
+    "pytest-sugar==1.*",
+    "pytest-xdist==3.*",
+    "requests==2.*",
+]
+
+[tool.black]
+line-length = 120
+color = true
+exclude = '''
+/(
+    \.git
+    | \.hg
+    | \.mypy_cache
+    | \.tox
+    | \.venv
+    | _build
+    | buck-out
+    | build
+    | dist
+    | env
+    | venv
+)/
+'''
+
+[tool.pytest.ini_options]
+filterwarnings = [
+    # "ignore::typeguard.InstrumentationWarning",
+    "ignore::DeprecationWarning",
+]
+addopts = [
+    "--verbose",
+    "--verbose",
+    "--cov=src/docstring_format_checker",
+    "--cov-report=term",
+    "--cov-report=html:cov-report/html",
+    "--cov-report=xml:cov-report/xml/cov-report.xml",
+]
+testpaths = [
+    "src/tests",
+]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.mypy]
+ignore_missing_imports = true
+pretty = true
+disable_error_code = [
+    "valid-type",
+    "attr-defined",
+    "no-redef",
+]
+
+[tool.isort]
+import_heading_future = "## Future Python Library Imports ----"
+import_heading_stdlib = "## Python StdLib Imports ----"
+import_heading_thirdparty = "## Python Third Party Imports ----"
+import_heading_firstparty = "## Local First Party Imports ----"
+import_heading_localfolder = "## Local Module Imports ----"
+profile = "black"
+split_on_trailing_comma = true
+combine_as_imports = true
+lines_after_imports = 2
+
+[tool.codespell]
+ignore-words-list = "demog"
+
+[tool.bump_version.replacements]
+files = [
+    { file = "src/docstring_format_checker/__init__.py", pattern = "__version__ = \"{VERSION}\"" },
+    { file = "src/tests/test_version.py", pattern = "__version__ = \"{VERSION}\"" },
+    { file = "pyproject.toml", pattern = "version = \"{VERSION}\"" },
+]
+
+[tool.dfc]
+# Default configuration for docstring format checker
+
+[[tool.dfc.sections]]
+order = 1
+name = "summary"
+type = "free_text"
+admonition = "note"
+prefix = "!!!"
+required = true
+
+[[tool.dfc.sections]]
+order = 2
+name = "details"
+type = "free_text"
+admonition = "info"
+prefix = "???+"
+required = false
+
+[[tool.dfc.sections]]
+order = 3
+name = "params"
+type = "list_name_and_type"
+required = true
+
+[[tool.dfc.sections]]
+order = 4
+name = "returns"
+type = "list_name_and_type"
+required = false
+
+[[tool.dfc.sections]]
+order = 5
+name = "yields"
+type = "list_type"
+required = false
+
+[[tool.dfc.sections]]
+order = 6
+name = "raises"
+type = "list_type"
+required = false
+
+[[tool.dfc.sections]]
+order = 7
+name = "examples"
+type = "free_text"
+admonition = "example"
+prefix = "???+"
+required = false
+
+[[tool.dfc.sections]]
+order = 8
+name = "notes"
+type = "free_text"
+admonition = "note"
+prefix = "???"
+required = false
+
+[build-system]
+requires = ["uv_build>=0.7.19,<0.8.0"]
+build-backend = "uv_build"

{docstring_format_checker-0.1.0 → docstring_format_checker-0.2.0}/src/docstring_format_checker/__init__.py

@@ -1,22 +1,22 @@
-"""
-Docstring Format Checker.
-
-A CLI tool to check and validate Python docstring formatting and completeness.
-"""
-
-__version__ = "0.1.0"
-__author__ = "Chris Mahoney"
-__email__ = "docstring-format-checker@data-science-extensions.com"
-
-
-# ## Local First Party Imports ----
-from docstring_format_checker.config import DEFAULT_CONFIG, load_config
-from docstring_format_checker.core import DocstringChecker, SectionConfig
-
-
-__all__: list[str] = [
-    "DocstringChecker",
-    "SectionConfig",
-    "load_config",
-    "DEFAULT_CONFIG",
-]
+"""
+Docstring Format Checker.
+
+A CLI tool to check and validate Python docstring formatting and completeness.
+"""
+
+__version__ = "v0.2.0"
+__author__ = "Chris Mahoney"
+__email__ = "docstring-format-checker@data-science-extensions.com"
+
+
+# ## Local First Party Imports ----
+from docstring_format_checker.config import DEFAULT_CONFIG, load_config
+from docstring_format_checker.core import DocstringChecker, SectionConfig
+
+
+__all__: list[str] = [
+    "DocstringChecker",
+    "SectionConfig",
+    "load_config",
+    "DEFAULT_CONFIG",
+]

{docstring_format_checker-0.1.0 → docstring_format_checker-0.2.0}/src/docstring_format_checker/core.py

@@ -242,6 +242,28 @@ class DocstringChecker:
 
         return results
 
+    def _is_overload_function(self, node: Union[ast.FunctionDef, ast.AsyncFunctionDef]) -> bool:
+        """
+        !!! note "Summary"
+            Check if a function definition is decorated with @overload.
+
+        Params:
+            node (Union[ast.FunctionDef, ast.AsyncFunctionDef]):
+                The function node to check for @overload decorator.
+
+        Returns:
+            (bool):
+                True if the function has @overload decorator, False otherwise.
+        """
+        for decorator in node.decorator_list:
+            # Handle direct name reference: @overload
+            if isinstance(decorator, ast.Name) and decorator.id == "overload":
+                return True
+            # Handle attribute reference: @typing.overload
+            elif isinstance(decorator, ast.Attribute) and decorator.attr == "overload":
+                return True
+        return False
+
     def _extract_items(self, tree: ast.AST) -> list[FunctionAndClassDetails]:
         """
         !!! note "Summary"
@@ -260,8 +282,9 @@ class DocstringChecker:
 
         class ItemVisitor(ast.NodeVisitor):
 
-            def __init__(self) -> None:
+            def __init__(self, checker: DocstringChecker) -> None:
                 self.class_stack: list[str] = []
+                self.checker: DocstringChecker = checker
 
             def visit_ClassDef(self, node: ast.ClassDef) -> None:
                 if not node.name.startswith("_"):  # Skip private classes
@@ -288,23 +311,27 @@ class DocstringChecker:
 
             def _visit_function(self, node: Union[ast.FunctionDef, ast.AsyncFunctionDef]) -> None:
                 """Visit function definition node (sync or async)."""
-                if not node.name.startswith("_"):  # Skip private functions
-                    item_type: Literal["function", "method"] = "method" if self.class_stack else "function"
-                    parent_class: Optional[str] = self.class_stack[-1] if self.class_stack else None
 
-                    items.append(
-                        FunctionAndClassDetails(
-                            item_type=item_type,
-                            name=node.name,
-                            node=node,
-                            lineno=node.lineno,
-                            parent_class=parent_class,
+                if not node.name.startswith("_"):  # Skip private functions
+                    # Skip @overload functions - they don't need docstrings
+
+                    if not self.checker._is_overload_function(node):
+                        item_type: Literal["function", "method"] = "method" if self.class_stack else "function"
+                        parent_class: Optional[str] = self.class_stack[-1] if self.class_stack else None
+
+                        items.append(
+                            FunctionAndClassDetails(
+                                item_type=item_type,
+                                name=node.name,
+                                node=node,
+                                lineno=node.lineno,
+                                parent_class=parent_class,
+                            )
                         )
-                    )
 
                 self.generic_visit(node)
 
-        visitor = ItemVisitor()
+        visitor = ItemVisitor(self)
         visitor.visit(tree)
 
         return items