Simplification of the Call Hierarchy in the Lorem Provider

[Jota-Ve]

Description

Currently, the lorem.Provider() exposes the following main methods:

1. word()
2. words()
3. sentence()
4. sentences()
5. paragraph()
6. paragraphs()
7. text()
8. texts()

Most plural methods (e.g., sentences()) internally call their singular counterpart (sentence()) N times. In turn, the singular methods often delegate to the plural of the next hierarchical level (e.g., sentence() → words()).
The exception is word(), which directly returns words(nb=1)[0].

Additionally, the helper method get_word_list() is invoked twice in the same execution path, but the second invocation is always a no-op (simply returning the received argument):

• sentence() → get_word_list()

  • → words() → get_word_list()

• word() → get_word_list()

  • → words() → get_word_list()

---

Proposal

I suggest a simplification and standardization of this hierarchy:

1. Every singular method should return its plural counterpart with nb=1, as already implemented in word().

• (Simplifyed) Example:

def sentence(): 
  return sentences(nb=1)[0]

2. get_random_list() should only be called inside words().

3. New parameters to sentences() and paragraphs() to preserve current behavior and backward compatibility:

   • sentences() should accept nb_words and variable_nb_words.
   • paragraphs() should accept nb_sentences and variable_nb_sentences.
   • The addition of these parameters increases the flexibility of plural methods, allowing calls like sentences() not to be limited to default word counts and flags.

This would result in a cleaner, more predictable call hierarchy.

---

Motivation

• Consistency: Aligns all singular methods with the same design pattern.
• Readability: Simplifies the mental model of how plural and singular methods interact.
• Maintainability: Reduces redundant calls to helper functions.
• Flexibility: Expands the usability of sentences() and paragraphs() methods by exposing parameters directly.
• Performance: While initial prototypes show no significant performance gain, the reduced number of function calls may still reduce potential overhead.

---

Backward Compatibility

• Existing behavior is preserved by ensuring plural methods accept the new parameters with the same default values as they implicitly assume today.
• No breaking changes are expected for current user code.

[Jota-Ve]

• I've diagnosed this situation myself and came up with an improvement, and then I used Edge Copilot to help me translate and formalize the issue description.