docstring-format-checker 1.11.4__tar.gz → 1.12.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: docstring-format-checker
3
- Version: 1.11.4
3
+ Version: 1.12.0
4
4
  Summary: A CLI tool to check and validate Python docstring formatting and completeness
5
5
  Author: Chris Mahoney
6
6
  Author-email: Chris Mahoney <docstring-format-checker@data-science-extensions.com>
@@ -12,27 +12,27 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
12
12
  Classifier: Topic :: Software Development :: Testing :: Unit
13
13
  Classifier: Topic :: Utilities
14
14
  Classifier: Programming Language :: Python :: 3
15
- Classifier: Programming Language :: Python :: 3.9
16
15
  Classifier: Programming Language :: Python :: 3.10
17
16
  Classifier: Programming Language :: Python :: 3.11
18
17
  Classifier: Programming Language :: Python :: 3.12
19
18
  Classifier: Programming Language :: Python :: 3.13
20
19
  Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Programming Language :: Python :: 3.15
21
21
  Classifier: Intended Audience :: Developers
22
22
  Classifier: Environment :: Console
23
- Requires-Dist: typer>=0.9.0
23
+ Requires-Dist: typer>=0.9.0,<1
24
24
  Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
25
25
  Requires-Dist: rich>=13.0.0
26
26
  Requires-Dist: toolbox-python==1.*
27
27
  Requires-Dist: pyfiglet==1.*
28
28
  Maintainer: Chris Mahoney
29
29
  Maintainer-email: Chris Mahoney <docstring-format-checker@data-science-extensions.com>
30
- Requires-Python: >=3.9
31
- Project-URL: Changelog, https://data-science-extensions.com/toolboxes/docstring-format-checker/latest/usage/changelog/
32
- Project-URL: Documentation, https://data-science-extensions.com/toolboxes/docstring-format-checker/latest/code/
30
+ Requires-Python: >=3.10
33
31
  Project-URL: Homepage, https://data-science-extensions.com/toolboxes/docstring-format-checker
34
- Project-URL: Issues, https://github.com/data-science-extensions/docstring-format-checker/issues
32
+ Project-URL: Documentation, https://data-science-extensions.com/toolboxes/docstring-format-checker/latest/code/
35
33
  Project-URL: Repository, https://github.com/data-science-extensions/docstring-format-checker
34
+ Project-URL: Changelog, https://data-science-extensions.com/toolboxes/docstring-format-checker/latest/usage/changelog/
35
+ Project-URL: Issues, https://github.com/data-science-extensions/docstring-format-checker/issues
36
36
  Description-Content-Type: text/markdown
37
37
 
38
38
  <h1 align="center"><u><code>docstring-format-checker</code></u></h1>
