Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Tweak calculation of Docstring size #13

Merged
merged 1 commit into from
Jan 13, 2025
Merged

Tweak calculation of Docstring size #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
# (Fork) 0.0.12 (2025-01-13)

- Tweaked how to calculate the size of a `Docstring` object

# (Fork) 0.0.11 (2025-01-12)

- Added calculation of the size of a `Docstring` object
Expand Down
5 changes: 4 additions & 1 deletion docstring_parser/common.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,9 +233,12 @@ def size(self) -> int:
"""Calculate the "size" of the docstring. "Size" is an arbitrary
metric for how populated a docstring is."""
return (
# We want to down-weight long/short descriptions, because
# if a docstring doesn't descriptions, the other sections
# could be mistakenly parsed as long/short descriptions.
int(self.short_description is not None)
+ int(self.long_description is not None)
+ len(self.meta)
+ len(self.meta) * 10
)

@property
Expand Down
67 changes: 66 additions & 1 deletion docstring_parser/tests/test_google.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1165,6 +1165,36 @@ def test_compose_expanded(source: str, expected: str) -> None:
""",
2, # because Google style parser can't parse other styles
),
(
"""
Parameters
----------
a: int
description
b: int
description

Returns
-------
int
The return value

Yields
------
str
The yielded value

Raises
------
ValueError
If something goes wrong.
TypeError
If something else goes wrong.
IOError
If something else goes wrong.
""",
2, # because the beginning is parsed into long/short description
),
(
"""
Short description.
Expand All @@ -1186,7 +1216,26 @@ def test_compose_expanded(source: str, expected: str) -> None:
TypeError: If something else goes wrong.
IOError: If something else goes wrong.
""",
9,
72,
),
(
"""
Args:
a (int): description
b (int): description

Returns:
int: The return value

Yields:
str: The yielded value

Raises:
ValueError: If something goes wrong.
TypeError: If something else goes wrong.
IOError: If something else goes wrong.
""",
70,
),
(
"""
Expand All @@ -1208,6 +1257,22 @@ def test_compose_expanded(source: str, expected: str) -> None:
""",
2, # because numpy style parser can't parse other styles
),
(
"""
:param a: description
:type a: int
:param b: description
:type b: int
:returns: The return value
:rtype: int
:yield: The yielded value
:rtype: str
:raises ValueError: If something goes wrong.
:raises TypeError: If something else goes wrong.
:raises IOError: If something else goes wrong.
""",
2, # because the beginning is parsed into long/short description
),
],
)
def test_docstring_size(src: str, expected_size: int) -> None:
Expand Down
67 changes: 66 additions & 1 deletion docstring_parser/tests/test_numpydoc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1235,7 +1235,37 @@ def test_compose(source: str, expected: str) -> None:
IOError
If something else goes wrong.
""",
9,
72,
),
(
"""
Parameters
----------
a: int
description
b: int
description

Returns
-------
int
The return value

Yields
------
str
The yielded value

Raises
------
ValueError
If something goes wrong.
TypeError
If something else goes wrong.
IOError
If something else goes wrong.
""",
70,
),
(
"""
Expand All @@ -1260,6 +1290,25 @@ def test_compose(source: str, expected: str) -> None:
""",
2, # because numpy style parser can't parse other styles
),
(
"""
Args:
a (int): description
b (int): description

Returns:
int: The return value

Yields:
str: The yielded value

Raises:
ValueError: If something goes wrong.
TypeError: If something else goes wrong.
IOError: If something else goes wrong.
""",
2, # because the Arg section are parsed into long/short descriptions
),
(
"""
Short description.
Expand All @@ -1280,6 +1329,22 @@ def test_compose(source: str, expected: str) -> None:
""",
2, # because numpy style parser can't parse other styles
),
(
"""
:param a: description
:type a: int
:param b: description
:type b: int
:returns: The return value
:rtype: int
:yield: The yielded value
:rtype: str
:raises ValueError: If something goes wrong.
:raises TypeError: If something else goes wrong.
:raises IOError: If something else goes wrong.
""",
2, # because the beginning is parsed into long/short descriptions
),
],
)
def test_docstring_size(src: str, expected_size: int) -> None:
Expand Down
67 changes: 66 additions & 1 deletion docstring_parser/tests/test_rest.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -584,6 +584,36 @@ def test_short_rtype() -> None:
""",
2, # because Google style parser can't parse other styles
),
(
"""
Parameters
----------
a: int
description
b: int
description

Returns
-------
int
The return value

Yields
------
str
The yielded value

Raises
------
ValueError
If something goes wrong.
TypeError
If something else goes wrong.
IOError
If something else goes wrong.
""",
2, # because the beginning is parsed into short/long description
),
(
"""
Short description.
Expand All @@ -607,6 +637,25 @@ def test_short_rtype() -> None:
""",
2, # because ReST style parser can't parse other styles
),
(
"""
Args:
a (int): description
b (int): description

Returns:
int: The return value

Yields:
str: The yielded value

Raises:
ValueError: If something goes wrong.
TypeError: If something else goes wrong.
IOError: If something else goes wrong.
""",
2, # because the beginning is parsed into short/long description
),
(
"""
Short description.
Expand All @@ -625,7 +674,23 @@ def test_short_rtype() -> None:
:raises TypeError: If something else goes wrong.
:raises IOError: If something else goes wrong.
""",
9,
72,
),
(
"""
:param a: description
:type a: int
:param b: description
:type b: int
:returns: The return value
:rtype: int
:yield: The yielded value
:rtype: str
:raises ValueError: If something goes wrong.
:raises TypeError: If something else goes wrong.
:raises IOError: If something else goes wrong.
""",
70,
),
],
)
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "docstring_parser_fork"
version = "0.0.11"
version = "0.0.12"
description = "Parse Python docstrings in reST, Google and Numpydoc format"
authors = ["Marcin Kurczewski <[email protected]>"]
license = "MIT"
Expand Down
Loading