Add helpers; get ready for v0.2 release

CHANGELOG

@@ -6,6 +6,18 @@
    :local:
 
 
+Version 0.2: February 16th, 2013
+================================
+
+**API-breaking changes:**
+
+None
+
+**Changes**
+
+* Added some helper functions for generating data.
+
+
 Version 0.1: September 28th, 2012
 =================================
 

MANIFEST.in

@@ -1,4 +1,5 @@
 include README.rst CHANGELOG LICENSE CONTRIBUTORS
 include requirements*.txt
 include docs/Makefile docs/conf.py
-recursive-include docs *.rst *.py
+include eadred/data/*.txt
+recursive-include docs *.rst *.py

docs/api.rst

@@ -0,0 +1,20 @@
+=====
+ API
+=====
+
+eadred comes with some helper functions for generating random data. If
+they work for you, yay! If not, you can look at the code and write
+your own.
+
+
+.. automodule:: eadred.helpers
+
+   .. autofunction:: make_unique
+
+   .. autofunction:: name_generator
+
+   .. autofunction:: email_generator
+
+   .. autofunction:: sentence_generator
+
+   .. autofunction:: paragraph_generator

docs/conf.py

@@ -26,7 +26,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ['sphinx.ext.autodoc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/index.rst

@@ -23,6 +23,7 @@ Table of Contents
    changelog
    installation
    sampledata
+   api
    hacking_howto
 
 

eadred/_version.py

@@ -3,5 +3,5 @@
 # * 0.3     - released version
 # * 0.3a1   - alpha version
 # * 0.3.dev - version in development
-__version__ = '0.1'
-__releasedate__ = '20120928'
+__version__ = '0.2'
+__releasedate__ = '20130216'

eadred/data/domains.txt

@@ -0,0 +1,7 @@
+example.net
+example.com
+example.org
+mail1.example.org
+foo.example.com
+eadred.example.net
+ednapiranha.example.org

eadred/data/english_monarchs.txt

@@ -0,0 +1,63 @@
+Æthelstan
+Edmund I
+Eadred
+Eadwig
+Edgar the Peaceful
+Edward the Martyr
+Æthelred the Unready
+Sweyn Forkbeard
+Edmund Ironside
+Cnut
+Harold Harefoot
+Harthacnut
+Edward the Confessor
+Harold Godwinson
+Edgar the Ætheling
+William I
+William Rufus
+Henry Beauclerc
+Stephen of Blois
+Matilda
+Henry Curtmantle
+Henry the Young King
+Richard I
+John Lackland
+Louis
+Henry of Winchester
+Edward I
+Edward of Caernarfon
+Edward III
+Richard II
+Henry IV
+Henry V
+Henry VI
+Edward IV
+Edward V
+Richard III
+Henry VII
+Henry VIII
+Edward VI
+Jane
+Mary I
+Philip
+Elizabeth I
+James I
+Charles I
+Oliver Cromwell
+Richard Cromwell
+Charles II
+James II
+Mary II
+William of Orange
+Anne
+George Louis
+George Augustus
+George William Frederick
+George Augustus Frederick
+William Henry
+Alexandrina Victoria
+Albert Edward
+George Frederick Ernest Albert
+Edward Albert Christian George Andrew Patrick David
+Albert Frederick Arthur George
+Elizabeth Alexandra Mary

eadred/data/lorem_ipsum.txt

@@ -0,0 +1,4 @@
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

eadred/helpers.py

@@ -0,0 +1,200 @@
+import os
+import random
+from itertools import count
+
+
+def get_file(fn):
+    """Returns file contents in unicode as list."""
+    fn = os.path.join(os.path.dirname(__file__), 'data', fn)
+    f = open(fn, 'rb')
+    lines = [line.decode('utf-8').strip() for line in f.readlines()]
+    return lines
+
+
+LOREM = get_file('lorem_ipsum.txt')
+ENGLISH_MONARCHS = get_file('english_monarchs.txt')
+DOMAINS = get_file('domains.txt')
+
+
+_unique_counter = count()
+
+
+def reset_counter():
+    global _unique_counter
+    _unique_counter = count()
+
+
+def make_unique(gen):
+    """Wraps a generator to uniquify strings by appending counter
+
+    :arg gen: the generator to wrap
+
+    Example::
+
+        from eadred.helpers import name_generator, make_unique
+
+        gen = make_unique(name_generator())
+        for i in range(50):
+            mymodel = SomeModel(name=gen.next())
+            mymodel.save()
+
+
+    Example 2:
+
+    >>> gen = make_unique(name_generator(['alice', 'jane', 'harry']))
+    >>> gen.next()
+    u'alice0'
+    >>> gen.next()
+    u'harry1'
+    >>> gen.next()
+    u'jane2'
+
+    """
+    while True:
+        yield gen.next() + unicode(_unique_counter.next())
+
+
+def name_generator(names=None):
+    """Creates a generator for generating names.
+
+    :arg sentences:
+
+        list or tuple of sentences you want to use; defaults to
+        ENGLISH_MONARCHS
+
+    :returns: generator for names
+
+    Example::
+
+        from eadred.helpers import name_generator
+
+        gen = name_generator()
+        for i in range(50):
+            mymodel = SomeModel(name=gen.next())
+            mymodel.save()
+
+
+    Example 2:
+
+    >>> gen = name_generator()
+    >>> gen.next()
+    u'James II'
+    >>> gen.next()
+    u'Stephen of Blois'
+    >>> gen.next()
+    u'James I'
+
+    .. Note::
+
+       This gives full names for a "name" field. It's probably not
+       useful for broken down name fields like "firstname",
+       "lastname", etc.
+
+    """
+    if names is None:
+        names = ENGLISH_MONARCHS
+
+    while True:
+        yield unicode(random.choice(names))
+
+
+def email_generator(names=None, domains=None, unique=False):
+    """Creates a generator for generating email addresses.
+
+    :arg names: list of names to use; defaults to ENGLISH_MONARCHS
+        lowercased, ascii-fied, and stripped of whitespace
+
+    :arg domains: list of domains to use; defaults to DOMAINS
+
+    :arg unique: True if you want the username part of the email
+        addresses to be unique
+
+    :returns: generator
+
+    Example::
+
+        from eadred.helpers import email_generator
+
+        gen = email_generator()
+        for i in range(50):
+            mymodel = SomeModel(email=gen.next())
+            mymodel.save()
+
+
+    Example 2:
+
+    >>> gen = email_generator()
+    >>> gen.next()
+    'eadwig@example.net'
+    >>> gen.next()
+    'henrybeauclerc@mail1.example.org'
+    >>> gen.next()
+    'williamrufus@example.com'
+
+    """
+    if names is None:
+        names = [name.encode('ascii', 'ignore').lower().replace(' ', '')
+                 for name in ENGLISH_MONARCHS]
+    if domains is None:
+        domains = DOMAINS
+
+    if unique:
+        uniquifyer = lambda: str(_unique_counter.next())
+    else:
+        uniquifyer = lambda: ''
+
+    while True:
+        yield '{0}{1}@{2}'.format(
+            random.choice(names), uniquifyer(), random.choice(domains))
+
+
+def sentence_generator(sentences=None):
+    """Creates a generator for generating sentences.
+
+    :arg sentences: list or tuple of sentences you want to use;
+        defaults to LOREM
+
+    :returns: generator
+
+    Example::
+
+        from eadred.helpers import sentence_generator
+
+        gen = sentence_generator()
+        for i in range(50):
+            mymodel = SomeModel(summary=gen.next())
+            mymodel.save()
+
+    """
+    if sentences is None:
+        sentences = LOREM
+    while True:
+        yield random.choice(sentences)
+
+
+def paragraph_generator(sentences=None):
+    """Creates a generator for generating paragraphs.
+
+    :arg sentences: list or tuple of sentences you want to use;
+        defaults to LOREM
+
+    :returns: generator
+
+    Example::
+
+        from eadred.helpers import paragraph_generator
+
+        gen = paragraph_generator()
+        for i in range(50):
+            mymodel = SomeModel(description=gen.next())
+            mymodel.save()
+
+    """
+    if sentences is None:
+        sentences = LOREM
+
+    while True:
+        # Paragraph consists of 1-7 sentences.
+        paragraph = [random.choice(sentences)
+                     for num in range(random.randint(1, 7))]
+        yield u' '.join(paragraph)