# Python Slugify
**A Python slugify application that handles unicode**.
[![status-image]][status-link]
[![version-image]][version-link]
[![coverage-image]][coverage-link]
# Overview
**Best attempt** to create slugs from unicode strings while keeping it **DRY**.
# Notice
This module, by default installs and uses [text-unidecode](https://github.com/kmike/text-unidecode) _(GPL & Perl Artistic)_ for its decoding needs.
However, there is an alternative decoding package called [Unidecode](https://github.com/avian2/unidecode) _(GPL)_. It can be installed as `python-slugify[unidecode]` for those who prefer it. `Unidecode` is believed to be more [advanced](https://github.com/un33k/python-slugify/wiki/Python-Slugify-Wiki#notes-on-unidecode).
### `Official` Support Matrix
| Python | Slugify |
| -------------- | ------------------ |
| `>= 2.7 < 3.6` | `< 5.0.0` |
| `>= 3.6 < 3.7` | `>= 5.0.0 < 7.0.0` |
| `>= 3.7` | `>= 7.0.0` |
# How to install
easy_install python-slugify |OR| easy_install python-slugify[unidecode]
-- OR --
pip install python-slugify |OR| pip install python-slugify[unidecode]
# Options
```python
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): if parameter is True and max_length > 0 return whole words in the initial order
: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
"""
```
# How to use
```python
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 five'
r = slugify(txt, max_length=13, word_boundary=True, save_order=True)
self.assertEqual(r, "one-two-three")
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](test.py) file.
# Command Line Options
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
```
# Running the tests
To run the tests against the current environment:
python test.py
# Contribution
Please read the ([wiki](https://github.com/un33k/python-slugify/wiki/Python-Slugify-Wiki)) page prior to raising any PRs.
# License
Released under a ([MIT](LICENSE)) license.
### Notes on GPL dependencies
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](https://opensource.org/license/artistic-perl-1-0-2/) instead. Use without concern.
# Version
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.
[status-image]: https://github.com/un33k/python-slugify/actions/workflows/ci.yml/badge.svg
[status-link]: https://github.com/un33k/python-slugify/actions/workflows/ci.yml
[version-image]: https://img.shields.io/pypi/v/python-slugify.svg
[version-link]: https://pypi.python.org/pypi/python-slugify
[coverage-image]: https://coveralls.io/repos/un33k/python-slugify/badge.svg
[coverage-link]: https://coveralls.io/r/un33k/python-slugify
[download-image]: https://img.shields.io/pypi/dm/python-slugify.svg
[download-link]: https://pypi.python.org/pypi/python-slugify
# Sponsors
[Neekware Inc.](http://neekware.com)
Raw data
{
"_id": null,
"home_page": "https://github.com/un33k/python-slugify",
"name": "python-slugify",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Val Neekman",
"author_email": "info@neekware.com",
"download_url": "https://files.pythonhosted.org/packages/87/c7/5e1547c44e31da50a460df93af11a535ace568ef89d7a811069ead340c4a/python-slugify-8.0.4.tar.gz",
"platform": null,
"description": "# Python Slugify\n\n**A Python slugify application that handles unicode**.\n\n[![status-image]][status-link]\n[![version-image]][version-link]\n[![coverage-image]][coverage-link]\n\n# Overview\n\n**Best attempt** to create slugs from unicode strings while keeping it **DRY**.\n\n# Notice\n\nThis module, by default installs and uses [text-unidecode](https://github.com/kmike/text-unidecode) _(GPL & Perl Artistic)_ for its decoding needs.\n\nHowever, there is an alternative decoding package called [Unidecode](https://github.com/avian2/unidecode) _(GPL)_. It can be installed as `python-slugify[unidecode]` for those who prefer it. `Unidecode` is believed to be more [advanced](https://github.com/un33k/python-slugify/wiki/Python-Slugify-Wiki#notes-on-unidecode).\n\n### `Official` Support Matrix\n\n| Python | Slugify |\n| -------------- | ------------------ |\n| `>= 2.7 < 3.6` | `< 5.0.0` |\n| `>= 3.6 < 3.7` | `>= 5.0.0 < 7.0.0` |\n| `>= 3.7` | `>= 7.0.0` |\n\n# How to install\n\n easy_install python-slugify |OR| easy_install python-slugify[unidecode]\n -- OR --\n pip install python-slugify |OR| pip install python-slugify[unidecode]\n\n# Options\n\n```python\ndef slugify(\n text: str,\n entities: bool = True,\n decimal: bool = True,\n hexadecimal: bool = True,\n max_length: int = 0,\n word_boundary: bool = False,\n separator: str = DEFAULT_SEPARATOR,\n save_order: bool = False,\n stopwords: Iterable[str] = (),\n regex_pattern: str | None = None,\n lowercase: bool = True,\n replacements: Iterable[Iterable[str]] = (),\n allow_unicode: bool = False,\n) -> str:\n \"\"\"\n Make a slug from the given text.\n :param text (str): initial text\n :param entities (bool): converts html entities to unicode (foo & bar -> foo-bar)\n :param decimal (bool): converts html decimal to unicode (Ž -> \u017d -> z)\n :param hexadecimal (bool): converts html hexadecimal to unicode (Ž -> \u017d -> z)\n :param max_length (int): output string length\n :param word_boundary (bool): truncates to end of full words (length may be shorter than max_length)\n :param save_order (bool): if parameter is True and max_length > 0 return whole words in the initial order\n :param separator (str): separator between words\n :param stopwords (iterable): words to discount\n :param regex_pattern (str): regex pattern for disallowed characters\n :param lowercase (bool): activate case sensitivity by setting it to False\n :param replacements (iterable): list of replacement rules e.g. [['|', 'or'], ['%', 'percent']]\n :param allow_unicode (bool): allow unicode characters\n :return (str): slugify text\n \"\"\"\n```\n\n# How to use\n\n```python\nfrom slugify import slugify\n\ntxt = \"This is a test ---\"\nr = slugify(txt)\nself.assertEqual(r, \"this-is-a-test\")\n\ntxt = '\u5f71\u5e2b\u55ce'\nr = slugify(txt)\nself.assertEqual(r, \"ying-shi-ma\")\n\ntxt = '\u5f71\u5e2b\u55ce'\nr = slugify(txt, allow_unicode=True)\nself.assertEqual(r, \"\u5f71\u5e2b\u55ce\")\n\ntxt = 'C\\'est d\u00e9j\u00e0 l\\'\u00e9t\u00e9.'\nr = slugify(txt)\nself.assertEqual(r, \"c-est-deja-l-ete\")\n\ntxt = 'N\u00edn h\u01ceo. W\u01d2 sh\u00ec zh\u014dng gu\u00f3 r\u00e9n'\nr = slugify(txt)\nself.assertEqual(r, \"nin-hao-wo-shi-zhong-guo-ren\")\n\ntxt = '\u041a\u043e\u043c\u043f\u044c\u044e\u0442\u0435\u0440'\nr = slugify(txt)\nself.assertEqual(r, \"kompiuter\")\n\ntxt = 'jaja---lol-m\u00e9m\u00e9m\u00e9oo--a'\nr = slugify(txt, max_length=9)\nself.assertEqual(r, \"jaja-lol\")\n\ntxt = 'jaja---lol-m\u00e9m\u00e9m\u00e9oo--a'\nr = slugify(txt, max_length=15, word_boundary=True)\nself.assertEqual(r, \"jaja-lol-a\")\n\ntxt = 'jaja---lol-m\u00e9m\u00e9m\u00e9oo--a'\nr = slugify(txt, max_length=20, word_boundary=True, separator=\".\")\nself.assertEqual(r, \"jaja.lol.mememeoo.a\")\n\ntxt = 'one two three four five'\nr = slugify(txt, max_length=13, word_boundary=True, save_order=True)\nself.assertEqual(r, \"one-two-three\")\n\ntxt = 'the quick brown fox jumps over the lazy dog'\nr = slugify(txt, stopwords=['the'])\nself.assertEqual(r, 'quick-brown-fox-jumps-over-lazy-dog')\n\ntxt = 'the quick brown fox jumps over the lazy dog in a hurry'\nr = slugify(txt, stopwords=['the', 'in', 'a', 'hurry'])\nself.assertEqual(r, 'quick-brown-fox-jumps-over-lazy-dog')\n\ntxt = 'thIs Has a stopword Stopword'\nr = slugify(txt, stopwords=['Stopword'], lowercase=False)\nself.assertEqual(r, 'thIs-Has-a-stopword')\n\ntxt = \"___This is a test___\"\nregex_pattern = r'[^-a-z0-9_]+'\nr = slugify(txt, regex_pattern=regex_pattern)\nself.assertEqual(r, \"___this-is-a-test___\")\n\ntxt = \"___This is a test___\"\nregex_pattern = r'[^-a-z0-9_]+'\nr = slugify(txt, separator='_', regex_pattern=regex_pattern)\nself.assertNotEqual(r, \"_this_is_a_test_\")\n\ntxt = '10 | 20 %'\nr = slugify(txt, replacements=[['|', 'or'], ['%', 'percent']])\nself.assertEqual(r, \"10-or-20-percent\")\n\ntxt = '\u00dcBER \u00dcber German Umlaut'\nr = slugify(txt, replacements=[['\u00dc', 'UE'], ['\u00fc', 'ue']])\nself.assertEqual(r, \"ueber-ueber-german-umlaut\")\n\ntxt = 'i love \ud83e\udd84'\nr = slugify(txt, allow_unicode=True)\nself.assertEqual(r, \"i-love\")\n\ntxt = 'i love \ud83e\udd84'\nr = slugify(txt, allow_unicode=True, regex_pattern=r'[^\ud83e\udd84]+')\nself.assertEqual(r, \"\ud83e\udd84\")\n\n```\n\nFor more examples, have a look at the [test.py](test.py) file.\n\n# Command Line Options\n\nWith the package, a command line tool called `slugify` is also installed.\n\nIt allows convenient command line access to all the features the `slugify` function supports. Call it with `-h` for help.\n\nThe command can take its input directly on the command line or from STDIN (when the `--stdin` flag is passed):\n\n```\n$ echo \"Taking input from STDIN\" | slugify --stdin\ntaking-input-from-stdin\n```\n\n```\n$ slugify taking input from the command line\ntaking-input-from-the-command-line\n```\n\nPlease 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:\n\n```\n$ slugify --stopwords the in a hurry -- the quick brown fox jumps over the lazy dog in a hurry\nquick-brown-fox-jumps-over-lazy-dog\n```\n\n# Running the tests\n\nTo run the tests against the current environment:\n\n python test.py\n\n# Contribution\n\nPlease read the ([wiki](https://github.com/un33k/python-slugify/wiki/Python-Slugify-Wiki)) page prior to raising any PRs.\n\n# License\n\nReleased under a ([MIT](LICENSE)) license.\n\n### Notes on GPL dependencies\nThough the dependencies may be GPL licensed, `python-slugify` itself is not considered a derivative work and will remain under the MIT license. \nIf 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](https://opensource.org/license/artistic-perl-1-0-2/) instead. Use without concern.\n\n# Version\n\nX.Y.Z Version\n\n `MAJOR` version -- when you make incompatible API changes,\n `MINOR` version -- when you add functionality in a backwards-compatible manner, and\n `PATCH` version -- when you make backwards-compatible bug fixes.\n\n[status-image]: https://github.com/un33k/python-slugify/actions/workflows/ci.yml/badge.svg\n[status-link]: https://github.com/un33k/python-slugify/actions/workflows/ci.yml\n[version-image]: https://img.shields.io/pypi/v/python-slugify.svg\n[version-link]: https://pypi.python.org/pypi/python-slugify\n[coverage-image]: https://coveralls.io/repos/un33k/python-slugify/badge.svg\n[coverage-link]: https://coveralls.io/r/un33k/python-slugify\n[download-image]: https://img.shields.io/pypi/dm/python-slugify.svg\n[download-link]: https://pypi.python.org/pypi/python-slugify\n\n# Sponsors\n\n[Neekware Inc.](http://neekware.com)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python slugify application that also handles Unicode",
"version": "8.0.4",
"project_urls": {
"Homepage": "https://github.com/un33k/python-slugify"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a46202da182e544a51a5c3ccf4b03ab79df279f9c60c5e82d5e8bec7ca26ac11",
"md5": "35c4a1ca7479cbad4b16f285e11986b6",
"sha256": "276540b79961052b66b7d116620b36518847f52d5fd9e3a70164fc8c50faa6b8"
},
"downloads": -1,
"filename": "python_slugify-8.0.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "35c4a1ca7479cbad4b16f285e11986b6",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 10051,
"upload_time": "2024-02-08T18:32:43",
"upload_time_iso_8601": "2024-02-08T18:32:43.911471Z",
"url": "https://files.pythonhosted.org/packages/a4/62/02da182e544a51a5c3ccf4b03ab79df279f9c60c5e82d5e8bec7ca26ac11/python_slugify-8.0.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "87c75e1547c44e31da50a460df93af11a535ace568ef89d7a811069ead340c4a",
"md5": "5fda51099fc7161fc0869d4aac7ccb27",
"sha256": "59202371d1d05b54a9e7720c5e038f928f45daaffe41dd10822f3907b937c856"
},
"downloads": -1,
"filename": "python-slugify-8.0.4.tar.gz",
"has_sig": false,
"md5_digest": "5fda51099fc7161fc0869d4aac7ccb27",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 10921,
"upload_time": "2024-02-08T18:32:45",
"upload_time_iso_8601": "2024-02-08T18:32:45.488675Z",
"url": "https://files.pythonhosted.org/packages/87/c7/5e1547c44e31da50a460df93af11a535ace568ef89d7a811069ead340c4a/python-slugify-8.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-08 18:32:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "un33k",
"github_project": "python-slugify",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "python-slugify"
}
JSON
