Metadata-Version: 1.1
Name: tdir
Version: 0.11.2
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
Description: 🗃 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)
        
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
