Add type hints by hugovk · Pull Request #15 · python-humanize/humanize · GitHub

Changes proposed in this pull request:

Redo of 🐑 Add seperate typing hints for humanize jmoiron/humanize#150
Should be a major release because some of the returns have changed from return value to return str(value)

TODO

Check the docs failure in mkdocstrings:

ERROR    -  mkdocstrings: name 'TypeAlias' is not defined
Traceback (most recent call last):

https://github.com/python-humanize/humanize/runs/6276428220?check_suite_focus=true

…yield, or raise in their body

…default of True or False

…is a literal int, float, str object

Co-authored-by: Jack Edge <yellowbounder@gmail.com>

Hmmm, I was going to say "get_type_hints + pytkdocs won't work on python less than 3.9" but your pipeline ran on python 3.10 🤔

typing.TypeAlias is new in 3.10, maybe mkdocstrings / pytkdocs doesn't support it yet?

https://docs.python.org/3/library/typing.html#typing.TypeAlias

Maybe it's simply because your TypeAlias import is type guarded? Therefore not available at runtime for get_type_hints to pick it up? pytkdocs doesn't do anything special with types (it has no particular knowledge of any other types).

Could you try to patch pytkdocs' loader module to add the future annotations import and see if it keeps failing?

Maybe it's simply because your TypeAlias import is type guarded? Therefore not available at runtime for get_type_hints to pick it up? pytkdocs doesn't do anything special with types (it has no particular knowledge of any other types).

Removing if TYPE_CHECKING: fixes it. I'd rather not remove it, because it would mean we need to add typing_extensions as a runtime library dependency, when it's only needed when checking types.

Could you try to patch pytkdocs' loader module to add the future annotations import and see if it keeps failing?

This doesn't fix it.

Looks good, couple of observations, but none of them blocking. 👍

This is a very specific type hint for something that's just going to be slapped into argument unpacking. 😅

Yeah, it's a bit of a jumble! Will replace with list[typing.Any]

Hmm, with this:

diff --git a/tests/test_filesize.py b/tests/test_filesize.py
index 0119d58..857a958 100644
--- a/tests/test_filesize.py
+++ b/tests/test_filesize.py
@@ -3,6 +3,8 @@
 """Tests for filesize humanizing."""
 from __future__ import annotations
 
+import typing
+
 import pytest
 
 import humanize
@@ -33,7 +35,7 @@ import humanize
         ([10**26 * 30, True, False, "%.3f"], "2481.542 YiB"),
     ],
 )
-def test_naturalsize(test_args: list[int] | list[int | bool], expected: str) -> None:
+def test_naturalsize(test_args: list[typing.Any], expected: str) -> None:
     assert humanize.naturalsize(*test_args) == expected
 
     args_with_negative = test_args

The mypy fails when run from pre-commit but only as part of the Git commit:

$ gc -m "Use typing.Any"
pyupgrade................................................................Passed
black....................................................................Passed
isort....................................................................Passed
autoflake................................................................Passed
flake8...................................................................Passed
check blanket noqa.......................................................Passed
check for merge conflicts................................................Passed
check toml...........................................(no files to check)Skipped
check yaml...........................................(no files to check)Skipped
fix end of files.........................................................Passed
pydocstyle...........................................(no files to check)Skipped
mypy.....................................................................Failed
- hook id: mypy
- exit code: 1

tests/test_filesize.py:10: error: Cannot find implementation or library stub for module named "humanize"
tests/test_filesize.py:10: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
Found 1 error in 1 file (checked 1 source file)

setup-cfg-fmt........................................(no files to check)Skipped
pyproject-fmt........................................(no files to check)Skipped
tox-ini-fmt..........................................(no files to check)Skipped

Fine when run in pre-commit or directly as mypy:

