Metadata-Version: 2.4
Name: pykwet
Version: 0.1.1
Summary: Python implementation of the Kwet rule-based generator originally written in Perl by Paul Hoffman
Author: Jonathan S. Farley
License: MIT
Keywords: text generation,random,rules,kwet
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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:
```bash
python demos/PyKwetDemo.py
```

## Rule-file metadata

A rule file may include metadata lines like these:

```text
_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:

```bash
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:

```bash
pykwet your_rules.kwet
```

Generate ten default results:

```bash
pykwet -n 10 your_rules.kwet
```

Generate from a selected variable:

```bash
pykwet -n 10 -s firstname your_rules.kwet
```

Use a repeatable seed:

```bash
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:

```bash
pykwet -n 20 -Z your_rules.kwet
```

Show metadata:

```bash
pykwet --info your_rules.kwet
```

Output as JSON:

```bash
pykwet -n 5 --json your_rules.kwet
```

Generate structured records:

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

Sort structured records by one of the generated fields:

```bash
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

```python
from pykwet import KwetEngine

engine = KwetEngine("your_rules.kwet")
```

### Read metadata

```python
info = engine.info()

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

### Generate from the default variable

```python
names = engine.generate(count=10)

for name in names:
    print(name)
```

### Generate from a specific variable

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

### Use a seed

```python
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:

```python
engine.reseed(12345)
```

### Sort output

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

### Sort using another generated rule as the sort key

```python
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

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

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

### One-shot helper

```python
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

```python
engine.generate(count=3)
```

### Result objects

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

Returns a list of `KwetResult` objects:

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

### Structured dictionaries

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

## Building a distributable package

Install the build tool:

```bash
python -m pip install build
```

Build source and wheel distributions:

```bash
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:

```bash
python -m pip install pykwet
```

For private/local use, editable install is enough.

If you later decide to publish:

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

## Project layout

```text
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.