@@ -0,0 +1,261 @@
1
+ [project]
2
+ name = "docstring-format-checker"
3
+ version = "1.12.0"
4
+ description = "A CLI tool to check and validate Python docstring formatting and completeness"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ classifiers = [
8
+ "Development Status :: 5 - Production/Stable",
9
+ "License :: OSI Approved :: MIT License",
10
+ "Topic :: Software Development :: Quality Assurance",
11
+ "Topic :: Software Development :: Libraries :: Python Modules",
12
+ "Topic :: Software Development :: Testing :: Unit",
13
+ "Topic :: Utilities",
14
+ "Programming Language :: Python :: 3",
15
+ "Programming Language :: Python :: 3.10",
16
+ "Programming Language :: Python :: 3.11",
17
+ "Programming Language :: Python :: 3.12",
18
+ "Programming Language :: Python :: 3.13",
19
+ "Programming Language :: Python :: 3.14",
20
+ "Programming Language :: Python :: 3.15",
21
+ "Intended Audience :: Developers",
22
+ "Environment :: Console",
23
+ ]
24
+ requires-python = ">=3.10"
25
+ dependencies = [
26
+ "typer>=0.9.0,<1",
27
+ "tomli>=2.0.0; python_version<'3.11'",
28
+ "rich>=13.0.0",
29
+ "toolbox-python==1.*",
30
+ "pyfiglet==1.*",
31
+ ]
32
+
33
+ [[project.authors]]
34
+ name = "Chris Mahoney"
35
+ email = "docstring-format-checker@data-science-extensions.com"
36
+
37
+ [[project.maintainers]]
38
+ name = "Chris Mahoney"
39
+ email = "docstring-format-checker@data-science-extensions.com"
40
+
41
+ [project.urls]
42
+ Homepage = "https://data-science-extensions.com/toolboxes/docstring-format-checker"
43
+ Documentation = "https://data-science-extensions.com/toolboxes/docstring-format-checker/latest/code/"
44
+ Repository = "https://github.com/data-science-extensions/docstring-format-checker"
45
+ Changelog = "https://data-science-extensions.com/toolboxes/docstring-format-checker/latest/usage/changelog/"
46
+ Issues = "https://github.com/data-science-extensions/docstring-format-checker/issues"
47
+
48
+ [project.scripts]
49
+ docstring-format-checker = "docstring_format_checker.cli:entry_point"
50
+ dfc = "docstring_format_checker.cli:entry_point"
51
+
52
+ [dependency-groups]
53
+ dev = [
54
+ "black==26.*",
55
+ "blacken-docs==1.*",
56
+ "codespell==2.*",
57
+ "ipykernel==7.*",
58
+ "isort==9.*",
59
+ "prek==0.*",
60
+ "pycln==2.*",
61
+ "pylint==4.*",
62
+ "pyright==1.*",
63
+ "pyupgrade==3.*",
64
+ "uv==0.*",
65
+ "pip>=26.1.2,<27",
66
+ ]
67
+ docs = [
68
+ "black==26.*",
69
+ "docstring-inheritance==3.*",
70
+ "livereload==2.*",
71
+ "mike==2.*",
72
+ "mkdocs==1.*",
73
+ "mkdocs-autorefs==1.*",
74
+ "mkdocs-coverage==2.*",
75
+ "mkdocs-material==9.*",
76
+ "mkdocstrings==1.*",
77
+ "mkdocstrings-python==2.*",
78
+ "pygithub==2.*",
79
+ ]
80
+ test = [
81
+ "ty==0.*",
82
+ "tomli>=2.0.0",
83
+ "parameterized==0.*",
84
+ "pytest==9.*",
85
+ "pytest-clarity==1.*",
86
+ "pytest-cov==7.*",
87
+ "pytest-icdiff==0.*",
88
+ "pytest-sugar==1.*",
89
+ "pytest-xdist==3.*",
90
+ "requests==2.*",
91
+ "complexipy>=5,<9",
92
+ ]
93
+
94
+ [tool.black]
95
+ line-length = 120
96
+ color = true
97
+ exclude = '''
98
+ /(
99
+ \.git
100
+ | \.hg
101
+ | \.mypy_cache
102
+ | \.tox
103
+ | \.venv
104
+ | _build
105
+ | buck-out
106
+ | build
107
+ | dist
108
+ | env
109
+ | venv
110
+ )/
111
+ '''
112
+
113
+ [tool.pytest.ini_options]
114
+ filterwarnings = ["ignore::DeprecationWarning"]
115
+ addopts = [
116
+ "--verbose",
117
+ "--verbose",
118
+ "--diff-width=120",
119
+ "--cov=src/docstring_format_checker",
120
+ "--cov-report=term",
121
+ "--cov-report=html:cov-report/html",
122
+ "--cov-report=xml:cov-report/xml/cov-report.xml",
123
+ ]
124
+ testpaths = ["src/tests"]
125
+ python_files = ["test_*.py"]
126
+ python_classes = ["Test*"]
127
+ python_functions = ["test_*"]
128
+
129
+ [tool.mypy]
130
+ ignore_missing_imports = true
131
+ pretty = true
132
+ disable_error_code = [
133
+ "valid-type",
134
+ "attr-defined",
135
+ "no-redef",
136
+ ]
137
+
138
+ [tool.isort]
139
+ import_heading_future = "## Future Python Library Imports ----"
140
+ import_heading_stdlib = "## Python StdLib Imports ----"
141
+ import_heading_thirdparty = "## Python Third Party Imports ----"
142
+ import_heading_firstparty = "## Local First Party Imports ----"
143
+ import_heading_localfolder = "## Local Module Imports ----"
144
+ profile = "black"
145
+ split_on_trailing_comma = true
146
+ combine_as_imports = true
147
+
148
+ [tool.codespell]
149
+ ignore-words-list = "demog"
150
+
151
+ [tool.pylint.main]
152
+ disable = [
153
+ "C0103",
154
+ "C0301",
155
+ "C0302",
156
+ "R0912",
157
+ "R0913",
158
+ "R0914",
159
+ "R0915",
160
+ "R0917",
161
+ "R1702",
162
+ "R1705",
163
+ "R1724",
164
+ "W0107",
165
+ "W0212",
166
+ "W0612",
167
+ "W0613",
168
+ "W0622",
169
+ "W0718",
170
+ ]
171
+
172
+ [tool.complexipy]
173
+ paths = "src/docstring_format_checker"
174
+ max-complexity-allowed = 13
175
+ quiet = false
176
+ ignore-complexity = false
177
+ details = "low"
178
+ sort = "asc"
179
+
180
+ [[tool.bump_version.replacements.files]]
181
+ file = "src/docstring_format_checker/__init__.py"
182
+ pattern = '__version__ = "{VERSION}"'
183
+
184
+ [[tool.bump_version.replacements.files]]
185
+ file = "src/tests/test_version.py"
186
+ pattern = '__version__ = "{VERSION}"'
187
+
188
+ [[tool.bump_version.replacements.files]]
189
+ file = "pyproject.toml"
190
+ pattern = 'version = "{VERSION}"'
191
+
192
+ [tool.dfc]
193
+ allow_undefined_sections = false
194
+ require_docstrings = true
195
+ check_private = true
196
+ validate_param_types = true
197
+ optional_style = "silent"
198
+
199
+ [[tool.dfc.sections]]
200
+ order = 1
201
+ name = "summary"
202
+ type = "free_text"
203
+ required = true
204
+ admonition = "note"
205
+ prefix = "!!!"
206
+
207
+ [[tool.dfc.sections]]
208
+ order = 2
209
+ name = "details"
210
+ type = "free_text"
211
+ required = false
212
+ admonition = "abstract"
213
+ prefix = "???+"
214
+
215
+ [[tool.dfc.sections]]
216
+ order = 3
217
+ name = "params"
218
+ type = "list_name_and_type"
219
+ required = false
220
+ admonition = false
221
+
222
+ [[tool.dfc.sections]]
223
+ order = 4
224
+ name = "raises"
225
+ type = "list_type"
226
+ required = false
227
+ admonition = false
228
+
229
+ [[tool.dfc.sections]]
230
+ order = 5
231
+ name = "returns"
232
+ type = "list_name_and_type"
233
+ required = false
234
+ admonition = false
235
+
236
+ [[tool.dfc.sections]]
237
+ order = 6
238
+ name = "yields"
239
+ type = "list_type"
240
+ required = false
241
+ admonition = false
242
+
243
+ [[tool.dfc.sections]]
244
+ order = 7
245
+ name = "examples"
246
+ type = "free_text"
247
+ required = false
248
+ admonition = "example"
249
+ prefix = "???+"
250
+
251
+ [[tool.dfc.sections]]
252
+ order = 8
253
+ name = "notes"
254
+ type = "free_text"
255
+ required = false
256
+ admonition = "note"
257
+ prefix = "???"
258
+
259
+ [build-system]
260
+ requires = ["uv_build>=0.12.23,<0.14"]
261
+ build-backend = "uv_build"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "docstring-format-checker"
3
- version = "1.11.4"
3
+ version = "1.12.0"
4
4
  description = "A CLI tool to check and validate Python docstring formatting and completeness"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -18,18 +18,18 @@ classifiers = [
18
18
  "Topic :: Software Development :: Testing :: Unit",
19
19
  "Topic :: Utilities",
20
20
  "Programming Language :: Python :: 3",
21
- "Programming Language :: Python :: 3.9",
22
21
  "Programming Language :: Python :: 3.10",
23
22
  "Programming Language :: Python :: 3.11",
24
23
  "Programming Language :: Python :: 3.12",
25
24
  "Programming Language :: Python :: 3.13",
26
25
  "Programming Language :: Python :: 3.14",
26
+ "Programming Language :: Python :: 3.15",
27
27
  "Intended Audience :: Developers",
28
28
  "Environment :: Console",
29
29
  ]
