A Python slugify application that handles unicode.
Best attempt to create slugs from unicode strings while keeping it DRY.
This module, by default installs and uses text-unidecode (GPL & Perl Artistic) for its decoding needs.
However, there is an alternative decoding package called Unidecode (GPL). It can be installed as python-slugify[unidecode] for those who prefer it. Unidecode is believed to be more advanced.
| Python | Slugify |
|---|---|
>= 2.7 < 3.6 |
< 5.0.0 |
>= 3.6 < 3.7 |
>= 5.0.0 < 7.0.0 |
>= 3.7 |
>= 7.0.0 |
pip install python-slugify
# OR
pip install python-slugify[unidecode]
def slugify( text: str, entities: bool = True, decimal: bool = True, hexadecimal: bool = True, max_length: int = 0, word_boundary: bool = False, separator: str = DEFAULT_SEPARATOR, save_order: bool = False, stopwords: Iterable[str] = (), regex_pattern: str | None = None, lowercase: bool = True, replacements: Iterable[Iterable[str]] = (), allow_unicode: bool = False, ) -> str: """ Make a slug from the given text. :param text (str): initial text :param entities (bool): converts html entities to unicode (foo & bar -> foo-bar) :param decimal (bool): converts html decimal to unicode (Ž -> Ž -> z) :param hexadecimal (bool): converts html hexadecimal to unicode (Ž -> Ž -> z) :param max_length (int): output string length :param word_boundary (bool): truncates to end of full words (length may be shorter than max_length) :param save_order (bool): when set, does not include shorter subsequent words even if they fit :param separator (str): separator between words :param stopwords (iterable): words to discount :param regex_pattern (str): regex pattern for disallowed characters :param lowercase (bool): activate case sensitivity by setting it to False :param replacements (iterable): list of replacement rules e.g. [['|', 'or'], ['%', 'percent']] :param allow_unicode (bool): allow unicode characters :return (str): slugify text """
from slugify import slugify txt = "This is a test ---" r = slugify(txt) self.assertEqual(r, "this-is-a-test") txt = '影師嗎' r = slugify(txt) self.assertEqual(r, "ying-shi-ma") txt = '影師嗎' r = slugify(txt, allow_unicode=True) self.assertEqual(r, "影師嗎") txt = 'C\'est déjà l\'été.' r = slugify(txt) self.assertEqual(r, "c-est-deja-l-ete") txt = 'Nín hǎo. Wǒ shì zhōng guó rén' r = slugify(txt) self.assertEqual(r, "nin-hao-wo-shi-zhong-guo-ren") txt = 'Компьютер' r = slugify(txt) self.assertEqual(r, "kompiuter") txt = 'jaja---lol-méméméoo--a' r = slugify(txt, max_length=9) self.assertEqual(r, "jaja-lol") txt = 'jaja---lol-méméméoo--a' r = slugify(txt, max_length=15, word_boundary=True) self.assertEqual(r, "jaja-lol-a") txt = 'jaja---lol-méméméoo--a' r = slugify(txt, max_length=20, word_boundary=True, separator=".") self.assertEqual(r, "jaja.lol.mememeoo.a") txt = 'one two three four' r = slugify(txt, max_length=12, word_boundary=True, save_order=False) self.assertEqual(r, "one-two-four") txt = 'one two three four' r = slugify(txt, max_length=12, word_boundary=True, save_order=True) self.assertEqual(r, "one-two") txt = 'the quick brown fox jumps over the lazy dog' r = slugify(txt, stopwords=['the']) self.assertEqual(r, 'quick-brown-fox-jumps-over-lazy-dog') txt = 'the quick brown fox jumps over the lazy dog in a hurry' r = slugify(txt, stopwords=['the', 'in', 'a', 'hurry']) self.assertEqual(r, 'quick-brown-fox-jumps-over-lazy-dog') txt = 'thIs Has a stopword Stopword' r = slugify(txt, stopwords=['Stopword'], lowercase=False) self.assertEqual(r, 'thIs-Has-a-stopword') txt = "___This is a test___" regex_pattern = r'[^-a-z0-9_]+' r = slugify(txt, regex_pattern=regex_pattern) self.assertEqual(r, "___this-is-a-test___") txt = "___This is a test___" regex_pattern = r'[^-a-z0-9_]+' r = slugify(txt, separator='_', regex_pattern=regex_pattern) self.assertNotEqual(r, "_this_is_a_test_") txt = '10 | 20 %' r = slugify(txt, replacements=[['|', 'or'], ['%', 'percent']]) self.assertEqual(r, "10-or-20-percent") txt = 'ÜBER Über German Umlaut' r = slugify(txt, replacements=[['Ü', 'UE'], ['ü', 'ue']]) self.assertEqual(r, "ueber-ueber-german-umlaut") txt = 'i love 🦄' r = slugify(txt, allow_unicode=True) self.assertEqual(r, "i-love") txt = 'i love 🦄' r = slugify(txt, allow_unicode=True, regex_pattern=r'[^🦄]+') self.assertEqual(r, "🦄")
For more examples, have a look at the test.py file.
With the package, a command line tool called slugify is also installed.
It allows convenient command line access to all the features the slugify function supports. Call it with -h for help.
The command can take its input directly on the command line or from STDIN (when the --stdin flag is passed):
$ echo "Taking input from STDIN" | slugify --stdin
taking-input-from-stdin
$ slugify taking input from the command line
taking-input-from-the-command-line
Please note that when a multi-valued option such as --stopwords or --replacements is passed, you need to use -- as separator before you start with the input:
$ slugify --stopwords the in a hurry -- the quick brown fox jumps over the lazy dog in a hurry
quick-brown-fox-jumps-over-lazy-dog
To run the tests against the current environment:
python test.py
Please read the (wiki) page prior to raising any PRs.
Released under a (MIT) license.
Though the dependencies may be GPL licensed, python-slugify itself is not considered a derivative work and will remain under the MIT license.
If you wish to avoid installation of any GPL licensed packages, please note that the default dependency text-unidecode explicitly lets you choose to use the Artistic License instead. Use without concern.
X.Y.Z Version
`MAJOR` version -- when you make incompatible API changes,
`MINOR` version -- when you add functionality in a backwards-compatible manner, and
`PATCH` version -- when you make backwards-compatible bug fixes.