wildling 2.0.1__tar.gz

wildling-2.0.1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: wildling
+Version: 2.0.1
+Summary: Pattern based string generator library and CLI
+License: MIT
+Project-URL: Repository, https://github.com/dotmonk/wildling
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# wildling
+
+Python library and CLI for pattern-based string generation. **Zero third-party dependencies** (stdlib only). Requires Python 3.9+.
+
+<!-- wildling:preamble -->
+**Docs:** [Website](https://dotmonk.github.io/wildling/) · [Sandbox](https://dotmonk.github.io/wildling/sandbox.html) · [Syntax](https://dotmonk.github.io/wildling/syntax.html) · [Source](https://github.com/dotmonk/wildling/tree/main/python)
+
+**Registry:** [PyPI](https://pypi.org/project/wildling/)
+
+## Example
+
+```text
+http://${'dev,stage,prod'}\-${'api,web'}#{0-2}.example.${'com,net,org'}/@.html
+```
+
+(The `\-` is a literal hyphen; bare `-` would mean “one letter or digit”. `@` is one lowercase letter.)
+
+That builds **URL-shaped** candidates: scheme `http://`, then environment × service × optional digits × TLD, then a one-letter path page. Three environments, two services, zero–two digits (`''`, `0`–`9`, `00`–`99`), three TLDs, and `a`–`z` → **51948** strings — the kind of list you generate for fuzzing links or probing staging hosts, not type out.
+
+A few of them:
+
+- `http://dev-api.example.com/a.html` / `http://stage-web.example.com/z.html`
+- `http://dev-api0.example.net/a.html` / `http://prod-web9.example.org/m.html`
+- `http://dev-api00.example.com/a.html` / `http://prod-web99.example.org/z.html`
+
+Named dictionaries (`%{'hosts'}`) work the same way when the word lists live in files.
+
+Try it in the [sandbox](https://dotmonk.github.io/wildling/sandbox.html?pattern=http%3A%2F%2F%24%7B%27dev%2Cstage%2Cprod%27%7D%5C-%24%7B%27api%2Cweb%27%7D%23%7B0-2%7D.example.%24%7B%27com%2Cnet%2Corg%27%7D%2F%40.html), or see [pattern syntax](https://dotmonk.github.io/wildling/syntax.html) for length ranges, dictionaries, and escapes.
+<!-- /wildling:preamble -->
+
+## Install
+
+From this repository:
+
+```bash
+cd python
+./build.sh
+# or without Docker:
+cp ../docs/help.txt wildling/help.txt
+```
+
+The CLI is `./bin/wildling`.
+
+**Registry:** `pip install wildling`
+
+**Git:**
+
+```bash
+pip install "git+https://github.com/dotmonk/wildling.git@v2.0.0#subdirectory=python"
+```
+
+## Library
+
+```python
+from wildling import create_wildling
+
+wildling = create_wildling(
+    patterns=["abrakadabra", "Year 19##"],
+    dictionaries={"colors": ["red", "blue"]},
+)
+
+wildling.count()  # 101
+wildling.get(0)   # "abrakadabra"
+
+value = wildling.next()
+while value is not False:
+    print(value)
+    value = wildling.next()
+
+wildling.reset()
+```
+
+### API
+
+| Method | Description |
+|--------|-------------|
+| `next()` | Next combination, or `False` when exhausted |
+| `get(index)` | Combination at `index`, or `False` if out of range |
+| `count()` | Total combinations across all patterns |
+| `index()` | Current position (after `next` calls) |
+| `reset()` | Reset iteration to the start |
+| `generators()` | Per-pattern generators |
+
+## CLI
+
+```bash
+./bin/wildling "Year 19##"
+./bin/wildling --dictionary planets:../dictionaries/planets.txt "%{'planets'}"
+./bin/wildling --template ./config.json
+```
+
+Help text and `--check` output follow [`docs/cli.md`](../docs/cli.md) / [`docs/help.txt`](../docs/help.txt).
+
+## Build
+
+```bash
+./build.sh   # Docker: copy help.txt + byte-compile
+```
+
+Project tests live in `../tests/` and are run with `../test.sh`.

wildling-2.0.1/README.md

@@ -0,0 +1,100 @@
+# wildling
+
+Python library and CLI for pattern-based string generation. **Zero third-party dependencies** (stdlib only). Requires Python 3.9+.
+
+<!-- wildling:preamble -->
+**Docs:** [Website](https://dotmonk.github.io/wildling/) · [Sandbox](https://dotmonk.github.io/wildling/sandbox.html) · [Syntax](https://dotmonk.github.io/wildling/syntax.html) · [Source](https://github.com/dotmonk/wildling/tree/main/python)
+
+**Registry:** [PyPI](https://pypi.org/project/wildling/)
+
+## Example
+
+```text
+http://${'dev,stage,prod'}\-${'api,web'}#{0-2}.example.${'com,net,org'}/@.html
+```
+
+(The `\-` is a literal hyphen; bare `-` would mean “one letter or digit”. `@` is one lowercase letter.)
+
+That builds **URL-shaped** candidates: scheme `http://`, then environment × service × optional digits × TLD, then a one-letter path page. Three environments, two services, zero–two digits (`''`, `0`–`9`, `00`–`99`), three TLDs, and `a`–`z` → **51948** strings — the kind of list you generate for fuzzing links or probing staging hosts, not type out.
+
+A few of them:
+
+- `http://dev-api.example.com/a.html` / `http://stage-web.example.com/z.html`
+- `http://dev-api0.example.net/a.html` / `http://prod-web9.example.org/m.html`
+- `http://dev-api00.example.com/a.html` / `http://prod-web99.example.org/z.html`
+
+Named dictionaries (`%{'hosts'}`) work the same way when the word lists live in files.
+
+Try it in the [sandbox](https://dotmonk.github.io/wildling/sandbox.html?pattern=http%3A%2F%2F%24%7B%27dev%2Cstage%2Cprod%27%7D%5C-%24%7B%27api%2Cweb%27%7D%23%7B0-2%7D.example.%24%7B%27com%2Cnet%2Corg%27%7D%2F%40.html), or see [pattern syntax](https://dotmonk.github.io/wildling/syntax.html) for length ranges, dictionaries, and escapes.
+<!-- /wildling:preamble -->
+
+## Install
+
+From this repository:
+
+```bash
+cd python
+./build.sh
+# or without Docker:
+cp ../docs/help.txt wildling/help.txt
+```
+
+The CLI is `./bin/wildling`.
+
+**Registry:** `pip install wildling`
+
+**Git:**
+
+```bash
+pip install "git+https://github.com/dotmonk/wildling.git@v2.0.0#subdirectory=python"
+```
+
+## Library
+
+```python
+from wildling import create_wildling
+
+wildling = create_wildling(
+    patterns=["abrakadabra", "Year 19##"],
+    dictionaries={"colors": ["red", "blue"]},
+)
+
+wildling.count()  # 101
+wildling.get(0)   # "abrakadabra"
+
+value = wildling.next()
+while value is not False:
+    print(value)
+    value = wildling.next()
+
+wildling.reset()
+```
+
+### API
+
+| Method | Description |
+|--------|-------------|
+| `next()` | Next combination, or `False` when exhausted |
+| `get(index)` | Combination at `index`, or `False` if out of range |
+| `count()` | Total combinations across all patterns |
+| `index()` | Current position (after `next` calls) |
+| `reset()` | Reset iteration to the start |
+| `generators()` | Per-pattern generators |
+
+## CLI
+
+```bash
+./bin/wildling "Year 19##"
+./bin/wildling --dictionary planets:../dictionaries/planets.txt "%{'planets'}"
+./bin/wildling --template ./config.json
+```
+
+Help text and `--check` output follow [`docs/cli.md`](../docs/cli.md) / [`docs/help.txt`](../docs/help.txt).
+
+## Build
+
+```bash
+./build.sh   # Docker: copy help.txt + byte-compile
+```
+
+Project tests live in `../tests/` and are run with `../test.sh`.

wildling-2.0.1/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wildling"
+version = "2.0.1"
+description = "Pattern based string generator library and CLI"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/dotmonk/wildling"
+
+[project.scripts]
+wildling = "wildling.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["wildling*"]
+
+[tool.setuptools.package-data]
+wildling = ["help.txt"]

wildling-2.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wildling-2.0.1/wildling/__init__.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import List, Optional, Union
+
+from .generator import Generator, create_generator
+from .parse_pattern import Dictionaries
+
+__version__ = "2.0.1"
+
+WildlingResult = Union[str, bool]
+
+
+class Wildling:
+    def __init__(
+        self,
+        patterns: List[str],
+        dictionaries: Optional[Dictionaries] = None,
+    ) -> None:
+        self._dictionaries: Dictionaries = dictionaries or {}
+        self._generators = [
+            create_generator(pattern, self._dictionaries) for pattern in patterns
+        ]
+        self._pattern_count = sum(generator.count() for generator in self._generators)
+        self._internal_index = 0
+
+    def index(self) -> int:
+        return self._internal_index
+
+    def count(self) -> int:
+        return self._pattern_count
+
+    def reset(self) -> None:
+        self._internal_index = 0
+
+    def next(self) -> WildlingResult:
+        if self._internal_index == self._pattern_count:
+            return False
+        self._internal_index += 1
+        return self.get(self._internal_index - 1)
+
+    def generators(self) -> List[Generator]:
+        return self._generators
+
+    def get(self, index: int) -> WildlingResult:
+        if index > self._pattern_count - 1 or index < 0:
+            return False
+
+        segment_index = 0
+        for generator in self._generators:
+            pattern_index = index - segment_index
+            if pattern_index < generator.count():
+                return generator.get(pattern_index)
+            segment_index += generator.count()
+        return False
+
+
+def create_wildling(
+    patterns: List[str],
+    dictionaries: Optional[Dictionaries] = None,
+) -> Wildling:
+    return Wildling(patterns, dictionaries)
+
+
+# Alias matching the JavaScript default export name in docs
+createWildling = create_wildling

wildling-2.0.1/wildling/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

wildling-2.0.1/wildling/cli.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple, Union
+
+from . import __version__, create_wildling
+from .generator import Generator
+
+Dictionary = Dict[str, List[str]]
+
+
+@dataclass
+class CliArgs:
+    selects: List[int] = field(default_factory=list)
+    ranges: List[Tuple[int, int]] = field(default_factory=list)
+    check: bool = False
+    dictionaries: Dictionary = field(default_factory=dict)
+    patterns: List[str] = field(default_factory=list)
+    help: bool = False
+    version: bool = False
+
+
+def parse_range(value: str) -> Optional[Tuple[int, int]]:
+    parts = value.split("-", 1)
+    if len(parts) != 2 or not parts[0].isdigit() or not parts[1].isdigit():
+        return None
+    start = int(parts[0])
+    end = int(parts[1])
+    return (start, end) if start <= end else None
+
+
+def load_dictionary_file(path: str) -> List[str]:
+    with open(path, encoding="utf-8") as handle:
+        return [line.strip() for line in handle.read().splitlines() if line.strip()]
+
+
+def apply_dictionary(result: CliArgs, name: str, value: Union[str, List[str]]) -> None:
+    if isinstance(value, list):
+        result.dictionaries[name] = [str(item) for item in value]
+        return
+    if isinstance(value, str) and os.path.exists(value):
+        try:
+            result.dictionaries[name] = load_dictionary_file(value)
+        except OSError:
+            pass
+
+
+def apply_template(result: CliArgs, path: str) -> None:
+    if not os.path.exists(path):
+        print(f"Template file not found: {path}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        with open(path, encoding="utf-8") as handle:
+            template = json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        print(f"Invalid JSON template: {path}", file=sys.stderr)
+        sys.exit(1)
+
+    if not isinstance(template, dict):
+        print(f"Invalid JSON template: {path}", file=sys.stderr)
+        sys.exit(1)
+
+    if template.get("check") is True:
+        result.check = True
+
+    select = template.get("select")
+    if isinstance(select, list):
+        for val in select:
+            try:
+                number = int(val)
+            except (TypeError, ValueError):
+                continue
+            if number >= 0:
+                result.selects.append(number)
+
+    ranges = template.get("range")
+    if isinstance(ranges, list):
+        for range_str in ranges:
+            parsed = parse_range(str(range_str))
+            if parsed is not None:
+                result.ranges.append(parsed)
+
+    dictionaries = template.get("dictionaries")
+    if isinstance(dictionaries, dict):
+        for name, value in dictionaries.items():
+            if isinstance(value, (str, list)):
+                apply_dictionary(result, str(name), value)
+
+    patterns = template.get("patterns")
+    if isinstance(patterns, list):
+        for pattern in patterns:
+            result.patterns.append(str(pattern))
+
+
+def parse_args(args: List[str]) -> CliArgs:
+    result = CliArgs()
+    i = 0
+    while i < len(args):
+        arg = args[i]
+
+        if arg in ("--help", "-h"):
+            result.help = True
+            i += 1
+            continue
+
+        if arg in ("--version", "-v"):
+            result.version = True
+            i += 1
+            continue
+
+        if arg == "--check":
+            result.check = True
+            i += 1
+            continue
+
+        if arg == "--select":
+            i += 1
+            if i >= len(args):
+                break
+            try:
+                val = int(args[i])
+            except ValueError:
+                val = -1
+            if val >= 0:
+                result.selects.append(val)
+            i += 1
+            continue
+
+        if arg == "--range":
+            i += 1
+            if i >= len(args):
+                break
+            parsed = parse_range(args[i])
+            if parsed is not None:
+                result.ranges.append(parsed)
+            i += 1
+            continue
+
+        if arg == "--dictionary":
+            i += 1
+            if i >= len(args):
+                break
+            name, sep, path = args[i].partition(":")
+            if sep and name and path:
+                apply_dictionary(result, name, path)
+            i += 1
+            continue
+
+        if arg == "--template":
+            i += 1
+            if i >= len(args):
+                print("Missing path for --template", file=sys.stderr)
+                sys.exit(1)
+            apply_template(result, args[i])
+            i += 1
+            continue
+
+        result.patterns.append(arg)
+        i += 1
+
+    return result
+
+
+def load_help_text() -> str:
+    here = os.path.dirname(os.path.abspath(__file__))
+    candidates = [
+        os.path.join(here, "help.txt"),
+        os.path.join(here, "..", "..", "docs", "help.txt"),
+    ]
+    for path in candidates:
+        if os.path.exists(path):
+            with open(path, encoding="utf-8") as handle:
+                return handle.read()
+    return "wildling - pattern based string generator\n\nHelp text unavailable.\n"
+
+
+def format_list(values: List[Union[str, int]]) -> str:
+    return "" if not values else " " + " ".join(str(value) for value in values)
+
+
+def format_check_output(args: CliArgs, total: int, generators: List[Generator]) -> str:
+    lines = [
+        f"patterns:{format_list(args.patterns)}",
+        f"dictionaries:{format_list(list(args.dictionaries.keys()))}",
+        f"select:{format_list(args.selects)}",
+        f"range:{format_list([f'{start}-{end}' for start, end in args.ranges])}",
+        f"total: {total}",
+    ]
+    for gen in generators:
+        lines.append(f"generator: {gen.source} {gen.count()}")
+    return "\n".join(lines)
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    args = parse_args(sys.argv[1:] if argv is None else argv)
+
+    if args.help:
+        print(load_help_text().rstrip())
+        sys.exit(0)
+
+    if args.version:
+        print(f"wildling {__version__}")
+        sys.exit(0)
+
+    if not args.patterns:
+        print("No pattern provided. Use --help for usage information.", file=sys.stderr)
+        sys.exit(1)
+
+    wildcard = create_wildling(args.patterns, args.dictionaries)
+
+    if args.check:
+        print(format_check_output(args, wildcard.count(), wildcard.generators()))
+        sys.exit(0)
+
+    if args.selects or args.ranges:
+        oor = False
+        for index in args.selects:
+            value = wildcard.get(index)
+            if value is False:
+                print(f"out of range: {index}", file=sys.stderr)
+                oor = True
+            else:
+                print(value)
+        for start, end in args.ranges:
+            for index in range(start, end + 1):
+                value = wildcard.get(index)
+                if value is False:
+                    print(f"out of range: {index}", file=sys.stderr)
+                    oor = True
+                else:
+                    print(value)
+        sys.exit(1 if oor else 0)
+
+    value = wildcard.next()
+    while value is not False:
+        print(value)
+        value = wildcard.next()
+
+
+if __name__ == "__main__":
+    main()

wildling-2.0.1/wildling/generator.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import List
+
+from .parse_pattern import Dictionaries, parse_pattern
+from .token import Token
+
+
+class Generator:
+    def __init__(self, input_pattern: str, dictionaries: Dictionaries) -> None:
+        self.source = input_pattern
+        self._tokens = parse_pattern(input_pattern, dictionaries)
+        self._count = 1
+        for token in self._tokens:
+            self._count *= token.count()
+
+    def count(self) -> int:
+        return self._count
+
+    def tokens(self) -> List[Token]:
+        return self._tokens
+
+    def get(self, index: int) -> str:
+        if index > self._count - 1 or index < 0:
+            return ""
+
+        string_array: List[str] = []
+        index_with_offset = index
+        for token in self._tokens:
+            string_array.append(token.get(index_with_offset % token.count()))
+            index_with_offset //= token.count()
+        return "".join(string_array)
+
+
+def create_generator(input_pattern: str, dictionaries: Dictionaries) -> Generator:
+    return Generator(input_pattern, dictionaries)

wildling-2.0.1/wildling/help.txt

@@ -0,0 +1,43 @@
+wildling - pattern based string generator
+
+USAGE
+    wildling [options] [pattern ...]
+
+OPTIONS
+    --select #                  Print only combination number # (repeatable)
+    --range #-#                 Print combinations from # to # inclusive (repeatable)
+    --check                     Print generation info instead of results
+    --dictionary <name>:<path>  Load a dictionary file as <name> (repeatable)
+    --template <path>           Load options from a JSON template file
+    --help, -h                  Show this help message
+    --version, -v               Show version
+
+PATTERNS
+    # #{N} #{N-M}               digits 0-9; optional fixed or ranged length
+    @ @{N} @{N-M}               lowercase a-z
+    * *{N} *{N-M}               lowercase a-z and digits 0-9
+    & &{N} &{N-M}               lowercase and uppercase letters
+    ! !{N} !{N-M}               uppercase A-Z
+    ? ?{N} ?{N-M}               uppercase A-Z and digits 0-9
+    - -{N} -{N-M}               letters and digits
+    ${'a,b',N-M}               combinations from a comma-separated word list
+    %{'name'} %{'name',N-M}     words from a named dictionary
+    \# \@ \$ ...                escape a wildcard character
+
+TEMPLATE JSON
+    {
+      "patterns": ["Year 19##", "%{'colors'}"],
+      "dictionaries": {
+        "colors": "path/to/colors.txt",
+        "inline": ["red", "blue"]
+      },
+      "select": [0, 2],
+      "range": ["5-7"],
+      "check": false
+    }
+
+EXAMPLES
+    wildling --dictionary colors:./colors.txt "%{'colors'}#"
+    wildling --template ./config.json
+    wildling --select 0 --range 8-9 "##"
+    wildling "${'blue,red',1-2}"

wildling-2.0.1/wildling/parse_pattern.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import re
+from typing import Callable, Dict, List, Union
+
+from .token import Token, TokenOptions, create_token
+
+Dictionaries = Dict[str, List[str]]
+
+TOKEN_PARSING_REGEX = re.compile(
+    r"(\\[%@$*#&?!-]|[%@$*#&?!-]\{.*?\}|[%@$*#&?!-])"
+)
+
+
+def parse_length_with_variants(part: str, variants: List[str]) -> TokenOptions:
+    length_arg_regex = re.compile(r"\{((\d+)-(\d+)|(\d+))\}")
+    match = length_arg_regex.search(part)
+
+    start_length = 1
+    end_length = 1
+
+    if match is not None and match.group(2):
+        start_length = int(match.group(2))
+        end_length = int(match.group(3))
+    elif match is not None and match.group(1):
+        start_length = int(match.group(1))
+        end_length = start_length
+
+    return {
+        "variants": variants,
+        "startLength": start_length,
+        "endLength": end_length,
+        "src": part,
+    }
+
+
+def parse_length_with_string(part: str) -> Union[TokenOptions, bool]:
+    length_arg_regex = re.compile(r"\{'(.*)'(?:,(\d+)-(\d+))?(?:,(\d+))?\}")
+    match = length_arg_regex.search(part)
+
+    if match is None:
+        return False
+
+    if match.group(2) is not None and match.group(3) is not None:
+        return {
+            "string": match.group(1) or "",
+            "startLength": int(match.group(2)),
+            "endLength": int(match.group(3)),
+            "src": part,
+        }
+
+    if match.group(4) is not None:
+        length = int(match.group(4))
+        return {
+            "string": match.group(1) or "",
+            "startLength": length,
+            "endLength": length,
+            "src": part,
+        }
+
+    return {
+        "string": match.group(1) or "",
+        "startLength": 1,
+        "endLength": 1,
+        "src": part,
+    }
+
+
+def simple_tokenizer(variants_string: str) -> Callable[[str], Token]:
+    variants = list(variants_string)
+
+    def tokenizer(part: str) -> Token:
+        return create_token(parse_length_with_variants(part, variants))
+
+    return tokenizer
+
+
+def _dictionary_tokenizer(part: str, dictionaries: Dictionaries) -> Token:
+    options = parse_length_with_string(part)
+    if options is False or (
+        isinstance(options, dict)
+        and options.get("string")
+        and options["string"] not in dictionaries
+    ):
+        options = {
+            "variants": [part],
+            "startLength": 1,
+            "endLength": 1,
+            "src": part,
+        }
+    else:
+        assert isinstance(options, dict)
+        options["variants"] = dictionaries.get(options.get("string") or "", [])
+    return create_token(options)
+
+
+def _words_tokenizer(part: str) -> Token:
+    options = parse_length_with_string(part)
+
+    if options is False:
+        options = {
+            "variants": [part],
+            "startLength": 1,
+            "endLength": 1,
+            "src": part,
+        }
+    else:
+        assert isinstance(options, dict)
+        variants: List[str] = []
+        work_string = options.get("string") or ""
+        index = 0
+        while index < len(work_string):
+            if work_string[index : index + 2] == "\\,":
+                index += 2
+            elif work_string[index] == ",":
+                variants.append(work_string[:index])
+                work_string = work_string[index + 1 :]
+                index = 0
+            else:
+                index += 1
+        variants.append(work_string)
+        options["variants"] = [variant.replace("\\,", ",") for variant in variants]
+
+    return create_token(options)
+
+
+def part_to_token(part: str, dictionaries: Dictionaries) -> Token:
+    tokenizers: Dict[str, Callable[[str], Token]] = {
+        "#": simple_tokenizer("0123456789"),
+        "@": simple_tokenizer("abcdefghijklmnopqrstuvwxyz"),
+        "*": simple_tokenizer("abcdefghijklmnopqrstuvwxyz0123456789"),
+        "-": simple_tokenizer(
+            "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+        ),
+        "!": simple_tokenizer("ABCDEFGHIJKLMNOPQRSTUVWXYZ"),
+        "?": simple_tokenizer("ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"),
+        "&": simple_tokenizer("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"),
+        "%": lambda p: _dictionary_tokenizer(p, dictionaries),
+        "$": _words_tokenizer,
+    }
+
+    tokenizer = tokenizers.get(part[0]) if part else None
+    is_escaped_token = (
+        len(part) > 1 and part[0] == "\\" and part[1] in tokenizers
+    )
+
+    if tokenizer is not None:
+        return tokenizer(part)
+    if is_escaped_token:
+        return create_token(
+            {
+                "variants": [re.sub(r"^\\", "", part)],
+                "src": part,
+            }
+        )
+    return create_token({"variants": [part], "src": part})
+
+
+def parse_pattern(input_pattern: str, dictionaries: Dictionaries) -> List[Token]:
+    parts = [part for part in TOKEN_PARSING_REGEX.split(input_pattern) if part]
+    return [part_to_token(part, dictionaries) for part in parts]

wildling-2.0.1/wildling/token.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import List, TypedDict
+
+
+class TokenOptions(TypedDict, total=False):
+    string: str
+    startLength: int
+    endLength: int
+    variants: List[str]
+    src: str
+
+
+def _default_integer_option(option: object, fallback: int) -> int:
+    return option if isinstance(option, int) and option >= 0 else fallback
+
+
+class Token:
+    def __init__(self, options: TokenOptions) -> None:
+        self._src = options.get("src", "")
+        self._start_length = _default_integer_option(options.get("startLength"), 1)
+        self._end_length = _default_integer_option(options.get("endLength"), 1)
+        self._variants = options.get("variants") or []
+        self._count = 0
+        for length in range(self._start_length, self._end_length + 1):
+            self._count += len(self._variants) ** length
+
+    def count(self) -> int:
+        return self._count
+
+    def src(self) -> str:
+        return self._src
+
+    def get(self, index: int) -> str:
+        if index > self._count - 1 or index < 0:
+            return ""
+
+        if index == 0 and self._start_length == 0:
+            return ""
+
+        index_with_offset = index
+        string_length = self._start_length
+        for string_length in range(self._start_length, self._end_length + 1):
+            offset_count = len(self._variants) ** string_length
+            if index_with_offset < offset_count:
+                break
+            index_with_offset -= offset_count
+
+        string_array: List[str] = []
+        for _ in range(string_length):
+            variant_index = index_with_offset % len(self._variants)
+            index_with_offset //= len(self._variants)
+            string_array.append(self._variants[variant_index])
+        return "".join(string_array)
+
+
+def create_token(options: TokenOptions) -> Token:
+    return Token(options)

wildling-2.0.1/wildling.egg-info/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: wildling
+Version: 2.0.1
+Summary: Pattern based string generator library and CLI
+License: MIT
+Project-URL: Repository, https://github.com/dotmonk/wildling
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# wildling
+
+Python library and CLI for pattern-based string generation. **Zero third-party dependencies** (stdlib only). Requires Python 3.9+.
+
+<!-- wildling:preamble -->
+**Docs:** [Website](https://dotmonk.github.io/wildling/) · [Sandbox](https://dotmonk.github.io/wildling/sandbox.html) · [Syntax](https://dotmonk.github.io/wildling/syntax.html) · [Source](https://github.com/dotmonk/wildling/tree/main/python)
+
+**Registry:** [PyPI](https://pypi.org/project/wildling/)
+
+## Example
+
+```text
+http://${'dev,stage,prod'}\-${'api,web'}#{0-2}.example.${'com,net,org'}/@.html
+```
+
+(The `\-` is a literal hyphen; bare `-` would mean “one letter or digit”. `@` is one lowercase letter.)
+
+That builds **URL-shaped** candidates: scheme `http://`, then environment × service × optional digits × TLD, then a one-letter path page. Three environments, two services, zero–two digits (`''`, `0`–`9`, `00`–`99`), three TLDs, and `a`–`z` → **51948** strings — the kind of list you generate for fuzzing links or probing staging hosts, not type out.
+
+A few of them:
+
+- `http://dev-api.example.com/a.html` / `http://stage-web.example.com/z.html`
+- `http://dev-api0.example.net/a.html` / `http://prod-web9.example.org/m.html`
+- `http://dev-api00.example.com/a.html` / `http://prod-web99.example.org/z.html`
+
+Named dictionaries (`%{'hosts'}`) work the same way when the word lists live in files.
+
+Try it in the [sandbox](https://dotmonk.github.io/wildling/sandbox.html?pattern=http%3A%2F%2F%24%7B%27dev%2Cstage%2Cprod%27%7D%5C-%24%7B%27api%2Cweb%27%7D%23%7B0-2%7D.example.%24%7B%27com%2Cnet%2Corg%27%7D%2F%40.html), or see [pattern syntax](https://dotmonk.github.io/wildling/syntax.html) for length ranges, dictionaries, and escapes.
+<!-- /wildling:preamble -->
+
+## Install
+
+From this repository:
+
+```bash
+cd python
+./build.sh
+# or without Docker:
+cp ../docs/help.txt wildling/help.txt
+```
+
+The CLI is `./bin/wildling`.
+
+**Registry:** `pip install wildling`
+
+**Git:**
+
+```bash
+pip install "git+https://github.com/dotmonk/wildling.git@v2.0.0#subdirectory=python"
+```
+
+## Library
+
+```python
+from wildling import create_wildling
+
+wildling = create_wildling(
+    patterns=["abrakadabra", "Year 19##"],
+    dictionaries={"colors": ["red", "blue"]},
+)
+
+wildling.count()  # 101
+wildling.get(0)   # "abrakadabra"
+
+value = wildling.next()
+while value is not False:
+    print(value)
+    value = wildling.next()
+
+wildling.reset()
+```
+
+### API
+
+| Method | Description |
+|--------|-------------|
+| `next()` | Next combination, or `False` when exhausted |
+| `get(index)` | Combination at `index`, or `False` if out of range |
+| `count()` | Total combinations across all patterns |
+| `index()` | Current position (after `next` calls) |
+| `reset()` | Reset iteration to the start |
+| `generators()` | Per-pattern generators |
+
+## CLI
+
+```bash
+./bin/wildling "Year 19##"
+./bin/wildling --dictionary planets:../dictionaries/planets.txt "%{'planets'}"
+./bin/wildling --template ./config.json
+```
+
+Help text and `--check` output follow [`docs/cli.md`](../docs/cli.md) / [`docs/help.txt`](../docs/help.txt).
+
+## Build
+
+```bash
+./build.sh   # Docker: copy help.txt + byte-compile
+```
+
+Project tests live in `../tests/` and are run with `../test.sh`.

wildling-2.0.1/wildling.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+wildling/__init__.py
+wildling/__main__.py
+wildling/cli.py
+wildling/generator.py
+wildling/help.txt
+wildling/parse_pattern.py
+wildling/token.py
+wildling.egg-info/PKG-INFO
+wildling.egg-info/SOURCES.txt
+wildling.egg-info/dependency_links.txt
+wildling.egg-info/entry_points.txt
+wildling.egg-info/top_level.txt

wildling-2.0.1/wildling.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

wildling-2.0.1/wildling.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wildling = wildling.cli:main

wildling-2.0.1/wildling.egg-info/top_level.txt

@@ -0,0 +1 @@
+wildling