Skip to content

Latest commit

 

History

History
128 lines (103 loc) · 3.45 KB

README.md

File metadata and controls

128 lines (103 loc) · 3.45 KB
Raw

Random Slug Generator

What it says on the tin - this generates random text slugs in Rust.

PyPi

Downloads

Usable as a standalone binary, web applications as a WebAssembly module (WASM), or even as a Python module.

Why?

I needed a way to generate random slugs for a web project so thought it was a good opporunity to try out Rust's WebAssembly capabilities while also being able to use the same code as a zero-dependency python module for other projects.

Key features

  • Generates unique random slugs for a input length in words
  • Fast
  • Zero dependencies (python and wasm)
  • Pre-filtered to avoid dodgy or rude vocabulary
  • Customisable slug length in words
  • Over half a million unique combinations for 2-word slugs ranging up to over 280 trillion unique combinations for 5-word slugs.

Usage

As a Python module

Install from PyPI

pip install rustyrs

Build from source

python -m venv venv
source venv/bin/activate
pip install maturin
maturin develop --features python

Then from Python:

from rustyrs import random_slugs
slugs: list[str] = random_slugs(3, 5)

# slugs: ['reflecting-unsealed-mamba', 'disabling-addicting-asp', 'pliable-begotten-barnacle', 'vaulting-telepathic-caracal', 'canonical-graven-beetle']

Other features:

  • get_slug(word_length: int) -> str: Generate a single slug of a specific length
  • SlugGenerator(word_length: int): Create a generator object to generate slugs of a specific length. Will generate slugs until all unique permutations have been reached. 
    from rustyrs import SlugGenerator
gen = SlugGenerator(3)
print(next(gen)) # 'unwieldy-unsuspecting-ant'
  • combinations(word_length: int) -> int: Get the number of possible combinations for a given word length 
    from rustyrs import combinations
print(combinations(2)) # 556,284

Python Performance

  • 0.5 million x 2 word slugs: ~210ms 
    time python -c "import rustyrs as r;a = set(r.random_slugs(2, 556_284));assert len(a) == 556_284"
real    0m0.219s
user    0m0.211s
sys     0m0.000s
  • 1 million x 5 word slugs: ~524ms 
    time python -c "import rustyrs as r;a = set(r.random_slugs(5, 1_000_000));assert len(a) == 1_000_000"
real    0m0.667s
user    0m0.524s
sys     0m0.051s

As a WASM module

# If wasm pack is not already installed
cargo install wasm-pack 

# build the WASM module
wasm-pack build --target web --features wasm

Then from JS/TS:

import init, { random_slugs } from './pkg/rustyrs.js';
init();
const slugs: string[] = random_slugs(3, 5);
console.log(slugs);

// slugs: ['postpartum-regal-taipan', 'devastating-elven-salamander', 'immense-ambivalent-wren', 'philosophical-bandaged-gaur', 'outlaw-noncommercial-sunfish']

See index.html for a full example

As a Rust binary

cargo run --release [length in words] [number of slugs]

As a standalone binary

cargo build --release
[build path]/rustyrs [length in words] [number of slugs]

Example Output

proctor-slimmer-guillemot
unsafe-warlike-avocado
garbled-pulled-stork
answerable-quick-whale
floral-apportioned-bobcat

License

MIT