# HG changeset patch # User Gustavo Picon # Date 1274675690 18000 # Node ID d172847043a4ca7effd460bfb6f0591044a2564b # Parent 8b43a8b64ef88c26acc349222ee64b0d316bde4c cleaning up and updating docs diff -r 8b43a8b64ef88c26acc349222ee64b0d316bde4c -r d172847043a4ca7effd460bfb6f0591044a2564b docs/api.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api.rst Sun May 23 23:34:50 2010 -0500 @@ -0,0 +1,53 @@ +API +=== + +.. module:: tagtools +.. moduleauthor:: Gustavo Picon + +.. inheritance-diagram:: Serializer +.. autoclass:: Serializer + :show-inheritance: + + Provides methods to subclass tagging serializers. + + Must not be used directly, use a subclass (:class:`FlickrSerializer`, + :class:`DeliciousSerializer` or :class:`CommaSerializer`) instead. + + The subclasses are not designed to be instantiated, they contains only + class and static methods. + + .. automethod:: str2tags + + .. note:: + + If more than one tag have the same normalized form, only the first + tag will be included in the resulting list. So for instance, if + using the :class:`CommaSerializer` subclass:: + + CommaSerializer.str2tags("TaG, tag, TAG") + + would return:: + + [('tag', 'TaG')] + + .. automethod:: tags2str + + .. note:: + + The use case for this method is when a program needs to + provide a user interface for the user to edit the tags, and + the user interface is a single input entry. + + .. automethod:: normalize + + .. note:: + + By default, all Serializers will call `.lower()` on the + given `tag`. You can change this behavior either by + further subclassing or composition, like:: + + class MySerializer(CommaSerializer): + + @staticmethod + def normalize(tag): + return tag.upper() diff -r 8b43a8b64ef88c26acc349222ee64b0d316bde4c -r d172847043a4ca7effd460bfb6f0591044a2564b docs/comma.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/comma.rst Sun May 23 23:34:50 2010 -0500 @@ -0,0 +1,25 @@ +CommaSerializer +=============== + +.. currentmodule:: tagtools +.. moduleauthor:: Gustavo Picon + +.. inheritance-diagram:: CommaSerializer +.. autoclass:: CommaSerializer + :show-inheritance: + + Example:: + + CommaSerializer.str2tags('Tag 1, Tag2, TAG 1, Tag3') + + returns:: + + [('tag 1', 'Tag 1'), ('tag2', 'Tag2'), ('tag3', 'Tag3')] + + and:: + + CommaSerializer.tags2str(['tag1', 'tag2', 'tag3']) + + returns:: + + 'tag1, tag2, tag3' diff -r 8b43a8b64ef88c26acc349222ee64b0d316bde4c -r d172847043a4ca7effd460bfb6f0591044a2564b docs/conf.py --- a/docs/conf.py Sun May 16 20:49:12 2010 -0500 +++ b/docs/conf.py Sun May 23 23:34:50 2010 -0500 @@ -22,7 +22,8 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.graphviz', + 'sphinx.ext.inheritance_diagram'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff -r 8b43a8b64ef88c26acc349222ee64b0d316bde4c -r d172847043a4ca7effd460bfb6f0591044a2564b docs/delicious.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/delicious.rst Sun May 23 23:34:50 2010 -0500 @@ -0,0 +1,25 @@ +DeliciousSerializer +=================== + +.. currentmodule:: tagtools +.. moduleauthor:: Gustavo Picon + +.. inheritance-diagram:: DeliciousSerializer +.. autoclass:: DeliciousSerializer + :show-inheritance: + + Example:: + + DeliciousSerializer.str2tags('Tag1 Tag2 TAG1 Tag3') + + returns:: + + [('tag1', 'Tag1'), ('tag2', 'Tag2'), ('tag3', 'Tag3')] + + and:: + + DeliciousSerializer.tags2str(['tag1', 'tag2', 'tag3']) + + returns:: + + 'tag1 tag2 tag3' diff -r 8b43a8b64ef88c26acc349222ee64b0d316bde4c -r d172847043a4ca7effd460bfb6f0591044a2564b docs/flickr.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/flickr.rst Sun May 23 23:34:50 2010 -0500 @@ -0,0 +1,31 @@ +FlickrSerializer +================ + +.. currentmodule:: tagtools +.. moduleauthor:: Gustavo Picon + +.. inheritance-diagram:: FlickrSerializer +.. autoclass:: FlickrSerializer + :show-inheritance: + + Example:: + + FlickrSerializer.str2tags('"Tag 1" Tag2 "TAG 1" Tag3') + + returns:: + + [('tag 1', 'Tag 1'), ('tag2', 'Tag2'), ('tag3', 'Tag3')] + + and:: + + FlickrSerializer.tags2str(['tag 1', 'tag2', 'tag3']) + + returns:: + + '"tag 1" tag2 tag3' + + .. note:: + + Flickr tags are very... peculiar. The test suite has lot of weird + cases and they all work exactly like Flickr. Please let me know if + there is a corner case I'm not covering. diff -r 8b43a8b64ef88c26acc349222ee64b0d316bde4c -r d172847043a4ca7effd460bfb6f0591044a2564b docs/index.rst --- a/docs/index.rst Sun May 16 20:49:12 2010 -0500 +++ b/docs/index.rst Sun May 23 23:34:50 2010 -0500 @@ -1,32 +1,36 @@ tagtools ======== -.. automodule:: tagtools +`tagtools `_ is a python library that +parses raw strings with tags into a list of tags and viceversa, written by +`Gustavo Picón `_ and licensed under the Apache License 2.0. - .. autoclass:: Serializer - :show-inheritance: +``tagtools`` is: - .. automethod:: str2tags - .. automethod:: tags2str - .. automethod:: normalize +- **Flexible**: Includes 3 different tag implementations with the same API: + 1. Flickr (:class:`FlickrSerializer`) + 2. Delicious (:class:`DeliciousSerializer`) + 3. Comma separated tags (:class:`CommaSerializer`) - .. autoclass:: FlickrSerializer - :show-inheritance: - - .. autoclass:: DeliciousSerializer - :show-inheritance: - - .. autoclass:: CommaSerializer - :show-inheritance: +- **Customizable**: Handles customizable per-tag normalization to avoid + tag duplicates. +- **Easy**: Simple :doc:`API ` +- **Clean**: Testable and well tested code base. 100% code/branch test + coverage. Contents -======== +-------- .. toctree:: :maxdepth: 2 + api + flickr + delicious + comma + Indices and tables ================== diff -r 8b43a8b64ef88c26acc349222ee64b0d316bde4c -r d172847043a4ca7effd460bfb6f0591044a2564b tagtools.py --- a/tagtools.py Sun May 16 20:49:12 2010 -0500 +++ b/tagtools.py Sun May 23 23:34:50 2010 -0500 @@ -1,44 +1,8 @@ -""" - -tagtools --------- - -:synopsys: Python helpers to work with tags. -:copyright: 2010 by Gustavo Picon -:license: Apache License 2.0 -:version: 0.8b -:url: http://code.tabo.pe/tagtools/ -:documentation: - `tagtools-docs - `_ -:examples: - `tagtools-tests - `_ - -Python library that parses raw strings with tags into a list of tags and -viceversa. - -Includes the tag parsing methods used in Flickr (:class:`FlickrSerializer`), -Delicious (:class:`DeliciousSerializer`) and tag separation with commas -(:class:`CommaSerializer`). - -Handles customizable per-tag normalization to avoid tag duplicates. - -""" - __version__ = '0.8b' class Serializer(object): - """ Provides methods to subclass tagging serializers. - - Must not be used directly, use a subclass (:class:`FlickrSerializer`, - :class:`DeliciousSerializer` or :class:`CommaSerializer`) instead. - - The subclasses are not designed to be instantiated, they contains only - class and static methods. - """ SEPARATOR = JOINER = TAGS_WITH_SPACES = None @classmethod @@ -54,19 +18,6 @@ :meth:`normalize` static method. - The raw tag as was entered, but without leading/trailing whitespace. - - .. note:: - - If more than one tag have the same normalized form, only the first - tag will be included in the resulting list. So for instance, if - using the :class:`CommaSerializer` subclass:: - - CommaSerializer.str2tags("TaG, tag, TAG") - - would return:: - - [('tag', 'TaG')] - """ if not tagstr: return [] @@ -97,13 +48,6 @@ * if a tag has a space when using :class:`DeliciousSerializer`, or * a tag has a comma when using :class:`CommaSerializer` - - .. note:: - - The use case for this method is when a program needs to - provide a user interface for the user to edit the tags, and - the user interface is a single input entry. - """ results = [] for tag in tags: @@ -121,18 +65,6 @@ no leading/trailing whitespace. :returns: A normalized version of the tag. - - .. note:: - - By default, all Serializers will call `.lower()` on the - given `tag`. You can change this behavior either by - further subclassing or composition, like:: - - class MySerializer(CommaSerializer): - - @staticmethod - def normalize(tag): - return tag.upper() """ return tag.lower() @@ -143,22 +75,6 @@ Delicious tags are separated by spaces, and don't allow spaces in a tag. Tags are normalized as lowercase by default to avoid tag duplication. - - Example:: - - DeliciousSerializer.str2tags('Tag1 Tag2 TAG1 Tag3') - - returns:: - - [('tag1', 'Tag1'), ('tag2', 'Tag2'), ('tag3', 'Tag3')] - - and:: - - DeliciousSerializer.tags2str(['tag1', 'tag2', 'tag3']) - - returns:: - - 'tag1 tag2 tag3' """ SEPARATOR = JOINER = ' ' TAGS_WITH_SPACES = False @@ -170,22 +86,6 @@ Comma separated tags don't allow commas in a tag. Tags are normalized as lowercase by default to avoid tag duplication. - - Example:: - - CommaSerializer.str2tags('Tag 1, Tag2, TAG 1, Tag3') - - returns:: - - [('tag 1', 'Tag 1'), ('tag2', 'Tag2'), ('tag3', 'Tag3')] - - and:: - - CommaSerializer.tags2str(['tag1', 'tag2', 'tag3']) - - returns:: - - 'tag1, tag2, tag3' """ SEPARATOR = ',' JOINER = ', ' @@ -199,28 +99,6 @@ enclosed with double quotes. Tags are normalized as lowercase by default to avoid tag duplication. - - Example:: - - FlickrSerializer.str2tags('"Tag 1" Tag2 "TAG 1" Tag3') - - returns:: - - [('tag 1', 'Tag 1'), ('tag2', 'Tag2'), ('tag3', 'Tag3')] - - and:: - - FlickrSerializer.tags2str(['tag 1', 'tag2', 'tag3']) - - returns:: - - '"tag 1" tag2 tag3' - - .. note:: - - Flickr tags are very... peculiar. The test suite has lot of weird - cases and they all work exactly like Flickr. Please let me know if - there is a corner case I'm not covering. """ SEPARATOR = ' '