Skip to content

docs: clarify that text() max_nb_chars is an upper bound - #2438

Open
saimoon504 wants to merge 1 commit into
joke2k:masterfrom
saimoon504:docs/text-max-nb-chars-upper-bound
Open

docs: clarify that text() max_nb_chars is an upper bound#2438
saimoon504 wants to merge 1 commit into
joke2k:masterfrom
saimoon504:docs/text-max-nb-chars-upper-bound

Conversation

@saimoon504

Copy link
Copy Markdown

Closes #2389

Brief summary: documentation-only fix. The text() docstring now states
explicitly that max_nb_chars is an upper bound, not a target.

What was wrong

While testing Faker for a university software testing course, we noticed
that text(max_nb_chars=200) regularly returns strings of 100-190
characters, and even max_nb_chars=99999 returned 99908 characters. We
reported this in #2389.

Reading the implementation, this is by design: the output is assembled
from whole words/sentences/paragraphs and the last unit that would
exceed the limit is dropped, so the result is always under max_nb_chars
but can be well under it. The docstring only said the length is
"approximate", which reads as "close to N" rather than "at most N,
possibly much less" - that is what confused us and what the issue is
really about.

How this fixes it

The docstring now states that:

  • max_nb_chars is a strict upper bound
  • the output can be substantially shorter, with an example
  • values below 5 raise ValueError (already true in the code, but
    previously undocumented)

No behavior changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

text() method does not respect max_nb_chars parameter consistently

1 participant