API reference

The supported public API is exported from profanex. Construct a Filter once and reuse it; configuration and compiled filters are immutable after construction.

For configuration recipes and tradeoffs, see the configuration guide. For normalization and matching semantics, see How Profanex works.

Filter

profanex.api.Filter

Compiled, immutable profanity filter.

Construct a filter once and reuse it. Construction loads and validates the effective lexicon and compiles the Rust matching engine.

Parameters:

Name	Type	Description	Default
config	FilterConfig | None	Immutable policy configuration. None uses FilterConfig defaults.	None

Raises:

Type	Description
ConfigError	If a configured lexicon cannot be loaded or validated.
ImportError	If the native profanex._core extension is unavailable.

config property

config

The immutable configuration snapshot used to build this filter.

from_defaults classmethod

from_defaults()

Construct a filter with the packaged lexicon and default policy.

contains

contains(text)

Return whether text contains at least one accepted match.

This is the lowest-overhead single-text detection API and may stop after the first accepted match.

Parameters:

Name	Type	Description	Default
text	str	Source text to inspect.	required

Returns:

Type	Description
bool	True when the configured policy accepts a match.

Raises:

Type	Description
TypeError	If text is not a string.

find

find(text)

Return ordered, non-overlapping matches in text.

Parameters:

Name	Type	Description	Default
text	str	Source text to inspect.	required

Returns:

Type	Description
list[Match]	Matches with half-open indices into the original Python string.

Raises:

Type	Description
TypeError	If text is not a string.

clean

clean(text)

Return text with every accepted match masked.

Parameters:

Name	Type	Description	Default
text	str	Source text to filter.	required

Returns:

Type	Description
str	A new string transformed by the configured built-in or custom mask.

Raises:

Type	Description
TypeError	If text is not a string or a custom mask returns a non-string.

analyze

analyze(text)

Return (contains_profanity, cleaned_text) from one scan.

Prefer this method over separate contains and clean calls when both results are needed.

Parameters:

Name	Type	Description	Default
text	str	Source text to inspect and filter.	required

Returns:

Type	Description
tuple[bool, str]	A detection flag and the corresponding cleaned text.

Raises:

Type	Description
TypeError	If text is not a string or a custom mask returns a non-string.

contains_many

contains_many(texts, *, parallel=False, workers=None)

Detect profanity in a sequence while preserving input order.

Parameters:

Name	Type	Description	Default
texts	Sequence[str]	Finite sequence of strings. A bare string is rejected.	required
parallel	bool	Use the Rust worker pool when True.	False
workers	int | None	Explicit worker count from 1 through 256. Requires parallel=True.	None

Returns:

Type	Description
list[bool]	One detection flag per input string.

Raises:

Type	Description
TypeError	If texts is not a sequence of strings.
ConfigError	If parallel or worker options are invalid.

find_many

find_many(texts, *, parallel=False, workers=None)

Find matches in a sequence while preserving input order.

Parameters:

Name	Type	Description	Default
texts	Sequence[str]	Finite sequence of strings. A bare string is rejected.	required
parallel	bool	Use the Rust worker pool when True.	False
workers	int | None	Explicit worker count from 1 through 256. Requires parallel=True.	None

Returns:

Type	Description
list[list[Match]]	One ordered match list per input string.

Raises:

Type	Description
TypeError	If texts is not a sequence of strings.
ConfigError	If parallel or worker options are invalid.

clean_many

clean_many(texts, *, parallel=False, workers=None)

Mask matches in a sequence while preserving input order.

Parameters:

Name	Type	Description	Default
texts	Sequence[str]	Finite sequence of strings. A bare string is rejected.	required
parallel	bool	Use the Rust worker pool when True.	False
workers	int | None	Explicit worker count from 1 through 256. Requires parallel=True.	None

Returns:

Type	Description
list[str]	One cleaned string per input string.

Raises:

Type	Description
TypeError	If an input or custom-mask result is not a string.
ConfigError	If worker options are invalid or a custom mask is combined with parallel cleaning.

analyze_many

analyze_many(texts, *, parallel=False, workers=None)

Return ordered flags and cleaned texts while scanning each input once.

Parameters:

Name	Type	Description	Default
texts	Sequence[str]	Finite sequence of strings. A bare string is rejected.	required
parallel	bool	Use the Rust worker pool when True.	False
workers	int | None	Explicit worker count from 1 through 256. Requires parallel=True.	None

Returns:

Type	Description
tuple[list[bool], list[str]]	Parallel lists of detection flags and cleaned strings.

Raises:

Type	Description
TypeError	If an input or custom-mask result is not a string.
ConfigError	If parallel or worker options are invalid.

iter_contains

iter_contains(
    texts, *, chunk_size=1000, parallel=False, workers=None
)

Yield detection flags from any string iterable in bounded chunks.

Parameters:

Name	Type	Description	Default
texts	Iterable[str]	Iterable of strings.	required
chunk_size	int	Maximum inputs materialized per batch; must be positive.	1000
parallel	bool	Process each chunk using the Rust worker pool.	False
workers	int | None	Explicit worker count from 1 through 256. Requires parallel=True.	None