$ pre-commit run --all-files
pyupgrade................................................................Passed
black....................................................................Passed
isort....................................................................Passed
autoflake................................................................Passed
flake8...................................................................Passed
check blanket noqa.......................................................Passed
check for merge conflicts................................................Passed
check toml...............................................................Passed
check yaml...............................................................Passed
fix end of files.........................................................Passed
pydocstyle...............................................................Passed
mypy.....................................................................Passed
setup-cfg-fmt............................................................Passed
pyproject-fmt............................................................Passed
tox-ini-fmt..............................................................Passed
$ mypy --strict .
Success: no issues found in 11 source files

Maybe I'll just leave the jumble...

Co-authored-by: coiax <yellowbounder@gmail.com>

Codecov Report

Merging #15 (f550e98) into main (0c177f7) will decrease coverage by 0.59%.
The diff coverage is 97.36%.

@@            Coverage Diff             @@
##             main      #15      +/-   ##
==========================================
- Coverage   99.68%   99.08%   -0.60%     
==========================================
  Files           9        9              
  Lines         635      658      +23     
==========================================
+ Hits          633      652      +19     
- Misses          2        6       +4

Flag	Coverage Δ
macos-latest	97.87% <97.36%> (-0.56%)	⬇️
ubuntu-latest	97.87% <97.36%> (-0.56%)	⬇️
windows-latest	97.56% <97.36%> (-0.55%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
src/humanize/number.py	96.77% <86.95%> (-2.37%)	⬇️
src/humanize/time.py	99.53% <98.18%> (-0.47%)	⬇️
src/humanize/__init__.py	100.00% <100.00%> (ø)
src/humanize/filesize.py	100.00% <100.00%> (ø)
src/humanize/i18n.py	98.11% <100.00%> (+0.03%)	⬆️
tests/test_filesize.py	100.00% <100.00%> (ø)
tests/test_i18n.py	100.00% <100.00%> (ø)
tests/test_number.py	100.00% <100.00%> (ø)
tests/test_time.py	100.00% <100.00%> (ø)

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0c177f7...f550e98. Read the comment docs.

Removing if TYPE_CHECKING: fixes it. I'd rather not remove it, because it would mean we need to add typing_extensions as a runtime library dependency, when it's only needed when checking types.

Of course, completely understandable.

This doesn't fix it.

Erm, too bad. I'm not sure what is required at this point to make get_type_hints work. I'll need to investigate a bit more. Thank you for trying!

@pawamoy Hi! Any news on this? Do you have an upstream issue to follow?

No news, no issue (feel free to open them in relevant repositories). Didn't take the time to investigate. At this point I'd recommend trying the new handler, which does not use introspection but rather visits the AST (I don't know if you already tried it or not).

I didn't try the new handler but happy to give it a go! What do we need to change to try it?

You just need to depend on mkdocstrings-python instead of mkdocstrings-python-legacy, or to use the python extra instead of the python-legacy one 🙂

More information about the two handlers: https://mkdocstrings.github.io/handlers/overview/#about-the-python-handlers.
Highlight: the new handler does not support documenting inherited members yet, and there are known issues with wildcard imports.

…ing bug

… appear in the function signature

Thanks, that works!

@hugovk the times in seconds are typed as int but they should be float. These changes are failing mypy on our side.

@sodul In which function? And what version of Humanize are you using?

@hugovk We got the issue with humanize==4.2.3, rolling back to humanize==4.1.0 helped.

Sample error:

error: Argument 1 to "precisedelta" has incompatible type "float"; expected "Union[timedelta, int]"

I took an other look and in a way the int type properly reflects the actual behavior:

>>> import humanize
>>> humanize.precisedelta(0.05)
'0 seconds'

>>> humanize.precisedelta(1.05)
'1 second'

>>> humanize.precisedelta(0.05, minimum_unit="microseconds")
'0 microseconds'

>>> humanize.precisedelta(1.05, minimum_unit="microseconds")
'1 second'

>>> humanize.precisedelta(1.05, minimum_unit="milliseconds")
'1 second'

>>> humanize.precisedelta(0.05, minimum_unit="milliseconds")
'0 milliseconds'

When the seconds are passed as a float it works, but only the integer part is used. That's because _date_and_delta() does value = int(value) but I think that it could do value = float(value) instead, and then only if the type is not already a number (I suspect the intent was to cast strings to a number value).

So at the end of the day ... the type annotation is reflecting the behavior. Personally I believe float is fine (it accepts int types as a subset of float), and that the code could even benefit to actually support fractions of seconds when minimum_unit allows for it.

For now I can update my code to cast to int in order to satisfy mypy, even though it does not feel right:
humanize.precisedelta(int(seconds))

@sodul I have an open PR (#39) that I believe will fix the mypy issue. It also adds more precise support for float values:

>>> precisedelta(0.01, "seconds", format="%0.3f")
BEFORE:  "0 seconds"
AFTER:   "0.010 seconds"

hugovk and others added 6 commits May 3, 2022 18:37

Typing: ignore second import

9b83619

Autotyping: add -> None return type to functions without any return, …

a6699f5

…yield, or raise in their body

Autotyping: add a : bool annotation to any function parameter with a …

7971aa6

…default of True or False

Autotyping: add an annotation to any parameter for which the default …

4de3e74

…is a literal int, float, str object

Move final return out of else

a4cacf0

Add type hints

e8f0e85

Co-authored-by: Jack Edge <yellowbounder@gmail.com>

hugovk added the changelog: Added For new features label May 3, 2022

hugovk mentioned this pull request May 3, 2022

🐑 Add seperate typing hints for humanize jmoiron/humanize#150

Closed

coiax reviewed May 4, 2022

View reviewed changes

Silence PyCharm more generically

0a86628

Co-authored-by: coiax <yellowbounder@gmail.com>

hugovk added 2 commits May 4, 2022 14:52

Replace deprecated typing.Iterable with collections.abc.Iterable

c86b138

Replace 'int | float' with 'float'

54af2f9

hugovk added 3 commits June 12, 2022 14:46

Use the new experimental handler instead of the legacy one to fix typ…

dfc69cb

…ing bug

Fix WARNING - griffe: humanize/time.py:104: Parameter 'when' does not…

5641b0e

… appear in the function signature

Fix GHA caching

f550e98

hugovk merged commit 7688f20 into python-humanize:main Jun 13, 2022

hugovk deleted the typing branch June 13, 2022 16:21

sodul mentioned this pull request Jul 7, 2022

Inconsistencies between documentation/annotations and behavior #28

Closed

Add type hints by hugovk · Pull Request #15 · python-humanize/humanize · GitHub

Uh oh!

Uh oh!

Add type hints - #15

Add type hints#15hugovk merged 12 commits intopython-humanize:mainpython-humanize/humanize:mainfrom hugovk:typinghugovk/humanize:typingCopy head branch name to clipboard

Conversation

hugovk commented May 3, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TODO

Uh oh!

pawamoy commented May 3, 2022

Uh oh!

hugovk commented May 3, 2022

Uh oh!

pawamoy commented May 3, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugovk commented May 4, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coiax left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coiax May 4, 2022

Choose a reason for hiding this comment

Uh oh!

hugovk May 4, 2022

Choose a reason for hiding this comment

Uh oh!

hugovk May 4, 2022

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented May 4, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

pawamoy commented May 6, 2022

Uh oh!

hugovk commented Jun 11, 2022

Uh oh!

pawamoy commented Jun 11, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugovk commented Jun 11, 2022

Uh oh!

pawamoy commented Jun 12, 2022

Uh oh!

hugovk commented Jun 12, 2022

Uh oh!

sodul commented Jul 7, 2022

Uh oh!

hugovk commented Jul 8, 2022

Uh oh!

sodul commented Jul 8, 2022 • edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nuztalgia commented Jul 11, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Add type hints#15
hugovk merged 12 commits into
python-humanize:mainfrom
hugovk:typing

hugovk commented May 3, 2022 •
edited
Loading

pawamoy commented May 3, 2022 •
edited
Loading

hugovk commented May 4, 2022 •
edited
Loading

codecov-commenter commented May 4, 2022 •
edited
Loading

pawamoy commented Jun 11, 2022 •
edited
Loading

sodul commented Jul 8, 2022 •
edited by hugovk
Loading