Coverage for /var/srv/projects/api.amasfac.comuna18.com/tmp/venv/lib/python3.9/site-packages/faker/providers/lorem/__init__.py: 41%
74 statements
« prev ^ index » next coverage.py v6.4.4, created at 2023-07-17 14:22 -0600
1from typing import List, Optional, Sequence, cast
3from .. import BaseProvider
5localized = True
7# 'Latin' is the default locale
8default_locale = "la"
11class Provider(BaseProvider):
12 """Implement default lorem provider for Faker.
14 .. important::
15 The default locale of the lorem provider is ``la``. When using a locale
16 without a localized lorem provider, the ``la`` lorem provider will be
17 used, so generated words will be in pseudo-Latin. The locale used for
18 the standard provider docs was ``en_US``, and ``en_US`` has a localized
19 lorem provider which is why the samples here show words in American
20 English.
21 """
23 word_connector = " "
24 sentence_punctuation = "."
26 def words(
27 self,
28 nb: int = 3,
29 part_of_speech: Optional[str] = None,
30 ext_word_list: Optional[Sequence[str]] = None,
31 unique: bool = False,
32 ) -> List[str]:
33 """Generate a tuple of words.
35 The ``nb`` argument controls the number of words in the resulting list,
36 and if ``ext_word_list`` is provided, words from that list will be used
37 instead of those from the locale provider's built-in word list.
39 If ``unique`` is ``True``, this method will return a list containing
40 unique words. Under the hood, |random_sample| will be used for sampling
41 without replacement. If ``unique`` is ``False``, |random_choices| is
42 used instead, and the list returned may contain duplicates.
44 ``part_of_speech`` is a parameter that defines to what part of speech
45 the returned word belongs. If ``ext_word_list`` is not ``None``, then
46 ``part_of_speech`` is ignored. If the value of ``part_of_speech`` does
47 not correspond to an existent part of speech according to the set locale,
48 then an exception is raised.
50 .. warning::
51 Depending on the length of a locale provider's built-in word list or
52 on the length of ``ext_word_list`` if provided, a large ``nb`` can
53 exhaust said lists if ``unique`` is ``True``, raising an exception.
55 :sample:
56 :sample: nb=5
57 :sample: nb=5, ext_word_list=['abc', 'def', 'ghi', 'jkl']
58 :sample: nb=4, ext_word_list=['abc', 'def', 'ghi', 'jkl'], unique=True
59 """
60 if ext_word_list is not None: 60 ↛ 61line 60 didn't jump to line 61, because the condition on line 60 was never true
61 word_list = ext_word_list
62 elif part_of_speech: 62 ↛ 63line 62 didn't jump to line 63, because the condition on line 62 was never true
63 if part_of_speech not in self.parts_of_speech: # type: ignore[attr-defined]
64 raise ValueError(f"{part_of_speech} is not recognized as a part of speech.")
65 else:
66 word_list = self.parts_of_speech[part_of_speech] # type: ignore[attr-defined]
67 else:
68 word_list = self.word_list # type: ignore[attr-defined]
70 if unique: 70 ↛ 71line 70 didn't jump to line 71, because the condition on line 70 was never true
71 unique_samples = cast(List[str], self.random_sample(word_list, length=nb))
72 return unique_samples
73 samples = cast(List[str], self.random_choices(word_list, length=nb))
74 return samples
76 def word(self, part_of_speech: Optional[str] = None, ext_word_list: Optional[Sequence[str]] = None) -> str:
77 """Generate a word.
79 This method uses |words| under the hood with the ``nb`` argument set to
80 ``1`` to generate the result.
82 :sample:
83 :sample: ext_word_list=['abc', 'def', 'ghi', 'jkl']
84 """
85 return self.words(1, part_of_speech, ext_word_list)[0]
87 def sentence(
88 self, nb_words: int = 6, variable_nb_words: bool = True, ext_word_list: Optional[Sequence[str]] = None
89 ) -> str:
90 """Generate a sentence.
92 The ``nb_words`` argument controls how many words the sentence will
93 contain, and setting ``variable_nb_words`` to ``False`` will generate
94 the exact amount, while setting it to ``True`` (default) will generate
95 a random amount (+/-40%, minimum of 1) using |randomize_nb_elements|.
97 Under the hood, |words| is used to generate the words, so the argument
98 ``ext_word_list`` works in the same way here as it would in that method.
100 :sample: nb_words=10
101 :sample: nb_words=10, variable_nb_words=False
102 :sample: nb_words=10, ext_word_list=['abc', 'def', 'ghi', 'jkl']
103 :sample: nb_words=10, variable_nb_words=True,
104 ext_word_list=['abc', 'def', 'ghi', 'jkl']
105 """
106 if nb_words <= 0:
107 return ""
109 if variable_nb_words:
110 nb_words = self.randomize_nb_elements(nb_words, min=1)
112 words = list(self.words(nb=nb_words, ext_word_list=ext_word_list))
113 words[0] = words[0].title()
115 return self.word_connector.join(words) + self.sentence_punctuation
117 def sentences(self, nb: int = 3, ext_word_list: Optional[Sequence[str]] = None) -> List[str]:
118 """Generate a list of sentences.
120 This method uses |sentence| under the hood to generate sentences, and
121 the ``nb`` argument controls exactly how many sentences the list will
122 contain. The ``ext_word_list`` argument works in exactly the same way
123 as well.
125 :sample:
126 :sample: nb=5
127 :sample: nb=5, ext_word_list=['abc', 'def', 'ghi', 'jkl']
128 """
129 return [self.sentence(ext_word_list=ext_word_list) for _ in range(0, nb)]
131 def paragraph(
132 self, nb_sentences: int = 3, variable_nb_sentences: bool = True, ext_word_list: Optional[Sequence[str]] = None
133 ) -> str:
134 """Generate a paragraph.
136 The ``nb_sentences`` argument controls how many sentences the paragraph
137 will contain, and setting ``variable_nb_sentences`` to ``False`` will
138 generate the exact amount, while setting it to ``True`` (default) will
139 generate a random amount (+/-40%, minimum of 1) using
140 |randomize_nb_elements|.
142 Under the hood, |sentences| is used to generate the sentences, so the
143 argument ``ext_word_list`` works in the same way here as it would in
144 that method.
146 :sample: nb_sentences=5
147 :sample: nb_sentences=5, variable_nb_sentences=False
148 :sample: nb_sentences=5, ext_word_list=['abc', 'def', 'ghi', 'jkl']
149 :sample: nb_sentences=5, variable_nb_sentences=False,
150 ext_word_list=['abc', 'def', 'ghi', 'jkl']
151 """
152 if nb_sentences <= 0:
153 return ""
155 if variable_nb_sentences:
156 nb_sentences = self.randomize_nb_elements(nb_sentences, min=1)
158 para = self.word_connector.join(self.sentences(nb_sentences, ext_word_list=ext_word_list))
160 return para
162 def paragraphs(self, nb: int = 3, ext_word_list: Optional[Sequence[str]] = None) -> List[str]:
163 """Generate a list of paragraphs.
165 This method uses |paragraph| under the hood to generate paragraphs, and
166 the ``nb`` argument controls exactly how many sentences the list will
167 contain. The ``ext_word_list`` argument works in exactly the same way
168 as well.
170 :sample: nb=5
171 :sample: nb=5, ext_word_list=['abc', 'def', 'ghi', 'jkl']
172 """
173 return [self.paragraph(ext_word_list=ext_word_list) for _ in range(0, nb)]
175 def text(self, max_nb_chars: int = 200, ext_word_list: Optional[Sequence[str]] = None) -> str:
176 """Generate a text string.
178 The ``max_nb_chars`` argument controls the approximate number of
179 characters the text string will have, and depending on its value, this
180 method may use either |words|, |sentences|, or |paragraphs| for text
181 generation. The ``ext_word_list`` argument works in exactly the same way
182 it would in any of those methods.
184 :sample: max_nb_chars=20
185 :sample: max_nb_chars=80
186 :sample: max_nb_chars=160
187 :sample: ext_word_list=['abc', 'def', 'ghi', 'jkl']
188 """
189 text: List[str] = []
190 if max_nb_chars < 5: 190 ↛ 191line 190 didn't jump to line 191, because the condition on line 190 was never true
191 raise ValueError("text() can only generate text of at least 5 characters")
193 if max_nb_chars < 25: 193 ↛ 207line 193 didn't jump to line 207, because the condition on line 193 was never false
194 # join words
195 while not text:
196 size = 0
197 # determine how many words are needed to reach the $max_nb_chars
198 # once;
199 while size < max_nb_chars:
200 word = (self.word_connector if size else "") + self.word(ext_word_list=ext_word_list)
201 text.append(word)
202 size += len(word)
203 text.pop()
204 text[0] = text[0][0].upper() + text[0][1:]
205 last_index = len(text) - 1
206 text[last_index] += self.sentence_punctuation
207 elif max_nb_chars < 100:
208 # join sentences
209 while not text:
210 size = 0
211 # determine how many sentences are needed to reach the
212 # $max_nb_chars once
213 while size < max_nb_chars:
214 sentence = (self.word_connector if size else "") + self.sentence(ext_word_list=ext_word_list)
215 text.append(sentence)
216 size += len(sentence)
217 text.pop()
218 else:
219 # join paragraphs
220 while not text:
221 size = 0
222 # determine how many paragraphs are needed to reach the
223 # $max_nb_chars once
224 while size < max_nb_chars:
225 paragraph = ("\n" if size else "") + self.paragraph(ext_word_list=ext_word_list)
226 text.append(paragraph)
227 size += len(paragraph)
228 text.pop()
230 return "".join(text)
232 def texts(
233 self, nb_texts: int = 3, max_nb_chars: int = 200, ext_word_list: Optional[Sequence[str]] = None
234 ) -> List[str]:
235 """Generate a list of text strings.
237 The ``nb_texts`` argument controls how many text strings the list will
238 contain, and this method uses |text| under the hood for text generation,
239 so the two remaining arguments, ``max_nb_chars`` and ``ext_word_list``
240 will work in exactly the same way as well.
242 :sample: nb_texts=5
243 :sample: nb_texts=5, max_nb_chars=50
244 :sample: nb_texts=5, max_nb_chars=50,
245 ext_word_list=['abc', 'def', 'ghi', 'jkl']
246 """
247 return [self.text(max_nb_chars, ext_word_list) for _ in range(0, nb_texts)]