arrow-py / arrow-py/arrow

Add a parameter to limit the amount of units returned by humanize

Open
#1,013 4 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
9.1k
Forks
784
PR merge metrics
No merged PRs in 30d

Description

## Feature Request

Add a parameter to `arrow.Arrow.humanize` which limits the amount of units in the returned string.

```py
>>> time1 = arrow.get(2021, 8, 7, 0, 30)
>>> time2 = arrow.get(2021, 8, 7, 2, 21, 11)
>>> time1.humanize(time2, granularity=["hour", "minute", "second"])
'an hour 51 minutes and 11 seconds ago'

>>> time1.humanize(time2, granularity=["hour", "minute", "second"], max_units=2)
'an hour and 51 minutes ago'

>>> time1.humanize(time2, granularity=["hour", "minute", "second"], max_units=1)
'an hour ago'

>>> time1.humanize(time2, granularity=["hour", "second"], max_units=3)
'an hour and 3071 seconds ago'
```

Just like the `granularity` parameter, it simply truncates the output; no rounding should be performed. It should start counting from the largest unit. In the example above it starts counting at hours; at minutes it reaches the specified limit of 2 units. Anything after (just seconds) is omitted.

The use case is to effectively limit the length of the output string. While `granularity` can be used to control the length of the output, the caller would already have to know what units the result will show. With the proposed parameter, the caller just specifies an amount and doesn't care which combination of units are returned.

The name is up to discussion; `max_units` is just used for the sake of example.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the arrow.Arrow.humanize entry point and its existing granularity handling. Verify the examples for max_units values of 1, 2, and 3, including truncation from the largest unit without rounding; the final parameter name remains to be decided.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.