From b6067d10fc140d30d5d8860f28758e56faa59b4e Mon Sep 17 00:00:00 2001 From: Val Neekman Date: Sat, 27 Jul 2019 22:39:01 -0400 Subject: update readme, add pydoc --- README.md | 139 ++++++++++++++++++++++++++++++++-------------------- format.sh | 13 +++++ pycodestyle.sh | 13 ----- slugify/__init__.py | 2 +- slugify/slugify.py | 8 +-- test.py | 27 +++++++++- 6 files changed, 131 insertions(+), 71 deletions(-) create mode 100755 format.sh delete mode 100755 pycodestyle.sh diff --git a/README.md b/README.md index 13c94a7..78c22d1 100644 --- a/README.md +++ b/README.md @@ -19,82 +19,117 @@ This module, by default installs and uses [text-unidecode](https://github.com/km 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. - How to install ==================== easy_install python-slugify |OR| easy_install python-slugify[unidecode] -- OR -- pip install python-slugify |OR| pip install python-slugify[unidecode] +Parammeters +=================== +```python +def slugify( + text, + entities=True, + decimal=True, + hexadecimal=True, + max_length=0, + word_boundary=False, + separator='-', + save_order=False, + stopwords=(), + regex_pattern=None, + lowercase=True, + replacements=() + ): + """ + 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 allowed characters + :param lowercase (bool): activate case sensitivity by setting it to False + :param replacements (iterable): list of replacement rules e.g. [['|', 'or'], ['%', 'percent']] + :return (str): slugify text + """ + {} +``` + How to use ==================== - ```python - from slugify import slugify +```python +from slugify import slugify - txt = "This is a test ---" - r = slugify(txt) - self.assertEqual(r, "this-is-a-test") +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) +self.assertEqual(r, "ying-shi-ma") - txt = 'C\'est déjà l\'été.' - r = slugify(txt) - self.assertEqual(r, "c-est-deja-l-ete") +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 = '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 = 'Компьютер' +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=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=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 = '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 = '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' +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 = '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 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, 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 = "___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 = '10 | 20 %' +r = slugify(txt, replacements=[['|', 'or'], ['%', 'percent']]) +self.assertEqual(r, "10-or-20-percent") - ``` +``` For more examples, have a look at the [test.py](test.py) file. @@ -137,4 +172,4 @@ X.Y.Z Version Sponsors ==================== -[![Surge](https://www.surgeforward.com/wp-content/themes/understrap-master/images/logo.png)](https://github.com/surgeforward) +[Surge](https://github.com/surgeforward) diff --git a/format.sh b/format.sh new file mode 100755 index 0000000..cd6122d --- /dev/null +++ b/format.sh @@ -0,0 +1,13 @@ +#!/bin/bash + +# Ignoring autogenerated files +# -- Migration directories +# Ignoring error codes +# -- E128 continuation line under-indented for visual indent +# -- E261 at least two spaces before inline comment +# -- E225 missing whitespace around operator +# -- E501 line too long +# Ignoring warning codes +# -- W605 invalid escape sequence '\d' + +pycodestyle --ignore=E128,E261,E225,E501,W605 slugify test.py setup.py diff --git a/pycodestyle.sh b/pycodestyle.sh deleted file mode 100755 index cd6122d..0000000 --- a/pycodestyle.sh +++ /dev/null @@ -1,13 +0,0 @@ -#!/bin/bash - -# Ignoring autogenerated files -# -- Migration directories -# Ignoring error codes -# -- E128 continuation line under-indented for visual indent -# -- E261 at least two spaces before inline comment -# -- E225 missing whitespace around operator -# -- E501 line too long -# Ignoring warning codes -# -- W605 invalid escape sequence '\d' - -pycodestyle --ignore=E128,E261,E225,E501,W605 slugify test.py setup.py diff --git a/slugify/__init__.py b/slugify/__init__.py index 0859113..c351e2e 100644 --- a/slugify/__init__.py +++ b/slugify/__init__.py @@ -3,4 +3,4 @@ from .slugify import * __author__ = 'Val Neekman @ Neekware Inc. [@vneekman]' __description__ = 'A Python slugify application that also handles Unicode' -__version__ = '3.0.2' +__version__ = '3.0.3' diff --git a/slugify/slugify.py b/slugify/slugify.py index fcd1d22..f9bd23d 100644 --- a/slugify/slugify.py +++ b/slugify/slugify.py @@ -80,11 +80,11 @@ def slugify(text, entities=True, decimal=True, hexadecimal=True, max_length=0, w """ Make a slug from the given text. :param text (str): initial text - :param entities (bool): - :param decimal (bool): - :param hexadecimal (bool): + :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): + :param word_boundary (bool): truncates to complete word even if length ends up 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 diff --git a/test.py b/test.py index 78b1956..e1efe38 100644 --- a/test.py +++ b/test.py @@ -142,11 +142,36 @@ class TestSlugification(unittest.TestCase): r = slugify(txt, stopwords=['the'], separator=' ') self.assertEqual(r, 'quick brown fox jumps over lazy dog') - def test_html_entities(self): + def test_html_entities_on(self): txt = 'foo & bar' r = slugify(txt) self.assertEqual(r, 'foo-bar') + def test_html_entities_off(self): + txt = 'foo & bar' + r = slugify(txt, entities=False) + self.assertEqual(r, 'foo-amp-bar') + + def test_html_decimal_on(self): + txt = 'Ž' + r = slugify(txt, decimal=True) + self.assertEqual(r, 'z') + + def test_html_decimal_off(self): + txt = 'Ž' + r = slugify(txt, entities=False, decimal=False) + self.assertEqual(r, '381') + + def test_html_hexadecimal_on(self): + txt = 'Ž' + r = slugify(txt, hexadecimal=True) + self.assertEqual(r, 'z') + + def test_html_hexadecimal_off(self): + txt = 'Ž' + r = slugify(txt, hexadecimal=False) + self.assertEqual(r, 'x17d') + def test_starts_with_number(self): txt = '10 amazing secrets' r = slugify(txt) -- cgit v1.2.1