Yields:

Type	Description
bool	Detection flags in input order.

iter_find

iter_find(
    texts, *, chunk_size=1000, parallel=False, workers=None
)

Yield match lists from any string iterable in bounded chunks.

Parameters:

Name	Type	Description	Default
texts	Iterable[str]	Iterable of strings.	required
chunk_size	int	Maximum inputs materialized per batch; must be positive.	1000
parallel	bool	Process each chunk using the Rust worker pool.	False
workers	int | None	Explicit worker count from 1 through 256. Requires parallel=True.	None

Yields:

Type	Description
list[Match]	Ordered match lists in input order.

iter_clean

iter_clean(
    texts, *, chunk_size=1000, parallel=False, workers=None
)

Yield cleaned strings from any string iterable in bounded chunks.

Parameters:

Name	Type	Description	Default
texts	Iterable[str]	Iterable of strings.	required
chunk_size	int	Maximum inputs materialized per batch; must be positive.	1000
parallel	bool	Process each chunk using the Rust worker pool.	False
workers	int | None	Explicit worker count from 1 through 256. Requires parallel=True.	None

Yields:

Type	Description
str	Cleaned strings in input order.

iter_analyze

iter_analyze(
    texts, *, chunk_size=1000, parallel=False, workers=None
)

Yield detection and cleaning results from one scan per input.

Parameters:

Name	Type	Description	Default
texts	Iterable[str]	Iterable of strings.	required
chunk_size	int	Maximum inputs materialized per batch; must be positive.	1000
parallel	bool	Process each chunk using the Rust worker pool.	False
workers	int | None	Explicit worker count from 1 through 256. Requires parallel=True.	None

Yields:

Type	Description
tuple[bool, str]	(contains_profanity, cleaned_text) tuples in input order.

FilterConfig

profanex.api.FilterConfig dataclass

Immutable filter policy.

Numeric knobs, mask, categories, mutual exclusion, and in-memory lexicon container shapes are validated eagerly. YAML path contents are validated when constructing a Filter.

Attributes:

Name	Type	Description
categories	frozenset[Category] | None	Enabled categories, or None to enable every category.
banned	Collection[str] | Mapping[str, Collection[str]] | None	In-memory replacement banned lexicon. Flat terms use general when enabled, otherwise the selected categories.
banned_path	str | None	YAML replacement banned lexicon path.
extra_banned	Collection[str] | Mapping[str, Collection[str]] | None	Terms merged into the selected banned lexicon. Flat terms use the same category assignment as banned.
extra_banned_path	str | None	YAML terms merged into the selected banned lexicon.
allowlist	Collection[str] | None	In-memory replacement allowlist.
allowlist_path	str | None	YAML replacement allowlist path.
extra_allowlist	Collection[str] | None	Terms merged into the selected allowlist.
extra_allowlist_path	str | None	YAML terms merged into the selected allowlist.
threshold	int	Minimum fuzzy similarity score from 0 through 100.
enable_fuzzy	bool	Whether to run optional single-token fuzzy matching.
min_fuzzy_len	int	Minimum normalized token and term length for fuzzy matching.
fuzzy_length_delta	int	Maximum token/term length difference considered by fuzzy matching, from 0 through 64.
fuzzy_max_token_len	int	Maximum token length considered by fuzzy matching, capped at 256.
word_boundaries	bool	Whether accepted matches must satisfy Unicode word boundaries.
mask	MaskSpec	Built-in mask name or serial Python callback.
normalize_leet	bool	Whether to normalize the built-in leetspeak substitutions.
normalize_separated_runs	bool	Whether to join guarded separated character runs.
normalize_repeated_chars	bool	Whether to collapse character runs of length three or more.

Raises:

Type	Description
ConfigError	If an option has the wrong type or range, mutually exclusive sources are combined, or an in-memory lexicon has an invalid shape.

builtin_mask property

builtin_mask

Return the validated built-in mask name, or None for a callback.

mask_callable property

mask_callable

Return the custom mask callback when configured.

enabled_categories

enabled_categories()

Return the concrete enabled category set.

Match

profanex.api.Match dataclass

One accepted, non-overlapping profanity match.

Attributes:

Name	Type	Description
start	int	Inclusive start index in the original Python string.
end	int	Exclusive end index in the original Python string.
text	str	Exact slice from the original string. Always equals source[start:end] for the source passed to Filter.find.
term	str	Canonical term from the effective banned lexicon.
categories	frozenset[Category]	Enabled policy categories associated with term.
score	float	Similarity from 0 through 100. Exact and phrase matches use 100.
kind	Literal['exact', 'phrase', 'fuzzy']	Matching path: "exact", "phrase", or "fuzzy".

Category

profanex.lexicon.Category

Bases: str, Enum

Built-in moderation-policy category.

ConfigError

profanex.lexicon.ConfigError

Bases: ValueError

Invalid filter configuration or lexicon input.