Metadata-Version: 2.4
Name: StringGenerator
Version: 0.5.1
Summary: Generate randomized strings of characters using a template
Home-page: https://github.com/paul-wolf/strgen
Author: Paul Wolf
Author-email: paul.wolf@yewleaf.com
License: BSD
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
License-File: LICENSE
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

strgen
======

|Python package| |RTD build|

.. image:: https://img.shields.io/pypi/pyversions/StringGenerator?color=brightgreen
   :alt: PyPI - Python Version

.. image:: https://badge.fury.io/py/StringGenerator.svg
    :target: https://badge.fury.io/py/StringGenerator
    :alt: PyPi Version

      
Generate test data, unique ids, passwords, vouchers or other randomized
textual data very quickly using a template language. The template
language is superficially similar to regular expressions but instead of
defining how to match or capture strings, it defines how to generate
randomized strings. A very simple invocation to produce a random string
with word characters of 30 characters length:

.. code:: python

   from strgen import StringGenerator as SG
   SG(r"[\w]{30}").render()
   'wQjLVRIj1sjjslORpqLJyDObaCnDR2'

`Full documentation <https://strgen.readthedocs.io>`__

The current package requires Python 3.7 or higher. Use version 0.3.4 or
earlier if you want to use Python 2.7 or an earlier Python 3 version.

NB: with version 0.4.2, the preferred method for generating a unique
list is ``StringGenerator.render_set()`` instead of ``render_list()``.
Generate 50000 unique secure tokens in a few seconds:

.. code:: python

   secure_tokens = SG(r"[\p\w]{32}").render_set(50000)

``render_set()`` does not support a progress callback.

Performance and secure generation
---------------------------------

By default ``StringGenerator`` uses ``random.SystemRandom`` (cryptographically
secure), which reads from the operating system entropy pool on every draw. That
is the right default for passwords, keys and tokens, but the per-draw syscall
makes very large batches slow.

For large batches you have two faster options:

- If you do **not** need cryptographic randomness (e.g. test data), pass a seed
  or a plain ``random.Random`` to use the much faster Mersenne Twister:

  .. code:: python

     SG(r"[\d]{10}", seed=1).render_set(1_000_000)

- If you **do** need cryptographic randomness, use ``BufferedSecureRandom``. It
  draws the same ``os.urandom`` entropy as ``SystemRandom`` but reads it in bulk
  to avoid a syscall per draw, making secure bulk generation many times faster.
  It is reachable without an extra import:

  .. code:: python

     SG(r"[\w\p]{32}", randomizer=SG.BufferedSecureRandom()).render_set(50000)

There is a rich feature set to randomize strings in situ or include
external data.

The purpose of this module is to save the Python developer from having
to write verbose code around the same pattern every time to generate
passwords, keys, tokens, test data, etc. of this sort:

.. code:: python

   my_secret_key = ''.join(random.choice(string.ascii_uppercase + string.digits) for x in range(30))

that is:

1. Hard to read even at this simplistic level.

2. Hard to safely change quickly. Even modest additions to the
   requirements need unreasonably verbose solutions.

3. Doesn’t use safe encryption standards.

4. Doesn’t provide the implied minimal guarantees of character
   occurance.

5. Hard to track back to requirements (“must be between x and y in
   length and have characters from sets Q, R and S”).

The template uses short forms similar to those of regular expressions.
An example template for generating a strong password:

::

    [\w\p]{20}

will generate something like the following:

::

    P{:45Ec5$3)2!I68x`{6

Guarantee at least two “special” characters in a string:

::

    [\w\p]{10}&[\p]{2}

You can also generate useful test data, like fake emails with plenty of
variation:

::

    [\c]{10}.[\c]{5:10}@[\c]{3:12}.(com|net|org)

Requirements
------------

From version 0.4.0, support for Python 2 is dropped. If you still need
support for Python 2, use version 0.3.4.

There are no dependencies beyond the Python Standard Library.

Installation
------------

Install as standard for Python packages from PyPi:

.. code:: shell

   pip install StringGenerator

License
-------

Released under the BSD license.

Acknowledgements
----------------

Thanks to Robert LeBlanc who caught some important errors in escaping
special characters. Thanks to Andreas Motl for the progress counter.

Original Author: paul.wolf@yewleaf.com

.. |Python package| image:: https://github.com/paul-wolf/strgen/actions/workflows/main.yml/badge.svg
   :target: https://github.com/paul-wolf/strgen/actions/workflows/main.yml

.. |RTD build| image:: https://readthedocs.org/projects/strgen/badge/?version=latest
   :target: https://strgen.readthedocs.io/en/latest/?badge=latest
   :alt: Documentation Status
            
