🗃 tdir - create and fill a temporary directory 🗃
======================================================

Creates a temporary directory using tempfile.TemporaryDirectory and then
populates it with files.  Great for tests!

* ``tdir`` is a context manager that runs in a populated temporary directory

* ``tdec`` is a decorator to run functions or test suites in a populated
  temporary directory

* ``fill`` recursively fills a directory (temporary or not)

EXAMPLE: to temporarily create a directory structure

.. code-block:: python

    import tdir

    with tdir.tdir(
        'one.txt', 'two.txt',
        three='some information',
        four=Path('/some/existing/file'),
        subdirectory1={
            'file.txt': 'blank lines\n\n\n\n',
            'subdirectory': ['a', 'b', 'c']
        },
    ):

EXAMPLE: as a decorator for tests

.. code-block:: python

    from pathlib import Path
    import tdir
    import unittest

    CWD = Path().absolute()


    # Decorate a whole class so each test runs in a new temporary directory
    @tdir('a', foo='bar')
    class MyTest(unittest.TestCast):
        def test_something(self):
            assert Path('a').read_text() = 'a\n'
            assert Path('foo').read_text() = 'bar\n'


    # Decorate single tests
    class MyTest(unittest.TestCast):
        @tdir(foo='bar', baz=bytes(range(4)))
        def test_something(self):
            assert Path('foo').read_text() = 'bar\n'
            assert Path('baz').read_bytes() = bytes(range(4)))

        # Run in an empty temporary directory
        @tdir
        def test_something_else(self):
            assert not Path('a').exists()
            assert Path().absolute() != CWD

API
---

``tdir.tdir(*args, cwd=True, **kwargs)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(`tdir.py, 75-108 <https://github.com/rec/tdir/blob/master/tdir.py#L75-L108>`_)

A context manager to create and fill a temporary directory.

ARGUMENTS
  args:
    A list of strings or dictionaries.  For strings, a file is created
    with that string as name and contents.  For dictionaries, the contents
    are used to recursively create and fill the directory.

  cwd:
    If true, change the working directory to the temp dir at the start
    of the context and restore the original working directory at the end.

  kwargs:
    A dictionary mapping file or directory names to values.
    If the key's value is a string it is used to file a file of that name.
    If it's a dictionary, its contents are used to recursively create and
    fill a subdirectory.

``tdir.tdec(*args, **kwargs)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(`tdir.py, 110-167 <https://github.com/rec/tdir/blob/master/tdir.py#L110-L167>`_)

Decorate a function or ``unittest.TestCase`` so it runs in a populated
temporary directory.

If ``tdec()`` has exactly one callable argument, either a function or a
class, ``tdec()`` decorates it to run in an empty temporary directory.

Otherwise, ``tdec()`` returns a decorator which decorates a function or
class to run a temporary directory populated with entries from args and
kwargs/

ARGUMENTS
  args:
    Either a single callable, or a list of strings or dictionaries.
    For strings, a file is created with that string as name and contents.
    For dictionaries, the contents are used to recursively create and
    fill the directory.

  cwd:
    If true, change the working directory to the temp dir at the start
    of the context and restore the original working directory at the end.

  kwargs:
    A dictionary mapping file or directory names to values.
    If the key's value is a string it is used to file a file of that name.
    If it's a dictionary, its contents are used to recursively create and
    fill a subdirectory.

``tdir.fill(root, *args, **kwargs)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(`tdir.py, 169-231 <https://github.com/rec/tdir/blob/master/tdir.py#L169-L231>`_)

Recursively populate a directory.

ARGUMENTS
  root:
    The root directory to fill

  args:
    A list of strings, dictionaries or Paths.

    For strings, a file is created with that string as name and contents.

    For dictionaries, the contents are used to recursively create and fill
    the directory.

    For Paths, the file is copied into the target directory

  kwargs:
    A dictionary mapping file or directory names to values.

    If the key's value is a string it is used to file a file of that name.

    If it's a dictionary, its contents are used to recursively create and
    fill a subdirectory.

    If it's a Path, that file is copied to the target directory.

(automatically generated by `doks <https://github.com/rec/doks/>`_ on 2020-06-29T20:14:56.309818)
