Metadata-Version: 2.1
Name: tdir
Version: 0.10.0
Summary: Create and recursively fill a temporary directory
Home-page: https://github.com/rec/tdir
Author: Tom Ritchford
Author-email: tom@swirly.com
License: MIT
Keywords: testing,modules
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
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: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities

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

Create a temporary directory using tempfile.TemporaryDirectory and then
populate it.

* ``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)

Extremely useful for unit tests where you want a whole directory
full of files really fast.

EXAMPLE: to temporarily create a directory structure

.. code-block:: python

    import tdir

    with tdir.tdir(
        'one', 'two', 'three',
        four='two\nlines',
        sub1={
            'six': 'A short file',
            'seven': 'blank lines\n\n\n\n',
            'eight': ['a', 'b', 'c']
    }) as td:
        # Now the directory `td` has files `one`, `two` and `three`, each with
        # one line, file `four` with two lines, and then a subdirectory `sub/`
        # with more files.

EXAMPLE: as a decorator for tests

.. code-block:: python

    from pathlib import Path
    import tdir
    import unittest
    CWD = Path().absolute()


    # Decorate a whole class
    @tdir('a', 'b', 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('a', 'b', foo='bar')
        def test_something(self):
            assert Path('a').read_text() = 'a\n'
            assert Path('foo').read_text() = 'bar\n'

        # 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, 78-111 <https://github.com/rec/tdir/blob/master/tdir.py#L78-L111>`_)

A context that creates and fills 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, 113-152 <https://github.com/rec/tdir/blob/master/tdir.py#L113-L152>`_)

Decorate a function or TestCase so it runs in a temporary directory with
file contents set.

If args has exactly one element which is callable (either a function or a
class), ``tdec`` returns that callable, but decorated.

Otherwise, ``tdec`` returns a decorator to wrap functions so they get run
in a temporary directory with data.

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

(`tdir.py, 154-202 <https://github.com/rec/tdir/blob/master/tdir.py#L154-L202>`_)

Fill a directory with files containing strings

ARGUMENTS
  root:
    The root directory to fill

  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.

  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.

(automatically generated by `doks <https://github.com/rec/doks/>`_ on 2020-06-25T15:03:27.688460)


