pykwet 0.1.1

Python implementation of the Kwet rule-based generator originally written in Perl by Paul Hoffman

pyKwet

pyKwet is a Python implementation inspired by the original Kwet system written in Perl by Paul Hoffman.

The original project, available at: https://sourceforge.net/projects/kwet/ is distributed under the GNU General Public License (GPLv2).

This package is an independent reimplementation and does not include any code from the original distribution.

All credit for the original design and concept goes to Paul Hoffman.

What the package provides

The package can:

• load one or more .kwet rule files by path
• read rule-set metadata from the file
• report the rule-set name, description, theme, allowed public variables, and default variable
• generate output from any selected rule/variable
• accept a seed for repeatable output
• generate a fixed number of results
• sort results alphabetically
• optionally generate structured records containing several variables
• install locally for development

Examples and Demos

A large collection of example .kwet rule files and demo scripts can be downloaded from the project repository or source distribution.

Note: when installed via pip, you will need to provide your own .kwet rule files or download the examples from the project repository.

Run the GUI demo with:

python demos/PyKwetDemo.py

Rule-file metadata

A rule file may include metadata lines like these:

_name = Russian Names
_description = Russian patronymic name generator
_theme = Russian
_allowed = word BOYNAME GIRLNAME

_allowed is a space-separated list of public rules/variables. The first item is always treated as the default variable.

If _allowed is omitted, all rule names are exposed, and the first rule encountered becomes the default.

Installation for local use

From inside the package directory:

python -m pip install -e .

The -e flag installs in editable/development mode, so changes to the source files take effect without reinstalling.

You do not need to upload the package to PyPI to use it locally.

Command-line demo usage

After installation, the command is:

pykwet your_rules.kwet

Generate ten default results:

pykwet -n 10 your_rules.kwet

Generate from a selected variable:

pykwet -n 10 -s firstname your_rules.kwet

Use a repeatable seed:

pykwet -n 10 -S 12345 your_rules.kwet

Decimal integer seeds are recommended. Python also accepts strings as seeds, but decimal integers are simplest to reproduce across CLI and code.

Sort generated output alphabetically:

pykwet -n 20 -Z your_rules.kwet

Show metadata:

pykwet --info your_rules.kwet

Output as JSON:

pykwet -n 5 --json your_rules.kwet

Generate structured records:

pykwet --records BOYNAME GIRLNAME -n 5 --json your_rules.kwet

Sort structured records by one of the generated fields:

pykwet --records BOYNAME LASTNAME -n 20 --sort-by LASTNAME --json your_rules.kwet

NB. Variables here are given as examples, actual file variables will be provided through metadata output.

Python API

Load a rule file

from pykwet import KwetEngine

engine = KwetEngine("your_rules.kwet")

Read metadata

info = engine.info()

print(info.name)
print(info.description)
print(info.theme)
print(info.allowed)
print(info.default_variable)

Generate from the default variable

names = engine.generate(count=10)

for name in names:
    print(name)

Generate from a specific variable

boys = engine.generate(variable="BOYNAME", count=10)
girls = engine.generate(variable="GIRLNAME", count=10)

Use a seed

engine = KwetEngine("your_rules.kwet", seed=12345)
print(engine.generate(count=5))

The seed is passed to Python's random.Random. Use a decimal integer such as 12345 for the most straightforward repeatability.

You can reseed an existing engine:

engine.reseed(12345)

Sort output

names = engine.generate(count=20, sort=True)

Sort using another generated rule as the sort key

results = engine.generate(
    variable="word",
    count=20,
    sort=True,
    sort_by="BOYNAME",
    as_results=True,
)

for result in results:
    print(result.sort_key, "=>", result.text)

Generate structured records

records = engine.generate_records(
    ["BOYNAME", "GIRLNAME"],
    count=10,
    sort_by="GIRLNAME",
)

for row in records:
    print(row["BOYNAME"], row["GIRLNAME"])

One-shot helper

from pykwet import generate

items = generate(
    "your_rules.kwet",
    variable="BOYNAME",
    count=10,
    seed=12345,
    sort=True,
)

Returned data design

The package supports three return styles.

Plain list of strings

engine.generate(count=3)

Result objects

engine.generate(count=3, as_results=True)

Returns a list of KwetResult objects:

KwetResult(text="...", variable="word", sort_key="...")

Structured dictionaries

engine.generate_records(["BOYNAME", "GIRLNAME"], count=3)

Building a distributable package

Install the build tool:

python -m pip install build

Build source and wheel distributions:

python -m build

This creates files in dist/, for example:

dist/pykwet-0.1.0.tar.gz
dist/pykwet-0.1.0-py3-none-any.whl

Uploading later

You only need PyPI if you want other people to install it with:

python -m pip install pykwet

For private/local use, editable install is enough.

If you later decide to publish:

python -m pip install twine
python -m twine upload dist/*

Project layout

pykwet/
├── demos
│   ├── pyKwet
│   └── PyKwetDemo.py
├── examples
│   └── *.kwet
├── LICENSE
├── pyproject.toml
├── README.md
└── src
    └── pykwet
        ├── cli.py
        ├── engine.py
        └── __init__.py

Notes on compatibility

The CLI keeps the familiar options:

• -n, --count
• -s, --start, --variable
• -S, --seed
• -Z, --sort
• -d, --debug

The old hidden -b compatibility option is still accepted, but not advertised.

The removed -D option is not used.