Getting started¶

araclean needs Python 3.12+. The core depends only on pydantic — no compiler, no Java, no model download.

Install¶

pip install araclean

Everything beyond the Python API lives behind optional extras, so the core stays lean:

Extra	Installs	Gives you
`araclean[cli]`	Typer	the `araclean` shell command — see the CLI guide
`araclean[pandas]`	pandas	the `.araclean` Series accessor — see pandas & polars
`araclean[polars]`	polars	the `.araclean` Series namespace — see pandas & polars
`araclean[emoji]`	emoji	`HandleEmoji`'s `demojize` mode (`keep`/`strip` need nothing)
`araclean[all]`	all of the above	everything

Using a feature without its extra never crashes with a bare ImportError: you get a clear error naming the exact pip install command to run.

Your first normalization¶

The quick-use API is one function:

>>> from araclean import normalize
>>> normalize("ﻻ يَحْمِلُ الحِــقْدَ")  # repair a presentation form and tatweel
'لا يَحْمِلُ الحِقْدَ'

With no profile, normalize applies the LIGHT profile: lossless encoding repair. It fixes the Unicode form, strips invisible bidi/zero-width characters, folds presentation-form glyphs back to letters, removes tatweel, unifies look-alike letters (Persian keheh ک → Arabic kaf ك), and collapses whitespace. It never removes tashkeel, never folds alef variants, never touches digits — it discards no linguistic signal, so it is safe to run on any Arabic corpus, including vocalized or Qur'anic text.

Choosing a profile¶

Anything lossy is opt-in through a named profile. Pass the name to normalize:

>>> normalize("عَلَى قَدْرِ أَهْلِ العَزْمِ")  # LIGHT preserves marks and spelling
'عَلَى قَدْرِ أَهْلِ العَزْمِ'
>>> normalize("عَلَى قَدْرِ أَهْلِ العَزْمِ", profile="search")
'علي قدر اهل العزم'
>>> normalize("جميييييل", profile="ml")   # ML: dediacritize + collapse emphatic elongation
'جميل'
>>> normalize("رااااائع 😍 https://t.co/xyz", profile="social")  # SOCIAL: clean noise, keep emoji
'راائع 😍 [رابط]'

Pick by task:

You are doing	Use	Why
anything — you just want clean, consistent text	`LIGHT` (default)	lossless; repairs encoding only
search / retrieval / matching	`SEARCH`	folds spelling & vocalization variants so على matches علي
training or feeding a model	`ML`	dediacritizes and caps elongation, but keeps letter distinctions that carry signal
social-media text	`SOCIAL`	cleans URLs/mentions/HTML, segments hashtags, keeps emoji
vocalized / classical / Qur'anic text	`CLASSICAL`	lossless repair with an explicit every-mark-preserved guarantee

Each profile page lists its steps in order and labels each one lossless or lossy. The pages are generated from the assembled pipelines, and CI checks them against the code.

Beyond one call¶

Process files from the shell: pip install 'araclean[cli]', then araclean normalize corpus.txt --profile search — see the CLI guide.
Normalize a dataframe column: df["text"].araclean.normalize(profile="search") — see pandas & polars.
Adjust one knob of a profile (map_digits=True, emoji="strip", …) — see Tuning profiles.
Assemble your own step sequence — see Composing pipelines.
Understand exactly what you might be discarding — see the safety contract.