.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "gallery/fundamentals/example4_path.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note Click :ref:`here ` to download the full example code .. rst-class:: sphx-glr-example-title .. _sphx_glr_gallery_fundamentals_example4_path.py: Mounting and Targets ======================== To keep track of files internally ``dman`` has some custom path specifications. .. GENERATED FROM PYTHON SOURCE LINES 9-21 Introduction --------------------------- Internally ``dman`` specifies paths through mount points and targets. A mount point determines the root of the file tree that is constructed during serialization, while targets are used to specify the positions of files within this tree defined relative to the current directory. We will operate in a temporary directory for the purpose of this example. To do so we need to make sure it contains a ``.dman`` subfolder. Usually you can create one by executing ``dman init`` in your terminal. We do so using :func:`get_root_path` here. .. GENERATED FROM PYTHON SOURCE LINES 21-34 .. code-block:: default import os, subprocess, textwrap import dman from tempfile import TemporaryDirectory # Create a temporary directory and change our directory to it. tmp = TemporaryDirectory() os.chdir(tmp.name) # Create the ``.dman`` folder. # This is identical to calling ``dman init`` in terminal. dman.get_root_path(create=True) .. rst-class:: sphx-glr-script-out .. code-block:: none '/tmp/tmp3mgn0i04/.dman' .. GENERATED FROM PYTHON SOURCE LINES 35-48 Mount points ---------------------------- We begin with introducing mount points. The signature of the :func:`dman.mount` method will appear often when using ``dman`` so we begin with discussing it in detail, before showing other functionalities provided by mount points. Initialization ^^^^^^^^^^^^^^^^^^^ A mount point is specified from some base directory, which usually is a ``.dman`` folder, located above the current working directory in the file tree (similarly to how a ``.git`` folder is located). For the purposes of this example we use the temporary directory created above. .. GENERATED FROM PYTHON SOURCE LINES 48-52 .. code-block:: default os.chdir(tmp.name) print(dman.mount('object')) .. rst-class:: sphx-glr-script-out .. code-block:: none /tmp/tmp3mgn0i04/.dman/cache/example4_path/object .. GENERATED FROM PYTHON SOURCE LINES 53-67 We can break up the path into three parts. - ``/.dman``` is the base directory, outputted by :func:`get_root_path`. - ``cache/example4_path``` is referred to as the generator. - ``object``` is the key of the specific file tree being operated on. These match the arguments of :func:`mount`. .. autofunction:: dman.mount The most complex argument is the ``generator``. Usually this is based on the path of the script relative to the root path containing ``.dman``. We can illustrate this by first creating a script local to the temporary directory. .. GENERATED FROM PYTHON SOURCE LINES 67-83 .. code-block:: default # Create script that prints the evaluation mount. os.chdir(tmp.name) os.mkdir(os.path.join(tmp.name, 'scripts')) local = os.path.join(tmp.name, 'scripts', 'script.py') content = ''' import dman print(dman.mount('object')) ''' with open(local, 'w') as f: f.write(content) # We can then see what the new output of ``mount`` is. out = subprocess.check_output(f'python {local}', shell=True) print(str(out, 'utf-8')) .. rst-class:: sphx-glr-script-out .. code-block:: none /tmp/tmp3mgn0i04/.dman/cache/scripts:script/object .. GENERATED FROM PYTHON SOURCE LINES 84-86 The other arguments are relatively straightforward. We provide some examples below .. GENERATED FROM PYTHON SOURCE LINES 86-93 .. code-block:: default os.chdir(tmp.name) print('generator ...', dman.mount('object', generator='gen')) print('base ........', dman.mount('object', base=os.path.join('home', 'user'))) print('subdir ......', dman.mount('object', subdir='folder')) print('cluster .....', dman.mount('object', cluster=False)) .. rst-class:: sphx-glr-script-out .. code-block:: none generator ... /tmp/tmp3mgn0i04/.dman/gen/object base ........ home/user/cache/example4_path/object subdir ...... /tmp/tmp3mgn0i04/.dman/cache/example4_path/folder/object cluster ..... /tmp/tmp3mgn0i04/.dman/cache/example4_path/ .. GENERATED FROM PYTHON SOURCE LINES 94-96 The final example, involving ``cluster``, does not include the key and is thus equivalent to .. GENERATED FROM PYTHON SOURCE LINES 96-100 .. code-block:: default os.chdir(tmp.name) print('cluster .....', dman.mount('')) .. rst-class:: sphx-glr-script-out .. code-block:: none cluster ..... /tmp/tmp3mgn0i04/.dman/cache/example4_path/ .. GENERATED FROM PYTHON SOURCE LINES 101-104 The reason for this redundancy is to be consistent with ``save``, ``load`` and ``track``. There the ``key`` determines the file name and the default ``cluster=True`` means a dedicated directory is created for the file tree. .. GENERATED FROM PYTHON SOURCE LINES 106-110 File IO ^^^^^^^^^^^^^^^^^^ Next we show how ``mount`` can be used to edit and remove files automatically. .. GENERATED FROM PYTHON SOURCE LINES 110-122 .. code-block:: default os.chdir(tmp.name) mnt = dman.mount('object', cluster=False) print(mnt) # Write some text to a file. with mnt.open('howto.txt', 'w') as f: f.write(textwrap.dedent(""" This is a book of bad ideas. At least, most of them are bad ideas. It's possible some good ones slipped through the cracks. If so, I apologize. """)) .. rst-class:: sphx-glr-script-out .. code-block:: none /tmp/tmp3mgn0i04/.dman/cache/example4_path/ .. GENERATED FROM PYTHON SOURCE LINES 123-125 One useful feature of mount points is that they detect when files have been written to before. For example: .. GENERATED FROM PYTHON SOURCE LINES 125-130 .. code-block:: default with mnt.open('howto.txt', 'w') as f: f.write(textwrap.dedent(""" This information was lost. """)) .. GENERATED FROM PYTHON SOURCE LINES 131-132 By default a warning is provided, but we can also raise an error .. GENERATED FROM PYTHON SOURCE LINES 132-144 .. code-block:: default from dman.core.path import UserQuitException try: # set retouch action dman.params.store.on_retouch = 'quit' with mnt.open('howto.txt', 'w') as f: f.write(textwrap.dedent(""" This string will never be written. """)) except UserQuitException as e: print(e) .. rst-class:: sphx-glr-script-out .. code-block:: none Attempted to write to target "howto.txt" twice during serialization.Operation exited by user. .. GENERATED FROM PYTHON SOURCE LINES 145-146 Alternatively we can automatically increment the file name. .. GENERATED FROM PYTHON SOURCE LINES 146-155 .. code-block:: default dman.params.store.on_retouch = 'auto' with mnt.open('howto.txt', 'w') as f: f.write(textwrap.dedent(""" This is a book of bad ideas. At least, most of them are bad ideas. It's possible some good ones slipped through the cracks. If so, I apologize. """)) .. GENERATED FROM PYTHON SOURCE LINES 156-168 You can also configure ``dman`` to prompt the user as follows: .. code-block:: python dman.params.store.on_retouch = 'prompt' The default behavior can be recovered using: .. code-block:: python dman.params.store.on_retouch = 'ignore' .. GENERATED FROM PYTHON SOURCE LINES 170-171 The final state of the .. GENERATED FROM PYTHON SOURCE LINES 171-174 .. code-block:: default mnt.close() dman.tui.walk_directory(mnt, show_content=True, show_hidden=True) .. rst-class:: sphx-glr-script-out .. code-block:: none 📂 /tmp/tmp3mgn0i04/.dman/cache/example4_path/ ┣━━ 📄 .gitignore (42 bytes) ┃ ────────────────────────────────────────────────────────────────────────── ┃ .gitignore ┃ howto.txt ┃ howto0.txt ┃ howto1.txt ┃ ────────────────────────────────────────────────────────────────────────── ┣━━ 📄 howto.txt (150 bytes) ┃ ────────────────────────────────────────────────────────────────────────── ┃ ┃ This is a book of bad ideas. ┃ At least, most of them are bad ideas. It's possible some ┃ good ones slipped through the cracks. If so, I apologize. ┃ ┃ ────────────────────────────────────────────────────────────────────────── ┣━━ 📄 howto0.txt (28 bytes) ┃ ────────────────────────────────────────────────────────────────────────── ┃ ┃ This information was lost. ┃ ┃ ────────────────────────────────────────────────────────────────────────── ┗━━ 📄 howto1.txt (150 bytes) ────────────────────────────────────────────────────────────────────────── This is a book of bad ideas. At least, most of them are bad ideas. It's possible some good ones slipped through the cracks. If so, I apologize. ────────────────────────────────────────────────────────────────────────── .. GENERATED FROM PYTHON SOURCE LINES 175-181 Note that the edited files are also added to a ``.gitignore`` file automatically. You can add ``gitignore=False`` to your call of ``mnt`` to avoid this. We can also remove files and they are removed from the ``.gitignore`` automatically. .. GENERATED FROM PYTHON SOURCE LINES 181-186 .. code-block:: default mnt.remove('howto.txt') mnt.close() dman.tui.walk_directory(mnt, show_content=True, show_hidden=True) .. rst-class:: sphx-glr-script-out .. code-block:: none 📂 /tmp/tmp3mgn0i04/.dman/cache/example4_path/ ┣━━ 📄 .gitignore (32 bytes) ┃ ────────────────────────────────────────────────────────────────────────── ┃ .gitignore ┃ howto0.txt ┃ howto1.txt ┃ ────────────────────────────────────────────────────────────────────────── ┣━━ 📄 howto0.txt (28 bytes) ┃ ────────────────────────────────────────────────────────────────────────── ┃ ┃ This information was lost. ┃ ┃ ────────────────────────────────────────────────────────────────────────── ┗━━ 📄 howto1.txt (150 bytes) ────────────────────────────────────────────────────────────────────────── This is a book of bad ideas. At least, most of them are bad ideas. It's possible some good ones slipped through the cracks. If so, I apologize. ────────────────────────────────────────────────────────────────────────── .. GENERATED FROM PYTHON SOURCE LINES 187-198 Targets --------------- For now we have been specifying paths relative to the mount point using strings. Internally ``dman`` used ``target`` to create these paths. It is useful to know about this since many higher-level methods use the same signature. .. autofunction:: dman.target We provide some examples here .. GENERATED FROM PYTHON SOURCE LINES 198-201 .. code-block:: default print('a.', dman.target(stem='file', suffix='.obj')) print('b.', dman.target(name='file.obj')) print('c.', dman.target(name='file.obj', subdir='folder')) .. rst-class:: sphx-glr-script-out .. code-block:: none a. file.obj b. file.obj c. folder/file.obj .. rst-class:: sphx-glr-timing **Total running time of the script:** ( 0 minutes 0.275 seconds) .. _sphx_glr_download_gallery_fundamentals_example4_path.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: example4_path.py ` .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: example4_path.ipynb ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_