Permalink
Browse files

Added docs to slugger module.

  • Loading branch information...
1 parent 10657d4 commit 0e1aee33fb5eef8e71b4403223bf095514a18811 @mbr committed Mar 15, 2012
Showing with 38 additions and 0 deletions.
  1. +38 −0 slugger/__init__.py
View
@@ -1,6 +1,8 @@
#!/usr/bin/env python
# coding=utf8
+"""Main slugger module. See the docstring of Slugger for details."""
+
import bz2
import imp
import re
@@ -122,6 +124,38 @@ def __init__(self,
maxlength=100,
invalid_pattern='[^A-Za-z-]+',
invalid_replacement='-'):
+ """Creates a new configuration for slugging.
+
+ Note that creating Slugger instances can be expensive, if possible it
+ should be avoided to repeat creating these everytime a slug is needed
+ with the same configuration.
+
+ :param lang: The language to use. Expects a language or
+ language_TERRITORY code, like 'de' or 'de_DE' (German,
+ German in Germany) or 'jp_JA' (Japanese in Japan).
+
+ If a language is not found, errors are silently swallowed
+ and the Slugger falls back to a basic default language.
+ :param chain: A chain of operations. Each language comes with a default
+ chain, a list of strings. Upon instantiation,
+ init_CHAINNAME methods are called, while
+ :py:method:`sluggify` will call do_CHAINNAME to do its
+ work.
+ :param hanlang: The language to use for transcribing chinese
+ characters, which are used in numerous asian languages.
+ This is mainly used when you have mixed-language input
+ and want better control, e.g. when having an English
+ text with Kanji mixed in and you want them interpreted
+ as Japanese, not Chinese.
+ :param lowercase: Convert slug to lowercase..
+ :param maxlength: Maximum length. Slugger will cut the slug short,
+ trying to keep words intact if possible.
+ :param invalid_pattern: In the final step, this regular expression is
+ used to find invalid characters which are
+ replaced with *invalid-replacement*.
+ :param invalid_replacement: The replacement for *invalid-pattern*-found
+ characters.
+ """
self.lang = lang
self.hanlang = hanlang
self.lowercase = lowercase
@@ -212,6 +246,10 @@ def init_cleanup(self):
self.invalid_exp = re.compile(self.invalid_pattern)
def sluggify(self, title):
+ """Turn *title* into a slug.
+
+ This will run the whole chain and return the end result of the
+ transformation."""
title = unicode(title)
for process in self.chain:
title = getattr(self, 'do_%s' % process)(title)

0 comments on commit 0e1aee3

Please sign in to comment.