python-slugify


Namepython-slugify JSON
Version 8.0.4 PyPI version JSON
download
home_pagehttps://github.com/un33k/python-slugify
SummaryA Python slugify application that also handles Unicode
upload_time2024-02-08 18:32:45
maintainer
docs_urlNone
authorVal Neekman
requires_python>=3.7
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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 &amp; bar -> foo-bar)
  :param decimal (bool): converts html decimal to unicode (&#381; -> Ž -> z)
  :param hexadecimal (bool): converts html hexadecimal to unicode (&#x17D; -> Ž -> 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 &amp; bar -> foo-bar)\n  :param decimal (bool): converts html decimal to unicode (&#381; -> \u017d -> z)\n  :param hexadecimal (bool): converts html hexadecimal to unicode (&#x17D; -> \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"
}
        
Elapsed time: 0.23938s