30
- requires-python = ">=3.9"
30
+ requires-python = ">=3.10"
31
31
  dependencies = [
32
- "typer>=0.9.0",
32
+ "typer>=0.9.0,<1",
33
33
  "tomli>=2.0.0; python_version<'3.11'",
34
34
  "rich>=13.0.0",
35
35
  "toolbox-python==1.*",
@@ -49,50 +49,44 @@ dfc = "docstring_format_checker.cli:entry_point"
49
49
 
50
50
  [dependency-groups]
51
51
  dev = [
52
- "black==25.*",
52
+ "black==26.*",
53
53
  "blacken-docs==1.*",
54
54
  "codespell==2.*",
55
- "ipykernel==6.*; python_version<'3.10'",
56
- "ipykernel==7.*; python_version>='3.10'",
57
- "isort==6.*; python_version<'3.10'",
58
- "isort==7.*; python_version>='3.10'",
59
- "pre-commit==4.*",
55
+ "ipykernel==7.*",
56
+ "isort==9.*",
57
+ "prek==0.*",
60
58
  "pycln==2.*",
61
- "pylint==3.*; python_version<'3.10'",
62
- "pylint==4.*; python_version>='3.10'",
59
+ "pylint==4.*",
63
60
  "pyright==1.*",
64
61
  "pyupgrade==3.*",
65
62
  "uv==0.*",
66
- "pip==25.*",
63
+ "pip>=26.1.2,<27",
67
64
  ]
68
65
  docs = [
69
- "black==25.*",
70
- "docstring-inheritance==3.*; python_version>='3.10'",
71
- "docstring-inheritance==2.*; python_version<'3.10'",
66
+ "black==26.*",
67
+ "docstring-inheritance==3.*",
72
68
  "livereload==2.*",
73
69
  "mike==2.*",
74
70
  "mkdocs==1.*",
75
71
  "mkdocs-autorefs==1.*",
76
72
  "mkdocs-coverage==2.*",
77
73
  "mkdocs-material==9.*",
78
- "mkdocstrings==1.*; python_version>='3.10'",
79
- "mkdocstrings==0.*; python_version<'3.10'",
80
- "mkdocstrings-python==2.*; python_version>='3.10'",
81
- "mkdocstrings-python==1.*; python_version<'3.10'",
74
+ "mkdocstrings==1.*",
75
+ "mkdocstrings-python==2.*",
82
76
  "pygithub==2.*",
83
77
  ]
84
78
  test = [
85
79
  "ty==0.*",
80
+ "tomli>=2.0.0",
86
81
  "parameterized==0.*",
87
- "pytest==9.*; python_version>='3.10'",
88
- "pytest==8.*; python_version<'3.10'",
82
+ "pytest==9.*",
89
83
  "pytest-clarity==1.*",
90
84
  "pytest-cov==7.*",
91
85
  "pytest-icdiff==0.*",
92
86
  "pytest-sugar==1.*",
93
87
  "pytest-xdist==3.*",
94
88
  "requests==2.*",
95
- "complexipy==5.*",
89
+ "complexipy>=5,<9",
96
90
  ]
97
91
 
98
92
  [tool.black]
@@ -153,7 +147,6 @@ import_heading_localfolder = "## Local Module Imports ----"
153
147
  profile = "black"
154
148
  split_on_trailing_comma = true
155
149
  combine_as_imports = true
156
- lines_after_imports = 2
157
150
 
158
151
  [tool.codespell]
159
152
  ignore-words-list = "demog"
@@ -212,5 +205,5 @@ sections = [
212
205
  ]
213
206
 
214
207
  [build-system]
215
- requires = ["uv_build>=0.8.17,<0.9.0"]
208
+ requires = ["uv_build>=0.12.23,<0.14"]
216
209
  build-backend = "uv_build"
@@ -11,7 +11,6 @@ from importlib.metadata import metadata
11
11
  from docstring_format_checker.config import DEFAULT_CONFIG, load_config
12
12
  from docstring_format_checker.core import DocstringChecker, SectionConfig
13
13
 
14
-
15
14
  ### Define package metadata ----
16
15
  _metadata = metadata("docstring-format-checker")
17
16
  __name__: str = _metadata["Name"]
@@ -29,7 +29,6 @@
29
29
  Command-line interface for the docstring format checker.
30
30
  """
31
31
 
32
-
33
32
  # ---------------------------------------------------------------------------- #
34
33
  # #
35
34
  # Setup ####
@@ -66,7 +65,6 @@ from docstring_format_checker.config import (
66
65
  )
67
66
  from docstring_format_checker.core import DocstringChecker, DocstringError
68
67
 
69
-
70
68
  ## --------------------------------------------------------------------------- #
71
69
  ## Exports ####
72
70
  ## --------------------------------------------------------------------------- #
@@ -204,8 +202,7 @@ def _show_usage_examples_callback() -> None:
204
202
  Nothing is returned.
205
203
  """
206
204
 
207
- examples_content: str = dedent(
208
- f"""
205
+ examples_content: str = dedent(f"""
209
206
  Execute the below commands in any terminal after installing the package.
210
207
 
211
208
  {_blue("dfc myfile.py")} {_green("# Check a single Python file (list output)")}
@@ -221,8 +218,7 @@ def _show_usage_examples_callback() -> None:
221
218
  {_blue("dfc . -c custom.toml")} {_green("# Use custom configuration file")}
222
219
  {_blue("dfc --example=config")} {_green("# Show example configuration")}
223
220
  {_blue("dfc -e usage")} {_green("# Show usage examples (this help)")}
224
- """
225
- ).strip()
221
+ """).strip()
226
222
 
227
223
  panel = Panel(
228
224
  examples_content,
@@ -245,8 +241,7 @@ def _show_config_example_callback() -> None:
245
241
  Nothing is returned.
246
242
  """
247
243
 
248
- example_config: str = dedent(
249
- r"""
244
+ example_config: str = dedent(r"""
250
245
  Place the below config in your `pyproject.toml` file.
251
246
 
252
247
  [blue]\[tool.dfc][/blue]
@@ -266,8 +261,7 @@ def _show_config_example_callback() -> None:
266
261
  [blue]{ order = 7, name = "examples", type = "free_text", required = false, admonition = "example", prefix = "???+" },[/blue]
267
262
  [blue]{ order = 8, name = "notes", type = "free_text", required = false, admonition = "note", prefix = "???" },[/blue]
268
263
  [blue]][/blue]
269
- """
270
- ).strip()
264
+ """).strip()
271
265
 
272
266
  panel = Panel(
273
267
  example_config,
@@ -29,7 +29,6 @@
29
29
  Configuration handling for the docstring format checker.
30
30
  """
31
31
 
32
-
33
32
  # ---------------------------------------------------------------------------- #
34
33
  # #
35
34
  # Setup ####
@@ -55,7 +54,6 @@ from docstring_format_checker.utils.exceptions import (
55
54
  InvalidTypeValuesError,
56
55
  )
57
56
 
58
-
59
57
  if sys.version_info >= (3, 11):
60
58
  # ## Python StdLib Imports ----
61
59
  import tomllib
@@ -531,7 +529,7 @@ def _parse_global_config(tool_config: dict[str, Any]) -> GlobalConfig:
531
529
  require_docstrings=tool_config.get("require_docstrings", True),
532
530
  check_private=tool_config.get("check_private", False),
533
531
  validate_param_types=tool_config.get("validate_param_types", True),
534
- optional_style=optional_style, # type:ignore
532
+ optional_style=optional_style,
535
533
  )
536
534
 
537
535
 
@@ -23,7 +23,6 @@
23
23
  Core docstring checking functionality.
24
24
  """
25
25
 
26
-
27
26
  # ---------------------------------------------------------------------------- #
28
27
  # #
29
28
  # Setup ####
@@ -51,7 +50,6 @@ from docstring_format_checker.utils.exceptions import (
51
50
  InvalidFileError,
52
51
  )
53
52
 
54
-
55
53
  ## --------------------------------------------------------------------------- #
56
54
  ## Exports ####
57
55
  ## --------------------------------------------------------------------------- #
@@ -1964,22 +1962,23 @@ class DocstringChecker:
1964
1962
  for line in docstring.split("\n"):
1965
1963
  line: str = line.strip()
1966
1964
  match: Optional[re.Match[str]] = re.match(section_pattern, line)
1967
- if match:
1968
- section_word: str = match.group(1)
1969
- section_name_lower: str = section_word.lower()
1965
+ if not match:
1966
+ continue
1967
+
1968
+ section_word: str = match.group(1)
1969
+ section_name_lower: str = section_word.lower()
1970
+ section_config: Optional[SectionConfig] = next(
1971
+ (s for s in self.sections_config if s.name.lower() == section_name_lower), None
1972
+ )
1973
+ if not section_config or section_config.admonition is not False:
1974
+ continue
1970
1975
 
1971
- # Check if this is a configured non-admonition section
1972
- section_config: Optional[SectionConfig] = next(
1973
- (s for s in self.sections_config if s.name.lower() == section_name_lower), None
1976
+ expected_title_case: str = section_config.name.title()
1977
+ if section_word != expected_title_case:
1978
+ errors.append(
1979
+ f"Section '{section_name_lower}' must be in title case as '{expected_title_case}', "
1980
+ f"found: '{section_word}'"
1974
1981
  )
1975
- if section_config and section_config.admonition is False:
1976
- # Check if it's title case
1977
- expected_title_case: str = section_config.name.title()
1978
- if section_word != expected_title_case:
1979
- errors.append(
1980
- f"Section '{section_name_lower}' must be in title case as '{expected_title_case}', "
1981
- f"found: '{section_word}'"
1982
- )
1983
1982
 
1984
1983
  return errors
1985
1984
 
@@ -2093,20 +2092,21 @@ class DocstringChecker:
2093
2092
  section_name: str = admonition_match.group(1)
2094
2093
  return next((s for s in parentheses_sections if s.name.lower() == section_name.lower()), None)
2095
2094
 
2096
- # Non-admonition sections (must not be indented)
2097
- if not full_line.startswith((" ", "\t")):
2098
- # Match section names (can include spaces) followed by an optional colon
2099
- simple_section_match: Optional[re.Match[str]] = re.match(r"^([A-Z][\w\s]+):?$", stripped_line)
2100
- if simple_section_match:
2101
- section_name: str = simple_section_match.group(1).strip()
2102
- # Check if it's a known section
2103
- potential_section: Optional[SectionConfig] = next(
2104
- (s for s in self.sections_config if s.name.lower() == section_name.lower()), None
2105
- )
2106
- if potential_section:
2107
- return next((s for s in parentheses_sections if s.name.lower() == section_name.lower()), None)
2095
+ if full_line.startswith((" ", "\t")):
2096
+ return None
2108
2097
 
2109
- return None
2098
+ simple_section_match: Optional[re.Match[str]] = re.match(r"^([A-Z][\w\s]+):?$", stripped_line)
2099
+ if not simple_section_match:
2100
+ return None
2101
+
2102
+ section_name: str = simple_section_match.group(1).strip()
2103
+ potential_section: Optional[SectionConfig] = next(
2104
+ (s for s in self.sections_config if s.name.lower() == section_name.lower()), None
2105
+ )
2106
+ if not potential_section:
2107
+ return None
2108
+
2109
+ return next((s for s in parentheses_sections if s.name.lower() == section_name.lower()), None)
2110
2110
 
2111
2111
  def _is_content_line(self, stripped_line: str) -> bool:
2112
2112
  """
@@ -24,7 +24,6 @@
24
24
  This module defines custom exceptions for handling various error scenarios
25
25
  """
26
26
 
27
-
28
27
  # ---------------------------------------------------------------------------- #
29
28
  # #
30
29
  # Main Section ####