Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.rst with latest changes from README.md #359

Merged
merged 1 commit into from
Oct 10, 2019
Merged

Update README.rst with latest changes from README.md #359

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
309 changes: 97 additions & 212 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ To install scratchdir from `pip <https://pypi.python.org/pypi/pip>`__:

.. code:: bash

$ pip install scratchdir
$ pip install scratchdir

To install scratchdir from source:

.. code:: bash

$ git clone [email protected]:ahawker/scratchdir.git
$ python setup.py install
$ git clone [email protected]:ahawker/scratchdir.git
$ python setup.py install

Usage
~~~~~
Expand All @@ -31,101 +31,101 @@ and call ``setup``:

.. code:: bash

⇒ cat examples/readme/setup.py
import scratchdir
⇒ cat examples/readme/setup.py
import scratchdir

sd = scratchdir.ScratchDir()
sd.setup()
print(sd.wd)
sd.teardown()
sd = scratchdir.ScratchDir()
sd.setup()
print(sd.wd)
sd.teardown()

⇒ python examples/readme/usage-1.py
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/3e56r54m.scratchdir
⇒ python examples/readme/usage-1.py
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/3e56r54m.scratchdir

Or as a context manager using the ``with`` statement:

.. code:: bash

⇒ cat examples/readme/context-manager.py
import scratchdir
⇒ cat examples/readme/context-manager.py
import scratchdir

with scratchdir.ScratchDir() as sd:
print(sd.wd)
with scratchdir.ScratchDir() as sd:
print(sd.wd)

⇒ python examples/readme/context-manager.py
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/_ibfhq1s.scratchdir
⇒ python examples/readme/context-manager.py
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/_ibfhq1s.scratchdir

Files created by the ``ScratchDir`` are automatically cleaned up on
teardown:

::

⇒ cat examples/readme/cleanup.py
import os
import scratchdir
⇒ cat examples/readme/cleanup.py
import os
import scratchdir

path = None
path = None

with scratchdir.ScratchDir() as sd:
tmp = sd.named(delete=False)
path = tmp.name
print('Path {} exists? {}'.format(path, os.path.exists(path)))
with scratchdir.ScratchDir() as sd:
tmp = sd.named(delete=False)
path = tmp.name
print('Path {} exists? {}'.format(path, os.path.exists(path)))

print('Path {} exists? {}'.format(path, os.path.exists(path)))
print('Path {} exists? {}'.format(path, os.path.exists(path)))

⇒ python examples/readme/cleanup.py
Path /var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/y1aedyk8.scratchdir/tmp7m79rev1 exists? True
Path /var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/y1aedyk8.scratchdir/tmp7m79rev1 exists? False
⇒ python examples/readme/cleanup.py
Path /var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/y1aedyk8.scratchdir/tmp7m79rev1 exists? True
Path /var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/y1aedyk8.scratchdir/tmp7m79rev1 exists? False

Directories within the ``ScratchDir`` are also easy to create:

.. code:: bash

⇒ cat examples/readme/directory.py
import scratchdir
⇒ cat examples/readme/directory.py
import scratchdir

with scratchdir.ScratchDir() as sd:
subdir = sd.directory()
print(subdir)
with scratchdir.ScratchDir() as sd:
subdir = sd.directory()
print(subdir)

⇒ python examples/readme/directory.py
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/c1odkxbw.scratchdir/tmpcyeqjk1v
⇒ python examples/readme/directory.py
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/c1odkxbw.scratchdir/tmpcyeqjk1v

Methods on the ``ScratchDir`` instance will pass arguments down to their
corresponding functions in
`tempfile <https://docs.python.org/3.6/library/tempfile.html#module-tempfile>`__.

.. code:: bash

⇒ cat examples/readme/params.py
import scratchdir
⇒ cat examples/readme/params.py
import scratchdir

with scratchdir.ScratchDir() as sd:
tmp = sd.named(suffix='.txt', prefix='logfile-', delete=False)
print(tmp.name)
with scratchdir.ScratchDir() as sd:
tmp = sd.named(suffix='.txt', prefix='logfile-', delete=False)
print(tmp.name)

⇒ python examples/readme/params.py
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/1h_7379t.scratchdir/logfile-z1gq195q.txt
⇒ python examples/readme/params.py
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/1h_7379t.scratchdir/logfile-z1gq195q.txt

Creating a hierarchy of ``ScratchDir`` instances to match that of your
domain objects is also simple:

.. code:: bash

⇒ cat examples/readme/hierarchy.py
import scratchdir
⇒ cat examples/readme/hierarchy.py
import scratchdir

with scratchdir.ScratchDir(prefix='grandparent-') as grandparent:
print(grandparent.wd)
with grandparent.child(prefix='parent-') as parent:
print(parent.wd)
with parent.child(prefix='child-') as child:
print(child.wd)
with scratchdir.ScratchDir(prefix='grandparent-') as grandparent:
print(grandparent.wd)
with grandparent.child(prefix='parent-') as parent:
print(parent.wd)
with parent.child(prefix='child-') as child:
print(child.wd)

⇒ python examples/readme/hierarchy.py
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/grandparent-4ld_pl8f.scratchdir
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/grandparent-4ld_pl8f.scratchdir/parent-s6y_gmxg.scratchdir
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/grandparent-4ld_pl8f.scratchdir/parent-s6y_gmxg.scratchdir/child-28k2hpdk.scratchdir
⇒ python examples/readme/hierarchy.py
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/grandparent-4ld_pl8f.scratchdir
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/grandparent-4ld_pl8f.scratchdir/parent-s6y_gmxg.scratchdir
/var/folders/86/zhtx1pv53qs2mm1fq1k1841w0000gn/T/grandparent-4ld_pl8f.scratchdir/parent-s6y_gmxg.scratchdir/child-28k2hpdk.scratchdir

