WordSiv is a Python library for generating text for an incomplete typeface.
+ + + + + + +Classes:
+| Name | +Description | +
|---|---|
Vocab |
+
+
+
+ A vocabulary of words and occurrence counts with metadata for filtering and punctuating. + |
+
WordSiv |
+
+
+
+ The main WordSiv object which uses Vocabs to generate text. + |
+
Attributes:
+| Name | +Type | +Description | +
|---|---|---|
CaseType |
+ + | +
+
+
+ Options for setting case via the |
+
module-attribute
+
+
+CaseType = Literal[
+ "any",
+ "any_og",
+ "lc",
+ "lc_force",
+ "cap",
+ "cap_og",
+ "cap_force",
+ "uc",
+ "uc_og",
+ "uc_force",
+]
+Options for setting case via the case argument.
+See Letter Case in the Guide for detailed descriptions and examples of each
+option
A vocabulary of words and occurrence counts with metadata for filtering and punctuating.
+ + +Attributes:
+| Name | +Type | +Description | +
|---|---|---|
lang |
+
+ str
+ |
+
+
+
+ The language of the vocabulary. + |
+
bicameral |
+
+ bool
+ |
+
+
+
+ Specifies whether the vocabulary has uppercase and lowercase letters. + |
+
punctuation |
+
+ dict
+ |
+
+
+
+ A dictionary or None for handling punctuation in generated text. + |
+
data |
+
+ str
+ |
+
+
+
+ A TSV-formatted string with word-count pairs or a newline-delimited list of words. + |
+
data_file |
+
+ str | Traversable
+ |
+
+
+
+ A path to a file to supply the data instead of the data attribute. + |
+
meta |
+
+ dict
+ |
+
+
+
+ Additional metadata for the vocabulary. + |
+
Methods:
+| Name | +Description | +
|---|---|
__init__ |
+
+
+
+ Initializes the Vocab instance. + |
+
Attributes:
+| Name | +Type | +Description | +
|---|---|---|
data |
+ + | +
+
+
+ Returns raw data from parameter _data or data_file. + |
+
wordcount |
+
+ tuple[tuple[str, int], ...]
+ |
+
+
+
+ Returns a tuple of tuples with words and counts. + |
+
wordcount_str |
+
+ str
+ |
+
+
+
+ Returns a TSV-formatted string with words and counts. + |
+
wordsiv/_vocab.py17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 | |
property
+
+
+Returns raw data from parameter _data or data_file.
+property
+
+
+Returns a tuple of tuples with words and counts.
+property
+
+
+Returns a TSV-formatted string with words and counts.
+Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ lang
+ |
+
+ str
+ |
+
+
+
+ The language of the vocabulary. + |
+ + required + | +
+ bicameral
+ |
+
+ bool
+ |
+
+
+
+ Specifies whether the vocabulary has uppercase and lowercase letters. + |
+ + required + | +
+ punctuation
+ |
+
+ dict
+ |
+
+
+
+ A dictionary or None for handling punctuation in generated text. + |
+
+ None
+ |
+
+ data
+ |
+
+ str
+ |
+
+
+
+ A TSV-formatted string with word-count pairs or a newline-delimited list of words. + |
+
+ None
+ |
+
+ data_file
+ |
+
+ str | Traversable
+ |
+
+
+
+ A path to a file to supply the data instead of the data attribute. + |
+
+ None
+ |
+
+ meta
+ |
+
+ dict
+ |
+
+
+
+ Additional metadata for the vocabulary. + |
+
+ None
+ |
+
wordsiv/_vocab.pyThe main WordSiv object which uses Vocabs to generate text.
+This object serves as the main interface for generating text. It can hold multiple +vocabulary objects, store default settings (like default glyphs and vocab), and +expose high-level methods that produce words, sentences, paragraphs, and more.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ vocab
+ |
+
+ str | None
+ |
+
+
+
+ The name of the default Vocab. + |
+
+ None
+ |
+
+ glyphs
+ |
+
+ str | None
+ |
+
+
+
+ The default set of glyphs that constrains the words +generated. + |
+
+ None
+ |
+
+ add_default_vocabs
+ |
+
+ bool
+ |
+
+
+
+ Whether to add the default Vocabs defined in
+ |
+
+ True
+ |
+
+ raise_errors
+ |
+
+ bool
+ |
+
+
+
+ Whether to raise errors or fail gently. + |
+
+ False
+ |
+
+ seed
+ |
+
+ int | None
+ |
+
+
+
+ Seed for the random number generator. + |
+
+ None
+ |
+
Attributes:
+| Name | +Type | +Description | +
|---|---|---|
vocab |
+
+ str | None
+ |
+
+
+
+ The name of the default Vocab. + |
+
glyphs |
+
+ str | None
+ |
+
+
+
+ The default set of glyphs that constrains the words +generated. + |
+
raise_errors |
+
+ bool
+ |
+
+
+
+ Whether to raise errors or fail gently. + |
+
_vocab_lookup |
+
+ dict[str, Vocab]
+ |
+
+
+
+ A dictionary of vocab names to |
+
_rand |
+
+ Random
+ |
+
+
+
+ A |
+
Methods:
+| Name | +Description | +
|---|---|
add_vocab |
+
+
+
+ Add a |
+
get_vocab |
+
+
+
+ Retrieve a |
+
list_vocabs |
+
+
+
+ Return a list of all available Vocab names. + |
+
number |
+
+
+
+ Generate a random numeric string (made of digits) constrained by glyphs and + |
+
para |
+
+
+
+ Generate a paragraph by creating multiple sentences with |
+
paras |
+
+
+
+ Generate multiple paragraphs with |
+
seed |
+
+
+
+ Seed the random number generator for reproducible results. + |
+
sent |
+
+
+
+ Generate a single sentence, optionally punctuated, using words (and/or numbers). + |
+
sents |
+
+
+
+ Generate multiple sentences with |
+
text |
+
+
+
+ Generate multiple paragraphs of text, calling |
+
top_word |
+
+
+
+ Retrieve the most common (or nth most common) word from the Vocab, subject to + |
+
top_words |
+
+
+
+ Retrieve the top |
+
word |
+
+
+
+ Generate a random word that meets a variety of constraints, such as glyphs, + |
+
words |
+
+
+
+ Generate a list of words (and optionally numbers) according to the specified + |
+
wordsiv/__init__.py109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 | |
Add a Vocab object to this WordSiv instance under a given name.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ vocab_name
+ |
+
+ str
+ |
+
+
+
+ The unique identifier for this Vocab. + |
+ + required + | +
+ vocab
+ |
+
+ Vocab
+ |
+
+
+
+ The |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ None
+ |
+
+
+
+ None + |
+
wordsiv/__init__.pyRetrieve a Vocab by name, or return the default Vocab if vocab_name is None.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ vocab_name
+ |
+
+ str | None
+ |
+
+
+
+ The name of the Vocab to retrieve. If None,
+use the default |
+
+ None
+ |
+
Returns:
+| Name | Type | +Description | +
|---|---|---|
Vocab |
+ Vocab
+ |
+
+
+
+ The |
+
Raises:
+| Type | +Description | +
|---|---|
+ ValueError
+ |
+
+
+
+ If no |
+
wordsiv/__init__.pynumber(
+ seed=None,
+ glyphs=None,
+ wl=None,
+ min_wl=1,
+ max_wl=_DEFAULT_MAX_NUM_LENGTH,
+ raise_errors=False,
+)
+Generate a random numeric string (made of digits) constrained by glyphs and +other parameters.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ seed
+ |
+
+ float | str | None
+ |
+
+
+
+ Seed the random number generator if seed is not +None. + |
+
+ None
+ |
+
+ glyphs
+ |
+
+ str | None
+ |
+
+
+
+ A string of allowed glyphs. If None, uses the default
+glyphs of this |
+
+ None
+ |
+
+ wl
+ |
+
+ int | None
+ |
+
+
+
+ Exact length of the generated numeric string. If None, a
+random length between |
+
+ None
+ |
+
+ min_wl
+ |
+
+ int
+ |
+
+
+
+ Minimum length of the numeric string. Defaults to 1. + |
+
+ 1
+ |
+
+ max_wl
+ |
+
+ int
+ |
+
+
+
+ Maximum length of the numeric string. Defaults to 4. + |
+
+ _DEFAULT_MAX_NUM_LENGTH
+ |
+
+ raise_errors
+ |
+
+ bool
+ |
+
+
+
+ Whether to raise an error if no numerals are available. + |
+
+ False
+ |
+
Returns:
+| Name | Type | +Description | +
|---|---|---|
str |
+ str
+ |
+
+
+
+ A randomly generated string consisting of numerals. + |
+
Raises:
+| Type | +Description | +
|---|---|
+ ValueError
+ |
+
+
+
+ If |
+
+ FilterError
+ |
+
+
+
+ If no numerals are available in |
+
wordsiv/__init__.pyGenerate a paragraph by creating multiple sentences with sents(...) and
+joining them with sent_sep.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ seed
+ |
+
+ float | str | None
+ |
+
+
+
+ Seed the random number generator if seed is not +None. + |
+
+ None
+ |
+
+ sent_sep
+ |
+
+ str
+ |
+
+
+
+ The string used to join sentences.
+**sents_kwargs: Keyword arguments passed to |
+
+ ' '
+ |
+
Returns:
+| Name | Type | +Description | +
|---|---|---|
str |
+ str
+ |
+
+
+
+ A single paragraph containing multiple sentences. + |
+
wordsiv/__init__.pyGenerate multiple paragraphs with para(...), returned as a list.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ seed
+ |
+
+ float | str | None
+ |
+
+
+
+ Seed the random number generator if seed is not +None. + |
+
+ None
+ |
+
+ n_paras
+ |
+
+ int
+ |
+
+
+
+ Number of paragraphs to generate. + |
+
+ 3
+ |
+
+ **para_kwargs
+ |
+ + | +
+
+
+ Additional keyword arguments passed to |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ list[str]
+ |
+
+
+
+ list[str]: A list of paragraphs. + |
+
wordsiv/__init__.pySeed the random number generator for reproducible results.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ seed
+ |
+
+ float | str | None
+ |
+
+
+
+ The seed value used to initialize the random +number generator. + |
+
+ None
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ None
+ |
+
+
+
+ None + |
+
wordsiv/__init__.pyGenerate a single sentence, optionally punctuated, using words (and/or numbers).
+A sentence is created by calling words(...), then (optionally) punctuating the
+resulting list.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ vocab
+ |
+
+ str | None
+ |
+
+
+
+ Name of the Vocab to use. If None, use the default Vocab. + |
+
+ None
+ |
+
+ glyphs
+ |
+
+ str | None
+ |
+
+
+
+ Allowed glyphs. If None, uses default glyphs. + |
+
+ None
+ |
+
+ seed
+ |
+
+ any
+ |
+
+
+
+ Seed for the random number generator. If None, current state is used. + |
+
+ None
+ |
+
+ punc
+ |
+
+ bool
+ |
+
+
+
+ Whether to add punctuation to the sentence. + |
+
+ True
+ |
+
+ rnd_punc
+ |
+
+ float
+ |
+
+
+
+ A randomness factor between 0 and 1 that adjusts the punctuation +frequency or distribution. + |
+
+ 0
+ |
+
+ **words_kwargs
+ |
+ + | +
+
+
+ Additional keyword arguments passed to |
+
+ {}
+ |
+
Returns:
+| Name | Type | +Description | +
|---|---|---|
str |
+ str
+ |
+
+
+
+ A single sentence, optionally with punctuation. + |
+
Raises:
+| Type | +Description | +
|---|---|
+ ValueError
+ |
+
+
+
+ If |
+
wordsiv/__init__.py679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 | |
Generate multiple sentences with sent(...), returned as a list.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ seed
+ |
+
+ float | str | None
+ |
+
+
+
+ Seed the random number generator if seed is not +None. + |
+
+ None
+ |
+
+ min_n_sents
+ |
+
+ int
+ |
+
+
+
+ Minimum number of sentences to produce if |
+
+ 3
+ |
+
+ max_n_sents
+ |
+
+ int
+ |
+
+
+
+ Maximum number of sentences to produce if |
+
+ 5
+ |
+
+ n_sents
+ |
+
+ int | None
+ |
+
+
+
+ If specified, exactly that many sentences are produced. + |
+
+ None
+ |
+
+ **sent_kwargs
+ |
+ + | +
+
+
+ Additional keyword arguments passed to |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ list[str]
+ |
+
+
+
+ list[str]: A list of generated sentences. + |
+
wordsiv/__init__.pyGenerate multiple paragraphs of text, calling paras(...) and joining them with
+para_sep.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ seed
+ |
+
+ float | str | None
+ |
+
+
+
+ Seed the random number generator if seed is not +None. + |
+
+ None
+ |
+
+ para_sep
+ |
+
+ str
+ |
+
+
+
+ The string used to separate paragraphs in the final text. + |
+
+ '\n\n'
+ |
+
+ **paras_kwargs
+ |
+ + | +
+
+
+ Additional keyword arguments passed to |
+
+ {}
+ |
+
Returns:
+| Name | Type | +Description | +
|---|---|---|
str |
+ str
+ |
+
+
+
+ A string containing multiple paragraphs of text, separated by
+ |
+
wordsiv/__init__.pytop_word(
+ vocab=None,
+ glyphs=None,
+ seed=None,
+ idx=0,
+ case="any",
+ min_wl=2,
+ max_wl=None,
+ wl=None,
+ contains=None,
+ inner=None,
+ startswith=None,
+ endswith=None,
+ regexp=None,
+ raise_errors=False,
+)
+Retrieve the most common (or nth most common) word from the Vocab, subject to +filtering constraints.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ vocab
+ |
+
+ str | None
+ |
+
+
+
+ Name of the Vocab to use. If None, use the default +Vocab. + |
+
+ None
+ |
+
+ glyphs
+ |
+
+ str | None
+ |
+
+
+
+ Whitelisted glyphs to filter words. If None, uses +default. + |
+
+ None
+ |
+
+ seed
+ |
+
+ float | str | None
+ |
+
+
+
+ Seed the random number generator if seed is +not None. + |
+
+ None
+ |
+
+ idx
+ |
+
+ int
+ |
+
+
+
+ Index of the desired word in the frequency-sorted list +(0-based). + |
+
+ 0
+ |
+
+ case
+ |
+
+ CaseType
+ |
+
+
+
+ Desired case form for the word (e.g., 'lower', 'upper', +'any'). + |
+
+ 'any'
+ |
+
+ min_wl
+ |
+
+ int
+ |
+
+
+
+ Minimum word length. + |
+
+ 2
+ |
+
+ max_wl
+ |
+
+ int | None
+ |
+
+
+
+ Maximum word length. If None, no maximum. + |
+
+ None
+ |
+
+ wl
+ |
+
+ int | None
+ |
+
+
+
+ Exact word length. If None, no exact length filter. + |
+
+ None
+ |
+
+ contains
+ |
+
+ str | Sequence[str] | None
+ |
+
+
+
+ Substring(s) that must appear in +the word. + |
+
+ None
+ |
+
+ inner
+ |
+
+ str | Sequence[str] | None
+ |
+
+
+
+ Substring(s) that must appear in the +interior. + |
+
+ None
+ |
+
+ startswith
+ |
+
+ str | None
+ |
+
+
+
+ Substring that the word must start with. + |
+
+ None
+ |
+
+ endswith
+ |
+
+ str | None
+ |
+
+
+
+ Substring that the word must end with. + |
+
+ None
+ |
+
+ regexp
+ |
+
+ str | None
+ |
+
+
+
+ Regex pattern that the word must match. + |
+
+ None
+ |
+
+ raise_errors
+ |
+
+ bool
+ |
+
+
+
+ Whether to raise errors on filter or index failures. + |
+
+ False
+ |
+
Returns:
+| Name | Type | +Description | +
|---|---|---|
str |
+ str
+ |
+
+
+
+ The nth most common word that meets the constraints (or an empty string
+on failure if |
+
Raises:
+| Type | +Description | +
|---|---|
+ FilterError
+ |
+
+
+
+ If filtering fails (no words match) and |
+
+ ValueError
+ |
+
+
+
+ If no default vocab is set when |
+
+ IndexError
+ |
+
+
+
+ If |
+
wordsiv/__init__.py379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 | |
top_words(
+ glyphs=None,
+ vocab=None,
+ n_words=10,
+ idx=0,
+ case="any",
+ min_wl=1,
+ max_wl=None,
+ wl=None,
+ contains=None,
+ inner=None,
+ startswith=None,
+ endswith=None,
+ regexp=None,
+ raise_errors=False,
+)
+Retrieve the top n_words from the Vocab, starting at index idx, subject to
+filtering constraints.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ glyphs
+ |
+
+ str | None
+ |
+
+
+
+ Allowed glyph set. If None, uses default glyphs. + |
+
+ None
+ |
+
+ vocab
+ |
+
+ str | None
+ |
+
+
+
+ Name of the Vocab to use. If None, use the default +Vocab. + |
+
+ None
+ |
+
+ n_words
+ |
+
+ int
+ |
+
+
+
+ Number of words to return. + |
+
+ 10
+ |
+
+ idx
+ |
+
+ int
+ |
+
+
+
+ The index at which to start returning words (0-based). + |
+
+ 0
+ |
+
+ case
+ |
+
+ CaseType
+ |
+
+
+
+ Desired case form ("any", "upper", "lower", etc.). + |
+
+ 'any'
+ |
+
+ min_wl
+ |
+
+ int
+ |
+
+
+
+ Minimum word length. Defaults to 1. + |
+
+ 1
+ |
+
+ max_wl
+ |
+
+ int | None
+ |
+
+
+
+ Maximum word length. If None, no maximum is applied. + |
+
+ None
+ |
+
+ wl
+ |
+
+ int | None
+ |
+
+
+
+ Exact word length. If None, no exact length filter. + |
+
+ None
+ |
+
+ contains
+ |
+
+ str | Sequence[str] | None
+ |
+
+
+
+ Substring(s) that must appear. + |
+
+ None
+ |
+
+ inner
+ |
+
+ str | Sequence[str] | None
+ |
+
+
+
+ Substring(s) that must appear, not at +edges. + |
+
+ None
+ |
+
+ startswith
+ |
+
+ str | None
+ |
+
+
+
+ Required starting substring. + |
+
+ None
+ |
+
+ endswith
+ |
+
+ str | None
+ |
+
+
+
+ Required ending substring. + |
+
+ None
+ |
+
+ regexp
+ |
+
+ str | None
+ |
+
+
+
+ Regex pattern(s) to match. + |
+
+ None
+ |
+
+ raise_errors
+ |
+
+ bool
+ |
+
+
+
+ Whether to raise errors or fail gently. + |
+
+ False
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ list[str]
+ |
+
+
+
+ list[str]: A list of up to |
+
Raises:
+| Type | +Description | +
|---|---|
+ FilterError
+ |
+
+
+
+ If filtering fails (no words match) and |
+
wordsiv/__init__.py602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 | |
word(
+ vocab=None,
+ glyphs=None,
+ seed=None,
+ rnd=0,
+ case="any",
+ top_k=0,
+ min_wl=1,
+ max_wl=None,
+ wl=None,
+ contains=None,
+ inner=None,
+ startswith=None,
+ endswith=None,
+ regexp=None,
+ raise_errors=False,
+)
+Generate a random word that meets a variety of constraints, such as glyphs, +length, regex filters, etc.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ vocab
+ |
+
+ str | None
+ |
+
+
+
+ Name of the Vocab to use. If None, uses default Vocab. + |
+
+ None
+ |
+
+ glyphs
+ |
+
+ str | None
+ |
+
+
+
+ A string of allowed glyphs. If None, uses default +glyphs. + |
+
+ None
+ |
+
+ seed
+ |
+
+ float | str | None
+ |
+
+
+
+ Seed the random number generator if seed is not +None. + |
+
+ None
+ |
+
+ rnd
+ |
+
+ float
+ |
+
+
+
+ Randomness factor in [0, 1] for selecting among the top words. + |
+
+ 0
+ |
+
+ case
+ |
+
+ CaseType
+ |
+
+
+
+ Desired case of the output word (e.g., 'upper', 'lower', +'any'). + |
+
+ 'any'
+ |
+
+ top_k
+ |
+
+ int
+ |
+
+
+
+ If > 0, only consider the top K words by frequency. + |
+
+ 0
+ |
+
+ min_wl
+ |
+
+ int
+ |
+
+
+
+ Minimum word length. + |
+
+ 1
+ |
+
+ max_wl
+ |
+
+ int | None
+ |
+
+
+
+ Maximum word length. If None, no maximum is applied. + |
+
+ None
+ |
+
+ wl
+ |
+
+ int | None
+ |
+
+
+
+ Exact word length. If None, no exact length is enforced. + |
+
+ None
+ |
+
+ contains
+ |
+
+ str | Sequence[str] | None
+ |
+
+
+
+ Substring(s) that must appear in the +word. + |
+
+ None
+ |
+
+ inner
+ |
+
+ str | Sequence[str] | None
+ |
+
+
+
+ Substring(s) that must appear, but not +at the start or end of the word. + |
+
+ None
+ |
+
+ startswith
+ |
+
+ str | None
+ |
+
+
+
+ Required starting substring. + |
+
+ None
+ |
+
+ endswith
+ |
+
+ str | None
+ |
+
+
+
+ Required ending substring. + |
+
+ None
+ |
+
+ regexp
+ |
+
+ str | None
+ |
+
+
+
+ A regular expression that the word must match. + |
+
+ None
+ |
+
+ raise_errors
+ |
+
+ bool
+ |
+
+
+
+ Whether to raise filtering errors or fail gently. + |
+
+ False
+ |
+
Returns:
+| Name | Type | +Description | +
|---|---|---|
str |
+ str
+ |
+
+
+
+ A randomly generated word meeting the specified constraints (or an
+empty string on failure if |
+
Raises:
+| Type | +Description | +
|---|---|
+ ValueError
+ |
+
+
+
+ If |
+
+ FilterError
+ |
+
+
+
+ If filtering yields no results and |
+
+ VocabFormatError
+ |
+
+
+
+ If the underlying Vocab data is malformed. + |
+
+ VocabEmptyError
+ |
+
+
+
+ If the underlying Vocab is empty. + |
+
wordsiv/__init__.py290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 | |
words(
+ vocab=None,
+ glyphs=None,
+ seed=None,
+ n_words=None,
+ min_n_words=10,
+ max_n_words=20,
+ numbers=0,
+ cap_first=None,
+ case="any",
+ rnd=0,
+ min_wl=1,
+ max_wl=None,
+ wl=None,
+ raise_errors=False,
+ **word_kwargs,
+)
+Generate a list of words (and optionally numbers) according to the specified +parameters.
+This method will produce n_words tokens, each of which may be a word or a
+number (digit string), depending on the numbers ratio. It can also
+automatically handle capitalization of the first token if cap_first is True
+(or inferred).
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
+ vocab
+ |
+
+ str | None
+ |
+
+
+
+ Name of the Vocab to use. If None, uses the default +Vocab. + |
+
+ None
+ |
+
+ glyphs
+ |
+
+ str | None
+ |
+
+
+
+ Allowed glyph set. If None, uses the default glyphs. + |
+
+ None
+ |
+
+ seed
+ |
+
+ any
+ |
+
+
+
+ Seed for the random number generator. If None, current state is +used. + |
+
+ None
+ |
+
+ n_words
+ |
+
+ int | None
+ |
+
+
+
+ Exact number of tokens to generate. If None, randomly
+choose between |
+
+ None
+ |
+
+ min_n_words
+ |
+
+ int
+ |
+
+
+
+ Minimum number of tokens if |
+
+ 10
+ |
+
+ max_n_words
+ |
+
+ int
+ |
+
+
+
+ Maximum number of tokens if |
+
+ 20
+ |
+
+ numbers
+ |
+
+ float
+ |
+
+
+
+ A value in [0, 1] that determines the probability of +generating a numeric token instead of a word. + |
+
+ 0
+ |
+
+ cap_first
+ |
+
+ bool | None
+ |
+
+
+
+ If True, capitalize the first word (if |
+
+ None
+ |
+
+ case
+ |
+
+ CaseType
+ |
+
+
+
+ Desired case form for the words ("any", "lower", "upper", +etc.). + |
+
+ 'any'
+ |
+
+ rnd
+ |
+
+ float
+ |
+
+
+
+ Randomness factor for word selection, in [0, 1]. + |
+
+ 0
+ |
+
+ min_wl
+ |
+
+ int
+ |
+
+
+
+ Minimum length for words/numbers. + |
+
+ 1
+ |
+
+ max_wl
+ |
+
+ int
+ |
+
+
+
+ Maximum length for words/numbers. + |
+
+ None
+ |
+
+ wl
+ |
+
+ int | None
+ |
+
+
+
+ Exact length for words/numbers. If None, uses min/max_wl. + |
+
+ None
+ |
+
+ raise_errors
+ |
+
+ bool
+ |
+
+
+
+ Whether to raise errors or fail gently. + |
+
+ False
+ |
+
+ **word_kwargs
+ |
+ + | +
+
+
+ Additional keyword arguments passed along to |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ list[str]
+ |
+
+
+
+ list[str]: A list of randomly generated tokens (words or numbers). + |
+
Raises:
+| Type | +Description | +
|---|---|
+ ValueError
+ |
+
+
+
+ If |
+
wordsiv/__init__.py466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 | |