Skip to content

Commit b6067d1

Browse files
un33kun33k
committed
update readme, add pydoc
1 parent a0cd8fd commit b6067d1

5 files changed

Lines changed: 118 additions & 58 deletions

File tree

‎README.md‎

Lines changed: 87 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -19,82 +19,117 @@ This module, by default installs and uses [text-unidecode](https://github.com/km
1919

2020
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.
2121

22-
2322
How to install
2423
====================
2524
easy_install python-slugify |OR| easy_install python-slugify[unidecode]
2625
-- OR --
2726
pip install python-slugify |OR| pip install python-slugify[unidecode]
2827

28+
Parammeters
29+
===================
30+
```python
31+
def slugify(
32+
text,
33+
entities=True,
34+
decimal=True,
35+
hexadecimal=True,
36+
max_length=0,
37+
word_boundary=False,
38+
separator='-',
39+
save_order=False,
40+
stopwords=(),
41+
regex_pattern=None,
42+
lowercase=True,
43+
replacements=()
44+
):
45+
"""
46+
Make a slug from the given text.
47+
:param text (str): initial text
48+
:param entities (bool): converts html entities to unicode (foo & bar -> foo-bar)
49+
:param decimal (bool): converts html decimal to unicode (Ž -> Ž -> z)
50+
:param hexadecimal (bool): converts html hexadecimal to unicode (Ž -> Ž -> z)
51+
:param max_length (int): output string length
52+
:param word_boundary (bool): truncates to end of full words (length may be shorter than max_length)
53+
:param save_order (bool): if parameter is True and max_length > 0 return whole words in the initial order
54+
:param separator (str): separator between words
55+
:param stopwords (iterable): words to discount
56+
:param regex_pattern (str): regex pattern for allowed characters
57+
:param lowercase (bool): activate case sensitivity by setting it to False
58+
:param replacements (iterable): list of replacement rules e.g. [['|', 'or'], ['%', 'percent']]
59+
:return (str): slugify text
60+
"""
61+
{}
62+
```
63+
2964
How to use
3065
====================
3166

32-
```python
33-
from slugify import slugify
67+
```python
68+
from slugify import slugify
3469

35-
txt = "This is a test ---"
36-
r = slugify(txt)
37-
self.assertEqual(r, "this-is-a-test")
70+
txt = "This is a test ---"
71+
r = slugify(txt)
72+
self.assertEqual(r, "this-is-a-test")
3873

39-
txt = '影師嗎'
40-
r = slugify(txt)
41-
self.assertEqual(r, "ying-shi-ma")
74+
txt = '影師嗎'
75+
r = slugify(txt)
76+
self.assertEqual(r, "ying-shi-ma")
4277

43-
txt = 'C\'est déjà l\'été.'
44-
r = slugify(txt)
45-
self.assertEqual(r, "c-est-deja-l-ete")
78+
txt = 'C\'est déjà l\'été.'
79+
r = slugify(txt)
80+
self.assertEqual(r, "c-est-deja-l-ete")
4681

47-
txt = 'Nín hǎo. Wǒ shì zhōng guó rén'
48-
r = slugify(txt)
49-
self.assertEqual(r, "nin-hao-wo-shi-zhong-guo-ren")
82+
txt = 'Nín hǎo. Wǒ shì zhōng guó rén'
83+
r = slugify(txt)
84+
self.assertEqual(r, "nin-hao-wo-shi-zhong-guo-ren")
5085

51-
txt = 'Компьютер'
52-
r = slugify(txt)
53-
self.assertEqual(r, "kompiuter")
86+
txt = 'Компьютер'
87+
r = slugify(txt)
88+
self.assertEqual(r, "kompiuter")
5489

55-
txt = 'jaja---lol-méméméoo--a'
56-
r = slugify(txt, max_length=9)
57-
self.assertEqual(r, "jaja-lol")
90+
txt = 'jaja---lol-méméméoo--a'
91+
r = slugify(txt, max_length=9)
92+
self.assertEqual(r, "jaja-lol")
5893

59-
txt = 'jaja---lol-méméméoo--a'
60-
r = slugify(txt, max_length=15, word_boundary=True)
61-
self.assertEqual(r, "jaja-lol-a")
94+
txt = 'jaja---lol-méméméoo--a'
95+
r = slugify(txt, max_length=15, word_boundary=True)
96+
self.assertEqual(r, "jaja-lol-a")
6297

63-
txt = 'jaja---lol-méméméoo--a'
64-
r = slugify(txt, max_length=20, word_boundary=True, separator=".")
65-
self.assertEqual(r, "jaja.lol.mememeoo.a")
98+
txt = 'jaja---lol-méméméoo--a'
99+
r = slugify(txt, max_length=20, word_boundary=True, separator=".")
100+
self.assertEqual(r, "jaja.lol.mememeoo.a")
66101

67-
txt = 'one two three four five'
68-
r = slugify(txt, max_length=13, word_boundary=True, save_order=True)
69-
self.assertEqual(r, "one-two-three")
102+
txt = 'one two three four five'
103+
r = slugify(txt, max_length=13, word_boundary=True, save_order=True)
104+
self.assertEqual(r, "one-two-three")
70105

71-
txt = 'the quick brown fox jumps over the lazy dog'
72-
r = slugify(txt, stopwords=['the'])
73-
self.assertEqual(r, 'quick-brown-fox-jumps-over-lazy-dog')
106+
txt = 'the quick brown fox jumps over the lazy dog'
107+
r = slugify(txt, stopwords=['the'])
108+
self.assertEqual(r, 'quick-brown-fox-jumps-over-lazy-dog')
74109

75-
txt = 'the quick brown fox jumps over the lazy dog in a hurry'
76-
r = slugify(txt, stopwords=['the', 'in', 'a', 'hurry'])
77-
self.assertEqual(r, 'quick-brown-fox-jumps-over-lazy-dog')
110+
txt = 'the quick brown fox jumps over the lazy dog in a hurry'
111+
r = slugify(txt, stopwords=['the', 'in', 'a', 'hurry'])
112+
self.assertEqual(r, 'quick-brown-fox-jumps-over-lazy-dog')
78113

79-
txt = 'thIs Has a stopword Stopword'
80-
r = slugify(txt, stopwords=['Stopword'], lowercase=False)
81-
self.assertEqual(r, 'thIs-Has-a-stopword')
114+
txt = 'thIs Has a stopword Stopword'
115+
r = slugify(txt, stopwords=['Stopword'], lowercase=False)
116+
self.assertEqual(r, 'thIs-Has-a-stopword')
82117

83-
txt = "___This is a test___"
84-
regex_pattern = r'[^-a-z0-9_]+'
85-
r = slugify(txt, regex_pattern=regex_pattern)
86-
self.assertEqual(r, "___this-is-a-test___")
118+
txt = "___This is a test___"
119+
regex_pattern = r'[^-a-z0-9_]+'
120+
r = slugify(txt, regex_pattern=regex_pattern)
121+
self.assertEqual(r, "___this-is-a-test___")
87122

88-
txt = "___This is a test___"
89-
regex_pattern = r'[^-a-z0-9_]+'
90-
r = slugify(txt, separator='_', regex_pattern=regex_pattern)
91-
self.assertNotEqual(r, "_this_is_a_test_")
123+
txt = "___This is a test___"
124+
regex_pattern = r'[^-a-z0-9_]+'
125+
r = slugify(txt, separator='_', regex_pattern=regex_pattern)
126+
self.assertNotEqual(r, "_this_is_a_test_")
92127

93-
txt = '10 | 20 %'
94-
r = slugify(txt, replacements=[['|', 'or'], ['%', 'percent']])
95-
self.assertEqual(r, "10-or-20-percent")
128+
txt = '10 | 20 %'
129+
r = slugify(txt, replacements=[['|', 'or'], ['%', 'percent']])
130+
self.assertEqual(r, "10-or-20-percent")
96131

97-
```
132+
```
98133

99134
For more examples, have a look at the [test.py](test.py) file.
100135

@@ -137,4 +172,4 @@ X.Y.Z Version
137172
Sponsors
138173
====================
139174

140-
[![Surge](https://www.surgeforward.com/wp-content/themes/understrap-master/images/logo.png)](https://github.com/surgeforward)
175+
[Surge](https://github.com/surgeforward)

pycodestyle.sh renamed to format.sh

File renamed without changes.

‎slugify/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@
33

44
__author__ = 'Val Neekman @ Neekware Inc. [@vneekman]'
55
__description__ = 'A Python slugify application that also handles Unicode'
6-
__version__ = '3.0.2'
6+
__version__ = '3.0.3'

‎slugify/slugify.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -80,11 +80,11 @@ def slugify(text, entities=True, decimal=True, hexadecimal=True, max_length=0, w
8080
"""
8181
Make a slug from the given text.
8282
:param text (str): initial text
83-
:param entities (bool):
84-
:param decimal (bool):
85-
:param hexadecimal (bool):
83+
:param entities (bool): converts html entities to unicode (foo & bar -> foo-bar)
84+
:param decimal (bool): converts html decimal to unicode (Ž -> Ž -> z)
85+
:param hexadecimal (bool): converts html hexadecimal to unicode (Ž -> Ž -> z)
8686
:param max_length (int): output string length
87-
:param word_boundary (bool):
87+
:param word_boundary (bool): truncates to complete word even if length ends up shorter than max_length
8888
:param save_order (bool): if parameter is True and max_length > 0 return whole words in the initial order
8989
:param separator (str): separator between words
9090
:param stopwords (iterable): words to discount

‎test.py‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,11 +142,36 @@ def test_stopwords_with_different_separator(self):
142142
r = slugify(txt, stopwords=['the'], separator=' ')
143143
self.assertEqual(r, 'quick brown fox jumps over lazy dog')
144144

145-
def test_html_entities(self):
145+
def test_html_entities_on(self):
146146
txt = 'foo & bar'
147147
r = slugify(txt)
148148
self.assertEqual(r, 'foo-bar')
149149

150+
def test_html_entities_off(self):
151+
txt = 'foo & bar'
152+
r = slugify(txt, entities=False)
153+
self.assertEqual(r, 'foo-amp-bar')
154+
155+
def test_html_decimal_on(self):
156+
txt = 'Ž'
157+
r = slugify(txt, decimal=True)
158+
self.assertEqual(r, 'z')
159+
160+
def test_html_decimal_off(self):
161+
txt = 'Ž'
162+
r = slugify(txt, entities=False, decimal=False)
163+
self.assertEqual(r, '381')
164+
165+
def test_html_hexadecimal_on(self):
166+
txt = 'Ž'
167+
r = slugify(txt, hexadecimal=True)
168+
self.assertEqual(r, 'z')
169+
170+
def test_html_hexadecimal_off(self):
171+
txt = 'Ž'
172+
r = slugify(txt, hexadecimal=False)
173+
self.assertEqual(r, 'x17d')
174+
150175
def test_starts_with_number(self):
151176
txt = '10 amazing secrets'
152177
r = slugify(txt)

0 commit comments

Comments
 (0)