Methods
~~~~~~~
Expand All @@ -135,168 +135,53 @@ functions/classes within the
`tempfile <https://docs.python.org/3.6/library/tempfile.html#module-tempfile>`__
module in the standard library. A table of methods is as follows:

+------+------+------+
| scra | temp | desc |
| tchd | file | ript |
| ir | | ion |
+======+======+======+
| file | Temp | Crea |
| , | orar | te |
| Temp | yFil | a |
| orar | e | name |
| yFil | | less |
| e | | temp |
| | | orar |
| | | y |
| | | file |
| | | that |
| | | is |
| | | auto |
| | | mati |
| | | call |
| | | y |
| | | dele |
| | | ted |
| | | once |
| | | it's |
| | | clos |
| | | ed. |
+------+------+------+
| name | Name | Crea |
| d, | dTem | te |
| Name | pora | a |
| dTem | ryFi | temp |
| pora | le | orar |
| ryFi | | y |
| le | | file |
| | | that |
| | | rece |
| | | ives |
| | | a |
| | | file |
| | | name |
| | | on |
| | | disk |
| | | that |
| | | is |
| | | auto |
| | | mati |
| | | call |
| | | y |
| | | dele |
| | | ted |
| | | once |
| | | it's |
| | | clos |
| | | ed |
| | | unle |
| | | ss |
| | | the |
| | | ``de |
| | | lete |
| | | `` |
| | | para |
| | | mete |
| | | r |
| | | is |
| | | ``Fa |
| | | lse` |
| | | `. |
+------+------+------+
| spoo | Spoo | Crea |
| led, | ledT | te |
| Spoo | empo | a |
| ledT | rary | temp |
| empo | File | orar |
| rary | | y |
| File | | file |
| | | that |
| | | will |
| | | over |
| | | flow |
| | | from |
| | | memo |
| | | ry |
| | | onto |
| | | disk |
| | | once |
| | | a |
| | | defi |
| | | ned |
| | | maxi |
| | | mum |
| | | size |
| | | is |
| | | exce |
| | | eded |
| | | . |
+------+------+------+
| secu | mkst | Crea |
| re, | emp | te |
| mkst | | a |
| emp | | temp |
| | | orar |
| | | y |
| | | file |
| | | in |
| | | as |
| | | secu |
| | | re |
| | | way |
| | | as |
| | | poss |
| | | ible |
| | | . |
+------+------+------+
| dire | mkdt | Crea |
| ctor | emp | te |
| y, | | a |
| mkdt | | temp |
| emp | | orar |
| | | y |
| | | dire |
| | | ctor |
| | | y. |
+------+------+------+
| file | N/A | Crea |
| name | | te |
| | | a |
| | | uniq |
| | | ue |
| | | file |
| | | name |
| | | with |
| | | in |
| | | the |
| | | ``Sc |
| | | ratc |
| | | hDir |
| | | ``. |
+------+------+------+
| join | N/A | Join |
| | | a |
| | | numb |
| | | er |
| | | of |
| | | path |
| | | s |
| | | to |
| | | the |
| | | root |
| | | of |
| | | the |
| | | ``Sc |
| | | ratc |
| | | hDir |
| | | ``. |
+------+------+------+
+-----------------------+-----------------------+-----------------------+
| scratchdir | tempfile | description |
+=======================+=======================+=======================+
| file, TemporaryFile | TemporaryFile | Create a nameless |
| | | temporary file that |
| | | is automatically |
| | | deleted once it’s |
| | | closed. |
+-----------------------+-----------------------+-----------------------+
| named, | NamedTemporaryFile | Create a temporary |
| NamedTemporaryFile | | file that receives a |
| | | filename on disk that |
| | | is automatically |
| | | deleted once it’s |
| | | closed unless the |
| | | ``delete`` parameter |
| | | is ``False``. |
+-----------------------+-----------------------+-----------------------+
| spooled, | SpooledTemporaryFile | Create a temporary |
| SpooledTemporaryFile | | file that will |
| | | overflow from memory |
| | | onto disk once a |
| | | defined maximum size |
| | | is exceeded. |
+-----------------------+-----------------------+-----------------------+
| secure, mkstemp | mkstemp | Create a temporary |
| | | file in as secure way |
| | | as possible. |
+-----------------------+-----------------------+-----------------------+
| directory, mkdtemp | mkdtemp | Create a temporary |
| | | directory. |
+-----------------------+-----------------------+-----------------------+
| filename | N/A | Create a unique |
| | | filename within the |
| | | ``ScratchDir``. |
+-----------------------+-----------------------+-----------------------+
| join | N/A | Join a number of |
| | | paths to the root of |
| | | the ``ScratchDir``. |
+-----------------------+-----------------------+-----------------------+

Goals
~~~~~

I've implemented similar functionality three times now, starting with my
I’ve implemented similar functionality three times now, starting with my
`scatter <https://github.com/ahawker/scatter>`__ project back in
2013-2014. I'd rather not write it *again*, so the goal is that
2013-2014. I’d rather not write it *again*, so the goal is that
scratchdir should be generic and reusable for future projects.

Contributing
Expand Down