Metadata-Version: 2.1
Name: python-lorem
Version: 0.1.0rc1
Summary: Lorem ipsum generator
Home-page: https://github.com/JarryShaw/lorem
Author: Jarry Shaw
Author-email: jarryshaw@icloud.com
License: BSD License
Description: # Lorem ipsum generator
        
        [![PyPI - Downloads](https://pepy.tech/badge/python-lorem)](https://pepy.tech/count/python-lorem)
        [![PyPI - Version](https://img.shields.io/pypi/v/python-lorem.svg)](https://pypi.org/project/python-lorem)
        [![PyPI - Format](https://img.shields.io/pypi/format/python-lorem.svg)](https://pypi.org/project/python-lorem)
        [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/python-lorem.svg)](https://pypi.org/project/python-lorem)
        
        [![Travis CI - Status](https://travis-ci.com/JarryShaw/lorem.svg)](https://travis-ci.org/JarryShaw/lorem)
        [![Codecov - Coverage](https://codecov.io/gh/JarryShaw/lorem/branch/master/graph/badge.svg)](https://codecov.io/gh/JarryShaw/lorem)
        [![License](https://img.shields.io/github/license/jarryshaw/lorem.svg)](https://opensource.org/licenses/BSD-3-Clause)
        [![LICENSE](https://img.shields.io/badge/license-Anti%20996-blue.svg)](https://github.com/996icu/996.ICU/blob/master/LICENSE)
        
        * [Installation](#installation)
        * [Usage](#usage)
          * [Get random words](#get-random-words)
            * [`word` -- renerate a list of random words](#word)
            * [`get_word`-- return random words](#get_word)
          * [Get random sentences](#get-random-sentences)
            * [`sentence` -- renerate a list of random sentences](#sentence)
            * [`get_sentence`-- return random sentences](#get_sentence)
          * [Get random paragraphs](#get-random-paragraphs)
            * [`paragraph` -- renerate a list of random paragraphs](#paragraph)
            * [`get_paragraph`-- return random paragraphs](#get_paragraph)
          * [Internal APIs](#internal-apis)
            * [`_TEXT` -- original *lorem ipsum* text pool](#_text)
            * [`_gen_word` -- generate random word](#_gen_word)
            * [`_gen_sentence` -- generate random sentence](#_gen_sentence)
            * [`_gen_paragraph` -- generate random paragraph](#_gen_paragraph)
        * [Testing](#testing)
        
        -------------------------------------------------------------------------------
        
        In publishing and graphic design, *lorem ipsum* is a placeholder text commonly
        used to demonstrate the visual form of a document or a typeface without
        relying on meaningful content.
        
        The `lorem` module provides a generic access to generating the *lorem ipsum*
        text from its very original text:
        
        > Lorem ipsum dolor sit amet, consectetur adipiscing 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.
        
        ## Installation
        
        > Note that the `lorem` module only supports Python versions __since 3.3__ 🐍
        
        Simply run the following to install the current version from PyPI:
        
        ```sh
        pip install python-lorem
        ```
        
        Or install the latest version from the git repository:
        
        ```sh
        git clone https://github.com/JarryShaw/lorem.git
        cd lorem
        pip install -e .
        # and to update at any time
        git pull
        ```
        
        ## Usage
        
        Usage of the `lorem` module is rather simple. Depending on your needs, the
        `lorem` module provides generation of **word**s, **sentence**s, and
        **paragraph**s.
        
        ### Get random words
        
        The `lorem` module provides two different ways for getting random words.
        
        <a name="word" />
        
        1. ```python
           def word(count=1, func=None, args=[], kwargs={}) -> Iterable[str]: ...
           ```
        
           Generate a list of random words.
        
           ```python
           >>> list(word(count=3))
           ['labore', 'tempor', 'commodo']
           >>> list(word(count=3, func='capitalize'))
           ['Ea', 'Lorem', 'Do']
           >>> list(word(count=3, func=lambda s: s.upper()))
           ['UT', 'AMET', 'EXCEPTEUR']
           ```
        
           - Args:
        
             * `count` -- `int`
        
               Number of random words.
        
               *default*: `1`
        
             * `func` -- `Optional[Union[str, Callable[[str], str]]]`
        
               Filter function. It can be an attribute name of `str`, or a customised
               function that takes the original `str` and returns the modified `str`.
        
               *default*: `None`
        
             * `args` -- `List[str]`
        
               Additional positional arguments for `func`.
        
               *default*: `[]`
        
             * `kwargs` -- `Dict[str, Any]`
        
               Additional keyword arguments for `func`.
        
               *default*: `{}`
        
           - Returns:
        
             * `Iterable[str]` -- random words generator
        
        <a name="get_word" />
        
        2. ```python
           def get_word(count=1, sep=' ', func=None, args=[], kwargs={}) -> str: ...
           ```
        
           Return random words.
        
           ```python
           >>> get_word(count=3)
           'anim voluptate non'
           >>> get_word(count=3, func='capitalize')
           'Non Labore Ut'
           >>> get_word(count=3, func=lambda s: s.upper())
           'NISI TEMPOR CILLUM'
           ```
        
           - Args:
        
             * `count` -- `Union[int, Tuple[int]]`
        
               Number of random words. To generate random number of words, supply a
               2-element tuple of `int`, the function will use `random.randint` to choose
               a random integer as the number of random words.
        
               *default*: `1`
        
             * `sep` -- `str`
        
               Seperator between each word.
        
               *default*: `' '`
        
             * `func` -- `Optional[Union[str, Callable[[str], str]]]`
        
               Filter function. It can be a function name of `str`, or a customised
               function that takes the original `str` and returns the modified `str`.
        
               *default*: `None`
        
             * `args` -- `List[str]`
        
               Additional positional arguments for `func`.
        
               *default*: `[]`
        
             * `kwargs` -- `Dict[str, Any]`
        
               Additional keyword arguments for `func`.
        
               *default*: `{}`
        
           - Returns:
        
             * `str` -- random words
        
        ### Get random sentences
        
        The `lorem` module provides two different ways for getting random sentences.
        
        <a name="sentence" />
        
        1. ```python
           def sentence(count=1, comma=(0, 2), word_range=(4, 8)) -> Iterable[str]: ...
           ```
        
           Generate a list of random sentences.
        
           ```python
           >>> list(sentence())
           ['Aute irure et commodo sunt do duis dolor.']
           ```
        
           - Args:
        
             * `count` -- `int`
        
               Number of random sentences.
        
               *default*: `1`
        
             * `comma` -- `Tuple[int]`
        
               Random range for number of commas. The function will use
               `random.randint` to choose a random integer as the number of commas.
        
               *default*: `(0, 2)`
        
             * `word_range` -- `Tuple[int]`
        
               Random range for number of words in each sentence. The function will
               use `random.randint` to choose a random integer as the number of words.
        
               *default*: `(4, 8)`
        
           - Returns:
        
             * `Iterable[str]` -- random sentence generator
        
        <a name="get_sentence" />
        
        2. ```python
           def get_sentence(count=1, comma=(0, 2), word_range=(4, 8), sep=' ') -> Union[str]: ...
           ```
        
           Return random sentences.
        
           ```python
           >>> get_sentence()
           'Nostrud laboris lorem minim sit culpa, aliqua nostrud in amet, sint pariatur eiusmod esse.'
           ```
        
           - Args:
        
             * `count` -- `Union[int, Tuple[int]]`
        
               Number of random sentences. To generate random number of sentences,
               supply a 2-element tuple of `int`, the function will use
               `random.randint` to choose a random integer as the number of random
               sentences.
        
               *default*: `1`
        
             * `comma` -- `Tuple[int]`
        
               Random range for number of commas. The function will use
               `random.randint` to choose a random integer as the number of commas.
        
               *default*: `(0, 2)`
        
             * `word_range` -- `Tuple[int]`
        
               Random range for number of words in each sentence. The function will
               use `random.randint` to choose a random integer as the number of words.
        
               *default*: `(4, 8)`
        
             * `sep` -- `str`
        
               Seperator between each sentence.
        
               *default*: `' '`
        
           - Returns:
        
             * `str` -- random sentences
        
        
        ### Get random paragraphs
        
        The `lorem` module provides two different ways for getting random paragraphs.
        
        <a name="paragraph" />
        
        1. ```python
           def paragraph(count=1, comma=(0, 2), word_range=(4, 8), sentence_range=(5, 10)) -> Iterable[str]: ...
           ```
        
           Generate a list of random paragraphs.
        
           ```python
           >>> list(paragraph())
           ['Aute sint et cupidatat aliquip. Non exercitation est aliquip voluptate '
            'fugiat, reprehenderit ad occaecat laboris velit consequat. Magna enim '
            'deserunt aute laborum fugiat exercitation. Aliqua ex sunt fugiat in '
            'magna voluptate. Elit nisi exercitation nostrud. Magna proident et '
            'fugiat eiusmod cupidatat fugiat, sit culpa fugiat non ea eu '
            'reprehenderit elit. Proident mollit mollit ut cillum. Nostrud voluptate '
            'aliquip cupidatat anim.']
           ```
        
           - Args:
        
             * `count` -- `int`
        
               Number of random paragraphs.
        
               *default*: `1`
        
             * `comma` -- `Tuple[int]`
        
               Random range for number of commas. The function will use
               `random.randint` to choose a random integer as the number of commas.
        
               *default*: `(0, 2)`
        
             * `word_range` -- `Tuple[int]`
        
               Random range for number of words in each sentence. The function will
               use `random.randint` to choose a random integer as the number of words.
        
               *default*: `(4, 8)`
        
             * `sentence_range` -- `Tuple[int]`
        
               Random range for number of sentences in each paragraph. The function
               will use `random.randint` to choose a random integer as the number of
               sentences.
        
               *default*: `(5, 10)`
        
           - Returns:
        
             * `Iterable[str]` -- random paragraph generator
        
        <a name="get_paragraph" />
        
        2. ```python
           def get_paragraph(count=1, comma=(0, 2), word_range=(4, 8), sentence_range=(5, 10)) -> Union[str]: ...
           ```
        
           Return random paragraphs.
        
           ```python
           >>> get_paragraph()
           'Exercitation magna sunt excepteur irure adipiscing commodo duis. Est '
           'ipsum qui deserunt, deserunt nostrud reprehenderit esse. Do velit '
           'est in velit sed. Sunt officia officia lorem. Commodo lorem '
           'exercitation veniam officia pariatur velit. Deserunt deserunt sed '
           'consequat laborum consequat dolor. Et consectetur irure sint elit tempor,'
           ' est minim nisi eiusmod id excepteur. Minim cillum veniam sed aliquip '
           'anim sit, pariatur nostrud ex cillum laboris laborum. Laborum ullamco '
           'mollit elit. Amet id incididunt ipsum sed.'
           ```
        
           - Args:
        
             * `count` -- `int`
        
               Number of random paragraphs. To generate random number of paragraphs,
               supply a 2-element tuple of `int`, the function will use
               `random.randint` to choose a random integer as the number of random
               paragraphs.
        
               *default*: `1`
        
             * `comma` -- `Tuple[int]`
        
               Random range for number of commas. The function will use
               `random.randint` to choose a random integer as the number of commas.
        
               *default*: `(0, 2)`
        
             * `word_range` -- `Tuple[int]`
        
               Random range for number of words in each sentence. The function will
               use `random.randint` to choose a random integer as the number of words.
        
               *default*: `(4, 8)`
        
             * `sentence_range` -- `Tuple[int]`
        
               Random range for number of sentences in each paragraph. The function
               will use `random.randint` to choose a random integer as the number of
               sentences.
        
               *default*: `(5, 10)`
        
             * `sep` -- `str`
        
               Seperator between each paragraph.
        
               *default*: `' '`
        
           - Returns:
        
             * `str` -- random paragraphs
        
        ### Internal APIs
        
        Following are internal APIs for the `lorem` module.
        
        <a name="_text" />
        
        1. ```python
           _TEXT: Tuple[str] = ('ad', 'adipiscing', 'aliqua', 'aliquip', 'amet', 'anim', 'aute', 'cillum', 'commodo',
                                'consectetur', 'consequat', 'culpa', 'cupidatat', 'deserunt', 'do', 'dolor', 'dolore',
                                'duis', 'ea', 'eiusmod', 'elit', 'enim', 'esse', 'est', 'et', 'eu', 'ex', 'excepteur',
                                'exercitation', 'fugiat', 'id', 'in', 'incididunt', 'ipsum', 'irure', 'labore', 'laboris',
                                'laborum', 'lorem', 'magna', 'minim', 'mollit', 'nisi', 'non', 'nostrud', 'nulla',
                                'occaecat', 'officia', 'pariatur', 'proident', 'qui', 'quis', 'reprehenderit', 'sed',
                                'sint', 'sit', 'sunt', 'tempor', 'ullamco', 'ut', 'velit', 'veniam', 'voluptate')
           ```
        
           Original *lorem ipsum* text pool.
        
        <a name="_gen_pool" />
        
        2. ```python
           def _gen_pool(dupe=1) -> Iterable[str]: ...
           ```
        
           Generate word pool.
        
           - Args:
        
             * `dupe` -- `int`
        
               Duplication to generate the word pool.
        
               *default*: `1`
        
           - Returns
        
             * `Iterable[str]` -- an infinite loop word pool
        
        <a name="_gen_word" />
        
        3. ```python
           def _gen_word(pool, func, args=[], kwargs={}) -> str: ...
           ```
        
           Generate random word.
        
           - Args:
        
             * `pool` -- `Iterable[str]`
        
               Word pool, returned by `_gen_pool`.
        
             * `func` -- `Optional[Union[str, Callable[[str], str]]]`
        
               Filter function. It can be an attribute name of `str`, or a customised
               function that takes the original `str` and returns the modified `str`.
        
             * `args` -- `List[str]`
        
               Additional positional arguments for `func`.
        
               *default*: `[]`
        
             * `kwargs` -- `Dict[str, Any]`
        
               Additional keyword arguments for `func`.
        
               *default*: `{}`
        
           - Returns:
        
             * `str` -- random word
        
        <a name="_gen_sentence" />
        
        4. ```python
           def _gen_sentence(pool, comma, word_range) -> str: ...
           ```
        
           Generate random sentence.
        
           - Args:
        
             * `pool` -- `Iterable[str]`
        
               Word pool, returned by `_gen_pool`.
        
             * `comma` -- `Tuple[int]`
        
               Random range for number of commas. The function will use
               `random.randint` to choose a random integer as the number of commas.
        
               *default*: `(0, 2)`
        
             * `word_range` -- `Tuple[int]`
        
               Random range for number of words in each sentence. The function will
               use `random.randint` to choose a random integer as the number of words.
        
               *default*: `(4, 8)`
        
           - Returns:
        
             * `str` -- random sentence
        
        <a name="_gen_paragraph" />
        
        5. ```python
           def _gen_paragraph(pool, comma, word_range, sentence_range) -> str: ...
           ```
        
           Generate random paragraph.
        
           - Args:
        
             * `pool` -- `Iterable[str]`
        
               Word pool, returned by `_gen_pool`.
        
             * `comma` -- `Tuple[int]`
        
               Random range for number of commas. The function will use
               `random.randint` to choose a random integer as the number of commas.
        
               *default*: `(0, 2)`
        
             * `word_range` -- `Tuple[int]`
        
               Random range for number of words in each sentence. The function will
               use `random.randint` to choose a random integer as the number of words.
        
               *default*: `(4, 8)`
        
             * `sentence_range` -- `Tuple[int]`
        
               Random range for number of sentences in each paragraph. The function
               will use `random.randint` to choose a random integer as the number of
               sentences.
        
               *default*: `(5, 10)`
        
           - Returns:
        
             * `str` -- random paragraph
        
        ## Testing
        
        The `lorem` module utilised `unittest.mock` to *patch* the builtin functions
        from `random` module. Test cases can be found in [`test.py`](test.py).
        **Contributions are welcome.**
        
Keywords: lorem loremipsum
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.3
Description-Content-Type: text/markdown
