Text Slug Utilities

Slug generation and validation.

Slug Generation Module

Functions for generating URL-friendly slugs.

Functions

add_slug_prefix(slug: str, prefix: str, delimiter: str = '-') -> str

Add a prefix to a slug.

Parameters:

Name	Type	Description	Default
slug	str	The original slug.	required
prefix	str	The prefix to add.	required
delimiter	str	The delimiter used in the slug (default: "-").	'-'

Returns:

Type	Description
str	The slug with the prefix added.

Example

add_slug_prefix("world", "hello") 'hello-world' add_slug_prefix("world", "hello", delimiter="_") 'hello_world'

add_slug_suffix(slug: str, suffix: str, delimiter: str = '-') -> str

Add a suffix to a slug.

Parameters:

Name	Type	Description	Default
slug	str	The original slug.	required
suffix	str	The suffix to add.	required
delimiter	str	The delimiter used in the slug (default: "-").	'-'

Returns:

Type	Description
str	The slug with the suffix added.

Example

add_slug_suffix("hello", "world") 'hello-world' add_slug_suffix("hello", "world", delimiter="_") 'hello_world'

is_valid_slug(slug: str, delimiter: str = '-') -> bool

Validate if a string is a valid slug.

A valid slug contains only lowercase letters, numbers, and delimiters, and does not start or end with a delimiter.

Parameters:

Name	Type	Description	Default
slug	str	The string to validate.	required
delimiter	str	The delimiter used in the slug (default: "-").	'-'

Returns:

Type	Description
bool	True if the string is a valid slug, False otherwise.

Example

is_valid_slug("hello-world") True is_valid_slug("Hello-World") False is_valid_slug("-hello-world") False is_valid_slug("hello--world") False

unique_slug(slug: str, existing_slugs: set[str] | list[str], delimiter: str = '-') -> str

Generate a unique slug by appending an incremental number.

If the slug already exists in the set of existing slugs, appends an incremental number (starting from 1) until a unique slug is found.

Parameters:

Name	Type	Description	Default
slug	str	The original slug.	required
existing_slugs	set[str] | list[str]	A set or list of existing slugs to check against.	required
delimiter	str	The delimiter used in the slug (default: "-").	'-'

Returns:

Type	Description
str	A unique slug with an incremental number if needed.

Example

unique_slug("hello-world", {"hello-world"}) 'hello-world-1' unique_slug("hello-world", {"hello-world", "hello-world-1"}) 'hello-world-2' unique_slug("hello-world", []) 'hello-world'

Modules

slug_add_prefix

Add Slug Prefix Function

Add a prefix to a slug.

Functions

add_slug_prefix(slug: str, prefix: str, delimiter: str = '-') -> str

Add a prefix to a slug.

Parameters:

Name	Type	Description	Default
slug	str	The original slug.	required
prefix	str	The prefix to add.	required
delimiter	str	The delimiter used in the slug (default: "-").	'-'

Returns:

Type	Description
str	The slug with the prefix added.

Example

add_slug_prefix("world", "hello") 'hello-world' add_slug_prefix("world", "hello", delimiter="_") 'hello_world'

slug_add_suffix

Add Slug Suffix Function

Add a suffix to a slug.

Functions

add_slug_suffix(slug: str, suffix: str, delimiter: str = '-') -> str

Add a suffix to a slug.

Parameters:

Name	Type	Description	Default
slug	str	The original slug.	required
suffix	str	The suffix to add.	required
delimiter	str	The delimiter used in the slug (default: "-").	'-'

Returns:

Type	Description
str	The slug with the suffix added.

Example

add_slug_suffix("hello", "world") 'hello-world' add_slug_suffix("hello", "world", delimiter="_") 'hello_world'

slug_is_valid

Is Valid Slug Function

Validate slug format.

Functions

is_valid_slug(slug: str, delimiter: str = '-') -> bool

Validate if a string is a valid slug.

A valid slug contains only lowercase letters, numbers, and delimiters, and does not start or end with a delimiter.

Parameters:

Name	Type	Description	Default
slug	str	The string to validate.	required
delimiter	str	The delimiter used in the slug (default: "-").	'-'

Returns:

Type	Description
bool	True if the string is a valid slug, False otherwise.

Example

is_valid_slug("hello-world") True is_valid_slug("Hello-World") False is_valid_slug("-hello-world") False is_valid_slug("hello--world") False

slug_unique

Unique Slug Function

Generate unique slugs with incremental numbers.

Functions

unique_slug(slug: str, existing_slugs: set[str] | list[str], delimiter: str = '-') -> str

Generate a unique slug by appending an incremental number.

If the slug already exists in the set of existing slugs, appends an incremental number (starting from 1) until a unique slug is found.

Parameters:

Name	Type	Description	Default
slug	str	The original slug.	required
existing_slugs	set[str] | list[str]	A set or list of existing slugs to check against.	required
delimiter	str	The delimiter used in the slug (default: "-").	'-'

Returns:

Type	Description
str	A unique slug with an incremental number if needed.

Example

unique_slug("hello-world", {"hello-world"}) 'hello-world-1' unique_slug("hello-world", {"hello-world", "hello-world-1"}) 'hello-world-2' unique_slug("hello-world", []) 'hello-world'

slugify

Slugify Function

Generate URL-friendly slugs from text.

Functions

slugify(text: str, delimiter: str = '-', max_length: int | None = None, lowercase: bool = True, custom_replacements: dict[str, str] | None = None) -> str

Generate a URL-friendly slug from text.

Converts the input text to a URL-friendly slug by: - Normalizing Unicode characters - Applying custom character replacements (optional) - Converting to lowercase (optional) - Replacing spaces and special characters with delimiters - Truncating to maximum length (optional)

Parameters:

Name	Type	Description	Default
text	str	The text to convert into a slug.	required
delimiter	str	The delimiter to use for separating words (default: "-").	'-'
max_length	int | None	Maximum length of the slug. If None, no limit is applied.	None
lowercase	bool	Convert slug to lowercase if True (default: True).	True
custom_replacements	dict[str, str] | None	Dictionary of custom character replacements.	None

Returns:

Type	Description
str	A URL-friendly slug.

Example

slugify("Hello World!") 'hello-world' slugify("Café au Lait", delimiter="_") 'cafe_au_lait' slugify("Hello World", max_length=8) 'hello-wo' slugify("Hello & World", custom_replacements={"&": "and"}) 'hello-and-world'

options: show_root_heading: true show_source: false heading_level: 2