• Stars
    star
    1,444
  • Rank 31,281 (Top 0.7 %)
  • Language
    Python
  • License
    MIT License
  • Created over 11 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Returns unicode slugs

Python Slugify

A Python slugify application that handles unicode.

status-image version-image coverage-image

Overview

Best attempt to create slugs from unicode strings while keeping it DRY.

Notice

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.

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

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

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 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) page prior to raising any PRs.

License

Released under a (MIT) 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 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.

Sponsors

Neekware Inc.

More Repositories

1

django-ipware

A Django application to retrieve client's IP address
Python
923
star
2

django-uuslug

Generates Unique (& Unicode) slugs in Django Edit Add topics
Python
273
star
3

node-ipware

Returns the real IP address of users in Node.js
JavaScript
124
star
4

python-emailahoy

Checks if an email address is real
Python
104
star
5

django-bootup

NO LONGER MAINTAINED
Python
30
star
6

django-finalware

A utility application that automates the bootstrapping of a Django-powered site
Python
16
star
7

django-geoaware

Django GeoAware provides a middleware as well as a context processor for including GeoIP related info in the session and/or the context of your application.
Python
15
star
8

django-freshly

Forces clients to reload static contents. (.js, .css, img)
Python
10
star
9

django-emailmgr

A Django application that manages multiple email addresses for a given user
Python
10
star
10

impacket

Automatically exported from code.google.com/p/impacket
Python
8
star
11

django-menuware

A powerful, yet simple to use menu generator for Django.
Python
8
star
12

python-ipware

Returns the best matched IP address from a given HTTP(s) header in Python
Python
6
star
13

django-toolware

A utility application that offers the most commonly-used tools and mixins.
Python
6
star
14

django-geoware

A Django application for handling geo related data while keeping it DRY
Python
5
star
15

django-worldwide

All Cities, States, Countries in the world in one app
Python
4
star
16

python-wikiware

Extracts summary data from Wikipedia
Python
3
star
17

django-countryware

A Django application that provides translated country names
Python
2
star
18

outsourcefactor

A Django application for building outsourcing sites.
Python
2
star
19

django-aweber

An Aweber based user-signup application for Django
Python
2
star
20

env

Shell
2
star
21

python-cloudy

A Line Interpreter for Server Configuration - Fabric / Python
Python
2
star
22

django-userware

A Django application for handling user management
Python
2
star
23

nw-nwlogger

Simple Python Logger Helper, can be used in Django
Python
1
star
24

test_1

test
1
star
25

djangoware

A Generic Django Project Template
Python
1
star
26

nw-nwgeolocation

Fetch Lat/Long of a location from Google API
Python
1
star
27

django-xlate

A Django Utility to automatically translate your project via Google API
1
star
28

django-authentico

A Django reusable app that allows email login and uuid while keeping the admin intact
Python
1
star
29

django-allauth

Integrated set of Django applications addressing authentication, registration, account management as well as 3rd party (social) account authentication. Visit http://jug.gl for a live demo ...
Python
1
star